Authenticate Bitbucket Packages with native Pipelines authentication

When we launched Bitbucket Packages, a native container registry, our goal was to let developers manage code, CI/CD, and container images in one place. Today, we enhance that experience by introducing a feature that removes a common CI/CD authentication friction: you can now authenticate with the Bitbucket Packages container registry using Bitbucket Pipelines’ built-in authentication for Bitbucket Packages, no personal tokens needed.

Why this matters

Managing personal tokens like API tokens for CI/CD authentication involves generating credentials, storing them as variables, rotating them regularly, and risking exposure. Our native support for Bitbucket Packages removes these risks:

• More secure, meaning tokens are short-lived, issued per pipeline step, and expire automatically. No long-lived credentials to leak or rotate.
• Zero setup because the BITBUCKET_PACKAGES_USERNAME and BITBUCKET_PACKAGES_TOKEN variables are available in every pipeline step. No tokens to create or variables to configure.
• Simpler access lets you push and pull packages within your repository automatically. Access scopes to the pipeline’s context, not an individual user account.

How it works

When a Bitbucket Pipeline runs, each step automatically has access to the BITBUCKET_PACKAGES_USERNAME and BITBUCKET_PACKAGES_TOKEN environment variables. You can pass this token directly as your password when authenticating with the Bitbucket Packages container registry at crg.apkg.io.

Here’s a bitbucket-pipelines.yml example that builds and pushes a Docker image using the native Packages integration:

pipelines:
  default:
    - step:
        services:
          - docker
        script:
          - docker login crg.apkg.io -u "$BITBUCKET_PACKAGES_USERNAME" -p "$BITBUCKET_PACKAGES_TOKEN"
          - docker build -t crg.apkg.io/<workspace>/my-container-app:latest .
          - docker image push crg.apkg.io/<workspace>/my-container-app 

Using the Bitbucket Packages Container Publishing pipe

If you prefer a higher-level abstraction, you can also use our dedicated pipe to push container images for an even cleaner configuration:

pipelines:
  default:
    - step:
        services:
          - docker
        script:
          - docker build -t my-container-app:latest .
          - pipe: atlassian/bbc-packages-push-container-image:1.0.7
            variables:
              IMAGE_NAME: "my-container-app"

Getting started

Getting up and running takes just a few steps:

1. Ensure Bitbucket Pipelines is enabled in your repository. Navigate to your repository settings and turn on Pipelines if it isn’t already active.
2. Update your bitbucket-pipelines.yml to use the Packages tokens for authentication, using either the direct docker login approach or the Bitbucket Packages pipe shown above.
3. Push your changes and run the pipeline. Your images will be built, authenticated, and pushed to your workspace’s container registry, all without a single stored credential.

For the full setup details, visit our Bitbucket Packages documentation.

What’s next

We’re just starting with Bitbucket Packages. The container registry supports Docker images, and we’re expanding package support. NPM and Maven packages are coming soon, letting your teams manage language-specific packages alongside containers, code, and CI/CD within Bitbucket. Stay tuned for the announcement.

Share your feedback

We’d love to hear from you. If you have questions about OIDC authentication, Bitbucket Packages, or want to share feedback on what package types and features you’d like to see next, reach out to us through the Atlassian Community. Your input directly shapes what we build.