# Set up ADR Compliance with Bitbucket

Copy as Markdown[View as Markdown](/docs/development/agents/set-up-adr-compliance/bitbucket.md)

***

Run ADR Compliance in **Bitbucket Pipelines** on your **Bitbucket Cloud** pull requests. New to ADR Compliance? Read the [introduction](/docs/development/agents/set-up-adr-compliance.md) first.

A pull request pipeline runs the agent on every push to the pull request. When the code conflicts with one of your ADRs, it comments on the pull request. Once the conflicts are fixed, it updates the comment and marks it **resolved**:

![ADR Compliance commenting on a Bitbucket pull request](/assets/images/bitbucket-adr-compliance-d9b819e01ade7aa976d3e1ecbdda0bc8.png)

## Before you start[​](#before-you-start "Direct link to Before you start")

You need:

* A Bitbucket Cloud repository with your source code (the **source repository**), with Pipelines turned on (**Repository settings → Pipelines → Settings**). Bitbucket only lets you turn on Pipelines once you've set up [Bitbucket two-step verification](https://support.atlassian.com/bitbucket-cloud/docs/enable-two-step-verification/), which is separate from your Atlassian account's and needs an SSH key on your account first.
* An EventCatalog in a Bitbucket repository (the **catalog repository**), with the catalog at the root of the repository, and your decisions documented as [ADRs](/docs/development/guides/resources/adrs/creating-adrs.md). Or keep it [on GitHub](#use-a-catalog-on-github).
* An API key for an AI model provider.

## Setup[​](#setup "Direct link to Setup")

### 1. Create the access tokens[​](#1-create-the-access-tokens "Direct link to 1. Create the access tokens")

Bitbucket Pipelines has no built-in token for the REST API, so the agent uses [repository access tokens](https://support.atlassian.com/bitbucket-cloud/docs/create-a-repository-access-token/). In each repository, open **Repository settings → Security → Access tokens**, and create a token with these permissions:

| Repository         | Permissions                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------- |
| Source repository  | **Repositories: Read** and **Pull requests: Write**, to comment and to read the description for exceptions |
| Catalog repository | **Repositories: Read**. The workflow never writes to it.                                                   |

Comments appear under the source token's name, so name it something like `EventCatalog Agents`. If your plan has project or workspace access tokens, one token with these permissions on both repositories works too.

### 2. Add the repository variables[​](#2-add-the-repository-variables "Direct link to 2. Add the repository variables")

In the source repository, open **Repository settings → Pipelines → Repository variables**, and add these as **secured** variables:

| Variable                       | Value                                                                                             |
| ------------------------------ | ------------------------------------------------------------------------------------------------- |
| `EVENTCATALOG_BITBUCKET_TOKEN` | The source repository's access token.                                                             |
| `EVENTCATALOG_CATALOG_TOKEN`   | The catalog repository's access token. Leave it out if the source token can read the catalog.     |
| `ANTHROPIC_API_KEY`            | Your model provider key (see [models](/docs/development/agents/set-up-adr-compliance.md#models)). |

Secured variables are hidden in the logs. To share them across repositories, add them as workspace variables instead.

### 3. Add the pipeline[​](#3-add-the-pipeline "Direct link to 3. Add the pipeline")

Add a pull request pipeline to `bitbucket-pipelines.yml` in your source repository. If you already have the file, add the step under your own `pipelines` section.

bitbucket-pipelines.yml

```
pipelines:
  pull-requests:
    '**': # every pull request
      - step:
          name: EventCatalog ADR Compliance
          image: node:24
          clone:
            depth: full
          script:
            - git clone --quiet --depth 1 --branch v2 https://github.com/event-catalog/agents.git /tmp/eventcatalog-agents
            - /tmp/eventcatalog-agents/bitbucket-pipelines/run.sh adr-compliance --catalog-repo acme/eventcatalog --adrs "adrs/**, domains/Orders/**"
```

Replace `acme/eventcatalog` with your catalog repository, as `workspace/repo`, and set `--adrs` to the [ADRs that apply to this repository](/docs/development/agents/set-up-adr-compliance.md#choose-which-adrs-to-check). Keep the quotes around the globs. To link ADRs to your hosted catalog, add `--catalog-url https://catalog.example.com`.

* **Keep `clone: depth: full`.** The agent needs the history to compare the pull request with its target branch, and Bitbucket clones only the last 50 commits by default.
* **Keep `image: node:24`**, or use another image with Node.js 22.19 or later and git.

### 4. Check it works[​](#4-check-it-works "Direct link to 4. Check it works")

Open a pull request that does something one of your accepted ADRs rules out. The agent comments on the pull request. Each push updates the same comment.

## Exceptions in Bitbucket[​](#exceptions-in-bitbucket "Direct link to Exceptions in Bitbucket")

The agent reads [exceptions](/docs/development/agents/set-up-adr-compliance.md#record-an-exception) from the pull request description when it runs. Bitbucket Pipelines doesn't run when a description changes, so after adding an `adr-exception:` line, push a commit or re-run the pull request's pipeline.

## Options[​](#options "Direct link to Options")

The first argument is the workflow. The options follow it:

| Option               | Required | Default                       | Description                                                                                                       |
| -------------------- | -------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `adr-compliance`     | Yes      |                               | The workflow to run.                                                                                              |
| `--adrs`             | Yes      |                               | Comma-separated globs, relative to the catalog root, selecting the ADRs to check against.                         |
| `--catalog-repo`     | Yes      |                               | Your catalog repository: `workspace/repo` (or `repo` in the same workspace), or its URL. `owner/repo` for GitHub. |
| `--catalog-ref`      | No       | `main`                        | The catalog branch to read.                                                                                       |
| `--catalog-provider` | No       | `bitbucket`                   | Where your catalog is hosted: `bitbucket` or `github`.                                                            |
| `--catalog-url`      | No       |                               | The URL of your hosted catalog. The comment links ADRs to it. Without it, they link to your catalog repository.   |
| `--model`            | No       | `anthropic/claude-sonnet-4-6` | The model the agent uses. See [models](/docs/development/agents/set-up-adr-compliance.md#models).                 |
| `--ignore-paths`     | No       | Build and dependency folders  | Comma-separated paths or glob patterns to leave out of the review.                                                |
| `--source-dir`       | No       | `$BITBUCKET_CLONE_DIR`        | The source checkout to compare.                                                                                   |

To pin an exact release, change `--branch v2` in the `git clone` line to a release such as `--branch v2.4.0`.

## Use a catalog on GitHub[​](#use-a-catalog-on-github "Direct link to Use a catalog on GitHub")

To keep your catalog on GitHub with your code in Bitbucket, add `--catalog-provider github`, set `--catalog-repo` to `owner/repo`, and set `EVENTCATALOG_CATALOG_TOKEN` to a GitHub token that can read the catalog repository. A [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) needs only **Contents: Read**.

## Differences from GitHub[​](#differences-from-github "Direct link to Differences from GitHub")

* **Bitbucket has no built-in token**, so you create access tokens for the agent and add them as secured variables.
* **The comment can be resolved.** Once the conflicts are gone, the agent marks its comment resolved. If a later push brings a conflict back, it reopens it.
* **Exceptions need a new run**, as above.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

| Message                                                       | What to do                                                                                                                     |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `Cannot find the commits to compare`                          | Set `clone: depth: full` on the step.                                                                                          |
| `Bitbucket needs an access token to comment on pull requests` | Add the `EVENTCATALOG_BITBUCKET_TOKEN` secured variable.                                                                       |
| `Could not fetch branch …`                                    | Give the catalog token **Repositories: Read** on the catalog repository, and check `--catalog-repo` and `--catalog-ref`.       |
| `failed (401): Unauthorized: the token was not accepted`      | The access token has expired or was revoked. Create a new one.                                                                 |
| No comment on the pull request                                | The pull request may follow your ADRs. If it doesn't, give the source token **Pull requests: Write** on the source repository. |

## Bitbucket Data Center[​](#bitbucket-data-center "Direct link to Bitbucket Data Center")

The agent supports Bitbucket Cloud. Bitbucket Data Center has a different API and isn't supported.