Bitbucket Security Guide: Access Tokens, Pipelines and Workspace Settings

Bitbucket holds source code, pipeline definitions and the credentials that deploy them, so a single over-scoped token or unprotected branch can become a production compromise. Atlassian has spent the last two years changing how machines authenticate to Bitbucket Cloud: app passwords have been retired in favour of scoped API tokens, and access tokens and Pipelines OIDC give integrations and builds identities that are not tied to a person. This guide explains workspace roles and permissions, the token types and when to use each, secured variables, OIDC federation to cloud providers, IP allowlisting, branch restrictions, logging and the main differences in Bitbucket Data Center. It is written for workspace administrators, platform engineers and security teams that run or assess Bitbucket.

Key takeaways

• App passwords are gone. Atlassian stopped new app password creation on 9 September 2025 and announced that existing app passwords would stop working on 9 June 2026; integrations must use scoped API tokens or access tokens.
• Prefer resource tokens for automation. Repository, project and workspace access tokens belong to the resource, not to a person, so they survive staff changes and can be limited to one scope with an expiry date.
• Use OIDC for cloud deployments. Bitbucket Pipelines issues a per-step OIDC token that AWS, Google Cloud or Vault can trust, so no cloud keys need to be stored as variables.
• Write access to a deploying branch is production access. Branch restrictions, required merge checks and deployment environments decide whether a pipeline change can reach production without review.
• Several key controls need Premium. IP allowlisting, workspace and project access tokens and enforced merge checks are Premium features in Bitbucket Cloud, which shapes what small teams can enforce.

How identity and access work in Bitbucket

In Bitbucket Cloud the top-level container is the workspace, which holds projects, which hold repositories. People sign in with an Atlassian account; organisations that verify their domain can enforce SSO and policy through Atlassian Administration (Atlassian Guard for SAML SSO and authentication policies). Permissions are granted through workspace user groups, which Atlassian recommends over adding individuals to repositories.

