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.
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.
To authenticate to the Container registry (
ghcr.io) within a GitHub Actions workflow, use the
GITHUB_TOKEN for the best security and experience. If your workflow is using a personal access token to authenticate to a registry, then we highly recommend you update your workflow to use the
For guidance on updating your workflows that authenticate to a registry with a personal access token, see "Upgrading a workflow that accesses a registry using a personal access token."
For more information about the
GITHUB_TOKEN, see "Authentication in a workflow."
For more information about the best practices when using a registry in actions, see "Security hardening for GitHub Actions."
GitHub Packages only supports authentication using a personal access token (classic). For more information, see "Creating a personal access token."
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.
Note: By default, when you select the
write:packagesscope for your personal access token (classic) in the user interface, the
reposcope will also be selected. The
reposcope offers unnecessary and broad access, which we recommend you avoid using for GitHub Actions workflows in particular. For more information, see "Security hardening for GitHub Actions." As a workaround, you can select just the
write:packagesscope for your personal access token (classic) in the user interface with this url:
- Select the
read:packagesscope to download container images and read their metadata.
- Select the
write:packagesscope to download and upload container images and read and write their metadata.
- Select the
delete:packagesscope to delete container images.
For more information, see "Creating a personal access token for the command line."
- Select the
Save your personal access token (classic). We recommend saving your token as an environment variable.
$ export CR_PAT=YOUR_TOKEN
Using the CLI for your container type, sign in to the Container registry service at
$ echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin > Login Succeeded
This example pushes the latest version of
$ docker push ghcr.io/OWNER/IMAGE_NAME:latest
This example pushes the
2.5 version of the image.
$ docker push ghcr.io/OWNER/IMAGE_NAME:2.5
When you first publish a package, the default visibility is private. To change the visibility or set access permissions, see "Configuring a package's access control and visibility."
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 pulland copy the SHA value after
$ docker inspect ghcr.io/OWNER/IMAGE_NAME
Remove image locally as needed.
$ docker rmi ghcr.io/OWNER/IMAGE_NAME:latest
Pull the container image with
@YOUR_SHA_VALUEafter the image name.
$ docker pull ghcr.io/OWNER/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs
$ docker pull ghcr.io/OWNER/IMAGE_NAME
Docker CLI example showing an image pulled by its name and the
1.14.1 version tag:
$ docker pull ghcr.io/OWNER/IMAGE_NAME:1.14.1 > 5e35bd43cf78: Pull complete > 0c48c2209aab: Pull complete > fd45dd1aad5a: Pull complete > db6eb50c2d36: Pull complete > Digest: sha256:ae3b135f133155b3824d8b1f62959ff8a72e9cf9e884d88db7895d8544010d8e > Status: Downloaded newer image for ghcr.io/orgname/image-name/release:1.14.1 > ghcr.io/orgname/image-name/release:1.14.1
$ docker pull ghcr.io/OWNER/IMAGE_NAME:latest > latest: Pulling from user/image-name > Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344 > Status: Downloaded newer image for ghcr.io/user/image-name:latest > ghcr.io/user/image-name:latest
This example builds the
$ docker build -t hello_docker .
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 > ghcr.io/my-username/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/OWNER/NEW_IMAGE_NAME:latest
You can use Docker labels to add metadata including a description, a license, and a source repository to your container image. For more information on Docker labels, see LABEL in the official Docker documentation and Pre-Defined Annotation Keys in the
The following labels are supported in the Container registry. Supported labels will appear on the package page for the image.
|The URL of the repository associated with the package. For more information, see "Connecting a repository to a package."|
|A text-only description limited to 512 characters. This description will appear on the package page, below the name of the package.|
|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 labels to an image, we recommend using the
LABEL instruction in your
Dockerfile. For example, if you're the user
monalisa 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
LABEL org.opencontainers.image.source=https://github.com/monalisa/my-repo LABEL org.opencontainers.image.description="My container image" LABEL org.opencontainers.image.licenses=MIT
Alternatively, you can add labels to an image at buildtime with the
docker build command.
docker build \ --label "org.opencontainers.image.source=https://github.com/monalisa/my-repo" \ --label "org.opencontainers.image.description=My container image" \ --label "org.opencontainers.image.licenses=MIT"