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.

Open a terminal and log in to your Magento Commerce (Cloud) project:
```
magento-cloud login
```
List your projects. With the project ID, you can complete additional commands:
```
magento-cloud project:list
```
Clone a project to your local environment:
```
magento-cloud project:get <project ID>
```
Add your Bitbucket repository as a remote. Replace <user-name>/<repo-name> with your Bitbucket information.
```
git remote add origin git@bitbucket.org:<user-name>/<repo-name>.git
```
Delete the default magento remote.
```
git remote remove magento
```

Verify that you added the Bitbucket remote correctly:

git remote -v show

You should see the following:

origin git@bitbucket.org:<user-name>/<repo-name>.git (fetch)
origin git@bitbucket.org:<user-name>/<repo-name>.git (push)

Push files to your new Bitbucket repository:
```
git push -u origin master
```
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.

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

A valid Callback URL isn’t required, but you must enter a value in this field to successfully complete the integration.
Click Save.
Click the consumer Name to reveal your OAuth key and secret.
Copy your OAuth key and secret. You’ll need it to complete the next section.

Configure the integration

Open a terminal and navigate to your local Magento Commerce (Cloud) project directory.

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
YOUR OAUTH CONSUMER KEY
YOUR OAUTH CONSUMER SECRET

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

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 successfull integration. A status of 400 or above indicates that an error occurred.
Delete the temporary bitbucket.json file.
```
rm bitbucket.json
```
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.

Create a test file:
```
touch test.md
```

Commit and push it to your Bitbucket repository:

git add . && git commit -m "Testing Bitbucket integration" && git push

Branching

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:

Log in to your project.
```
magento-cloud login
```
List your integrations. You need the Bitbucket integration ID to complete the next step.
```
magento-cloud integration:list
```
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.

Edit this page on GitHub

Give us feedback