• Default group: new invitees join the default group (Developers in new workspaces). Groups with a default access of Read, Write or Admin are added automatically to every new repository, so check what the default group grants.
• Projects for inheritance: new groups are not added to existing repositories; grant them through project permissions so access follows the project structure.
• Invitations: switch the invite permission to "Admins only" or use domain restrictions so members cannot bring in outside accounts.
• Machine identities: API tokens (tied to a person's Atlassian account), access tokens (tied to a repository, project or workspace), SSH keys and Pipelines OIDC tokens. Each is covered below.

Admin roles and privileged access

Workspace admins can change access controls, add tokens, read and replace workspace variables and switch off IP allowlisting, so they are privileged identities. Repository admins can change branch restrictions and repository variables on their repositories, which lets them alter what a pipeline deploys.

• Few workspace admins: keep a short named list, use the Atlassian organisation's SSO and MFA policy for them and review membership of admin groups quarterly.
• Repository admin is not a team default: developers need Write; Admin on a deploying repository should sit with the owning lead or platform team.
• Organisation versus workspace: Atlassian organisation admins control identity (domains, SSO, user lifecycle); workspace admins control Bitbucket. Align both so a leaver deprovisioned in the identity provider loses Bitbucket access. When a user deletes their account, Bitbucket removes them from repository access lists, but tokens they created and SSH keys on their account must be reviewed separately.
• Shared admin accounts: avoid them. The Nissan source code leak came from an internet-reachable Bitbucket server still using admin/admin, an owner-less privileged account that nobody rotated or monitored.

See the Atlassian Cloud Security Guide.

Integrations, API tokens and service accounts

The end of app passwords

Atlassian's announcement set two dates: from 9 September 2025 no new app passwords could be created, and existing app passwords would stop working on 9 June 2026. The replacement is the API token with scopes, created under Atlassian account settings » Security » Create and manage API tokens » "Create API token with scopes", where the user names the token, sets an expiry date, selects Bitbucket and chooses permissions. API tokens can be scoped to a single workspace, cannot be viewed after creation and cannot be used to log in to bitbucket.org. Any integration still configured with an app password should already have failed; search build servers, deployment tools and scripts for the old credentials and remove them.

Choosing a token type

• Access tokens are not users: they are tied to the resource, do not require two-step verification and each repository, project or workspace can hold at most 25 of each type. That makes them easier to own and audit, and it means expiry and scope are your only limits.
• Set an expiry and least permission: permissions are chosen at creation and cannot be edited, and the token value cannot be viewed again, so rotation is replacement. Record owner, purpose and expiry in your secrets inventory.
• Third-party integrations hold your tokens too: in the Docker Hub breach a single database exposed the Bitbucket and GitHub tokens Docker stored for automated builds, and Docker revoked them all. Inventory OAuth consumers and connected apps and remove unused ones.
• Service accounts: where a tool needs a user identity, create a dedicated, named account under organisation policy rather than reusing a person's. The Cloudflare Thanksgiving breach used a Bitbucket service account that was not rotated after the Okta compromise; the attacker viewed 120 repositories and Cloudflare treated 76 as exfiltrated.

Pipelines secured variables

Pipelines variables exist at workspace, repository and deployment level, with precedence Pipeline, then Deployment, then Repository, then Workspace. Marking a variable Secured masks its value (including URL-encoded variants) in logs, and secured values cannot be edited, only replaced or deleted. Atlassian says never to put credentials in bitbucket-pipelines.yml. Put production secrets in deployment variables on the Production environment rather than repository variables, so only steps assigned to that environment receive them. Masking is not a boundary: any step that can read the variable can send it elsewhere, so the real control is who can change the pipeline file on a branch that runs with those variables.

Pipelines OIDC to cloud providers

A step with oidc: true receives a signed token in BITBUCKET_STEP_OIDC_TOKEN. The identity provider URL and audience are shown in repository settings under Pipelines » OpenID Connect. Per Atlassian's AWS guide:

• Issuer: https://api.bitbucket.org/2.0/workspaces/{WORKSPACE}/pipelines-config/identity/oidc
• Audience: ari:cloud:bitbucket::workspace/{WORKSPACE_UUID} by default; custom audiences can be set (up to 10).
• Subject: {REPOSITORY_UUID}[:{ENVIRONMENT_UUID}]:{STEP_UUID}, where the environment part appears only for deployment steps.
• AWS trust policy: a StringLike condition on the ...:sub key, for example {REPO_UUID}*:{ENVIRONMENT_UUID}:* to allow only that repository's Production deployment steps; the step writes the token to the file named in AWS_WEB_IDENTITY_TOKEN_FILE and sets AWS_ROLE_ARN.

Atlassian recommends restricting trust per repository and per deployment environment, optionally by Pipelines IP ranges, and limiting step duration with max-time. A trust policy that checks only the audience lets every repository in the workspace assume the role. See the Workload Identity Federation Guide.

Workspace settings and network controls

Branch restrictions and merge checks

Branch restrictions limit who can push directly to a branch or pattern (for example main or release/*), who can merge pull requests into it, and prevent deletion and history rewrites. User and group rules override other settings and deny overrides allow. Merge checks add conditions such as approvals and passing builds; enforcing them so merges are blocked is a Premium feature. In the researcher demonstration on the CI/CD pipeline exploitation page, leaked repository credentials let the researcher edit bitbucket-pipelines.yml on master, and the next run used the pipeline's SSH deployment to add the researcher's key to the production server.

IP allowlisting

Under Workspace settings » Access management » Access controls, Premium workspaces can restrict private content to listed IPv4, IPv6 or CIDR ranges. Users outside the list cannot see restricted source or clone, push or pull private repositories; metadata such as pull request titles and repository names is not necessarily restricted. Admins outside the list see a page that lets them switch allowlisting off, so admin accounts need strong authentication. Atlassian says the full Pipelines IP ranges should not be used as a security control; steps of size 4x or larger can set atlassian-ip-ranges: true to use a smaller published set, and Atlassian advises pairing any IP rule with authentication such as OIDC.

Bitbucket Data Center differences

On Data Center, Atlassian recommends one token per integration so a compromised one can be revoked alone, and narrowing token permissions below the creator's own level. Project admins can stop repository admins managing repository tokens (since 8.8). Keep the server off the public internet behind SSO, and patch it like any other internet-facing application.

Logging and detection

Atlassian provides audit logs for Bitbucket Cloud workspaces and organisation-level logs through Atlassian Administration; Data Center has its own audit log. Confirm which events and retention your plan includes and forward them to the SIEM.

On the cloud side, CloudTrail AssumeRoleWithWebIdentity events (or the equivalent in Google Cloud) show which Bitbucket subject assumed which role, which is often the clearest signal of OIDC misuse.

Metrics

• Static cloud keys in Pipelines variables: count trending to zero as OIDC replaces them.
• Tokens without an expiry or owner: target zero across workspace, project and repository tokens.
• Deploying branches with enforced restrictions: 100% with no direct push and required approvals.
• Workspace admins: a short named list, reviewed quarterly.
• Time to revoke a leaver's tokens and keys: hours, measured against the deprovisioning date.

Hardening baseline

1. Inventory: list workspaces, admins, groups and their default access, all tokens and SSH keys, OAuth consumers and every Pipelines variable that holds a credential.
2. Identity: verify domains, enforce SSO and MFA through the Atlassian organisation, restrict invitations to admins or approved domains and review the default group.
3. Replace personal credentials in automation: move integrations from API tokens on personal accounts to access tokens with the narrowest scope and an expiry date; pilot on one repository and keep the old credential until the new one is proven, then revoke it.
4. Protect deploying branches: apply branch restrictions and merge checks to main and release/*, block history rewrites and deletion, and require pull requests for pipeline file changes.
5. Move secrets to deployment environments: put production values in secured deployment variables and restrict which branches can deploy.
6. Adopt OIDC: create one cloud role per repository and environment with sub conditions, test it in a staging environment, then delete the static keys. Roll back by restoring the previous variable only for the duration of the fix.
7. Network controls: on Premium, enable IP allowlisting after confirming office, VPN and CI egress ranges, starting with a small test workspace so admins can confirm the bypass path works.
8. Logging: forward audit logs and cloud role assumption logs and build the detections above.

Common misconfigurations

• Automation on personal credentials: integrations break or keep a leaver's access, and the app password retirement exposed how many still depended on one person.
• Cloud keys as repository variables: every branch's pipeline can read them, and any write user can change the pipeline to exfiltrate them.
• OIDC trust pinned only to the audience: every repository in the workspace can assume the production role.
• Default group with Write or Admin: every new member gets write access to every new repository.
• Unrotated integration accounts after a provider breach: the Cloudflare case shows a single missed service account is enough.
• Self-hosted servers on the internet with default or shared logins: the Nissan leak shows how quickly they are found.

Framework mapping

In CIS Controls v8.1 this work sits mainly in Control 5 (Account Management), Control 6 (Access Control Management) and Control 16 (Application Software Security); in ISO/IEC 27001:2022 Annex A in A.5.17 (authentication information), A.8.2 (privileged access rights) and A.8.25 (secure development life cycle). See the CI/CD Security Guide.

Practitioner checklist

• Confirm no integration still references an app password, and replace any personal API token used by automation with an access token.
• Give every access token an owner, the narrowest scope and an expiry date, recorded in the secrets inventory.
• Restrict workspace admins to a named list under SSO and MFA, and set invitations to admins only or approved domains.
• Check the default group's repository access and remove Write or Admin defaults.
• Enforce branch restrictions and merge checks on every deploying branch, including changes to bitbucket-pipelines.yml.
• Move production secrets to secured deployment variables and cloud access to OIDC with repository and environment sub conditions.
• Enable IP allowlisting on Premium workspaces after testing egress ranges and the admin bypass.
• Forward Bitbucket and cloud role assumption logs to the SIEM and alert on token creation, restriction changes and bulk cloning.
• Review OAuth consumers and third-party apps quarterly and revoke tokens after any provider breach.

Standards and references

• Atlassian: Bitbucket Cloud transitions to API tokens
• Atlassian Support: Access tokens
• Atlassian Support: API tokens
• Atlassian Support: Integrate Pipelines with resource servers using OIDC
• Atlassian Support: Deploy on AWS using Bitbucket Pipelines OpenID Connect
• Atlassian Support: Variables and secrets
• Atlassian: Bitbucket Data Center HTTP access tokens
• NIST: SP 800-53 Rev. 5

Related NHI Mgmt Group resources: CI/CD Security Guide · CI/CD Pipeline Identity Security Guide · GitHub and GitHub Actions Security Guide · Jenkins Security Guide · Atlassian Cloud Security Guide