{
  "schema": "aaes/capability-pack/1",
  "provider": "bitbucket",
  "version": "1.0.0",
  "description": "Bitbucket Cloud: list workspace repositories, pull requests and pipelines, approve a pull request, and trigger a pipeline.",
  "notes": "The registered host is api.bitbucket.org (Bitbucket Cloud). Bitbucket Data Center is a different product with its own host and API surface: this pack does not cover it, and a Data Center deployment needs its own separately reviewed pack rather than a host substitution into this one. WORKSPACE, REPO_SLUG and PULL_REQUEST_ID in the endpoint paths are placeholders the deployment substitutes with concrete values at registration time, before enabling: the pack is installed with the concrete paths it will actually call, not rebound per request.\n\nThis pack registers only endpoints the public Bitbucket Cloud REST API documentation describes: listing a workspace's repositories, listing a repository's pull requests, listing a repository's pipelines, approving a pull request, and triggering a pipeline.\n\nDocumented exclusions: pull request create, update, merge, decline, request-changes and comments (a comment notifies watchers and is judged by its documented effect), pipeline stop, pipeline schedules, deployment endpoints, repository variables, runners, SSH keys, webhooks, branch restrictions, and every endpoint outside the registered list; each addition is a pack change and requires its own review.\n\nApproval classification: reads sit at the minimum R0 tier. pipeline.trigger is registered as deploy at the minimum R3 tier because Bitbucket documents that the request body carries the caller-chosen target (branch, tag, commit or pull request), selector and variables, and its Run-a-pipeline reference documents an on-demand pipeline form whose request body is a full caller-supplied YAML definition (sent as application/yaml, with the target metadata in query parameters) that overrides the repository's bitbucket-pipelines.yml for that run — so the caller chooses the commands that run, not merely which existing pipeline starts, and intended limits need a separate enforceable control; deploy is one of the designated actions requiring human approval. pullrequest.approve is registered as approve at the minimum R3 tier because the approval is recorded under the caller's identity and typically counts toward merge checks, and approve is one of the designated actions requiring human approval.\n\nAAES has not been certified by Atlassian; review and test this configuration; it is not a vendor guarantee.",
  "credential": {
    "secret_ref_id": "secret-ref-bitbucket-api-token",
    "custody": "customer_vault",
    "inject": "header",
    "inject_name": "Authorization",
    "note": "An Atlassian account API token for Bitbucket Cloud, held in the client's own secret manager. The stored material must be the complete Authorization header value: the word Basic, one separating space, then the base64 encoding of <atlassian-account-email>:<api-token>. Bitbucket documents that API tokens authenticate with HTTP Basic per RFC 2617 using the account email address as the username and the token as the password, that an expiry date is required at token creation with a maximum lifetime of one year, and that a token cannot be viewed or adjusted after creation — rotation means creating a new token and updating the stored value, and deleting a token in the Atlassian account settings invalidates that issued token.\n\nApp passwords are deprecated by the provider and must not be substituted. Request the least-privilege scopes: read:repository:bitbucket, read:pullrequest:bitbucket and read:pipeline:bitbucket cover the three read capabilities; pullrequest.approve additionally needs write:pullrequest:bitbucket and pipeline.trigger additionally needs write:pipeline:bitbucket — scopes do not imply one another, so grant the write scopes only where the R3 capabilities are enabled, and nothing broader. Renewal ownership sits with an external deployment process: the executor injects the stored value verbatim and performs no token lifecycle itself, and it must never substitute a different credential without an approved pack change.\n\nExecutor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack."
  },
  "capabilities": [
    {
      "capability_id": "bitbucket.repositories.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "api.bitbucket.org"
      ],
      "endpoint": "https://api.bitbucket.org/2.0/repositories/WORKSPACE",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-bitbucket-api-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "bitbucket-workspace",
      "description": "List repositories in one workspace via GET /2.0/repositories/WORKSPACE.\n\nThe registered path covers the collection read only — single repository records, workspace membership, and workspace-level settings are not registered by this pack. WORKSPACE is a placeholder the deployment binds to a concrete workspace before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "bitbucket.pullrequests.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "api.bitbucket.org"
      ],
      "endpoint": "https://api.bitbucket.org/2.0/repositories/WORKSPACE/REPO_SLUG/pullrequests",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-bitbucket-api-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "bitbucket-repository",
      "description": "List pull requests for one repository via GET /2.0/repositories/WORKSPACE/REPO_SLUG/pullrequests.\n\nThe registered path covers the collection read only — single pull request records, diffs, comments, and activity reads are not registered by this pack. WORKSPACE and REPO_SLUG are placeholders the deployment binds to concrete values before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "bitbucket.pipelines.read",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R0",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "api.bitbucket.org"
      ],
      "endpoint": "https://api.bitbucket.org/2.0/repositories/WORKSPACE/REPO_SLUG/pipelines",
      "method": "GET",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-bitbucket-api-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "read"
      ],
      "resource_id": "bitbucket-repository",
      "description": "List pipelines for one repository via GET /2.0/repositories/WORKSPACE/REPO_SLUG/pipelines.\n\nThe registered path covers the collection read only — single pipeline records, step details, and log reads are not registered by this pack. WORKSPACE and REPO_SLUG are placeholders the deployment binds to concrete values before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "bitbucket.pullrequest.approve",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "internal",
      "egress_allowlist": [
        "api.bitbucket.org"
      ],
      "endpoint": "https://api.bitbucket.org/2.0/repositories/WORKSPACE/REPO_SLUG/pullrequests/PULL_REQUEST_ID/approve",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-bitbucket-api-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "approve"
      ],
      "resource_id": "bitbucket-repository",
      "description": "Approve a pull request via POST /2.0/repositories/WORKSPACE/REPO_SLUG/pullrequests/PULL_REQUEST_ID/approve. Bitbucket documents this call as recording the caller's approval, which typically counts toward merge checks — the capability is registered as approve at the minimum R3 tier, and approve is one of the designated actions requiring human approval.\n\nOn supported AAES-mediated execution paths, irreversible actions require approval by an authorized person; this does not prevent calls through bypass or observation-only paths. A documented unapprove endpoint exists, but this pack does not register it, so reversing an approval is outside this pack and this pack claims no general reversibility. WORKSPACE, REPO_SLUG and PULL_REQUEST_ID are placeholders the deployment binds to concrete values before enabling.",
      "requires_review": true
    },
    {
      "capability_id": "bitbucket.pipeline.trigger",
      "version": "1.0.0",
      "kind": "tool",
      "risk_tier": "R3",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN",
      "data_class": "pii",
      "egress_allowlist": [
        "api.bitbucket.org"
      ],
      "endpoint": "https://api.bitbucket.org/2.0/repositories/WORKSPACE/REPO_SLUG/pipelines",
      "method": "POST",
      "connector": "http",
      "custody": "customer_vault",
      "secret_ref_id": "secret-ref-bitbucket-api-token",
      "inject": "header",
      "inject_name": "Authorization",
      "actions": [
        "deploy"
      ],
      "resource_id": "bitbucket-repository",
      "description": "Trigger a pipeline for one repository via POST /2.0/repositories/WORKSPACE/REPO_SLUG/pipelines. Bitbucket documents that the request body carries the caller-chosen target (branch, tag, commit or pull request), selector and variables, and its Run-a-pipeline reference documents an on-demand pipeline form whose request body is a full caller-supplied YAML definition (sent as application/yaml, with the target metadata in query parameters) that overrides the repository's bitbucket-pipelines.yml for that run — so the caller chooses the commands that run, not merely which existing pipeline starts, and intended limits need a separate enforceable control.\n\nThat effect-widening, together with the provider's own description of pipelines as build, test and deploy infrastructure, is why the capability is registered as deploy at the minimum R3 tier, and deploy is one of the designated actions requiring human approval.\n\nOn supported AAES-mediated execution paths, irreversible actions require approval by an authorized person; this does not prevent calls through bypass or observation-only paths. A triggered pipeline is outwardly visible, consumes billable build minutes, and any deployment it performs cannot be undone by this pack. WORKSPACE and REPO_SLUG are placeholders the deployment binds to concrete values before enabling.",
      "requires_review": true
    }
  ],
  "resources": [
    {
      "resource_id": "bitbucket-workspace",
      "kind": "api",
      "locator": "https://api.bitbucket.org/2.0/repositories/WORKSPACE",
      "data_class": "pii",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    },
    {
      "resource_id": "bitbucket-repository",
      "kind": "repo",
      "locator": "https://api.bitbucket.org/2.0/repositories/WORKSPACE/REPO_SLUG",
      "data_class": "pii",
      "owner": "REPLACE-WITH-ACCOUNTABLE-HUMAN"
    }
  ],
  "review": {
    "state": "library",
    "date": "2026-09-22",
    "sources": [
      "https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/ (retrieved 2026-09-21)",
      "https://developer.atlassian.com/cloud/bitbucket/rest/api-group-repositories/ (retrieved 2026-09-21)",
      "https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pipelines/ (retrieved 2026-09-21)",
      "https://developer.atlassian.com/cloud/bitbucket/rest/intro/#authentication (retrieved 2026-09-21)",
      "https://developer.atlassian.com/cloud/bitbucket/rest/intro/#filtering (retrieved 2026-09-21)"
    ],
    "reviewer_id": "aaes-eng"
  }
}