What are packages?

Packages are a built-in container registry that 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.

Create an Atlassian API token

To authenticate packages, an Atlassian API token with specific scopes is required.

1. To create an API token, visithttps://id.atlassian.com/manage-profile/security/api-tokens and selectCreate API token with scopes.

2. Enter a name and expiry for the token.

3. Select the required scoperead:package:bitbucket.

4. You can also select thewrite:package:bitbucket scope if you want the token to allow to push images to the registry.

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

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.

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.

1. SelectCreateon the top navigation bar to open theCreatedropdown menu.

2. SelectPackagefrom theCreatedropdown.

3. Provide a name for the package in thePackage namefield.

4. Select theRepository to link todropdown 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.

5. SelectSubmitto create your package.

Authentication

Pushing to and pulling from the container registry requires you to authenticate your client with an Atlassian API token. If you are using the Docker CLI, use the following command, replacing the default content with your username and Atlassian email address, to configure your credentials:

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.

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 namedmy-image to the workspacemy-workspace with thedocker CLI. The following example also assumes you are in the same directory as yourDockerfile.

Pulling a container image

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

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.

• To view the images within the workspace, selectPackageson the top navigation bar. This opens the Packages page which lists all the images within the workspace.

• To view the images within a project, selectPackageson the left sidebar from within the project in which you want to see a list of images.

• To view the images within a repository, selectPackageson 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.

As an example, the following step authenticates usingATLASSIAN_EMAIL andAPI_TOKENvariables (API_TOKEN should be a secured variable due to its sensitive nature):

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 theOpen Container Initiative, specifically we don’t support directDELETE API calls and the tags APIs.