# Connect Bitbucket

> Authorize ApiTraffic on Bitbucket Cloud, link a repository to a bucket and map branches to environments so pushes and tags become event markers.

Source: https://www.apitraffic.io/docs/git-integrations/bitbucket

Connecting Bitbucket authorizes ApiTraffic, through OAuth, to see your repositories and to add a push webhook to each repository you link. Pushes of branches become `git.push` markers and pushes of tags become `git.tag` markers. Only Bitbucket Cloud is supported; Bitbucket Server and Data Center are not.

## Before you begin

- You are an ApiTraffic account **owner** or **admin**.
- On Bitbucket, you have **admin** permission on each repository you want to track. That is needed to add a repository webhook.
- Your plan includes **Git integration**. See [Git integrations](https://www.apitraffic.io/docs/git-integrations/overview#before-you-begin).

## Connect Bitbucket

**Start the connection**

Open the account menu, choose **Account**, then select **Git** under **Integration**. In **Connect a Provider**, select **Connect Bitbucket**.

**Grant access on Bitbucket**

Bitbucket asks you to grant ApiTraffic access. Grant it.

**Return to ApiTraffic**

Bitbucket sends you back to **Git Integration**, which shows **Git provider connected.** The Bitbucket card shows your workspace account and the status `active`.

**Link a repository**

On the Bitbucket card, select **Add Repository**. Choose the **Repository** and the **Bucket** whose traffic it serves, and select **Link Repository**. ApiTraffic adds the webhook to the repository.

**Map branches to environments**

Under **Branch → Environment mappings**, add a row for each branch that deploys and select **Add**. Mark one as **Fallback** if tags should go to an environment other than the default branch's.

**Verify**

Push a commit to a mapped branch. Within a few seconds a `git.push` marker appears on the bucket's charts. If it doesn't, select **Diagnose**.

## How Bitbucket diagnostics work

**Diagnose** checks that the Bitbucket access token works, that it can reach the repository, that ApiTraffic's webhook is still on the repository, and the deliveries ApiTraffic has received. If the webhook is missing, select **Re-register webhook**.

## Disconnect

- **In ApiTraffic:** select **Disconnect** on the Bitbucket card. All of its repositories are unlinked, and ApiTraffic removes the webhooks it added where it still can.
- **On Bitbucket:** you can also revoke ApiTraffic's access in your Bitbucket personal settings.

## Troubleshooting

**A repository I want isn't listed**

ApiTraffic lists the repositories your Bitbucket user can access. Check your access, then open **Add Repository** again.

**No marker after pushing**

Select **Diagnose**. Check that the branch matches a mapping, and that the webhook still exists under the repository's **Repository settings** → **Webhooks**.

**The connection shows error**

ApiTraffic refreshes Bitbucket tokens automatically, but if a refresh fails, for example because access was revoked, the connection is marked `error`. Connect Bitbucket again, link the repositories under the new connection, then disconnect the old one.

## Related

- [Git integrations](https://www.apitraffic.io/docs/git-integrations/overview):
    Branch mappings, marker types and health checks.

- [Event markers](https://www.apitraffic.io/docs/events):
    How markers appear on charts.