Create an OAuth consumer

The Bitbucket integration requires an OAuth consumer. You need the OAuth key and secret from this consumer to complete the next section.

To create an OAuth consumer in Bitbucket:

  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

    WARNING
    A valid Callback URL is not 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 for configuring the integration.

Configure the integration

  1. From the terminal, navigate to your Adobe Commerce on cloud infrastructure project.

  2. Create a temporary file called bitbucket.json and add the following, replacing the variables in angle brackets with your values:

    {
      "type": "bitbucket",
      "repository": "<bitbucket-user-name/bitbucket-repo-name>",
      "app_credentials": {
        "key": "<oauth-consumer-key>",
        "secret": "<oauth-consumer-secret>"
      },
      "prune_branches": true,
      "fetch_branches": true,
      "build_pull_requests": true,
      "resync_pull_requests": true
    }
    
    TIP
    Be sure to use the name of your Bitbucket repository and not the URL. The integration fails if you use a URL.
  3. Add the integration to your project using the magento-cloud CLI tool.

    WARNING
    The following command overwrites all code in your Adobe Commerce on cloud infrastructure project with code from your Bitbucket repository. This includes all branches, including the production branch. This action happens instantly and cannot be undone. As a best practice, it is important to clone all of your branches from your Adobe Commerce on cloud infrastructure project and push them to your Bitbucket repository before adding the Bitbucket integration.
    magento-cloud project:curl -p '<project-ID>' /integrations -i -X POST -d "$(< bitbucket.json)"
    

    This returns a long HTTP response with headers. A successful integration returns a 200 or 201 status code. A status of 400 or above indicates that an error occurred.

  4. Delete the temporary bitbucket.json file.

  5. Verify the project integration.

    magento-cloud integrations -p <project-ID>
    
    +----------+-----------+--------------------------------------------------------------------------------+
    | ID       | Type      | Summary                                                                        |
    +----------+-----------+--------------------------------------------------------------------------------+
    | <int-id> | bitbucket | Repository: bitbucket_Account/magento-int                                      |
    |          |           | Hook URL:                                                                      |
    |          |           | https://magento-url.cloud/api/projects/<project-id>/integrations/<int-id>/hook |
    +----------+-----------+--------------------------------------------------------------------------------+
    

    Make a note of the Hook URL to configure a webhook in BitBucket.

Add a webhook in BitBucket

In order to communicate events—such as a push—with your Cloud Git server, is it necessary to have a webhook for your BitBucket repository. The method of setting up a Bitbucket integration detailed on this page, when followed correctly, automatically creates a webhook. It is important to verify the webhook to avoid creating multiple integrations.

  1. Log in to your Bitbucket account.

  2. Click Repositories and select your project.

  3. Click Repository Settings > Workflow > Webhooks.

  4. Verify the webhook before continuing.

    If the hook is active, skip the remaining steps and Test the integration. The hook should have a name similar to “Adobe Commerce on cloud infrastructure <project_id>” and a hook URL format similar to: https://<zone>.magento.cloud/api/projects/<project_id>/integrations/<id>/hook

  5. Click Add webhook.

  6. In the Add new webhook view, edit the following fields:

    • Title: Adobe Commerce Integration
    • URL: Use the Hook URL from your magento-cloud integration list
    • Triggers: The default is a basic Repository push
  7. Click Save.

Test the integration

After configuring the Bitbucket integration, you can verify that the integration is operational using the magento-cloud CLI:

magento-cloud integration:validate

Or you can test it by pushing a simple change to your Bitbucket repository.

  1. Create a test file.

    touch test.md
    
  2. Commit and push the change to your Bitbucket repository.

    git add . && git commit -m "Testing Bitbucket integration" && git push
    
  3. Log in to the Cloud Console and verify that your commit message is displayed and your project deploying.

    Testing the Bitbucket integration

Create a Cloud branch

The Bitbucket integration cannot activate new environments in your Adobe Commerce on cloud infrastructure project. If you create an environment with Bitbucket, you must activate the environment manually. To avoid this extra step, it is best practice to create environments using the magento-cloud CLI tool or the Cloud Console.

To activate a branch created with Bitbucket:

  1. Use the magento-cloud CLI to push the branch.

    magento-cloud environment:push from-bitbucket
    
    Pushing from-bitbucket to the new environment from-bitbucket
    Activate from-bitbucket after pushing? [Y/n] y
    Parent environment [master]: integration
    --- (Validation and activation messages)
    
  2. Verify that the environment is active.

    magento-cloud environment:list
    
    Your environments are:
    +---------------------+----------------+--------+
    | ID                  | Name           | Status |
    +---------------------+----------------+--------+
    | master              | Master         | Active |
    |  integration        | integration    | Active |
    |    from-bitbucket * | from-bitbucket | Active |
    +---------------------+----------------+--------+
    * - Indicates the current environment
    

After you create an environment, you can push the corresponding branch to your remote Bitbucket repository using regular Git commands. Subsequent changes to your branch in Bitbucket 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 Bitbucket integration:

  1. From the terminal, log in to your Adobe Commerce on cloud infrastructure project.

  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 <int-ID>
    

Also, you can remove the Bitbucket integration by logging in to your Bitbucket account and revoking the OAuth grant on the account Settings page.

Bitbucket server integration

To use the Bitbucket server integration, you need the following:

Though you can use the Cloud CLI to walk through the Bitbucket server integration steps, the full command looks similar to the following:

magento-cloud integration:add --type=bitbucket_server --base-url=<bitbucket-url> --username=<username> --token=<bitbucket-access-token> --project=<project-ID>

Use the help command for more usage requirements and options: magento-cloud integration:add --help

Commerce