Working with the container registry
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:latestPulling 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:latestViewing 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
DELETEAPI calls and the tags APIs.
Delete a container image and tag
In Bitbucket Cloud, you can delete either a container image tag or the entire container image, including all of its associated tags.
Only users with repository write permission can delete a container image tag.
Delete a container image tag
Deleting a container image tag permanently removes it from Bitbucket Cloud. Once it is deleted, the tag can no longer be pulled. To delete a container image tag:
From the packages list view under the workspace, project, or repository, select the image containing the tag you want to delete.
From the image tags list view, select More actions ().
Select Delete tag, then Confirm.
Deleting a container image tag does not immediately free up the storage.
Delete a container image
Only users with repository admin permission can delete a container image.
Deleting a container image permanently removes it and all of its tags from Bitbucket Cloud. Once deleted, the image and all its tags can no longer be pulled. To delete a container image:
From the packages list view under the workspace, project, or repository, select the image you want to delete.
From the images list view, select More actions ().
Select Delete image, then Confirm.
Deleting a container image tag does not immediately free up the storage.
Free up storage
How container images and tags are stored
Container images and tags are references that point to a manifest (or manifest list). A manifest lists the blobs or layers that make up the image.
Bitbucket container registry stores those blobs once in a blob store within the same workspace. Multiple manifests or images can reference the same blob if layers are identical.
Deleting a container image or tag doesn’t immediately free up space
Deleting an image or tag typically removes the reference to manifest mapping. The manifest and the blobs remain on disk because:
Another tag or manifest might still reference them.
The registry doesn’t immediately delete blobs on tag removal to avoid race conditions (for example, concurrent pushes).
Bitbucket container registry uses a separate cleanup step to safely find blobs that are truly unreferenced.
After you delete tags, the blob files still exist, and storage space is not freed until cleanup runs.
How garbage collection frees the storage
Bitbucket container registry has a garbage collection process to clean up storage. This is triggered when:
A same tag is being pushed
A container image is deleted
A container image tag is deleted
When garbage collection is triggered, a background task is kicked off to identify blobs that are unreferenced and delete them, which frees up storage.
Untagged container image manifests can exist in the system during an interrupted upload, for example, and are eventually automatically cleaned up in the background.
Was this helpful?