Platform.sh User Documentation

Integrate with Bitbucket

Upsun Beta

Access our newest offering - Upsun!

Get your free trial by clicking the link below.

Get your Upsun free trial

If you have code in a Bitbucket repository, you might want to connect it to a Platform.sh project. This means you can keep your Bitbucket workflows and treat the Bitbucket repository as the source of truth for your code.

Your Platform.sh project becomes a mirror of your Bitbucket repository. This means you shouldn’t push code directly to Platform.sh. Any changes you push directly get overwritten by the integration when changes happen in the Bitbucket repository.

When you set up an integration with Bitbucket, it automates the following processes for you:

  • Creating a new environment when a branch is created or a pull request is opened.
  • Rebuilding the environment when new code is pushed to Bitbucket.
  • Deleting the environment when a pull request is merged.

You can set up an integration with either Bitbucket Cloud or a self-hosted Bitbucket Server.

Before you begin Anchor to this heading

To manage source integrations, you need to be a project admin.

You also need a Bitbucket Cloud or Bitbucket Server repository with working code.

Bitbucket Cloud Anchor to this heading

1. Create an OAuth consumer Anchor to this heading

To integrate your Platform.sh project with an existing Bitbucket Cloud repository, create an OAuth consumer:

A screenshot of how to setup the Bitbucket OAuth consumer

The Callback URL isn’t important in this case. You can set it to http://localhost.

Copy the Key and Secret for your consumer.

2. Enable the Cloud integration Anchor to this heading

To enable the integration, use either the CLI or the Console.

Run the following command:

platform integration:add \
  --project PROJECT_ID \
  --type bitbucket \
  --repository OWNER/REPOSITORY \
  --key CONSUMER_KEY \
  --secret CONSUMER_SECRET

For example, if your repository is located at https://bitbucket.org/platformsh/platformsh-docs, the command is similar to the following:

platform integration:add \
  --project abcdefgh1234567 \
  --type bitbucket \
  --repository platformsh/platformsh-docs \
  --key abc123 \
  --secret abcd1234 \
  1. Select the project where you want to enable the integration.
  2. Click Settings.
  3. Under Project settings, click Integrations.
  4. Click + Add integration.
  5. Under Bitbucket, click + Add.
  6. Complete the form with:
  7. Check that the other options match what you want.
  8. Click Add integration.

In both the CLI and Console, you can choose from the following options:

CLI flag Default Description
fetch-branches true Whether to track all branches and create inactive environments from them.
prune-branches true Whether to delete branches from Platform.sh that don’t exist in the Bitbucket repository. Automatically disabled when fetching branches is disabled.
build-pull-requests true Whether to track all pull requests and create active environments from them, which builds the pull request.
resync-pull-requests false Whether to sync data from the parent environment on every push to a pull request.

To keep your repository clean and avoid performance issues, make sure you enable both the fetch-branches and prune-branches options.

3. Validate the integration Anchor to this heading

Verify that your integration is functioning properly using the CLI:

platform integration:validate

Add the webhook manually Anchor to this heading

If the integration was added with the correct permissions, the necessary webhook is added automatically. If you see a message that the webhook wasn’t added, add one manually.

To configure a webhook on a Bitbucket repository, you need to have Admin user permissions.

  1. Get the webhook URL by running this command: platform integration:get --property hook_url.

  2. Copy the returned URL.

  3. Follow the Bitbucket instructions to create a webhook using the URL you copied. Make sure to update the triggers to include all pull request events except comments and approval.

You can now start pushing code, creating new branches, and opening pull requests directly in your Bitbucket repository. Your Platform.sh environments are automatically created and updated.

Bitbucket Server Anchor to this heading

1. Generate a token Anchor to this heading

To integrate your Platform.sh project with a repository on a Bitbucket Server instance, you first need to create an access token associated with your account.

Generate a token. and give it at least read access to projects and admin access to repositories. Copy the token.

