Skip to content

Bitbucket Integration Guide

This guide provides step-by-step instructions on how to connect your Bitbucket repository with the AppAmbit Dashboard to enable automated CI/CD workflows.

Prerequisites

Before you begin, ensure you have an existing Bitbucket repository with a configured bitbucket-pipelines.yml file that generates the required build artifacts.

Step 1: Create a Repository Access Token

The AppAmbit Dashboard needs an Access Token to communicate securely with your Bitbucket repository.

  1. Navigate to your Bitbucket repository and click on Repository settings in the left-hand menu. Settings (light) Settings (dark)

  2. Select Access tokens and click the Create access token button. Create access token (light) Create access token (dark)

  3. Configure the token with the following permissions:

    • Name: Give your token a descriptive name (e.g., "AppAmbit Dashboard Delivery").
    • Scopes: Grant the following permissions:
      • Pipelines: Read
      • Webhooks: Read and write
      • Repositories: Read Token permissions (light) Token permissions token (dark)

  4. Click Create.

Save Your Token!

Bitbucket will only show you the token once. Copy it immediately and store it in a secure place. You will need this for Step 3. If you lose it, you must create a new one.

Step 2: Configure the Webhook

The webhook notifies the dashboard whenever a pipeline completes.

  1. In Repository settings, navigate to Webhooks under the "Workflow" section and click Add webhook. Webhook (light) Webhook (dark)

Tip

For a quick start, use Bitbucket’s official templates for your technology stack. These templates provide a solid foundation and can be customized to fit your deployment process.

  1. Fill in the configuration form:

    • Title: A descriptive name (e.g., "AppAmbit Delivery Notification").
    • URL: Your dashboard's webhook endpoint. 
      [https://appambit.com/bitbucket/webhook/YOUR_APP_KEY_HERE](https://appambit.com/bitbucket/webhook/YOUR_APP_KEY_HERE)
    • Secret: Paste the Webhook Secret. For instructions on how to generate it, see the Securing Your Webhooks section in our overview guide.
    • Triggers: Select Repository > Build status updated. This ensures the webhook fires only after a pipeline run is complete. Webhook triggers (light) Webhook triggers (dark)

  2. Click Save to create the webhook.

Step 3: Configure AppAmbit Dashboard

The final step is to provide your repository details and the Access Token to the dashboard.

  1. Navigate to your App's Edit view in the AppAmbit Dashboard.
  2. Locate the App Release section.
  3. Fill in the following fields:
    • Repo name: Enter your Bitbucket repository name in the format workspace/repository-slug.
    • Delivery token: Paste the Bitbucket Access Token you created in Step 1. AppAmbit release information (light) AppAmbit release information (dark)
  4. Click Save changes.

Configuration Complete!

Your Bitbucket repository is now fully integrated. From now on, successful pipeline runs will automatically appear in your Releases Section.

Troubleshooting

  • Ensure the webhook URL and secret are correct.
  • Verify workflow artifacts are generated as expected.
  • Check permissions for the Personal Access Token.
  • Review Bitbucket Pipelines (Webhooks) logs for errors.

Next Steps

Learn about Azure CI/CD integration