There are two options for setting up Bitbucket integrations with Bitbucket add-on

The Bitbucket add-on allows you to manage your environments directly from your Bitbucket repository.


  • Create a new environment when creating a branch or opening a pull request on Bitbucket.
  • Rebuild the environment when pushing new code to Bitbucket.
  • Delete the environment when merging a pull request.

Install the add-on

On your Bitbucket account, click on your avatar and select App Marketplace. Filter the list of available add-ons for the "Deployment" category. Add the add-on titled " PHP PaaS" and grant its access to the account.

Bitbucket add-on


  • The Bitbucket Integration can only be connected by the account owner.
  • recommends you install the add-on at the team level (select Manage Team instead) so that every repository that belongs to the team can use the add-on.
  • If you have created your account using the bitbucket oAuth Login in order to use the Platform CLI you will need to setup a password which you can do by visiting this page

Setup the integration

To connect your Bitbucket repository to, go to the repository page as an administrator and click on the Settings icon. Then click integration under the PLATFORM.SH section.

The add-on will give you two options when you grant access to the repository:

  1. Create a new project: this will allow you to choose a region and create a project for the repository.
  2. Connect to an existing project (bottom of the page): this will allow you to connect the repository to a pre-initialized empty project on

Setting up an OAuth consumer

If that add-on does not configure the integration automatically, you can also do so manually by creating an OAuth consumer for your account.

On Bitbucket

  1. Go to your user account and click "Settings".
  2. Under "ACCESS MANAGEMENT" click OAuth.
  3. At the bottom of that page under "OAuth consumers", click the "Add consumer" button.
  4. Fill out the information for the consumer. In order for OAuth2 to work correctly, it's recommended that you include:
    • Name: Give the consumer a recognizable name, like consumer or integration.
    • Callback URL: The URL users will be redirected to after access authorization. It is sufficient to set this value to http://localhost.
    • Set as a private consumer: At the bottom of the "Details" section, select the "This is a private consumer" checkbox.
    • Permissions: Sets the integration permissions for These permissions will create the webhooks that will enable to mirror actions from the Bitbucket repository.
      • Account - Email, Read
      • Repositories - Read, Write
      • Pull requests - Read
      • Webhooks - Read and write
  5. After you have completed the form, Save the consumer.
  6. After you have saved, you will see consumer listed in the "OAuth consumers" section. If you open that item, it will expose two variables that you will need to complete the integration using the CLI: Key and Secret.


Install the CLI if you have not already done so.

Retrieve a PROJECT_ID for an existing project with platform project:list or create a new project with platform project:create.

Then run the integration command:

platform integration:add --type=bitbucket --project <PLATFORMSH_PROJECT_ID> --key <CONSUMER_KEY> --secret <CONSUMER_SECRET> --repository <USER>/<REPOSITORY>


  • PLATFORMSH_PROJECT_ID is the project ID for your project.
  • CONSUMER_KEY is the Key variable of the consumer you created.
  • CONSUMER_SECRET is the Secret variable of the consumer you created.
  • USER/REPOSITORY is the location of the repository.

Validate the integration

In both cases, you can verify that your integration is functioning properly using the CLI command

$ platform integration:validate

Optional parameters

By default several parameters will be set for the Bitbucket integration. They can be changed using the platform integration:update command.

  • --fetch-branches: Track and deploy branches (true by default)
  • --prune-branches: Delete branches that do not exist in the remote Bitbucket repository (true by default)
  • --build-pull-requests: Track and deploy pull-requests (true by default)
  • --build-pull-requests-post-merge: false to have build the branch specified in a PR. true to build the result of merging the PR. (false by default)
  • --pull-requests-clone-parent-data: Set to false to disable cloning of parent environment data when creating a PR environment, so each PR environment starts with no data. (true by default)

For more information see:

platform help integration:update


The --prune-branches option depends on --fetch-branches being enabled. If --fetch-branches is disabled, --prune-branches will automatically be set to false, even if specifically set to true.