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 a user-based Bitbucket API token with scopes and the Atlassian account email that owns the token.

Agent Barn currently generates a Basic-auth runtime profile containing:

auth_type = "basic_api_token"
email = "[email protected]"
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.

Workspace and repository access tokens use bearer authentication. Although credential validation can probe some bearer tokens, the current Agent runtime generates a Basic-auth aai-cli profile. Use an account API token for the complete validation-and-runtime flow.

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.

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 = "[email protected]"
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": "[email protected]",
        "api_token": "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