Getting started with packages

Prerequisites to access Bitbucket Packages

Workspace must be linked to an Atlassian organization. Check out our support documentation for more details on how to link your workspace to an Atlassian org.
You must have either a Standard or Premium plan. This feature is available exclusively on Standard and Premium plans with specific limits based on the plan. Check out Bitbucket plans and pricing for packages
Packages can only be created and used by customers on a monthly plan.
Packages are supported only in team-managed workspaces. Read about different workspaces

What is Packages?

Packages brings artifact management directly into Bitbucket Cloud workflows. Development teams can publish, manage, and consume container images, which are linked to specific repositories.

The Bitbucket container registry offers:

A workspace-level namespace for container images that are integrated directly into Bitbucket Cloud.
Repository-linked images that inherit repository permissions (Admin, Write, Read) by default.
A unified-developer experience, where source code, pipelines, and artifacts can live together in one place.

Authentication

You can authenticate with Packages with an API token or with natively through the Bitbucket Pipelines integration.

Create an Atlassian API token in Bitbucket

Pushing to and pulling from the container registry requires you to authenticate your client with an Atlassian API token.

To create an API token, visit https://id.atlassian.com/manage-profile/security/api-tokens and select Create API token with scopes.
Enter a name and expiry for the token.
Select the required scope read:package:bitbucket.
You can also select the write:package:bitbucket scope if you want the token to allow to push images to the registry.

Use the Docker CLI to authenticate

If you are using the Docker CLI to authenticate, use the following command, replacing the default content with your username and Atlassian email address, to configure your credentials:

docker login --username <your_atlassian_account_email_address> crg.apkg.io

When prompted for a password, enter your API token. Once you are authenticated, your credentials will be stored on your machine and used for all future container registry operations.

Check out our support documentation for more information on creating and setting up API tokens.

Bitbucket Pipelines integration

You can push and pull from the container registry within Bitbucket Pipelines using the automatically provided environment variables $BITBUCKET_PACKAGES_USERNAME and $BITBUCKET_PACKAGES_TOKEN.

Enable Bitbucket Pipelines for your repository.
Ensure the bitbucket-pipelines.yml file is in your repository.
The environment variable are available in each pipeline step in your bitbucket-pipelines.yml file via the default variable $BITBUCKET_PACKAGES_USERNAME and $BITBUCKET_PACKAGES_TOKEN.

docker login crg.apkg.io -u "$BITBUCKET_PACKAGES_USERNAME" -p "$BITBUCKET_PACKAGES_TOKEN"

Using the container registry

The container registry operates within a workspace with images linked to individual repositories. Permissions of images will align with the following repository roles: Admin, Write, and Read as described below.

Repository permission	Description
Admin	Can create a new package linked to a repository, allowing the package to inherit the repository's permissions, and can also delete container images.
Write	Can push container images to the Bitbucket package registry, and can also delete container image tags.
Read	Pull container images that have been pushed onto the Bitbucket package registry.

Creating a package

Before pushing and pulling container images from the registry, you will first need to create a package which represents the container image in Bitbucket.

Select Create on the top navigation bar to open the Create dropdown menu.
Select Package from the Create dropdown.
Provide a name for the package in the Package name field.
Select the Repository to link to dropdown and select the repository that you want to link the package to. Note: The package inherits the permissions of the repository which then grants users the same permissions to access the package.
Select Submit to create your package.

Pushing a container image to the registry

In order to push a container image, the image reference must include both the container registry hostname (crg.apkg.io) and the slug of the Bitbucket workspace being pushed to. The following example shows how to build and push an image named my-image to the workspace my-workspace with the docker CLI. The following example also assumes you are in the same directory as your Dockerfile.

docker build --tag crg.apkg.io/my-workspace/my-image:latest .
docker push crg.apkg.io/my-workspace/my-image:latest

Pulling a container image

The following example shows how to pull a container image with docker pull: using the same image name and workspace as the example above.

docker pull crg.apkg.io/my-workspace/my-image:latest

Viewing container images

The images within your container registry can be viewed from the workspace, project, and repository. You will see a list of images that have been pushed to your workspace, project or repository.

There may be some delay between a docker push command completing and the image appearing on the pages.

To view the images within the workspace, select Packages on the left sidebar. This opens the Packages page which lists all the images within the workspace.
To view the images within a project, select Packages on the left sidebar from within the project in which you want to see a list of images.
To view the images within a repository, select Packages on the left sidebar within the repository in which you want to see a list of images.

Viewing image details

Display an image: Select the image name from the list of packages to see details about that image.
Display a tag: Select the tag name to see details specific to that tag associated to the image.

Using the container registry in Pipelines

Pushing an image from a Bitbucket Pipeline requires authenticating the container client, for example Docker, within the pipeline step performing the push.

For example, your bitbucket-pipelines.yml file includes a step that authenticates with the static username BITBUCKET_PACKAGES_TOKENas the secret. The following example assumes a Dockerfile exists in the same directory.

 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 

You can alternatively use the bbc-packages-push-container-image pipe to push an image from your pipeline step. The pipe handles authentication for you.

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"

Known Limitations

The Container registry has a 32 GB size limit for each layer.
The Container registry has a 7-minute timeout limit for uploads.
Bitbucket container registry is not 100% compatible with the Open Container Initiative, specifically we don’t support direct DELETE API calls and the tags APIs.

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community