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.
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.
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.
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 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.
この内容はお役に立ちましたか?