---
title: Connect Bitbucket
canonical: "https://agentbarn.dev/guides/integrations/bitbucket"
pubDate: "2026-08-29T00:00:00.000Z"
updatedDate: "2026-09-02T11:46:37.000Z"
author: Agent Barn
description: "Connect Bitbucket Cloud to an Agent Barn Agent with scoped Integration credentials, optional repository defaults, Shared Credentials, the isolated Bitbucket Skill, and aai-cli validation."
tags: [Integrations, How-to, "Bitbucket administrators, Agent operators, and Organization administrators", Bitbucket, Bitbucket Cloud, API token, repository access, pull requests, Pipelines, aai-cli, Bitbucket Skill, aai-bitbucket, generated profile, Shared Credentials]
categories: [Guides, Integrations]
---

-   Integrations
-   10–15 minutes
-   Requires a Bitbucket Cloud API token

Connect Bitbucket Cloud to let an Agent inspect repositories, branches, commits, source files, pull requests, review comments, and pipeline results.

Agent Barn stores the credential as an encrypted Agent Secret, and exposes Bitbucket operations to the Agent through the built-in **Bitbucket** Skill and `aai-cli`.

**Note**

This integration supports **Bitbucket Cloud**. It does not configure Bitbucket Data Center or Bitbucket Server.

## What you will configure

1.  Bitbucket account
2.  Scoped API token
3.  Encrypted Agent Secret
4.  Bitbucket Skill
5.  aai-cli profile

```
Bitbucket account
        │
        ├── Scoped API token
        ├── Workspace ID
        └── Repository slugs
                  │
                  ▼
       Encrypted Agent Secret
                  │
                  ▼
        Built-in Bitbucket Skill
                  │
                  ▼
       aai-cli profile and commands
```

At the end of this guide, the Agent will have:

-   An encrypted `bitbucket` credential
-   The built-in Bitbucket Skill
-   A generated `bitbucket-work` profile
-   Explicit access to the repositories allowed by the Bitbucket account and API token
-   Commands for inspecting source, pull requests, branches, commits, and pipelines

## Before you begin

You need:

-   An Agent Barn Organization
-   An existing Agent, or permission to hire one
-   Permission to update the Agent and manage its Secrets
-   A Bitbucket Cloud account with access to the intended repositories
-   The workspace ID and repository slugs you want the Agent to use
-   Permission to create an Atlassian API token

For a dedicated production Agent, use a dedicated Bitbucket account instead of a maintainer’s personal account. Grant that account access only to the repositories required by the Agent’s role.

**Important**

A repository entered in Agent Barn becomes a runtime default. It does not reduce what the token can access. The Bitbucket account, token scopes, workspace restriction, and repository permissions remain the authorization boundary.

## Choose the authentication method

Use the credential pattern supported by the token you provision. Email plus an API token uses Basic authentication; workspace- and repository-scoped access tokens can use bearer authentication when the supplied token supports it.

A Basic-auth profile includes:

```
auth_type = "basic_api_token"
email = "agent@example.com"
api_token_secret = "bitbucket.api_token"
```

This matches Bitbucket Cloud’s supported API-token authentication using an Atlassian account email and API token.

**Warning**

Do not create or reuse an app password. Atlassian stopped allowing new app passwords on September 9, 2025, and disabled existing app passwords on June 9, 2026. API tokens with scopes are their replacement.

If an Agent Barn screen still refers to “App password scopes,” treat that wording as legacy UI copy. Supply a scoped Bitbucket API token.

The validator checks authentication and, where possible, configured repository and pull-request access. Relevant access includes account or user read access when required by the token type, repository read access, pull-request read access, and pull-request write access when the Agent must post review comments. A token can authenticate successfully while still producing missing-scope warnings; an identity lookup alone does not prove access to every configured repository.

Official references:

