Docs
Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Bitbucket Data Center integration overview

2 weeks ago7 min read
Cloud
On This Page

This page walks you through integrating a Bitbucket Data Center project with CircleCI. The sections below introduce you to concepts and ways to manage CI/CD (continuous integration and continuous delivery) pipelines for your Bitbucket Data Center project. CircleCI features that are in development for Bitbucket Data Center projects are detailed in the Coming soon section.

CircleCI Bitbucket Data Center integration overview

CircleCI CI/CD allows you to build, test (continuous integration) and deploy (continuous deployment, continuous delivery) your Bitbucket Data Center projects each time a developer pushes a change to the codebase, and when a pull request is merged.

Integrate with CircleCI to access features for automated software delivery:

Steps to integrate Bitbucket Data Center projects with CircleCI

Prerequisites

  • Follow the steps on the Sign up and try CircleCI page to create a CircleCI account, create a new CircleCI organization. Alternatively you can use an existing organization.

  • Follow the steps on the Create a project page to create a project in CircleCI and set up an integration with your Bitbucket Data Center project.

Integrate a project with CircleCI

  1. Set up your integration with Bitbucket Data Center if you have not already:

    1. In the CircleCI web app, select Organization Settings in the sidebar.

    2. Select Integrations in the sidebar.

    3. Select Set Up Integration next to Bitbucket Data Center.

    4. In the modal, enter your Bitbucket Data Center instance URL and your known_hosts. For guidance on generating known_hosts, see Generate known_hosts.

    5. Select Set Up Integration.

    6. Select the back arrow to exit Organization Settings.

  2. For the next sections you will need to create a project HTTP access token with the project admin scope. Create this under Projects in Bitbucket. For more information, see the Bitbucket docs. Copy the token somewhere safe, you will need to enter it when creating pipelines and triggers in CircleCI.

  3. Set up a pipeline:

    1. Select Project Settings.

    2. Select Pipelines in the sidebar.

    3. Select Set Up Pipeline. Fill in the required fields:

      • Give your pipeline a descriptive name.

      • Select Bitbucket Data Center under Integration.

      • Provide the project HTTP access token you created in the previous step. Select Connect.

      • Under Config, define where the config file for this pipeline is stored:

        • Select a repository from the dropdown.

        • Enter the path to the config file. Typically this is .circleci/config.yml but can be any file path with extension *.yml.

      • Under Build Assets, select a checkout source for this pipeline. This is the repository that will be checked out when a checkout step is run. If your config is stored in the same repository as your code, pick the same repository you selected under Config Source.

    4. Select Save.

  4. Set up a trigger:

    1. Select Triggers in the Project Settings sidebar.

    2. Select Add Trigger.

    3. Select Bitbucket Data Center from the dropdown and select Next.

    4. Fill in the required fields:

      • Give your trigger a descriptive name.

      • Provide the project HTTP access token you created above. Select Connect.

      • Select the Trigger source repository

      • Choose the pipeline you created in the previous step under the dropdown to show CircleCI which pipeline to trigger.

      • If prompted, enter a config branch. This is the name of the branch that should be used to fetch your config file when a pipeline is triggered. This field is only required if your config is stored in a repository that is not the source of your trigger.

      • If prompted, enter a checkout branch. This is the name of the branch that should be used to check out your code when a checkout step is run. This field is only required if the Checkout Source repository you configured in your Pipeline is not the source of your trigger.

    5. Select Save.

  5. If you have not already done so, create a .circleci directory to the root of your repository, then add a config.yml file in that directory. When you commit this change in your repository, you should see the pipeline trigger for the first time on the CircleCI dashboard.

Each time you push changes to your Bitbucket Data Center repository, a new pipeline is triggered and you should see it running for the project within the CircleCI web app.

Successful pipeline run

Make any further changes to your CircleCI config in your Bitbucket Data Center repository. Editing an existing CircleCI configuration within the web app is not currently available.

Committing changes in your repository will automatically trigger a pipeline. Manually triggering a pipeline from the CircleCI web app is not available at this time.

Generate known_hosts

Integrating CircleCI with your Bitbucket Data Center instance requires that you store a public SSH host key within the CircleCI organization that will be accessing the Bitbucket Data Center instance.

To get the required SSH host key, run ssh-keyscan with the hostname and port of your Bitbucket Data Center instance. For example:

ssh-keyscan -p 1234 bitbucket-datacenter.example.com

The output will look something like the following:

