Connect to a Bitbucket Server host

This page explains how to connect to a Bitbucket Server host to Cloud Build.

Before you begin

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

If you have not installed a Bitbucket Server instance, see Bitbucket Server installation guide for instructions.

Setting up

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

Obtaining an API key

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

To obtain an API key:

Open the Credentials page in the Google Cloud console:

Open the Credentials page
Click Create credentials.
Click API Key.

You will see a dialog with your API key created. Take note of your API key.
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.

Required IAM permissions

To connect your Bitbucket Server host, grant the Cloud Build Editor (roles/cloudbuild.builds.editor) role and the Cloud Build Integrations Owner (cloudbuild.integrations.owner) role to your user account.

To add the required roles to your user account, see Configuring access to Cloud Build resources. To learn more about IAM roles associated with Cloud Build, see IAM roles and permissions.

Creating personal access tokens

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

Create webhooks: create a personal access token with admin access.
Retrieve repository data: create a personal access token with read access. You can optionally create a token that has both read and write access.

These personal access tokens are the minimum permissions required. You may need to configure additional permissions in Bitbucket Server as needed. For example, you may select Bitbucket Server account to have access only to a subset of the repositories on your Bitbucket Server 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 to connect to your Bitbucket Server repository.

Connecting to a Bitbucket Server host

Console

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

Open the Manage repositories page in the Google Cloud console:

Open the Manage repositories page
Click Connect Host.

You will see the Connect host panel.

Enter the following information to connect your Bitbucket Server instance to Cloud Build:
- Host url: The host URL of your Bitbucket Server instance. For example, https://bbs.example-test.com:7990.
- Google Cloud API key: The API key used to authenticate your credentials.
- [OPTIONAL] 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 will be used in place.
  
  Note: By default, Google only trusts a set of publicly trusted certificate authorities. If you want to change the certificate authorities to trust or if your certificate is self-signed, you can provide your own set of certificates to trust.
- Username: Your Bitbucket Server account username. This account should have admin access to the repositories that you want to connect with Cloud Build.
- Read access token: Your Bitbucket Server account personal access token with read permissions.
- Admin access token: Your Bitbucket Server 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.
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=BITBUCKET_SERVER_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_SERVER_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.
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",
      "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 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.

Note: The expected format for the resource name for your secret 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.
[Optional] PEERED_NETWORK is the VPC network to peer to for your Bitbucket Server instances on-premises.
[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"  -H "x-goog-user-project: PROJECT_NUMBER" https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/bitbucketServerConfigs/?bitbucketServerConfigId=BITBUCKET_SERVER_CONFIG_NAME -d @config.json

Where:

PROJECT_NUMBER is your Cloud project number.
PROJECT_ID is your Cloud project ID.
REGION is the region associated with your Bitbucket Server configuration.
BITBUCKET_SERVER_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 Cloud project number.
PROJECT_ID is your 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

Learn how to connect a Bitbucket Server repository.