Connect to a Bitbucket Server host

This page explains how to connect a Bitbucket Server host to Cloud Build. Connecting to a Bitbucket Server host integrates your Bitbucket Server repositories with Cloud Build. This way, you can configure build triggers to build repositories from Bitbucket Server and build repositories from Bitbucket Server in a private network.

Before you begin

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

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

Required IAM permissions

To get the permissions that you need to connect to your Bitbucket Server host, ask your administrator to grant you the following IAM roles on your user account:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

If your Bitbucket Server instance is hosted in a private network, see Build repositories from Bitbucket Server in a private network to learn about additional IAM roles required to configure a host connection.

Create personal access tokens

Before you create a host connection for your Bitbucket Server instance, create personal access tokens in Bitbucket Server by doing the following:

  1. Sign in to your Bitbucket Server instance.

  2. Follow the instructions to create HTTP access tokens for your user account.

    1. Create an access token with the repository admin scope to use for connecting and disconnecting repositories.

    2. Create an access token with the repository read scope to ensure Cloud Build repositories can access source code in repositories.

  3. Save your token values securely. You'll use them to connect to your Bitbucket Server repository.

Connect to a Bitbucket Server host

Console

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

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

    Open the Repositories page

  2. At the top of the page, select the 1st gen tab.

  3. Click Connect Host.

  4. Select Bitbucket Server from the drop-down menu.

    You will see the Connect host panel.

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

    1. Region: Select the region for your connection.

    2. Name: Enter a name for your connection.

    3. Host url: Your host URL of your Bitbucket Server instance. For example, https://bbs.example-test.com:7990.

    4. Google Cloud API key: Enter the API key used to authenticate your credentials.

    5. 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 you leave this section blank, Google Cloud uses a certificate from the default set of certificates.

    6. Username: Your Bitbucket Server account username. This account should have admin access to the repositories that you want to connect with Cloud Build.

    7. Read access token: Enter your Bitbucket Server account personal access token with read permissions.

    8. Admin access token: Enter your Bitbucket Server account personal access token with admin permissions on projects and repositories.

    9. Under Network type, select one of the following options:

      1. Public internet: Select this option if your instance is accessible using the public internet.

      2. Private network: Select this option if your instance is hosted on a private network.

        1. Project: Select your Google Cloud project ID.

        2. Network: Select your network from the drop-down menu. If you have not created a network, see Create and manage VPC networks to learn how to create a network.

        3. IP range: Enter the internal IP range that VMs can be assigned within a peered network's allocated range.

          You can specify the range using the Classless Inter-Domain Routing (CIDR) routing notation in the format STARTING_IP/SUBNET_PREFIX_SIZE. For example, 192.0.2.0/24 has a prefix length of 24. The first 24 bits of the IP range are used as the subnet mask (192.0.2.0) while the possible hosts addresses range from 192.0.2.0 to 192.0.2.255.

          The value of your prefix length must not exceed /29. If no value is specified for the range, a default value of /24 is automatically assigned. If no value is specified for the prefix length, IP addresses are automatically assigned within the peered VPC network. If no value is specified for the IP address, the IP address is automatically assigned a range within the peered VPC network.

  5. Click Connect Host.

    If your Bitbucket Server 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 Server 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=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 \
    --peered-network-ip-range=PEERED_NETWORK_IP_RANGE \
    --ssl-ca-file=SSL_CA_FILE

Where:

  • CONFIG_NAME is the name of your Bitbucket Server configuration.
  • USERNAME is your Bitbucket Server username.
  • HOST_URI is the host URI of your Bitbucket Server 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 Server instances on-premises. To learn more, see Build repositories from Bitbucket Server in a private network.

  • Optional: PEERED_NETWORK_IP_RANGE is the internal IP range that VMs can be assigned to within a peered network's allocated range.

  • SSL_CA_FILE is the path to a local file that contains your SSL certificate to use for requests to Bitbucket Server. The certificate should be in PEM format.

API

To connect your Bitbucket Server 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",
    "peeredNetworkIpRange": "PEERED_NETWORK_IP_RANGE",
    "sslCa": "SSL_CERTIFICATE"
}

Where:

  • HOST_URI is the host URI of your Bitbucket Server instance.
  • USERNAME is your Bitbucket Server 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 Secret Accessor role to your Cloud Build service agent, 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 webhook secret stored in Secret Manager.

  • Optional: PEERED_NETWORK is the VPC network to peer to for your Bitbucket Server instances on-premises.

    You can specify the range using the Classless Inter-Domain Routing (CIDR) routing notation in the format STARTING_IP/SUBNET_PREFIX_SIZE. For example, 192.0.2.0/24 has a prefix length of 24. The first 24 bits of the IP range are used as the subnet mask (192.0.2.0) while the possible hosts addresses range from 192.0.2.0 to 192.0.2.225.

  • Optional: PEERED_NETWORK_IP_RANGE is the internal IP range that VMs can be assigned to within a peered network's allocated range.

  • Optional: SSL_CERTIFICATE is the SSL certificate used for your Bitbucket Server 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/REGION/bitbucketServerConfigs/?bitbucketServerConfigId=CONFIG_NAME -d @config.json

Where:

  • PROJECT_ID is your Google Cloud project ID.
  • REGION is the region associated with your Bitbucket Server configuration.
  • CONFIG_NAME is the name of your Bitbucket Server 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/REGION/operations/OPERATION_ID

Where:

  • PROJECT_NUMBER is your Google Cloud project number.
  • PROJECT_ID is your Google Cloud project ID.
  • REGION is the region associated with your Bitbucket Server configuration.
  • OPERATION_ID is the ID of your Bitbucket Server 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 Server configuration is created successfully, you can see the configuration in the response.value field. Otherwise, see the error field for a detailed error report.

What's next