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

Using the docker command, you can authenticate to GitHub Package Registry using your GitHub username and a personal access token with the read:packages and write:packages scopes. Your personal access token must also have the repo scope when the repository is private. For more information, see "Creating a personal access token for the command line."

$ docker login docker.pkg.github.com -u USERNAME -p TOKEN

Publishing a package

GitHub Package Registry supports multiple top-level Docker images per repository.

  1. Determine the image name and ID for your docker image using the docker images command:

    $ docker images
    > < >
    > REPOSITORY        TAG        IMAGE ID       CREATED      SIZE
    > IMAGE_NAME        VERSION    IMAGE_ID       4 weeks ago  1.11MB
  2. 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
  3. Push the image to GitHub Package Registry:

    $ docker push docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION
  4. You can access your packages from this URL by replacing OWNER with your GitHub user or organization name and REPOSITORY with your repository name:

    https://github.com/OWNER/REPOSITORY/packages

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 published or 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 deleting published versions of a package or an entire published package for public repositories. 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."

You can delete private packages via GitHub's API. For more information, see "Access to package version deletion" in the GitHub Developer documentation.

Ask a human

Can't find what you're looking for?

Contact us