Connect to a Bitbucket Data Center host

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

Before you begin

Enable the Cloud Build and Secret Manager APIs.
Enable the APIs

Have your source code ready in a Bitbucket Data Center repository.
Have either a Dockerfile or a Cloud Build config file in your Bitbucket Data Center source repository.
If you have not installed a Bitbucket Data Center instance, see Install Bitbucket Data Center for instructions.
To use gcloud commands on this page, install the Google Cloud CLI.

Note: If you've installed gcloud CLI previously, make sure you have the latest available version by running gcloud components update.

Required IAM permissions

To get the permissions that you need to connect your Bitbucket Data Center host, ask your administrator to grant you the Cloud Build Connection Admin (roles/cloudbuild.connectionAdmin) IAM role on user account. For more information about granting roles, see Manage access.

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

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

Connect to a Bitbucket Data Center host

Before creating a host connection for your Bitbucket Data Center instance, you must create personal access tokens in Bitbucket Data Center by completing the following steps:

Sign in to your Bitbucket Data Center instance.
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.
Note: In addition to access tokens for your user account, you can also use access tokens for projects or repositories. See Create HTTP access tokens for projects or repositories.

Console

To connect your Bitbucket Data Center host to Cloud Build:

Open the Repositories page in the Google Cloud console.

Open the Repositories page

You will see the Repositories page.
At the top of the page, select the 2nd gen tab.
In the project selector in the top bar, select your Google Cloud project.
Click Create host connection to connect a new host to Cloud Build.
On the left panel, select Bitbucket as your source provider.
In the Configure Connection section, enter the following information:
1. Region: Select a region for your connection. You must specify a region. Your connection cannot exist globally.
2. Name: Enter a name for your connection.
In the Host details section, select or enter the following information:
1. Bitbucket host: Select Bitbucket Data Center as your host.
2. Host URL: Enter the URL of your Bitbucket Data Center host.
In the Networking section, 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. CA Certificate: Your self-signed certificate. Click Browse to open the certificate from your local machine.
    
    Your certificate must not exceed 10 KB in size and should be in PEM format (.pem, .cer,or .crt). If you leave this field blank, Cloud Build uses a certificate from the default set of certificates.
  2. In the Service Directory service section, select the location of your service. You can accept the pre-populated project ID or specify a different project.
    1. Select the project of your service. You can accept the pre-populated project, choose In another project to browse, or choose Enter manually.
      
      If you choose enter the following information:
      - Project: Enter or select your Google Cloud project ID from the drop-down menu.
      - Region: This field pre-selects the region of your connection. The region specified for your service must match the region associated with your connection.
    2. Namespace: Select the namespace of your service.
    3. Service: Select the service name in your namespace.
In the HTTP access tokens section, enter the following information:
1. Admin access token: Enter the token with the repository admin scope access. This token is used for connecting and disconnecting repositories.
2. Read access token: Enter the token with the repository read scope access. Cloud Build triggers use this token to access source code in repositories.
Click Connect.

After clicking the Connect button, your personal access tokens are securely stored in Secret Manager. After connecting to the Bitbucket Data Center host, Cloud Build creates a webhook secret on your behalf. You can view and manage your secrets on the Secret Manager page.

gcloud

Store your tokens in Secret Manager.
Create a webhook secret in Secret Manager by running the following command, where WEBHOOK_SECRET is the name you want to give to your webhook secret:
```
  cat /proc/sys/kernel/random/uuid | tr -d '\n' | gcloud secrets create WEBHOOK_SECRET --data-file=-
```

If you store your secrets in a different Google Cloud project than the one you plan to use to create a host connection, run the following command to grant your project access to the Cloud Build service agent:

PN=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT}" \ \
    --role="roles/secretmanager.admin"

Where:

PROJECT_ID is your Google Cloud project ID.

You can now proceed to connect your Bitbucket Data Center host to Cloud Build.

Run the following command to create a Bitbucket Data Center connection:

