Building repositories from Bitbucket Data Center

Cloud Build enables you to create triggers to build from repositories hosted on Bitbucket Data Center, allowing you to execute builds in response to events such as commit pushes or pull requests associated with your Bitbucket Data Center repository.

This page explains how you can enable trigger functionality on a Bitbucket Data Center instance and how you can build repositories from Bitbucket Data Center if your instance is hosted in an on-premises environment.

Before you begin

  • Enable the Cloud Build, Secret Manager, and Compute Engine APIs.

    Enable the APIs

  • If you have not installed a Bitbucket Data Center instance, see Install Bitbucket Data Center for instructions.
  • [Optional] If your Bitbucket Data Center instance is hosted in an on-premises environment, enable the Service Networking API to peer a Virtual Private Cloud network.

Setting up

Before you create a Bitbucket Data Center trigger, you must obtain an API key to authenticate and accept incoming events from Bitbucket Data Center. Additionally, you must grant IAM permissions in your Google Cloud project to create triggers and create personal access tokens in Bitbucket Data Center to create webhooks and retrieve repository data.

This section discusses steps you need to complete before creating a Bitbucket Data Center trigger.

Obtaining an API key

To connect your host repositories and authenticate incoming webhook events, you need an API key.

To obtain an API key:

  1. Open the Credentials page in the Google Cloud console:

    Open the Credentials page

  2. Click Create credentials.

  3. Click API Key.

    You will see a dialog with your API key created. Take note of your API key.

  4. If you would like to restrict your key for product applications, click Restrict key to complete additional steps to secure your key. Otherwise, click Close.

    To learn how to restrict your key, see Applying API key restrictions.

Creating personal access tokens

You must create two personal access tokens in Bitbucket Data Center to perform the following tasks:

These personal access tokens are the minimum permissions required. You may configured additional permissions in Bitbucket Data Center as needed. For example, you may select Bitbucket Data Center account to have access only to a subset of the repositories on your Bitbucket Data Center instance to allow for finer grained control over what is available in Cloud Build.

After you've created your personal access tokens, save your token values securely. You will be using these tokens to connect to your Bitbucket Data Center repository later.

Invoking triggers from Bitbucket Data Center

This sections explains how you can connect your Bitbucket Data Center repositories to Cloud Build and create a trigger to automatically invoke builds on your connected repositories. If you want to use Bitbucket Data Center triggers in an on-premises environment, see Building repos in an on-premises environment from Bitbucket Data Center for further instructions.

Connecting to a Bitbucket Data Center host

Console

To connect your Bitbucket Data Center host to Cloud Build using the Google Cloud console:

  1. Open the Manage repositories page in the Google Cloud console:

    Open the Manage repositories page

  2. Click Connect Host.

    You will see the Connect host panel.

    Enter the following information to connect your Bitbucket Data Center instance to Cloud Build:

    • Host url: Your host URL of your Bitbucket Data Center instance. For example, https://bbs.example-test.com:7990.
    • Google Cloud API key: Your API key used to authenticate your credentials.
    • CA Certificate: Your self-signed certificate. Your certificate must not exceed 10 kB in size and should be in PEM format (.pem, .cer,or .crt). If this section is left blank, a default set of certificates is used in place.
    • Username: Your Bitbucket Data Center account username. This account should have admin access to the repositories that you want to connect with Cloud Build.
    • Read access token: Your Bitbucket Data Center account personal access token with read permissions.
    • Admin access token: Your Bitbucket Data Center account personal access token with admin permissions on projects and repositories.
    • [OPTIONAL] Network project: Your network project ID for your on-premises network.
    • [OPTIONAL] Network name: Your network name for your on-premises network.

  3. Click Connect Host.

    If your Bitbucket Data Center instance is on a peered network, connecting your host may take several minutes to complete.

    You will be redirected to the Connect Repository panel.

    After creating a host connection, your personal access tokens and webhook secret will be securely stored in Secret Manager. You can view and manage your secrets on the Secret Manager page.

gcloud

To connect your Bitbucket Data Center host to Cloud Build using gcloud commands, you must run the gcloud alpha builds enterprise-config bitbucketserver create command in your terminal. Unlike connecting your host using the Google Cloud console, you'll need to manually store your personal access tokens and webhook secret in Secret Manager before running the following command:

