The Container registry stores container images within your organization or personal account, and allows you to associate an image with a repository. You can choose whether to inherit permissions from a repository, or set granular permissions independently of a repository. You can also access public container images anonymously.
About Container registry support
The Container registry currently supports the following container image formats:
When installing or publishing a Docker image, the Container registry supports foreign layers, such as Windows images.
Authenticating to the Container registry
You need an access token to publish, install, and delete private, internal, and public packages.
You can use a personal access token (classic) to authenticate to GitHub Packages or the GitHub API. When you create a personal access token (classic), you can assign the token different scopes depending on your needs. For more information about packages-related scopes for a personal access token (classic), see About permissions for GitHub Packages.
To authenticate to a GitHub Packages registry within a GitHub Actions workflow, you can use:
GITHUB_TOKEN to publish packages associated with the workflow repository.
A personal access token (classic) with at least read:packages scope to install packages associated with other private repositories (GITHUB_TOKEN can be used if the repository is granted read access to the package. See Configuring a package’s access control and visibility).
Authenticating in a GitHub Actions workflow
This registry supports granular permissions. For registries that support granular permissions, if your GitHub Actions workflow is using a personal access token to authenticate to a registry, we highly recommend you update your workflow to use the GITHUB_TOKEN. For guidance on updating your workflows that authenticate to a registry with a personal access token, see Publishing and installing a package with GitHub Actions.
You can use a GITHUB_TOKEN in a GitHub Actions workflow to delete or restore a package using the REST API, if the token has admin permission to the package. Repositories that publish packages using a workflow, and repositories that you have explicitly connected to packages, are automatically granted admin permission to packages in the repository.
Authenticating with a personal access token (classic)
Create a new personal access token (classic) with the appropriate scopes for the tasks you want to accomplish. If your organization requires SSO, you must enable SSO for your new token.
Select the read:packages scope to download container images and read their metadata.
Select the write:packages scope to download and upload container images and read and write their metadata.
When you push a container image from the command line, the image is not linked to a repository by default. This is the case even if you tag the image with a namespace that matches the name of the repository, such as ghcr.io/octocat/my-repo:latest.
The easiest way to connect a repository to a container package is to publish the package from a workflow using ${{secrets.GITHUB_TOKEN}}, as the repository that contains the workflow is linked automatically. Note that the GITHUB_TOKEN will not have permission to push the package if you have previously pushed a package to the same namespace, but have not connected the package to the repository.
To connect a repository when publishing an image from the command line, and to ensure your GITHUB_TOKEN has appropriate permissions when using a GitHub Actions workflow, we recommend adding the label org.opencontainers.image.source to your Dockerfile. For more information, see “ Labelling container images ” in this article and “ Publishing and installing a package with GitHub Actions.”
Pulling container images
Pull by digest
To ensure you’re always using the same image, you can specify the exact container image version you want to pull by the digest SHA value.
To find the digest SHA value, use docker inspect or docker pull and copy the SHA value after Digest:
docker inspect ghcr.io/NAMESPACE/IMAGE_NAME
Replace NAMESPACE with the name of the personal account or organization to which the image is scoped.
Remove image locally as needed.
docker rmi ghcr.io/NAMESPACE/IMAGE_NAME:latest
Pull the container image with @YOUR_SHA_VALUE after the image name.
Replace NAMESPACE with the name of the personal account or organization to which the image is scoped.
Pull by name and latest version
$ docker pull ghcr.io/NAMESPACE/IMAGE_NAME:latest> latest: Pulling from NAMESPACE/IMAGE_NAME> Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344> Status: Downloaded newer image for ghcr.io/NAMESPACE/IMAGE_NAME:latest> ghcr.io/NAMESPACE/IMAGE_NAME:latest
Replace NAMESPACE with the name of the personal account or organization to which the image is scoped.
Building container images
This example builds the hello_docker image:
docker build -t hello_docker .
Tagging container images
Find the ID for the Docker image you want to tag.
$ docker images> REPOSITORY TAG IMAGE ID CREATED SIZE> ghcr.io/my-org/hello_docker latest 38f737a91f39 47 hours ago 91.7MB> hello-world latest fce289e99eb9 16 months ago 1.84kB
Tag your Docker image using the image ID and your desired image name and hosting destination.
docker tag 38f737a91f39 ghcr.io/NAMESPACE/NEW_IMAGE_NAME:latest
Replace NAMESPACE with the name of the personal account or organization to which you want the image to be scoped.
Labelling container images
You can use pre-defined annotation keys to add metadata including a description, a license, and a source repository to your container image. Values for supported keys will appear on the package page for the image.
For most images, you can use Docker labels to add the annotation keys to an image. For more information, see LABEL in the official Docker documentation and Pre-Defined Annotation Keys in the opencontainers/image-spec repository.
For multi-arch images, you can add a description to the image by adding the appropriate annotation key to the annotations field in the image’s manifest. For more information, see Adding a description to multi-arch images.
The following annotation keys are supported in the Container registry.
A text-only description limited to 512 characters. This description will appear on the package page, below the name of the package.
org.opencontainers.image.licenses
An SPDX license identifier such as “MIT,” limited to 256 characters. The license will appear on the package page, in the “Details” sidebar. For more information, see SPDX License List.
To add a key as a Docker label, we recommend using the LABEL instruction in your Dockerfile. For example, if you’re the user octocat and you own my-repo, and your image is distributed under the terms of the MIT license, you would add the following lines to your Dockerfile:
A multi-arch image is an image that supports multiple architectures. It works by referencing a list of images, each supporting a different architecture, within a single manifest.
The description that appears on the package page for a multi-arch image is obtained from the annotations field in the image’s manifest. Like Docker labels, annotations provide a way to associate metadata with an image, and support pre-defined annotation keys. For more information, see Annotations in the opencontainers/image-spec repository.
To provide a description for a multi-arch image, set a value for the org.opencontainers.image.description key in the annotations field of the manifest, as follows.
"annotations": { "org.opencontainers.image.description": "My multi-arch image"}
For example, the following GitHub Actions workflow step builds and pushes a multi-arch image. The outputs parameter sets the description for the image.
# This workflow uses actions that are not certified by GitHub.# They are provided by a third-party and are governed by# separate terms of service, privacy policy, and support# documentation.- name: Build and push Docker image uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4 with: context: . file: ./Dockerfile platforms: ${{ matrix.platforms }} push: true outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=My multi-arch image
Troubleshooting
The Container registry has a 10 GB size limit for each layer.
The Container registry has a 10 minute timeout limit for uploads.