Bitbucket

Integration

Connect via OAuth for Bitbucket Cloud repository access.

Bitbucket integration uses OAuth for authentication. Currently supports Bitbucket Cloud only.

Bitbucket Cloud only. Bitbucket Data Center and Server are not currently supported. If you need Data Center support, please let us know.

Setup Guide

Start OAuth Connection

Go to your team's Integrations page (Settings → Integrations) and select the Bitbucket tab. Click "Connect with Bitbucket" to start the OAuth flow.

Authorize Arbtr

You'll be redirected to Bitbucket to authorize Arbtr. Review and approve the requested permissions.

Permissions Requested:

• Read-Only mode: Account (read), Repositories (read), Pull requests (read)
• Full Access mode: Account (read), Repositories (write), Pull requests (write)

After authorization, you'll be redirected back to Arbtr with your account connected. Your Bitbucket username will be displayed in the integration settings.

Configure Repository

After connecting, configure which repository to sync decisions to.

Fill in the following:

Workspace:Your Bitbucket workspace (from URL: bitbucket.org/workspace/...)
Repository Slug:Repository name as it appears in the URL
Branch:Target branch, usually main
ADR Directory:Where to store ADRs (e.g., docs/adr)

Finding your workspace and slug: Look at your repository URL:bitbucket.org/workspace/repo-slug

Test and Save

Click "Test Connection" to verify everything is configured correctly, then save your settings.

The test will verify that Arbtr can access your repository using the OAuth token. Tokens are automatically refreshed, so you won't need to reconnect manually.

Publishing Decisions

Once configured with Full Access mode, you can publish concluded decisions to Bitbucket:

Manual Publishing

On any concluded decision, click Actions → Publish to Git. This creates a Pull Request with your ADR file. Review and merge the PR in Bitbucket.

Auto-Publishing

Enable "Auto-publish on conclusion" in Integrations settings. Decisions will be automatically published when you approve the comprehensive summary.

Self-Hosted Arbtr Setup

If you're self-hosting Arbtr, you'll need to create your own OAuth consumer in Bitbucket.

Creating a Bitbucket OAuth Consumer

In Bitbucket, go to Workspace Settings → OAuth consumers
Click "Add consumer" and configure:
- • Name: "Arbtr"
- • Callback URL: https://your-arbtr-instance.com/api/auth/bitbucket/callback
- • Permissions: Account (read), Repositories (read or write), Pull requests (read or write)
Copy the Key and Secret

Environment Variables

BITBUCKET_CLIENT_ID_READ - OAuth consumer key for read-only mode
BITBUCKET_CLIENT_SECRET_READ - OAuth secret for read-only consumer
BITBUCKET_CLIENT_ID_FULL - OAuth consumer key for full access mode
BITBUCKET_CLIENT_SECRET_FULL - OAuth secret for full access consumer

Troubleshooting

401 Unauthorized

Your OAuth token may have expired and failed to refresh. Disconnect and reconnect your Bitbucket account to get new credentials.

403 Forbidden

You don't have access to the specified repository, or the OAuth scopes are insufficient. Make sure you have write access to the repository.

404 Repository Not Found

The workspace or repository slug is incorrect. Verify them by checking your repository URL in Bitbucket: bitbucket.org/workspace/repo-slug

Workspace vs Username

Make sure you're using the workspace identifier, not your personal username. Workspaces can be found in your Bitbucket URL or in workspace settings.

GitLab Setup

Arbtr Code Tools

Command Palette