Magento 2.0.18 is the final 2.0.x release. After March 2018, Magento 2.0.x will no longer receive security patches, quality fixes, or documentation updates.
To maintain your site's performance, security, and PCI compliance, upgrade to the latest version of Magento.

Bitbucket integration

Use the Bitbucket integration to automatically build and deploy an environment when you push new code to Bitbucket. This integration synchronizes your Bitbucket repository with your Magento Commerce Cloud account.

For Pro projects created before October 23, 2017, this integration works on Integration environments only. You must request an upgrade before you can use this integration on Staging and Production environments.

We strongly recommend using a private Bitbucket repository for your Magento Commerce Cloud project.

Before you begin

  • You must have a Magento Commerce Cloud project and you must be an administrator of the project.
  • You must have a Bitbucket account and administrative access to the Bitbucket repository you want to integrate.
  • You must install the magento-cloud CLI tool in your local environment.

Prepare your repository

This section shows you how to clone your Magento Commerce Cloud project from and existing environment and add that code to a new, empty Bitbucket repository. If you don’t already have an empty Bitbucket repository, create one before proceeding.

  1. Open a terminal and log in to your Magento Commerce Cloud project:

    magento-cloud login
  2. List your projects. With the project ID, you can complete additional commands:

    magento-cloud project:list
  3. Clone a project to your local environment:

    magento-cloud project:get <project ID>
  4. Add your Bitbucket repository as a remote. Replace <user-name>/<repo-name> with your Bitbucket information.

    git remote add origin<user-name>/<repo-name>.git
  5. Delete the default magento remote.

    git remote remove magento
  6. Verify that you added the Bitbucket remote correctly:

    git remote -v show

    You should see the following:

    origin<user-name>/<repo-name>.git (fetch)
    origin<user-name>/<repo-name>.git (push)
  7. Push files to your new Bitbucket repository:

    git push -u origin master
  8. Verify that your Bitbucket repository contains all of your project files.

Create an OAuth consumer

The Bitbucket integration requires an OAuth consumer. This section shows you how to create one in Bitbucket. You’ll need the OAuth key and secret from this consumer to complete the next section.

  1. Log in to your Bitbucket account.
  2. Click Settings > Access Management > OAuth.
  3. Click Add consumer and configure it as follows:

    Bitbucket OAuth consumer configuration

    A valid Callback URL isn’t required, but you must enter a value in this field to successfully complete the integration.

  4. Click Save.
  5. Click the consumer Name to reveal your OAuth key and secret.
  6. Copy your OAuth key and secret. You’ll need it to complete the next section.

Configure the integration

  1. Open a terminal and navigate to your local Magento Commerce Cloud project directory.
  2. Create a temporary new file called bitbucket.json and add the following:

      "type": "bitbucket",
      "repository": "bitbucket-user-name/bitbucket-repo-name",
      "app_credentials": {
        "key": "YOUR OAUTH CONSUMER KEY",
        "secret": "YOUR OAUTH CONSUMER SECRET"
      "prune_branches": true,
      "fetch_branches": true,
      "build_pull_requests": true,
      "resync_pull_requests": true

    Replace the following values with your information:

    • bitbucket-user-name/bitbucket-repo-name

    Be sure to use the name of your Bitbucket repository and not the URL. The integration will fail if you use the URL.

  3. Add the integration to your project using the magento-cloud CLI tool. Replace PROJECT ID with your Magento Commerce Cloud project ID.

    Running the following command overwrites all code in your Magento Commerce Cloud project with code from your Bitbucket repository. This includes all branches, including the master (production) branch. This action happens instantly and cannot be undone.

    magento-cloud project:curl -p 'PROJECT ID' /integrations -i -X POST -d "$(< bitbucket.json)"

    This command returns a long HTTP response, including headers. The first line of the output should contain a 200 or 201 status code indicating successful integration. A status of 400 or above indicates that an error occurred.

  4. Delete the temporary bitbucket.json file.

    rm bitbucket.json
  5. Your Magento Commerce Cloud project, including all branches, is now synchronized with your Bitbucket repository. List the project’s integration with the following command:

    magento-cloud integrations -p 'PROJECT ID'

Verify that it works

After configuring the Bitbucket integration, test it by pushing a simple change to your Bitbucket repository.

  1. Create a test file:

  2. Commit and push it to your Bitbucket repository:

    git add . && git commit -m "Testing Bitbucket integration" && git push
  3. Log in to the Project Web Interface and verify that your commit message is displayed and your project is being deployed.

    Testing the Bitbucket integration


The Bitbucket integration cannot create new environments in your project, so you must use the magento-cloud CLI tool to create branches.

After creating a new environment, you can push the corresponding branch up to your remote Bitbucket repository using regular git commands. For example, git push -u origin <your-branch>. Subsequent changes to your branch in Bitbucket will automatically build and deploy the environment.

Remove the integration

You can safely remove the Bitbucket integration from your project without affecting your code.

To remove the integration using the magento-cloud CLI tool:

  1. Log in to your project.

    magento-cloud login
  2. List your integrations. You need the Bitbucket integration ID to complete the next step.

    magento-cloud integration:list
  3. Delete the integration.

    magento-cloud integration:delete <ID>

You can also remove the Bitbucket integration by logging in to your Bitbucket account and revoking the OAuth grant on the Settings page.