Set up ADR Compliance with Bitbucket

View as Markdown

---

Run ADR Compliance in Bitbucket Pipelines on your Bitbucket Cloud pull requests. New to ADR Compliance? Read the introduction 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:

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, 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. Or keep it on GitHub.
• An API key for an AI model provider.

Setup

1. Create the access tokens

Bitbucket Pipelines has no built-in token for the REST API, so the agent uses repository access tokens. 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

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).

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

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. 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

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

The agent reads exceptions 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

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.
--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

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 needs only Contents: Read.

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

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

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