Configuring Docker for use with GitHub Package Registry
You can configure the Docker client to use GitHub Package Registry to publish and retrieve docker images.
In this article
- Authenticating to GitHub Package Registry
- Publishing a package
- Receiving package registry events
- Installing a package
- Deleting a package
Authenticating to GitHub Package Registry
docker command, you can authenticate to GitHub Package Registry using either your GitHub username and password or your GitHub username and a personal access token with the
write:packages scopes. Your personal access token must also have the
repo scope when the repository is private.
Note: If you have two-factor authentication enabled, you must use a personal access token instead of a password. For more information, see "Creating a personal access token for the command line."
$ docker login docker.pkg.github.com -u USERNAME -p PASSWORD/TOKEN
Publishing a package
GitHub Package Registry supports multiple top-level Docker images per repository.
Determine the image name and ID for your docker image using the
$ docker images > < > > REPOSITORY TAG IMAGE ID CREATED SIZE > IMAGE_NAME VERSION IMAGE_ID 4 weeks ago 1.11MB >
Using the ID from the previous step, tag the docker image with the endpoint for the repository you want to push it to, the name of the image, and the version. Because upper case letters aren't supported, you must use lowercase letters for the repository owner even if the GitHub user or organization name contains uppercase letters.
$ docker tag IMAGE_ID docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION
Alternatively, you can refer to the local name of your docker image instead of the image ID.
$ docker tag local-image docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION
If you are building a new docker image from scratch, you can specify GitHub Package Registry at build time.
$ docker build -t docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION PATH
Push the image to GitHub Package Registry:
$ docker push docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION
You can access your packages from this URL by replacing
OWNERwith your GitHub user or organization name and
REPOSITORYwith your repository name:
For example, to push version 1.0 of an image called
monalisa to the
octocat/octo-app repository, the commands would be:
$ docker images > REPOSITORY TAG IMAGE ID CREATED SIZE > monalisa 1.0 c75bebcdd211 4 weeks ago 1.11MB # Tag the image with the OWNER/REPO/IMAGE_NAME format $ docker tag c75bebcdd211 docker.pkg.github.com/octocat/octo-app/monalisa:1.0 # Push the image to GitHub Package Registry $ docker push docker.pkg.github.com/octocat/octo-app/monalisa:1.0
Alternatively, you could refer to the local image name.
# Tag the image with the OWNER/REPO/IMAGE_NAME format $ docker tag monalisa:1.0 docker.pkg.github.com/octocat/octo-app/monalisa:1.0 # Push the image to GitHub Package Registry $ docker push docker.pkg.github.com/octocat/octo-app/monalisa:1.0
This is how you would publish if you are building the monalisa docker image from scratch:
# Build the image with the docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION format # Assumes Dockerfile in the current working directory (.) $ docker build -t docker.pkg.github.com/octocat/octo-app/monalisa:1.0 . # Push the image to GitHub Package Registry $ docker push docker.pkg.github.com/octocat/octo-app/monalisa:1.0
Receiving package registry events
You can receive webhook events when a package is
updated. For more information, see "RegistryPackageEvent" in the GitHub Developer documentation.
Installing a package
You can install a docker image from GitHub Package Registry using the
docker pull command with the repository and tag name of the image. Because upper case letters aren't supported, you must use lowercase letters for the repository owner even if the GitHub user or organization name contains uppercase letters.
$ docker pull docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:TAG_NAME
Deleting a package
To avoid breaking projects that may depend on your packages, GitHub Package Registry does not support package deletion or deleting a version of a package. Under special circumstances, such as for legal reasons or to conform with GDPR standards, you can request deleting a package through GitHub Support. Contact GitHub Support using our contact form and the subject line "GitHub Package Registry."