gcloud alpha builds enterprise-config bitbucketserver create
--name=BITBUCKET_DATA_CENTER_CONFIG_NAME \
--user-name=USERNAME \
--host-uri=HOST_URI \
--admin-access-token-secret-version=ADMIN_ACCESS_TOKEN_SECRET_VERSION \
--read-access-token-secret-version=READ_ACCESS_TOKEN_SECRET_VERSION \
--webhook-secret-secret-version=WEBHOOK_SECRET_SECRET_VERSION \
--api-key=API_KEY \
--peered-network=PEERED_NETWORK \
--ssl-ca-file=SSL_CA_FILE

Where:

  • BITBUCKET_DATA_CENTER_CONFIG_NAME is the name of your Bitbucket Data Center configuration.
  • USERNAME is your Bitbucket Data Center username.
  • HOST_URI is the host URI of your Bitbucket Data Cemter instance.
  • ADMIN_ACCESS_TOKEN_SECRET_VERSION is the resource name of your admin access token stored in Secret Manager. The expected format for secrets stored in Secret Manager is projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/${VERSION_NUMBER}. You can specify latest as your version to use the latest version of your secret. This applies to each resource stored in Secret Manager.
  • READ_ACCESS_TOKEN_SECRET_VERSION is the resource name of your read access token stored in Secret Manager.
  • WEBHOOK_SECRET_SECRET_VERSION is the resource name of your of your webhook secret stored in Secret Manager.
  • API_KEY is the Google Cloud API key.
  • [Optional] PEERED_NETWORK is the VPC network to connect to for your Bitbucket Data Center instances on-premises.
  • SSL_CA_FILE is the path to a local file that contains your SSL certificate to use for requests to Bitbucket Data Center. The certificate should be in PEM format.

API

To connect your Bitbucket Data Center host to Cloud Build using the API, use the following JSON template. Unlike connecting your host using the Google Cloud console, you need to manually store your personal access tokens and webhook secret in Secret Manager before calling the API:

  {
      "hostUri": HOST_URI,
      "username": USERNAME,
      "apiKey": API_KEY,
      "secrets": {
        "adminAccessTokenVersionName": ADMIN_ACCESS_TOKEN_SECRET_VERSION,
        "readAccessTokenVersionName": READ_ACCESS_TOKEN_SECRET_VERSION,
        "webhookSecretVersionName": WEBHOOK_SECRET_SECRET_VERSION,
      },
      "peeredNetwork": PEERED_NETWORK,
      "sslCa": SSL_CERTIFICATE
  }

