Building repositories hosted on Bitbucket Server

Preview

This feature is covered by the Pre-GA Offerings Terms of the Google Cloud Platform Terms of Service. Pre-GA features may have limited support, and changes to pre-GA features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

This page explains how you can invoke builds on Bitbucket Server by using webhook triggers.

Before you begin

• Enable the Cloud Build and Secret Manager APIs.

  Enable the APIs

• Install the gcloud command-line tool.

Setting up

Before creating a webhook trigger to invoke builds on Bitbucket Server, you will need to set up an API key in order to authenticate and accept incoming webhook events. When you create a trigger without an associated repository and access your code on an external SCM, such as Bitbucket Server, you'll also need to retrieve an SSH key in your inline build configuration.

This section discusses how you can both obtain and store necessary credentials prior to creating a webhook trigger.

Obtaining an API key

You will need an API key to authenticate your incoming webhook event.

To obtain an API key:

1. Open the Credentials page in the Cloud Console:

   Open the Credentials page

2. Click Create credentials.

3. Click API Key.

   You will see a pop-up box with your API key created. You can use this key by passing key=API_KEY into your application as described below.

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

Creating an SSH key

In order to access your code on Bitbucket Server, you'll need to retrieve an SSH key in your inline build config.

To create an SSH key:

1. Open a terminal window.

2. Create a new directory named working-dir and navigate into it:

   mkdir working-dir
   cd working-dir
   

3. Create a new Bitbucket SSH key, where BITBUCKET_HOST/REPOSITORY is the URL for your Bitbucket repository:

   ssh-keygen -t rsa -b 4096 -N '' -C BITBUCKET_HOST/REPOSITORY -f id_bitbucket
   

   The command creates a new SSH key in working-dir/id_bitbucket without a passphrase for your SSH key. Cloud Build cannot use your SSH key if it is protected with a passphrase.

Enabling SSH access on Bitbucket Server

You will need to enable SSH access on your Bitbucket Server to allow users on your server to add their own SSH keys and use those SSH keys to secure Git operations between their computer and the Bitbucket Server instance. To learn how to enable SSH access on your Bitbucket Server, refer to the Bitbucket page on Enabling SSH access to Git repositories in Bitbucket Server.

Adding your public SSH access key on Bitbucket Server

In order to secure operations that other systems perform on your repositories managed in Bitbucket Server, you will need to add your public SSH access key on Bitbucket Server and grant your key Read permissions. To learn how to add your key, see SSH access keys for system use.

Creating and storing your credentials in Secret Manager

When you create an SSH key, an id_bitbucket file is created in your local environment. Since this file contains sensitive information associated with authentication, you must store the file in Secret Manager before using it to invoke a build.

In addition to the secret used when creating a webhook trigger, you will also need to create a secret in Secret Manager to validate and authorize incoming webhook events to Cloud Build.

To create and store your credentials in Secret Manager:

1. Go to the Secret Manager page in the Cloud Console:

   Go to the Secret Manager page

2. On the Secret Manager page, click Create Secret.

3. On the Create secret page, under Name, enter a name for your secret.

4. In the Secret value field, enter a name for your secret or upload a file.

   To upload your SSH key file, click Upload to include your working-dir/id_bitbucket file.

5. Leave the Regions section unchanged.

6. Click the Create secret button to create your secret.

After you create your secret, Google Cloud Console will automatically grant the Secret Manager Secret Accessor role to your Cloud Build service account, ${PROJECT_NUMBER}@gcp-sa-cloudbuild.iam.gserviceaccount.com. If you do not see this role on your service account, complete the following steps outlined in Granting Secret Manager role to your service account.

Now that you have stored your SSH key, you can also delete the SSH key from your environment by running the following command:

rm id_bitbucket*

You are now ready to create your webhook trigger.

Creating webhook triggers

Console

To create a webhook trigger that invokes builds from Bitbucket Server using the Google Cloud Console:

