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 either your GitHub username and password or 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.

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.

  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.

    $ docker tag IMAGE_ID docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION
  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

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.

$ 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."

Ask a human

Can't find what you're looking for?

Contact us