Automating releases, semantic version bumps, and API calls often involves configuring branch permissions and storing long-lived credentials in pipeline variables. Managing credential rotation adds an ongoing maintenance burden.

Today, we’re introducing granular step-level permissions and container tokens in Bitbucket Pipelines to make your automated workflows easier to manage and more secure by default:

  • Push to restricted branches natively: Repository admins can configure branch restrictions to explicitly allow pipelines from selected source branches to push to a restricted branch.
  • Container tokens (BITBUCKET_OAUTH_TOKEN): Use short-lived, container-isolated tokens that are valid only for the duration of the step and limited to the scopes you declare.
  • New dedicated git-only scopes: Follow the principle of least privilege with fine-grained git access scopes.

Breaking changes and actions required

We’re replacing broad default permissions with explicit, targeted access to give you more precise control over what each step can do and which pipelines can push to restricted branches.

Oct 28, 2026 (in effect): The Run a pipeline API now needs the pipeline:write scope, along with pipeline, for OAuth 2.0 consumers and access tokens. API tokens, Forge apps and step tokens (auth.system.scopes) are not affected.

Nov 30, 2026: Adding the workspace user to branch restrictions no longer lets pipelines push. Add the source branch under Pipelines write access instead.

Apr 30, 2027: Steps without an auth block will stop receiving broad default permissions. When cloning is enabled, read:git:bitbucket will still be added automatically. To push commits or tags using the step’s built-in token, explicitly grant write:git:bitbucket in auth.system.scopes.

If you use self-hosted runners, upgrade them to version 6.1.0 or later to use these features.

What’s new

1. Push to restricted branches from authorized pipelines

Repository admins can now configure branch restrictions to trust pipelines from specific source branches. Automated release pipelines (such as a release branch) can push a version bump or changelog commit directly to main, while pull requests and other feature branches remain strictly restricted.

This replaces the need to add bot users to branch exemption lists.

  • Scope requirement: The pushing step must declare read:git:bitbucket and write:git:bitbucket.
  • Configuration: Go to Repository Settings → Branch restrictions, edit or create a restriction, and add the allowed pipeline source branches.

2. Short-lived build container tokens

Each step provides a short-lived OAuth token through the BITBUCKET_OAUTH_TOKEN environment variable. The token is isolated to the build container, limited to the repository running the pipeline, and valid only while the step runs. When you configure auth.system.scopes, the token receives those permissions, plus read:git:bitbucket automatically when cloning is enabled. Steps without an auth block retain broad default permissions until Apr 30, 2027

  • Use it in your build scripts and curl commands instead of managing long-lived repository variables or API tokens:
- step:
    name: Read pull request details
    auth:
      system:
        scopes:
          - read:pullrequest:bitbucket
    script:
      - >
        curl -X GET -H "Authorization: Bearer $BITBUCKET_OAUTH_TOKEN"
        -H "Content-Type: application/json"
        "https://api.bitbucket.org/2.0/repositories/$BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG/pullrequests/$BITBUCKET_PR_ID"
  • Pass BITBUCKET_OAUTH_TOKEN to the trigger-pipeline pipe, so you don’t need to store an access token. This only works for the repository running the pipeline. To trigger a pipeline in another repository, use an access token for that repository.
- step:
    name: Trigger deployment pipeline
    auth:
      system:
        scopes:
          - read:pipeline:bitbucket
          - write:pipeline:bitbucket
    script:
      - pipe: atlassian/trigger-pipeline:5.10.1
        variables:
          BITBUCKET_ACCESS_TOKEN: $BITBUCKET_OAUTH_TOKEN
          REPOSITORY: $BITBUCKET_REPO_SLUG
          REF_TYPE: 'branch'
          REF_NAME: 'main'
          CUSTOM_PIPELINE_NAME: 'deploy'
          WAIT: 'true'

3. New dedicated Git-only scopes

To support the principle of least privilege, we’ve introduced new dedicated scopes for git operations so you don’t need to grant broader repository API access just to push code or tags:

ScopeAllowed ActionsRecommended Use Case
read:git:bitbucketClone and fetchStandard build, test, and lint steps (new default)
write:git:bitbucketPush. Use together with read:git:bitbucket.Release automation, version bumping, automated changelogs

The broader read:repository:bitbucket and write:repository:bitbucket scopes remain available for steps that require REST API access to repository settings or commit statuses.

Already in effect

Triggering pipelines through the API now requires the pipeline write scope

As of Oct 28, 2026 the Run a pipeline API (POST /2.0/repositories/{workspace}/{repo_slug}/pipelines) requires the pipeline:write scope. Before this change, the read-only pipeline scope was enough.

Credential typeScope needed
OAuth consumer, Connect app, or access tokenpipeline andpipeline:write
API token or Forge appA step’s BITBUCKET_OAUTH_TOKENread:pipeline:bitbucket and write:pipeline:bitbucket (no change)

Upcoming breaking changes

1. Pushing to restricted branches by adding the workspace user to branch restrictions

Starting on Nov 30, 2026 pipelines will no longer be able to push to a restricted branch by having the workspace user on the branch restriction’s allow list. Pushes that work this way today will fail.

2. Default step scopes

Starting on Apr 30, 2027 steps that do not explicitly declare an auth.system.scopes block will no longer inherit broad default scopes (read:repository:bitbucket, write:repository:bitbucket, read:pipeline:bitbucket, and write:pipeline:bitbucket). Instead, a step gets only what it needs to clone, plus the scopes you list. When clone is enabled, read:git:bitbucket is added automatically.

Step setupScopes the step gets
Clone enabled, no scopes listedread:git:bitbucket
Clone disabled, no scopes listedNone
Clone enabled, scopes listedread:git:bitbucket and your scopes
Clone disabled, scopes listedOnly your scopes

Note on immediate enforcement: Any step that explicitly defines an auth block adheres to its specified scopes immediately today, plus read:git:bitbucket when clone is enabled. Make sure to list all scopes the step needs.

Actions required

Complete the following migration steps:

  1. Configure Branch Restrictions before Nov 30, 2026 : If your pipeline pushes back to a restricted branch, edit the branch restriction in Repository Settings → Branch restrictions and add the pipeline’s source branch under allowed pipelines.
  2. Audit and update bitbucket-pipelines.yml before Apr 30, 2027 : Add an auth.system.scopes block to any step that pushes commits/tags, calls Bitbucket REST APIs, or triggers downstream pipelines.
- step:
    name: Bump version and push tag
    auth:
      system:
        scopes:
          - read:git:bitbucket
          - write:git:bitbucket
    script:
      - git commit -am "Bump version"
      - git push origin main --tags
  1. Steps that trigger other pipelines:
    1. If the step uses BITBUCKET_OAUTH_TOKEN, add write:pipeline:bitbucket to auth.system.scopes.
    2. If the step uses its own stored credential, such as an access token or OAuth consumer, give that credential the pipeline:write scope.
  2. Upgrade Self-Hosted Runners: If you use self-hosted runners, upgrade them to version 6.1.0 or later. Earlier versions do not support these features.

Need help?

For more details, check out the documentation on Step scopes documentation and Branch restrictions documentation. If you have questions or feedback, reach out on the Atlassian Community or contact Atlassian Support.