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

[Marc Lopez]

Hello,
I have a similar problem but it only fails when using repository access tokens from outside the pipeline.

I replied with more detail in this same post.

[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..... 

[James Zhang]

@Arkadiusz Wroblewski  Thanks for the information. Yes I want the package image to be used in top level.

[Arkadiusz Wroblewski]

@James Zhang 

before you roll this out across hundreds of repos, you should get this confirmed by Atlassian.

For your exact case, the open question is whether that token approach is really supported for the top-level pipeline image, not just for image pulls later in the step.

So I would not build around that yet. You should ask Atlassian to confirm the supported setup first.

[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.

[James Zhang]

@Ajay _view26_ Thanks for the response. Let me try that.

[Marc Lopez]

Hi @Ajay _view26_ 

I have a Bitbucket Pipeline in my repository that successfully builds a Docker image and pushes it to the Bitbucket Container Registry.

I can pull the image from my laptop using a Personal API Token with the read:package:bitbucket scope, so the registry itself is working correctly. However, I would prefer not to use my personal token for this use case.

To avoid that, I created a Repository Access Token. The available scopes only seem to include read:repository (I could not find any package/container registry related scope), but authentication always fails when I try to pull the image using this token.

I also tried authenticating with both:

x-token-auth

<repo-uuid>@bots.bitbucket.org

for docker login, based on your suggestion, but I still receive authorization errors.

Am I missing a required scope or configuration for pulling images from the Bitbucket Container Registry using Repository Access Tokens?

Thanks.