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.

  • Packages can only be created and used by customers on a monthly plan.

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 by default.

  • A unified-developer experience, where your 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, visit https://id.atlassian.com/manage-profile/security/api-tokens and select Create API token with scopes.

  2. Enter a name and expiry for the token.

  3. Select the required scope read:package:bitbucket.

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

Check out our support documentation for more information on creating 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.

Repository permission

説明

管理

Create a new package and link it to a repository, enabling the package to inherit the permissions of a repository.

書き込み

Push container images onto the Bitbucket package registry.

読み取り

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.

  1. Select Create on the top navigation bar to open the Create dropdown menu.

  2. Select Package from the Create dropdown.

  3. Provide a name for the package in the Package name field.

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

  5. Select Submit to create your package.

認証

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:

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.

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 top navigation bar. 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.

As an example, the following step authenticates using ATLASSIAN_EMAIL and API_TOKEN variables (API_TOKEN should be a secured variable due to its sensitive nature):

- step: name: Build and push Docker image services: - docker script: - export IMAGE_NAME="crg.apkg.io/my-workspace/my-image" - echo $API_TOKEN | docker login crg.apkg.io --user $ATLASSIAN_EMAIL --password-stdin - docker build --tag "$IMAGE_NAME:latest" . - docker image push "$IMAGE_NAME:latest"

Known Limitations

  • Container images and tags cannot be deleted and there is no garbage collection of the storage used by the images to free up storage.

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

さらにヘルプが必要ですか?

アトラシアン コミュニティをご利用ください。