Building repositories from Bitbucket Server

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

Before you begin

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

  • To use gcloud commands on this page, install the Cloud SDK.

Setting up

Before creating a webhook trigger to build on Bitbucket Server, you will need to create an SSH key in order to authenticate your connection to Bitbucket Server. When you create a trigger without an associated repository and access your code on an external source code management system, such as Bitbucket Server, you'll need to retrieve your SSH key in your inline build configuration.

This section discusses how you can both create and store your SSH key prior to creating a webhook trigger.

Creating an SSH key

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 Server SSH key, where BITBUCKET_SERVER_HOST/REPOSITORY is the URL for your Bitbucket Server repository:

    ssh-keygen -t rsa -b 4096 -N '' -C BITBUCKET_SERVER_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 use SSH with Bitbucket Server, refer to 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} 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


To create a webhook trigger that 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: Use the webhook URL 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.

        If you use an existing secret, you may need to manually grant the Secret Manager Secret Accessor role to your Cloud Build service account, ${PROJECT_NUMBER} To learn more, see Granting Secret Manager role to your service account.

      After you have created or selected your secret, you will see a Webhook URL preview. Your URL will contain an API key generated by Cloud Build and your secret. If Cloud Build is unable to retrieve your API key, you can manually add your API key to the URL or learn how to obtain an API key if you do not have one yet.

      You can use the URL to invoke a webhook event by making an HTTP request using the POST method.

       curl -X POST -H "application/json" "${PROJECT_NAME}/triggers/${TRIGGER_NAME}:webhook?key=${API_KEY}&secret=${SECRET_VALUE}" -d "{}"

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

    • Source (optional): The repository to build when the webhook trigger runs. Leave this field blank. In this example, the build configuration is an inline build config so a source is not needed.

    • 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.

      # 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:
          - '-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
          - SSHKEY
          - name: ssh
            path: /root/.ssh
      # second, clone the repository
      - name:
          - clone
          - '-n'
          - .
          - name: ssh
            path: /root/.ssh
      # third, checkout the specific commit that invoked this build
      - name:
          - checkout
          - $_TO_SHA
        - versionName: PATH_TO_SECRET_VERSION
          env: SSHKEY


      • 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_VERSION is the path to your secret version as stored in Secret Manager. This is the secret that contains your SSH key. For example, projects/project-id/secrets/secret-name/versions/1
      • 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, let's say you want to watch for a specific branch name associated with a commit ID and then switch to that branch name in the build definition. To obtain this data, you can create substitution variables using payload bindings to save the branch name.

      Specify the following variables and values below:

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

      To view the payload associated with Bitbucket Server events, see Event payload.

    • 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 you want the trigger to execute a build if the branch name matches main, you 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.


To create a webhook trigger that builds from Bitbucket Server, 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 \
         _BRANCH='$(body.changes[0].refId)', TO_SHA='$(body.changes[0].refId)'
       --filter='_BRANCH == refs/heads/main'


  • TRIGGER_NAME is the name of your trigger.
  • PATH_TO_REPO is the path to the repository to invoke a build on. For example,
  • 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.

  • 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.

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