1. Open the Triggers page:

   Open the Build 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.
   • Description (Optional): A description for your trigger.
   • Event: Select Webhook event to set up your trigger to start builds in response to incoming webhook events.

   • Webhook URL: After entering your credentials, use the webhook URL generated below and the API key you initially set up to authenticate incoming webhook events.

     • Secret: You will need a secret to authenticate incoming webhook events. You can create a new secret or use an existing secret.

       To create a new secret:

       1. Select Create New.

       2. Click Create Secret.

          You will see the Create a webhook secret pop-up box.

       3. In the Secret name field, enter a name for your secret.

       4. Click Create secret to save your secret, which will automatically be created and stored for you in Secret Manager.

       To use an existing secret:

       1. Select Use existing.
       2. In the Secret field, select the name of the secret you want to use from the drop-down menu or follow the instructions to add a secret by resource ID.
       3. In the Secret version field, select your secret version from the drop-down menu.

     After you have created or selected your secret, you will see a preview of your webhook URL, which will look similar to the following:

     https://cloudbuild.googleapis.com/v1/projects/${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}
     

     To learn how you can use the URL when creating a webhook in Bitbucket server, see Creating a webhook in Bitbucket Server.

   • Source (optional): Leave this field blank. Since we plan to use an inline build config as our build configuration, we do not need to select a source.

   • Configuration: Create an inline build config in the Google Cloud Console.

     In the following example, the inline build config authenticates your connection to Bitbucket Server using your SSH key and accesses your specified repository. Following that, it checks out the commit that invoked the webhook.

     steps:
     # first, setup SSH:
     # 1- save the SSH key from Secret Manager to a file
     # 2- add the host key to the known_hosts file
     - name: gcr.io/cloud-builders/git
       args:
         - '-c'
         - |
           echo "$$SSHKEY" > /root/.ssh/id_rsa
           chmod 400 /root/.ssh/id_rsa
           ssh-keyscan -p BITBUCKET_PORT BITBUCKET_HOST > /root/.ssh/known_hosts
       entrypoint: bash
       secretEnv:
         - SSHKEY
       volumes:
         - name: ssh
           path: /root/.ssh
     # second, clone the repository
     - name: gcr.io/cloud-builders/git
       args:
         - clone
         - '-n'
         - 'ssh://BITBUCKET_HOST:BITBUCKET_PORT/BITBUCKET_REPO'
         - .
       volumes:
         - name: ssh
           path: /root/.ssh
     # third, checkout the specific commit that invoked this build
     - name: gcr.io/cloud-builders/git
       args:
         - checkout
         - $_TO_SHA
     availableSecrets:
       secretManager:
       - versionName: PATH_TO_SECRET
         env: SSHKEY
     

     Where:

     • BITBUCKET_HOST is the hostname of your Bitbucket repository.
     • BITBUCKET_PORT is the SSH port of your Bitbucket repository (typically 7999).
     • BITBUCKET_REPO is the path for your Bitbucket repo.
     • PATH_TO_SECRET is the path to your secret as stored in Secret Manager.
     • SSHKEY is the name of the environment used in this case to store the path to your secret.

   • Substitutions (optional): You can choose to define trigger-specific substitution variables using this field.

     In this example, we want to watch for a specific branch name associated with a commit ID. To obtain this data, we can create substitution variables using payload bindings.

     Specify the following variables and values below:

     Variable Name	Variable Value
     _BRANCH	$(body.changes[0].refId)
     _TO_SHA	$(body.changes[0].toHash)

   • Filters (optional): You can create a rule within a trigger that determines whether or not your trigger will execute a build based on your substitution variables.

     Since we want the trigger to execute a build if the branch name matches main, we can use the "==" operator to check for exact matches. You can also use the "matches" keyword if you want to match by regular expression.

     Specify the following as your filters:

     • _BRANCH == refs/heads/main

     To see more example syntax for filtering you could apply to your webhook triggers, see Using CEL to filter build events.

5. Click Create to create your build trigger.

gcloud

To create a webhook trigger that invokes builds from Bitbucket Server, you will need to run the gcloud alpha command. In the example below, the trigger is configured to respond to builds with a branch matching refs/heads/main based on the specified payload as defined by the substitution variable, _BRANCH.

     gcloud alpha builds triggers create webhook \
       --name=TRIGGER_NAME \
       --repo=PATH_TO_REPO \
       --secret=PATH_TO_SECRET \
       --subtitutions=\
         _BRANCH='$(body.changes[0].refId)', TO_SHA='$(body.changes[0].refId)'
       --filter='_BRANCH == refs/heads/main'
       --inline-config=PATH_TO_INLINE_BUILD_CONFIG
       --branch=BRANCH_NAME

Where:

• TRIGGER_NAME is the name of your trigger.
• PATH_TO_REPO is the path to the repository to invoke a build on. For example, https://www.github.com/owner/repo.
• PATH_TO_SECRET is the path to your secret as stored in Secret Manager. For example, projects/my-project/secrets/my-secret/versions/2.

• PATH_TO_INLINE_BUILD_CONFIG is the path to your inline build config.

  Note: Although the build config is stored inline on the trigger you're creating, the config path here is pulled from a local file.

• BRANCH_NAME is the name of your branch if you want to set your trigger to build on a branch.

Creating a webhook in Bitbucket Server

In order for Bitbucket Server to make requests to Cloud Build, you will need to create a webhook in Bitbucket Server by following the instructions outlined in Creating webhooks.

Note: Your webhook in Bitbucket Server must be active in order to communicate with Cloud Build.

Now, each time updates to your repository match the trigger event you specified in your webhook, a build will automatically be invoked by Cloud Build webhook triggers.

What's next

• Learn how to create webhook triggers
• Learn how to create and manage triggers.
• Learn how to start builds manually.
• Learn how to view build results.