2. Enable the Server integration Anchor to this heading

To enable the integration, use either the CLI or the Console.

Run the following command:

platform integration:add \
  --project PROJECT_ID \
  --type bitbucket_server \
  --repository OWNER/REPOSITORY \
  --username BITBUCKET_USERNAME \
  --token BITBUCKET_SERVER_ACCESS_TOKEN \
  --base-url BITBUCKET_SERVER_URL 
  • PROJECT_ID is the ID of your Platform.sh project.
  • OWNER/REPOSITORY is the name of the repository in Bitbucket server.
  • BITBUCKET_SERVER_ACCESS_TOKEN is the token you generated.
  • BITBUCKET_SERVER_URL is the base URL for your Bitbucket server.

For example, if your repository is located at https://example.com/platformsh/platformsh-docs, the command is similar to the following:

platform integration:add \
  --project abcdefgh1234567 \
  --type bitbucket_server \
  --repository platformsh/platformsh-docs \
  --username user@example.com \
  --token abc123 
  1. Select the project where you want to enable the integration.

  2. Click Settings.

  3. Under Project settings, click Integrations.

  4. Click + Add integration.

  5. Under Bitbucket server, click + Add.

  6. Complete the form with:

    • Your server URL
    • Your Bitbucket username
    • The token you generated
    • The Bitbucket server project name
    • The repository in the form owner/repository
  7. Check that the other options match what you want.

  8. Click Add integration.

In both the CLI and Console, you can choose from the following options:

CLI flag Default Description
fetch-branches true Whether to track all branches and create inactive environments from them.
prune-branches true Whether to delete branches from Platform.sh that don’t exist in the Bitbucket server repository. Automatically disabled when fetching branches is disabled.
build-pull-requests true Whether to track all pull requests and create active environments from them, which builds the pull request.
pull-requests-clone-parent-data true Whether to clone data from the parent environment when creating a pull request environment.

To keep your repository clean and avoid performance issues, make sure you enable both the fetch-branches and prune-branches options.

3. Validate the integration Anchor to this heading

Verify that your integration is functioning properly using the CLI:

platform integration:validate

Add the webhook manually Anchor to this heading

If the integration was added with the correct permissions, the necessary webhook is added automatically. If you see a message that the webhook wasn’t added, add one manually.

To configure a webhook on a Bitbucket repository, you need to have Admin user permissions.

  1. Get the webhook URL by running this command: platform integration:get --property hook_url.

  2. Copy the returned URL.

  3. Follow the Bitbucket instructions to create a webhook using the URL you copied. Send all events except comments and approval.

You can now start pushing code, creating new branches, and opening pull requests directly in your Bitbucket repository. Your Platform.sh environments are automatically created and updated.

Environment parent and status Anchor to this heading

When a branch is created in Bitbucket, an environment is created in Platform.sh with the default branch as its parent. It starts as an inactive environment with no data or services.

When a pull request is opened in Bitbucket, an environment is created in Platform.sh with the pull request’s target branch as its parent. It starts as an active environment with a copy of its parent’s data.

Source of truth Anchor to this heading

When you add an integration, your Bitbucket repository is considered to be the source of truth for the project. Your Platform.sh project is only a mirror of that repository and you should only push commits to Bitbucket. Any changes you push to Platform.sh get overwritten by the integration when changes happen in your Bitbucket repository.

To clone your code, follow these steps:

Run the following command:

platform get PROJECT_ID
  1. In the Console, open the project you want to clone.
  2. Click Code.
  3. Click Git.
  4. Run the command you find using Git.

When you do this, you're cloning from your integrated Bitbucket repository, if you have the appropriate access to do so.

Pull request URLs Anchor to this heading

When a pull request is deployed, the integration reports the primary URL for the deployed environment. So you get a link to the deployed environment right in the pull request.

If you have multiple routes, ensure the correct one is reported by specifying the primary route.

Is this page helpful?