-   [Create a Bitbucket API token](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/)
-   [Use Bitbucket API tokens](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/)
-   [Review Bitbucket API-token permissions](https://support.atlassian.com/bitbucket-cloud/docs/api-token-permissions/)
-   [App-password retirement information](https://support.atlassian.com/bitbucket-cloud/docs/revoke-an-app-password/)

## Plan token permissions

Choose permissions based on what the Agent is expected to do.

| Bitbucket permission | Scope | Use in Agent Barn | Recommendation |
| --- | --- | --- | --- |
| User: Read | `read:user:bitbucket` | Displays and validates the token owner’s identity | Recommended |
| Repositories: Read | `read:repository:bitbucket` | Lists repositories and reads branches, commits, and source files | Required |
| Pull requests: Read | `read:pullrequest:bitbucket` | Lists and reads pull requests, diffs, activity, and comments | Required for review workflows |
| Pull requests: Write | `write:pullrequest:bitbucket` | Creates or changes pull requests and performs write operations | Grant only when the workflow requires it |
| Pipelines: Read | `read:pipeline:bitbucket` | Reads pipelines, steps, and logs | Required only for CI inspection |
| Repositories: Write | `write:repository:bitbucket` | Modifies repository content | Not required by the current read-oriented source workflow |

A common code-review configuration is:

```
read:user:bitbucket
read:repository:bitbucket
read:pullrequest:bitbucket
read:pipeline:bitbucket
```

Add `write:pullrequest:bitbucket` only when the Agent must perform pull-request write operations beyond the actions covered by read access.

**Tip**

Start with read access. Expand the token only when a documented Agent workflow requires another operation.

## Create a Bitbucket API token

1.  Sign in to the Atlassian account that the Agent will use.
2.  Open the account’s **Security** settings.
3.  Select **Create and manage API tokens**.
4.  Select **Create API token with scopes**.
5.  Enter a descriptive name, such as `agent-barn-code-reviewer`.
6.  Set an expiration date that matches your credential-rotation policy.
7.  Select **Bitbucket** as the application.
8.  Select the permissions planned in the previous section.
9.  Restrict the token to the intended workspace if Atlassian offers that option in your account.
10.  Review the configuration and create the token.
11.  Copy the token immediately.

Bitbucket displays the token only once.

**Warning**

Do not paste the token into an issue, chat message, shell history, source file, screenshot, or documentation page. Paste it directly into Agent Barn’s secret field.

## Collect repository details

Collect the following values before opening Agent Barn.

| Value | Example | Where to find it |
| --- | --- | --- |
| Workspace ID | `acme-engineering` | The workspace segment in a Bitbucket repository URL |
| Repository slug | `agent-barn` | The final repository segment in the URL |
| Account email | `agent@example.com` | The Atlassian account that created the API token |
| API token | `REDACTED` | The token copied during creation |

For this repository URL:

```
https://bitbucket.org/acme-engineering/agent-barn
```

Use workspace `acme-engineering` and repository `agent-barn`.

Enter a bare repository slug in Agent Barn. Do not enter the full URL or `workspace/repository`.

### Correct

```
agent-barn
```

### Incorrect

```
https://bitbucket.org/acme-engineering/agent-barn
acme-engineering/agent-barn
```

The workspace ID can differ from the workspace’s display name. Use the value from the repository URL.

## Connect Bitbucket

1.  In Agent Barn, open **Agents**.
2.  Select the Agent that needs Bitbucket access.
3.  Open the Agent’s **Configuration**.
4.  Select **Keys & integrations**.
5.  Select **Edit**.
6.  Under **Integration credentials**, add **Bitbucket**.
7.  Select **Manual credential**.
8.  Complete the Bitbucket fields.
9.  Apply the configuration.

| Agent Barn field | Required | Value |
| --- | --- | --- |
| **Workspace** (`workspace`) | Yes | Bitbucket workspace identifier |
| **Repositories** (`repos`) | No | Optional list of bare repository slugs |
| **Email** (`email`) | Yes | Account email used when Basic authentication is required |
| **API token** (`apiToken`) | Yes | Secret token or supported access token |

Example:

```
Workspace
acme-engineering

Repositories
agent-barn
internal-platform

Email
agent@example.com

API token
••••••••••••••••
```

`repos` is a list, not a single `repo` field. Legacy credentials with one repository may be normalized into this list; new entries should always use `repos`. The API token is encrypted and write-only, so examples never display a real token.

If the Agent is running, use the website’s restart-aware apply flow. The updated credential and generated profile become available when the Agent starts again.

**Note**

Agent Barn allows one active credential for each provider on an Agent. Adding another Bitbucket credential replaces the existing Bitbucket credential, rather than creating a second independent provider entry.

## Assign the Bitbucket Skill

The `aai-bitbucket` Skill supplies instructions and command references; the Bitbucket Integration credential supplies authentication and generated profile configuration. Bitbucket is a tool Integration, not a Communication Connection.

1.  Open the Agent’s **Skills** configuration.
2.  Select **Edit**.
3.  Add the built-in **Bitbucket** Skill.
4.  Apply the change.
5.  Restart the Agent if prompted.

The mounted Skill’s canonical entry point is:

```
./skills/aai-bitbucket/SKILL.md
```

```
aai-bitbucket/
├── SKILL.md
└── references/
    └── command-reference.md
```

The Agent should read `./skills/aai-bitbucket/SKILL.md` before using Bitbucket. The supporting command reference belongs to that same bundle; the Skill is not one file inside a shared `aai-cli` directory. It documents the `aai-cli bitbucket` command group.

Assigning the Skill does not create, reveal, or grant a credential; adding a credential does not mutate the Skill. The bundled Skill declares Bitbucket as a required provider, which Agent configuration validates against available Integration credentials. Bitbucket is also eligible for the manual-entry [Shared Credentials](/guides/integrations/shared-credentials) workflow.

**Important**

Do not instruct the Agent to call the Bitbucket REST API directly, or ask users for a token in conversation. The supported Agent interface is the configured `aai-cli bitbucket` command group.

## Validate the connection

After saving the credential:

1.  Return to **Keys & integrations**.
2.  Find the configured Bitbucket credential.
3.  Select **Validate**.
4.  Review the validation status, identity, and missing scopes.

| Status | Meaning |
| --- | --- |
| Valid | Authentication succeeded and no checked scope is missing |
| Warning | Authentication succeeded, but the validator detected a missing permission |
| Invalid | The token was rejected, expired, unreachable, or could not access a required resource |

A successful response resembles:

```
{
  "validation_status": "valid",
  "validation_identity": "Agent Account (@agent-account)",
  "validation_error": null,
  "missing_scopes": []
}
```

A usable token with incomplete permissions can return:

```
{
  "validation_status": "warning",
  "validation_identity": "Agent Account (@agent-account)",
  "validation_error": null,
  "missing_scopes": [
    "Repositories (read) scope missing"
  ]
}
```

**Important**

Validation checks authentication and selected provider endpoints. It does not prove that every future Agent workflow will succeed. Always test a real repository operation after validation.

## Verify Agent access

Ask the Agent to identify its configured Bitbucket integration and inspect a known repository. For direct runtime verification, use commands like these inside the Agent environment.

List repositories:

```
aai-cli bitbucket repos list \
  --limit 3 \
  --profile bitbucket-work
```

Read repository metadata:

```
aai-cli bitbucket repos get acme-engineering/agent-barn \
  --profile bitbucket-work
```

Read the default branch:

```
aai-cli bitbucket branches get main \
  --owner acme-engineering \
  --repo agent-barn \
  --profile bitbucket-work
```

Read a source file:

```
aai-cli bitbucket source get main README.md \
  --owner acme-engineering \
  --repo agent-barn \
  --profile bitbucket-work
```

List pull requests:

```
aai-cli bitbucket prs list \
  --owner acme-engineering \
  --repo agent-barn \
  --state OPEN \
  --limit 5 \
  --profile bitbucket-work
```

Inspect recent pipelines:

```
aai-cli bitbucket pipelines list \
  --owner acme-engineering \
  --repo agent-barn \
  --limit 5 \
  --profile bitbucket-work
```

Successful command output is JSON. Errors are written to standard error as a JSON object, and return a non-zero exit code.

**Tip**

Always pass `--owner`, `--repo`, and `--profile` explicitly for repository operations. `repos list` is the exception, because it does not accept `--repo`. Explicit flags make the target clear, and avoid accidental use of a profile default.

## Use the supported command groups

```
aai-cli bitbucket repos
aai-cli bitbucket prs
aai-cli bitbucket branches
aai-cli bitbucket commits
aai-cli bitbucket source
aai-cli bitbucket pipelines
```

These commands list and inspect repositories, pull requests, branches, commits, source files and history, pipelines, steps, and logs. Pull-request commands also read diffs, diff statistics, commits, and activity, and can list, create, update, or delete comments. The Skill documents these commands; `aai-cli` performs the provider operation.

**Capability is not permission**

The CLI can expose write operations, but an Agent’s Template, role instructions, or operating policy can still prohibit them. A code-review Agent may post permitted review comments while being prohibited from approving, declining, or merging a pull request.

## Review a pull request through aai-cli

1.  Run `prs get` to inspect pull-request metadata.
2.  Run `prs diffstat` to identify changed files.
3.  Use `prs diff --output` for a large diff.
4.  Use `source get <commit> <path>` for exact file contents.
5.  Use `prs comments create` only when the Agent’s policy permits review comments.

```
aai-cli bitbucket prs get 42 --repo my-workspace/my-repo --profile bitbucket-work
aai-cli bitbucket prs diffstat 42 --repo my-workspace/my-repo --profile bitbucket-work
aai-cli bitbucket prs diff 42 --repo my-workspace/my-repo --output local/logs/pr-42.diff --profile bitbucket-work
aai-cli bitbucket source get <commit> <path> --repo my-workspace/my-repo --profile bitbucket-work
```

For an inline comment, use `--inline-path` and `--inline-to` for a line added in the new file, or `--inline-from` for a line removed from the old file. Do not use direct Bitbucket REST calls as the Agent interface.

## Repository profiles

Agent Barn converts the repository list into one or more `aai-cli` profiles.

### One repository

Workspace `acme-engineering` with repository `agent-barn` creates a single profile:

`bitbucket-work → acme-engineering/agent-barn`

### Multiple repositories

Each additional repository adds a numbered profile: `bitbucket-work-2`, `bitbucket-work-3`, and so on.

### No configured repository

`bitbucket-work` is still created, but without a default `repo`. Repository commands must pass `--repo`.

With three repositories configured, Agent Barn creates:

```
bitbucket-work   → acme-engineering/agent-barn
bitbucket-work-2 → acme-engineering/internal-platform
bitbucket-work-3 → acme-engineering/documentation
```

The Agent’s generated tool context contains the authoritative mapping. Do not infer that a numbered profile refers to a particular repository without checking that mapping.

Because command-line values override profile defaults, the Agent can normally continue using `bitbucket-work` and pass the intended `--owner` and `--repo` explicitly:

```
--owner acme-engineering --repo agent-barn
```

**Important**

Leaving the repository list empty does not mean “no repository access.” It means “no default repository.” The token can still reach repositories allowed by its Bitbucket permissions.

## Runtime behavior

When the Agent starts, Agent Barn:

1.  Decrypts the Bitbucket credential for the runtime.
2.  Writes the token to the encrypted `aai-cli` secret store.
3.  Generates the Bitbucket profile.
4.  Mounts the built-in Bitbucket Skill.
5.  Adds the profile mapping to the Agent’s tool context.

A generated profile resembles:

```
[profiles.bitbucket-work]
auth_type = "basic_api_token"
workspace = "acme-engineering"
repo = "agent-barn"
email = "agent@example.com"
api_token_secret = "bitbucket.api_token"
```

The token itself is not written into the profile. The profile references the encrypted secret name `bitbucket.api_token`.

The complete runtime path is:

```
Encrypted Bitbucket credential
              │
              ▼
         Agent start
              │
              ├── aai-cli encrypted secret store
              ├── bitbucket-work profile
              └── Bitbucket Skill files
                         │
                         ▼
                aai-cli bitbucket
                         │
                         ▼
                 Bitbucket Cloud API
```

Credential changes take effect after the Agent restarts.

## Use a Shared Credential

An Organization administrator can create an Organization-owned Shared Credential for Bitbucket, and attach it to multiple Agents.

Use a Shared Credential when:

-   Multiple Agents should use the same dedicated Bitbucket service account
-   One administrator should rotate the token centrally
-   Individual Agent operators should not handle the token
-   The same workspace and repository defaults apply to several Agents

To attach one:

1.  Create or locate the Bitbucket Shared Credential in the Organization.
2.  Open the Agent’s **Keys & integrations** configuration.
3.  Add **Bitbucket**.
4.  Switch from **Manual credential** to **Shared Credential**.
5.  Select the intended credential.
6.  Apply the change, and restart the Agent if prompted.
7.  Validate the connection from the Agent.

An Agent can use either a manual Bitbucket credential or a Shared Bitbucket Credential, not both simultaneously.

**Important**

Repository defaults belong to the Shared Credential. If different Agents need different repository defaults, or different Bitbucket authorization boundaries, use separate Shared Credentials.

Continue to [Use shared credentials](/guides/integrations/shared-credentials) for the complete ownership and rotation model.

## Rotate or remove the credential

### Rotate a manual credential

1.  Create a replacement API token in Atlassian.
2.  Keep the old token active temporarily.
3.  Open the Agent’s **Keys & integrations** configuration.
4.  Replace the Bitbucket credential with the new token.
5.  Apply the change.
6.  Restart the Agent.
7.  Validate the new credential.
8.  Run a real repository command.
9.  Revoke the old token in Atlassian.

Because secret values are write-only, rotation replaces the complete credential content. Re-enter the workspace, repositories, email, and token.

### Rotate a Shared Credential

Update the Organization-owned Shared Credential, validate it, and restart attached Agents so their runtime artifacts are regenerated.

### Remove the credential

Before removing Bitbucket:

1.  Remove or replace any assigned Skill that requires Bitbucket.
2.  Stop the Agent, or use the website’s restart-aware apply flow.
3.  Open **Keys & integrations**.
4.  Mark the Bitbucket credential for removal.
5.  Apply the change.
6.  Restart and verify the Agent.

Agent Barn blocks removal when a remaining assigned Skill requires the `bitbucket` provider.

**Security**

Revoking the token in Atlassian immediately prevents further provider access, even if Agent Barn still contains the encrypted credential.

## API reference

### Add or replace a manual credential

The Agent must be stopped when using the raw update endpoint.

```
PATCH /api/v1/organizations/{organization_id}/agents/{agent_id}
Content-Type: application/json
```

```
{
  "secrets": [
    {
      "provider": "bitbucket",
      "content": {
        "workspace": "acme-engineering",
        "repos": [
          "agent-barn",
          "internal-platform"
        ],
        "email": "agent@example.com",
        "apiToken": "REDACTED"
      }
    }
  ]
}
```

### Attach a Shared Credential

```
{
  "shared_credentials": [
    {
      "shared_credential_id": "00000000-0000-0000-0000-000000000000"
    }
  ]
}
```

### Validate the Agent credential

```
POST /api/v1/organizations/{organization_id}/agents/{agent_id}/integrations/bitbucket/validate
```

The response includes:

```
{
  "validation_status": "valid",
  "validation_identity": "Agent Account (@agent-account)",
  "validation_error": null,
  "missing_scopes": []
}
```

### Remove the credential

```
{
  "removed_secret_providers": [
    "bitbucket"
  ]
}
```

Credential operations require access to the Agent and the appropriate update and secret-management permissions, including `agent.secret.manage`.

## Troubleshooting

### The Agent cannot find the Bitbucket command guidance

Skill, credential, or profile

Confirm the Bitbucket Integration exists for the Agent, the required Skill is assigned and published, and the Agent has started with the generated artifacts. Read `./skills/aai-bitbucket/SKILL.md` and pass `--profile bitbucket-work` explicitly. If no repository is configured, include `--repo`; for several repositories, select the corresponding generated profile or pass an explicit repository identity.

### Validation reports “Invalid API token or credentials”

Check the token type and email

Check that:

-   You created an API token with scopes for the Bitbucket application
-   **Email** is the Atlassian account email that owns the token
-   The token was copied completely
-   The token has not expired or been revoked
-   You did not enter an Atlassian account password
-   You did not enter a retired Bitbucket app password

Create a replacement token if the original token can no longer be retrieved.

### Validation succeeds but repository commands return 403

A permission or membership gap

The token authenticated, but it lacks a required permission, or the account cannot access the repository. Check:

-   `read:repository:bitbucket` is selected
-   The account is a member of the target workspace, or has repository access
-   The token is allowed to access the target workspace
-   The workspace ID and repository slug are correct
-   Pull-request and pipeline permissions are present for those operations

### Pull requests work but source files fail

Separate scopes

Pull-request access and repository access use separate scopes. Add `read:repository:bitbucket`.

The pull-request scope does not automatically grant access to repository source endpoints.

### Source files work but pull requests fail

Repository Read is not enough

Add `read:pullrequest:bitbucket`. Repository Read does not include pull-request access.

### Pipeline commands return 403

Pipelines has its own scope

Add `read:pipeline:bitbucket`. Repository Read does not include Bitbucket Pipelines.

### The repository cannot be found

Check IDs and slugs

Confirm that:

-   **Workspace** contains the workspace ID, not its display name
-   **Repositories** contains a bare slug
-   `--owner` contains only the workspace ID
-   `--repo` contains only the repository slug
-   The token-owning account can open the repository in Bitbucket

### aai-cli reports that the repository is missing

No default repository

No default repository was configured, or the command did not include `--repo`. Run the command with explicit values:

```
aai-cli bitbucket prs list \
  --owner acme-engineering \
  --repo agent-barn \
  --profile bitbucket-work
```

### The wrong repository is used

Pass the target explicitly

Pass both the workspace and repository explicitly:

```
--owner acme-engineering --repo agent-barn
```

If using a numbered profile, consult the Agent’s generated integration mapping before selecting it.

### Validation succeeds but runtime commands fail authentication

Bearer tokens do not match the profile

Confirm that you supplied a user-based Bitbucket API token and its Atlassian account email.

Workspace and repository access tokens use bearer authentication, while the current Agent Barn runtime profile uses `basic_api_token`. Replace the credential with an account API token for the supported end-to-end flow.

### The credential cannot be removed

A Skill still requires it

A remaining assigned Skill requires Bitbucket.

Remove the Bitbucket Skill, or replace the dependent Skill, before removing the credential.

### Changes are not visible to the Agent

Artifacts are produced at startup

Restart the Agent. Profiles, encrypted runtime Secrets, mounted Skills, and generated tool context are produced during Agent startup.

## Security practices

-   Use a dedicated Bitbucket account for production Agents
-   Grant the account access only to required repositories
-   Create a separate API token for Agent Barn
-   Set an expiration date
-   Start with read scopes
-   Avoid repository write, admin, and delete scopes unless a documented workflow requires them
-   Use different credentials for different authorization boundaries
-   Treat the repository list as defaults, not access control
-   Prefer Shared Credentials when administrators should own rotation
-   Validate after every rotation
-   Test a real repository operation after validation
-   Revoke replaced or compromised tokens immediately
-   Never place a real token in documentation, source control, logs, prompts, or chat messages

## Next steps

[**Connect Zoho** The next integration in this section](/guides/integrations/zoho) [**Use shared credentials** Organization-owned credential ownership and rotation](/guides/integrations/shared-credentials) [**Manage Agent credentials** Credential classes, validation, and boundaries](/guides/integrations/credentials) [**Work with Skills** How Skills package provider workflows](/guides/templates-and-skills/skills)

-   [Connect Confluence](/guides/integrations/confluence)
-   [Review Agent health and logs](/guides/agents/health-and-logs)
-   [Manage Skill Versions](/guides/templates-and-skills/skill-versions)
-   [Configure an Agent](/guides/agents/configuration)