Bitbucket Pipelines Enhances CI/CD Security with Granular Step-Level Permissions and Short-Lived Container Tokens

Atlassian has announced a significant update to Bitbucket Pipelines, introducing granular step-level permissions and short-lived container tokens designed to streamline automated workflows while fortifying the security posture of continuous integration and delivery (CI/CD) environments. These updates address long-standing challenges in the DevOps lifecycle, specifically regarding the management of long-lived credentials, the complexity of credential rotation, and the risks associated with broad, default access permissions within automated pipelines.

For many development teams, automating routine tasks such as semantic versioning, software releases, and API-driven deployment triggers has historically required a trade-off between convenience and security. Traditionally, these workflows often necessitated storing sensitive, long-lived credentials as pipeline variables or configuring broad branch permissions for "bot" users. Such practices not only increased the maintenance burden—due to the need for regular credential rotation—but also expanded the potential attack surface if a token or account were to be compromised. The newly introduced features aim to eliminate these pain points by shifting toward a "least privilege" model, where permissions are tightly scoped to specific tasks and valid only for the duration of a specific execution step.

The Shift to Granular Step-Level Permissions

The core of this update is the introduction of step-level permissions, allowing repository administrators and DevOps engineers to define exactly what each individual step in a pipeline is authorized to do. Rather than granting a pipeline broad access to a repository for its entire duration, permissions can now be isolated. This means a "lint" or "test" step can be restricted to read-only access, while only a specific "deploy" or "release" step is granted the authority to push code or interact with sensitive API endpoints.

This granular control is facilitated through a new auth block in the bitbucket-pipelines.yml configuration file. Within this block, users can define system scopes that dictate the capabilities of the step. By explicitly declaring these scopes, teams ensure that even if a build container is compromised, the potential damage is limited to the specific permissions granted to that single step.

Short-Lived Build Container Tokens

To support this granular permission model, Bitbucket Pipelines now provides short-lived OAuth tokens for every build step. Accessible via the BITBUCKET_OAUTH_TOKEN environment variable, these tokens are dynamically generated and isolated to the specific build container. Unlike traditional repository variables that may remain valid for months or years, these container tokens are valid only while the step is running.

The scope of these tokens is strictly limited to the repository where the pipeline is executing. When a developer configures the auth.system.scopes in their pipeline configuration, the BITBUCKET_OAUTH_TOKEN is automatically imbued with those specific permissions. Furthermore, if the pipeline step is configured to clone the repository, the token is automatically granted read:git:bitbucket permissions to facilitate the fetch and clone operations. This automation reduces the manual overhead of managing tokens while ensuring that every step operates with a temporary, secure identity.

Dedicated Git-Only Scopes for Enhanced Security

In a move to further refine the principle of least privilege, Atlassian has introduced new dedicated Git-only scopes. Previously, granting a pipeline the ability to push code often required granting broader repository API access, which might include permissions to modify repository settings or delete branches. The new scopes provide a more targeted alternative:

• read:git:bitbucket: This scope allows a step to perform basic Git operations such as cloning and fetching. It is intended to be the new default for standard build, test, and linting steps that do not require making changes to the source code.
• write:git:bitbucket: This scope, when used in conjunction with the read scope, allows a step to push commits and tags back to the repository. This is specifically designed for release automation, version bumping, and the automated generation of changelogs.

By separating Git operations from broader REST API scopes (such as read:repository:bitbucket or write:repository:bitbucket), Bitbucket ensures that automation tools only have the access necessary for their specific function.

Authorized Pipelines and Restricted Branch Pushes

One of the most impactful changes for release management is the ability to authorize specific pipelines to push to restricted branches. In many organizations, the main or master branch is heavily protected, requiring pull request approvals and restricting direct pushes to prevent accidental or unauthorized changes. However, automated release processes often need to push version updates or tags to these same branches.

Previously, the standard workaround was to create a "bot" user, add that user to the branch restriction exemption list, and store that user’s credentials in the pipeline. The new update allows repository admins to configure branch restrictions to trust pipelines originating from specific source branches. For example, an administrator can now allow any pipeline running on a release/* branch to push directly to the main branch. This eliminates the need for bot users and simplifies the management of protected branches.

Mandatory Timeline and Breaking Changes

Atlassian has outlined a clear roadmap for the transition to these new security standards, including several breaking changes that will require action from users to avoid pipeline failures.

October 28, 2026: This change is already in effect. The "Run a pipeline" API (used to trigger pipelines via POST requests) now strictly requires the pipeline:write scope. This applies to OAuth 2.0 consumers and access tokens. While API tokens, Forge apps, and internal step tokens are not affected by this specific change, teams using external integrations to trigger builds must ensure their tokens have been updated with the correct scope.

November 30, 2026: A significant change to branch restrictions will take place. Currently, some teams allow pipelines to push to restricted branches by adding the "workspace user" to the branch restriction allow list. After this date, this method will no longer function. Pipelines will be denied push access unless the specific source branch of the pipeline is explicitly added under the "Pipelines write access" section of the branch restriction settings.

April 30, 2027: This marks the final transition away from broad default permissions. After this date, any pipeline step that does not include an explicit auth block will no longer receive the broad default permissions (which currently include various repository and pipeline read/write scopes). Instead, a step will only receive the permissions it absolutely needs to clone the repository (read:git:bitbucket). If a step needs to push code, tags, or interact with the Bitbucket API, those permissions must be explicitly declared in the auth.system.scopes block.

Implementation and Migration Requirements

To take advantage of these features and prepare for the upcoming deadlines, Atlassian recommends several immediate actions for Bitbucket users.

First, users operating self-hosted runners must ensure their runners are upgraded to version 6.1.0 or later. These versions contain the necessary logic to handle the new token generation and scope enforcement.

Second, developers should begin auditing their bitbucket-pipelines.yml files. Any step that performs a Git push or an API call should be updated to include an auth block. For example, a step that bumps a version and pushes a tag would now look like this:

- 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

Third, repository administrators should review their branch restriction settings. The move away from bot users toward branch-based pipeline authorization represents a more secure and maintainable path forward. By transitioning to "Pipelines write access" now, teams can avoid the disruption scheduled for late 2026.

Conclusion

The introduction of granular permissions and short-lived tokens in Bitbucket Pipelines represents a shift toward modern, secure-by-default CI/CD practices. By reducing the reliance on long-lived credentials and providing more precise control over pipeline actions, Atlassian is helping organizations implement a more robust defense-in-depth strategy for their software supply chains. While the transition requires configuration changes and adherence to a strict timeline of breaking changes, the long-term benefits include reduced administrative overhead and a significantly improved security profile for automated workflows. Developers and administrators are encouraged to consult the official Bitbucket documentation for step options and branch restrictions to ensure a smooth migration before the 2026 and 2027 enforcement dates.