gcloud builds connections create bitbucket-data-center CONNECTION_NAME \
    --host-uri=HOST_URI \
    --project=PROJECT_ID \
    --region=REGION \
    --authorizer-token-secret-version=projects/PROJECT_ID/secrets/ADMIN_TOKEN/versions/SECRET_VERSION \
    --read-authorizer-token-secret-version=projects/PROJECT_ID/secrets/READ_TOKEN/versions/SECRET_VERSION \
    --webhook-secret-secret-version=projects/PROJECT_ID/secrets/WEBHOOK_SECRET/versions/SECRET_VERSION
 ```

Where:

CONNECTION_NAME is the name of your connection.
HOST_URI is the URI of your Bitbucket Data Center instance.
PROJECT_ID is your Google Cloud project ID.
REGION is the region for your connection.
ADMIN_TOKEN is the name of your token with repository admin scope.
READ_TOKEN is the name of your token with repository read scope.
SECRET_VERSION is the version of your secret.
WEBHOOK_SECRET is your webhook secret.

Terraform

You can connect your Bitbucket Data Center host to Cloud Build using Terraform.

In the following example, the code snippet does the following:

Configures the Terraform Google provider.
Creates a Secret Manager secret to store the Bitbucket tokens.
Grants necessary permissions to the Cloud Build service agent to access secrets.

Creates a Bitbucket Data Center connection.

// Configure the Terraform Google provider
terraform {
  required_providers {
    google = {}
  }
}

provider "google" {
  project = "PROJECT_ID"
  region = "REGION"
}

// Create secrets and grant permissions to the Cloud Build service agent
resource "google_secret_manager_secret" "admin-token-secret" {
    project = "PROJECT_ID"
    secret_id = "ADMIN_TOKEN_NAME"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "admin-token-secret-version" {
    secret = google_secret_manager_secret.admin-token-secret.id
    secret_data = "ADMIN_TOKEN_VALUE"
}

resource "google_secret_manager_secret" "read-token-secret" {
    project = "PROJECT_ID"
    secret_id = "READ_TOKEN_NAME"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "read-token-secret-version" {
    secret = google_secret_manager_secret.read-token-secret.id
    secret_data = "READ_TOKEN_VALUE"
}

resource "google_secret_manager_secret" "webhook-secret-secret" {
    project = "PROJECT_ID"
    secret_id = "WEBHOOK_SECRET_NAME"

    replication {
        auto {}
    }
}

resource "google_secret_manager_secret_version" "webhook-secret-secret-version" {
    secret = google_secret_manager_secret.webhook-secret-secret.id
    secret_data = "WEBHOOK_SECRET_VALUE"
}

data "google_iam_policy" "p4sa-secretAccessor" {
    binding {
        role = "roles/secretmanager.secretAccessor"
        members = ["serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"]
    }
}

resource "google_secret_manager_secret_iam_policy" "policy-pak" {
  project = google_secret_manager_secret.admin-token-secret.project
  secret_id = google_secret_manager_secret.admin-token-secret.secret_id
  policy_data = data.google_iam_policy.p4sa-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-rpak" {
  project = google_secret_manager_secret.read-token-secret.project
  secret_id = google_secret_manager_secret.read-token-secret.secret_id
  policy_data = data.google_iam_policy.p4sa-secretAccessor.policy_data
}

resource "google_secret_manager_secret_iam_policy" "policy-whs" {
  project = google_secret_manager_secret.webhook-secret-secret.project
  secret_id = google_secret_manager_secret.webhook-secret-secret.secret_id
  policy_data = data.google_iam_policy.p4sa-secretAccessor.policy_data
}

// Create the connection resource
resource "google_cloudbuildv2_connection" "my-connection" {
    project = "PROJECT_ID"
    location = "REGION"
    name = "CONNECTION_NAME"

    bitbucket_data_center_config {
        host_uri = "BITBUCKET_URI"
        authorizer_credential {
            user_token_secret_version = google_secret_manager_secret_version.admin-token-secret-version.id
        }
        read_authorizer_credential {
            user_token_secret_version = google_secret_manager_secret_version.read-token-secret-version.id
        }
        webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
    }

    depends_on = [
        google_secret_manager_secret_iam_policy.policy-pak,
        google_secret_manager_secret_iam_policy.policy-rpak,
        google_secret_manager_secret_iam_policy.policy-whs
    ]
}

Where:

PROJECT_ID is your Google Cloud project ID.
PROJECT_NUMBER is your Google Cloud project number.
ADMIN_TOKEN_NAME is the name of your token with repository:admin scope.
ADMIN_TOKEN_VALUE is the value of your ADMIN_TOKEN_NAME.
READ_TOKEN_NAME is the name of your token with repository:read scope.
READ_TOKEN_VALUE is the value of your READ_TOKEN_NAME.
WEBHOOK_SECRET_NAME is the name of your webhook secret.
WEBHOOK_SECRET_VALUE is the value of your WEBHOOK_SECRET_NAME.
REGION is the region for your connection.
CONNECTION_NAME is the name of your connection.
BITBUCKET_URI is the URI of your Bitbucket Data Center instance.

What's next

Learn how to connect a Bitbucket Data Center repository.
Learn how to perform blue/green deployments on Compute Engine.