Where:

  • HOST_URI is the host URI of your Bitbucket Data Center instance.
  • USERNAME is your Bitbucket Data Center username.
  • API_KEY is the Google Cloud API key.

  • ADMIN_ACCESS_TOKEN_SECRET_VERSION is the resource name of your admin access token stored in Secret Manager. You may need to grant the Secret Manager role to your Cloud Build service account, service-${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. To learn more, see Granting Secret Manager role to your service account.

  • READ_ACCESS_TOKEN_SECRET_VERSION is the resource name of your read access token stored in Secret Manager.

  • WEBHOOK_SECRET_SECRET_VERSION is the resource name of your of your webhook secret stored in Secret Manager.

  • [Optional] PEERED_NETWORK is the VPC network to connect to for your Bitbucket Data Center instances on-premises.

  • [Optional] SSL_CERTIFICATE is the SSL certificate used for your Bitbucket Data Center instances on-premises.

Enter the following curl command in your terminal:

  curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8" https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/bitbucketServerConfigs/?bitbucketServerConfigId=BITBUCKET_DATA_CENTER_CONFIG_NAME -d @config.json

Where:

  • PROJECT_ID is your Cloud project ID.
  • BITBUCKET_DATA_CENTER_CONFIG_NAME is the name of your Bitbucket Data Center configuration.

If successful, the response body contains a newly created instance of Operation.

Enter the following curl command in your terminal:

  curl -X GET -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8"  -H "x-goog-user-project: PROJECT_NUMBER" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/global/operations/OPERATION_ID

Where:

  • PROJECT_NUMBER is your Cloud project number.
  • PROJECT_ID is your Cloud project ID.
  • OPERATION_ID is the ID of your Bitbucket Data Center configuration creation operation.

You may need to keep running the GetOperation API command until the response contains done: true, which indicates the operation is completed. If the Bitbucket Data Center configuration is created successfully, you can see the configuration in the response.value field. Otherwise, see the error field for a detailed error report.

Connecting to a Bitbucket Data Center repository

Console

To connect a Bitbucket Data Center repository to Cloud Build using the Google Cloud console:

  1. Open the Triggers page in the Google Cloud console.

    Open the Triggers page

  2. Click Connect Repository.

    You will see the Connect repository panel.

  3. Under Select source, select Bitbucket Data Center.

  4. Under Select Repository, select the Bitbucket Data Center repositories you wish to connect to Cloud Build.

  5. Click Connect to connect your repositories.

    When a repository is connected, Cloud Build configures a webhook on the repository in your Bitbucket Data Center instance. The repository then sends webhooks to invoke the corresponding Bitbucket Data Center triggers when you make changes to your repository. A repository can also be connected multiple times with multiple host connections. To learn how to manage webhooks, see Manage webhooks.

    To locate the webhook, you need the webhook ID. The webhook ID for each connected repository can be found in the BitbucketServerConfig. Enter the following command to retrieve the webhook ID, where CONFIG_NAME is the name of the Bitbucket Data Center config:

    gcloud alpha builds enterprise-config bitbucketserver describe --config=CONFIG_NAME

  6. Click Done. Optionally, click Create a trigger to create a trigger.

gcloud

gcloud support is currently not available for connecting to a Bitbucket Data Center repository.

API

To connect your Bitbucket Data Center repository to Cloud Build using the API, use the following JSON template:

  {
    "parent": "projects/PROJECT_NUMBER/locations/global/bitbucketServerConfigs/BITBUCKET_DATA_CENTER_CONFIG_NAME",
    "requests": {
      "parent": "projects/PROJECT_NUMBER/locations/global/bitbucketServerConfigs/BITBUCKET_DATA_CENTER_CONFIG_NAME",
      "bitbucketServerConnectedRepository": {
        "parent": "projects/PROJECT_NUMBER/locations/global/bitbucketServerConfigs/BITBUCKET_DATA_CENTER_CONFIG_NAME",
        "repo": {
           "projectKey":PROJECT_KEY,
           "repoSlug": REPO_SLUG,
         }
       }
    }
  }

Where:

  • PROJECT_NUMBER is the project number of your Cloud project.
  • BITBUCKET_DATA_CENTER_CONFIG_NAME is the name of your Bitbucket Data Center configuration.
  • PROJECT_KEY is the key of your Bitbucket Data Center project. If you want to connect a personal repository, your project key should contain the tilde (~) symbol before your username. For example, ~${USERNAME}. The complete URL for a host repository may look like https://${HOST_URI}/projects/~${USER_NAME}/repos/${REPO_SLUG}.
  • REPO_SLUG is the slug of your Bitbucket Data Center repository.

Enter the following curl command in your terminal:

  curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8" -H "x-goog-user-project: PROJECT_NUMBER" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/global/bitbucketServerConfigs/BITBUCKET_DATA_CENTER_CONFIG_NAME/connectedRepositories:batchCreate -d @requests.json

Where:

  • PROJECT_ID is your Cloud project ID.
  • BITBUCKET_DATA_CENTER_CONFIG_NAME is the name of your Bitbucket Data Center configuration.

If successful, the response body contains a newly created instance of Operation.

Enter the following curl command in your terminal:

  curl -X GET -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8"  -H "x-goog-user-project: PROJECT_NUMBER" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/global/operations/OPERATION_ID

Where:

  • PROJECT_NUMBER is your Cloud project number.
  • PROJECT_ID is your Cloud project ID.
  • OPERATION_ID is the ID of your Bitbucket Data Center configuration creation operation.

You may need to keep running the GetOperation API command until the response contains done: true, which indicates the operation is completed. If the Bitbucket Data Center repository is connected successfully, you can see the connected repository in the response.bitbucketServerConnectedRepositories field. Otherwise, see the error field for a detailed error report.

Creating a Bitbucket Data Center trigger

Console

To create a Bitbucket Data Center trigger using the Google Cloud console:

  1. Open the Triggers page:

    Open the Triggers page

  2. Select your project from the top of the page and click Open.

  3. Click Create trigger.

  4. Enter the following trigger settings:

    • Name: A name for your trigger.

    • Region: Select the region for your trigger.

    • Description (Optional): A description for your trigger.

    • Event: Select the repository event to invoke your trigger.

      • Push to a branch: Set your trigger to start a build on commits to a particular branch.

      • Push new tag: Set your trigger to start a build on commits that contain a particular tag.

      • Pull request (Cloud Source Repositories not supported): Set your trigger to start a build on commits to a pull request.

    • Source: Select the repository to build when the Bitbucket Data Center trigger runs.

    • Revision: Select the branch or tag to build when the Bitbucket Data Center trigger runs.

    • Branch: Set a trigger to build this branch.

    • Tag: Set a trigger to build this tag.

    • Configuration: Select the build config file located in your repository or configure your build inline on the trigger.

    • Type: Select the type of configuration to use for your build.

      • Cloud Build configuration file (yaml or json): Use a build config file for your configuration.
      • Dockerfile: Use a Dockerfile for your configuration.

    • Location: Specify the location for your configuration.

      • Repository: If your config file is in located in your repository, provide the location of your build config file or the Dockerfile directory and a name for the resulting image. If your configuration is a Dockerfile, you can optionally provide a timeout for your build. When you've provided the Dockerfile and image name, you'll see a preview of the docker build command that your build will execute.

      • Inline: If you selected Cloud Build configuration file (yaml or json) as your configuration option, you can specify your build config inline. Click Open Editor to write your build config file in the Google Cloud console using YAML or JSON syntax. Click Done to save your build config.

  5. Click Create to create your Bitbucket Data Center trigger.

gcloud

To create a Bitbucket Data Center trigger using gcloud commands, you will need to run the following gcloud alpha builds triggers create bitbucketserver command in your terminal:

gcloud alpha builds triggers create bitbucketserver
--name=TRIGGER_NAME \
--project-key=PROJECT_KEY \
--repo-slug=REPO_SLUG \
--bitbucket-server-config-resource=projects/PROJECT_NUMBER/locations/global/bitbucketServerConfigs/ID \
--branch-pattern=BRANCH_NAME \ # --tag-pattern=TAG_NAME
--build-config=BUILD_CONFIG

Where:

  • TRIGGER_NAME is the name of your trigger.
  • PROJECT_KEY is the key of your Bitbucket Data Center project.
  • REPO_SLUG is the slug of your Bitbucket Data Center repository.
  • PROJECT_NUMBER is the project number of your Cloud project.
  • ID is the ID of your BitbucketServerConfig.
  • BRANCH_NAME is the regex of your branch if you want to set your trigger to build certain branches.
  • TAG_NAME is the regex of your tag if you want to set your trigger to build certain tags.
  • BUILD_CONFIG is the path to your build config file.

API

To create a Bitbucket Data Center trigger with the API, use the following JSON template.

    {
      "filename": "cloudbuild.yaml",
      "name": "curl-trigger",
      "description": "curl trigger",
      "bitbucket_server_trigger_config": {
          "repo_slug": REPO_SLUG
          "project_key": PROJECT_KEY
          "push": {
             "branch": BRANCH_NAME # "tag": TAG_NAME
          }
     "bitbucket_server_config_resource": "projects/PROJECT_NUMBER/locations/global/bitbucketServerConfigs/ID"
      }
  }

Where:

  • PROJECT_KEY is the key of your Bitbucket Data Center project.
  • REPO_SLUG is the slug of your Bitbucket Data Center repository.
  • PROJECT_NUMBER is the project number of your Cloud project.
  • ID is the ID of your BitbucketServerConfig.
  • BRANCH_NAME is the regex of your branch if you want to set your trigger to build certain branches.
  • TAG_NAME is the regex of your tag if you want to set your trigger to build certain tags.

Enter the following curl command in your terminal, where PROJECT_ID is your Cloud project ID:

curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/triggers -d @trigger.json

Building repos in an on-premises environment from Bitbucket Data Center

If your Bitbucket Data Center instance is hosted in an on-premises environment and not reachable over a public internet connection, you need to create a private connection between your VPC network and the service producer network. You also need a private pool to build in an on-premises environment.

To create a Bitbucket Data Center trigger to build in your on-premises environment:

  1. Create a private connection to between your VPC network and your service producer network by completing the following steps:

    1. Enable the Service Networking API.

    2. Create a new VPC network or select an existing VPC network.

    3. Allocate a named IP range in the VPC network. To use the VPC network with Cloud Build, your prefix length must be /23 or lower, such as /22, /21, etc.

    4. Establish a VPC network private connection between your VPC network and Google Cloud. To learn more, see Creating a private connection.

    5. If you have DNS configured for your Bitbucket Data Center instance, you need to manually peer your DNS zone to our service provider. To learn more, see the Sharing private DNS zones with service producers.

    6. [OPTIONAL] If you do not want to create a private connection from your Cloud project, you can set up a Shared VPC and have your Cloud project use that network instead if your project is part of an organization. You will still need the Shared VPC to be peered to the Service Networking API.

  2. Use private pools to run your builds. If you have not created a private pool, see create a new private pool.

  3. Create a Bitbucket Data Center trigger to build repositories hosted on a Bitbucket Data Center instance.

Your Bitbucket Data Center trigger will now automatically invoke builds on your Bitbucket Data Center instance based on your configuration. To learn how to run builds using a private worker pool, see Running builds in a private pool.

What's next