[bitbucket-datacenter.example.com]:1234 ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAA//NF6iU86j0hfGxn8ncjgwvmk9tMKzhFqrRLaltP0TGt760PhfWk070raKLHS3L6H0BdN9qNVsTk63czziFDmtBehE82/XXX+59MuppY0DHG3brNvw4REPmzZkQNIR6Cs8b15iFbwnIL51IH9kBVMztWQaRDPkPPxihM6e0n/vo5n3uEIPCTZiwLgKRcpeks2LsfbsW0NN5Q7J1Irp/ACstfrsFWSntranbjMe6cIwELNY6FhvYmETzH0cY0=

Copy the full output from the ssh-keyscan command and enter it into the "known hosts" text box when setting up your integration in the CircleCI web app under Organization Settings  Integrations.

How it works

When you connect a repository with your CircleCI project, behind the scenes, CircleCI is registering a webhook within your Bitbucket Data Center project. You may verify this once you have successfully created the project by navigating to your repository’s Project Settings  Webhooks page.

Limitations

The following limits are currently in place for Bitbucket Data Center integrations:

  • Each user can create up to three organizations.

  • Each organization under a Free Plan can have up to 10 projects.

If you need more organizations or projects, consider upgrading to a Paid plan, or contact our Support team.

Project settings

Project settings is where you can access the following and more:

  • Set up collaborators and roles.

  • Set up and manage pipelines and triggers.

  • Set up project level environment variables, SSH keys and API permissions.

  • Set up integrations, for example, Slack notifications, LLMOps, status badges, webhooks.

People and groups

Project roles give control over which users have access to which projects within an organization. This enables teams to have limited access to only their projects, while managers and others can have broader organizational access. The access options are:

  • Admin: Read and write access to the project and all settings and ability to manage other users' access.

  • Contributor: Read and write access to the project and some settings.

  • Viewer: Read only access to the project and some settings.

For full details of roles, permissions, and groups, see the following pages:

Pipelines and triggers

You can add or delete pipelines and triggers for your project. For details see the pipelines overview.

Advanced

  • You can optionally choose to enable the auto-cancel redundant workflows setting

  • You can enable dynamic configuration using setup workflows in CircleCI. To learn about dynamic configuration, read the Dynamic configuration guide.

  • At this time, the Free and Open Source setting is not currently supported for Bitbucket Data Center, but there are plans to make this available in the future.

Additional SSH keys

You can add additional SSH keys to the project. You might want to set this up for a few reasons:

  • If you would like to allow your project to access or deploy to services

  • If you would like your project to write to, or checkout code from, other repositories

For details see the Additional SSH keys overview.

Organization settings

For Bitbucket Data Center integrations, organizations and users are managed independently from your VCS. Organizations and users are considered CircleCI organizations and users, with their own roles and permissions that do not rely on those defined in your VCS.

To manage settings at the organization level, select Organization Settings in the CircleCI web app sidebar.

People

Add or remove users, and manage user roles for the organization as well as user invites. See the Roles and permissions overview page for full details.

Integrations

The Integrations page under Organization Settings allows you to connect your organization with either Bitbucket Data Center or a GitLab self-managed instance. Steps to integrate with Bitbucket Data Center are described on the Create a project page.

Deprecated system environment variables

A number of built-in environment variables are not available in Bitbucket Data Center-based projects. VCS support for each environment variable is indicated in the Built-in environment variables table on the Project values and variables page.

If your pipelines need the data provided by the deprecated environment variables, we recommend you use suitable replacements from the available pipeline values list.

Coming soon

The following sections are features of CircleCI which are not currently fully supported for Bitbucket Data Center. These features are planned for future releases.

Account integrations

You can only manage your connections between CircleCI and Bitbucket Data Center through project setup, pipeline and trigger settings. We are working on enabling users to manage their users’ Bitbucket Data Center identity as part of their user profile’s account integration settings.

Passing secrets to forked pull requests

Passing secrets to forked pull requests is not a currently supported option for Bitbucket Data Center integrations.

Scheduled pipelines

The ability to schedule pipelines is not currently supported for Bitbucket Data Center projects. This feature is planned for a future release.

Stop building

Bitbucket Data Center integrations do not currently support the Stop Building option that can normally be found in Project settings. As an alternative, you can Delete a project.

Additional SSH keys only

Deploy keys and user keys are not used by Bitbucket Data Center integrations. Additional Bitbucket Data Center keys are stored in Project Settings > Additional SSH Keys.

Free and open source setting

Open source plans are not currently available to Bitbucket Data Center customers. CircleCI will keep the open source community up to date as work continues to support this.

Test Insights

Test Insights is currently not supported for Bitbucket Data Center integrations.

CircleCI self-hosted server product

Bitbucket Data Center is not yet supported for CircleCI server.

Next steps

Suggest an edit to this page

Make a contribution
Learn how to contribute

Still need help?

Ask the CircleCI community
Join the research community
Visit our Support site