Using Bitbucket Packages Docker Images Without Personal API Tokens

[James Zhang]

Hi Atlassian Support,

I’m reaching out to understand whether there is a supported way to use Docker images hosted in Bitbucket Packages as base images within Bitbucket Pipelines without relying on personal API tokens.

Current situation:

• Bitbucket Packages provides native authentication for pushing Docker images, which works well.
• However, this native authentication does not appear to support pulling images within Bitbucket Pipelines.
• As a result, to use a Bitbucket-hosted image as a base image in a pipeline, we must use a personal API token.

Problem:

• Personal API tokens have an expiry, which introduces instability into our CI pipelines when tokens expire.
• Managing token rotation across a large number of repositories (hundreds) creates significant operational overhead and maintenance burden.
• This also introduces avoidable risk of unexpected pipeline failures.

What we’re looking for:

• Is there a way to use Bitbucket Packages Docker images in Pipelines using native authentication (similar to push), workspace-level credentials, or service accounts?
• Alternatively, are there recommended best practices to avoid using expiring personal API tokens for this use case?

If this is not currently supported, we would appreciate any guidance on:

• Roadmap plans for improving authentication between Bitbucket Pipelines and Bitbucket Packages
• Suggested architectural workarounds (e.g., workspace tokens, OIDC, or other mechanisms)

This capability would significantly improve reliability and reduce maintenance effort for teams managing multiple repositories.

Thanks in advance for your help.

Kind regards

[Arkadiusz Wroblewski]

Hello and welcome to the Community @James Zhang 

You should be a bit careful with the current reply in my opinion.

What Atlassian clearly documents today is that Bitbucket Packages uses crg.apkg.io, and that Pipelines has built-in package credentials through BITBUCKET_PACKAGES_USERNAME and BITBUCKET_PACKAGES_TOKEN. 

What you do not really see documented is repository, project, or workspace access tokens as the standard auth method for Bitbucket Packages registry access. Atlassian documents those tokens for Bitbucket API and Git usage. 

You shouldn't treat that token suggestion as confirmed. You are on firmer ground if you stick to the Packages auth methods Atlassian actually documents.

Can you clarify one point? do you need that image as the actual top-level pipeline image, or do you only need to pull it later inside the step? If it is the top-level build image, you would want Atlassian staff to confirm the supported auth path before you roll that out across hundreds of repos..... 

[Ajay _view26_]

Hi @James Zhang 

Welcome to the community!

This is a common pain point. The good news is there is a supported way to avoid personal API tokens for this — use Repository Access Tokens or Workspace Access Tokens, which are non-personal and can be rotated/managed independently.

Recommended solution 

1. Go to Repository Settings → Access tokens (or Workspace Settings → Access tokens) and create a token with read:repository:bitbucket scope.
2. Store the token as a secured Pipeline variable (e.g., DOCKER_TOKEN) in your repository or workspace settings.
3. In your bitbucket-pipelines.yml, authenticate to the registry using the token:
   yaml

   image:
     name: packages.atlassian.net/your-image:tag
     username: x-token-auth
     password: $DOCKER_TOKEN

This avoids personal tokens entirely. Workspace-level tokens are the best option for hundreds of repos since one token can be used across all of them via a workspace-level pipeline variable.