Connect Bitbucket

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

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.

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.

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
• Use Bitbucket API tokens
• Review Bitbucket API-token permissions
• App-password retirement information

Plan token permissions

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

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.

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.

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.

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

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.

Continue to Use 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.

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

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

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

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 Confluence
• Review Agent health and logs
• Manage Skill Versions
• Configure an Agent