---
title: Bitbucket Integration
description: Learn how to connect your Bitbucket repositories to Capawesome Cloud to build and automate your app directly from source.
---

# Bitbucket Integration

Connect your Bitbucket repositories to Capawesome Cloud to build and automate your app directly from source. A Git connection stores your provider and credentials once at the organization level and can be reused by any app in that organization.

## Prerequisites

Before you begin, ensure you have:

- A [Capawesome Cloud](https://console.cloud.capawesome.io){:target="_blank"} account and an organization (owner or admin role to manage Git connections).
- A Bitbucket Cloud account with access to the repositories you want to connect.

## Create a Git connection

A Git connection is created once at the organization level and can be reused by every app in that organization.

1. Open your organization's [Git connections](https://console.cloud.capawesome.io/organizations/_/git){:target="_blank"} page and click **Create Git connection**.
2. Select **Bitbucket** as the provider.
3. Choose one of the authentication methods below and follow the corresponding steps.

!!! note "Bitbucket Cloud only"

    Only Bitbucket Cloud is supported. Bitbucket self-hosted / Data Center instances cannot be connected through this flow, as there is no **Server URL** field for Bitbucket.

### Email & API token (recommended)

Authenticate with your Atlassian account email and an API token you create on Bitbucket. API tokens are available on every Bitbucket plan.

1. Create an [Atlassian API token with scopes](https://id.atlassian.com/manage-profile/security/api-tokens){:target="_blank"} and select **Bitbucket** as the app:
    - `read:user:bitbucket` — required for every connection.
    - `read:repository:bitbucket` for a read-only connection.
    - To enable [Automations](../automations/index.md): also add `read:webhook:bitbucket` and `write:webhook:bitbucket`.
2. Select **Email & API token** as the authentication method, enter your Atlassian account **email**, and paste the token.

!!! note "API tokens expire"

    Atlassian API tokens have a maximum lifetime of one year. When the token expires, the connection stops working until you update it with a new token.

!!! note "App passwords are deprecated"

    Bitbucket [app passwords are being removed](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation){:target="_blank"}. Create an API token with scopes instead.

### Workspace access token

Paste a workspace access token you create on Bitbucket. Workspace access tokens require a [Bitbucket Premium plan](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/){:target="_blank"}, do not expire, and belong to the workspace instead of a personal account.

1. Create a Bitbucket workspace access token (**Workspace settings → Access tokens**) with these permissions:
    - **Repositories → Read** for a read-only connection.
    - To enable [Automations](../automations/index.md): also add **Repositories → Admin** (required to manage webhooks).
2. Select **Workspace access token** as the authentication method and paste the token.

## Connect a repository to your app

Once a Git connection exists, connect a specific repository to your app:

1. Open your app's [Git repository](https://console.cloud.capawesome.io/apps/_/git){:target="_blank"} page and click **Connect Git repository**.
2. Select the Bitbucket connection.
3. Enter your **workspace** slug — from `bitbucket.org/<workspace>`, since Bitbucket can't list your workspaces — then select the repository you want to connect.

You can also connect a repository during **Create app** (on the **Git** tab).