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

Thanks @Marc! Such a shame this is not possible - seems like such a basic out of the box feature - the reason why you would want to use Bitbucket Packages in the first place in your CI/CD.

@Tomas Stevens here's the link in case you want to follow it: https://community.atlassian.com/forums/Bitbucket-questions/Using-Repository-Access-Tokens-to-pull-Docker-Images-from-the/qaq-p/3246902

nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

Using Bitbucket Packages Docker Images Without Personal API Tokens

James Zhang_w0gqh2

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

Accepted answers

All comments

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

Go to Repository Settings → Access tokens (or Workspace Settings → Access tokens) and create a token with read:repository:bitbucket scope.
Store the token as a secured Pipeline variable (e.g., DOCKER_TOKEN) in your repository or workspace settings.

In your bitbucket-pipelines.yml, authenticate to the registry using the token:

yaml

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

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.

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_w0gqh2

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

James Zhang_w0gqh2

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

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.

Marc_z6he7t

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.

Marc_z6he7t

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.

Tomas Stevens

Hi @Ajay _view26_ ,

Like @Marc I also tried your suggestion but I get authentication errors:

When I use packages.atlassian.net/<workspace>/<image>:<tag> I get the following error:

Container 'build' failed to pull image: 'rpc error: code = NotFound desc = failed to pull and unpack image "packages.atlassian.net/<workspace>/<image>:<tag>": failed to resolve reference "packages.atlassian.net/<workspace>/<image>:<tag>": packages.atlassian.net/<workspace>/<image>:<tag> : not found'

I also tried using crg.apkg.io as the base URL but then I also get a (different) error:

Container 'build' failed to pull image: 'failed to pull and unpack image "crg.apkg.io/<workspace>/<image>:<tag>": failed to resolve reference "crg.apkg.io/<workspace>/<image>:<tag>": failed to authorize: failed to fetch oauth token: unexpected status from GET request to https://crg.apkg.io/auth/registry-token?scope=repository:<workspace>%2F<image>%3Apull&service=crg.apkg.io: 401 Unauthorized'

I like that Bitbucket has its own Container Registry but it seems like a basic feature to be able to then use it in pipelines without needed a named access token.

Tomas Stevens

I havent been able to test it myself - but does this announcement help solve this issue?

https://www.atlassian.com/blog/bitbucket/share-packages-across-your-workspace-internal-packages

Welcome!

It looks like you're new here. Sign in or register to get started.

Quick Links

Find more posts tagged with

cloud

bitbucket

bitbucket-cloud