docs/content/packages/working-with-a-github-packages-registry/working-with-the-docker-registry.md

title, intro, product, redirect_from, versions

title	intro	product	redirect_from	versions
Working with the Docker registry	You can push and pull your Docker images using the {% data variables.product.prodname_registry %} Docker registry, which uses the package namespace `https://docker.pkg.github.com`.	{% data reusables.gated-features.packages %}	/articles/configuring-docker-for-use-with-github-package-registry /github/managing-packages-with-github-package-registry/configuring-docker-for-use-with-github-package-registry /github/managing-packages-with-github-packages/configuring-docker-for-use-with-github-packages /packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages /packages/guides/container-guides-for-github-packages/configuring-docker-for-use-with-github-packages /packages/guides/configuring-docker-for-use-with-github-packages	free-pro-team enterprise-server github-ae * >=2.22 *

{% data reusables.package_registry.packages-ghes-release-stage %} {% data reusables.package_registry.packages-ghae-release-stage %}

{% data reusables.package_registry.admins-can-configure-package-types %}

{% data reusables.package_registry.docker-vs-container-registry %}

About Docker support

When installing or publishing a Docker image, the Docker registry does not currently support foreign layers, such as Windows images.

{% if currentVersion == "enterprise-server@2.22" %}

Before you can use the Docker registry on {% data variables.product.prodname_registry %}, the site administrator for {% data variables.product.product_location %} must enable Docker support and subdomain isolation for your instance. For more information, see "Managing GitHub Packages for your enterprise."

{% endif %}

Authenticating to {% data variables.product.prodname_registry %}

{% data reusables.package_registry.authenticate-packages %}

{% data reusables.package_registry.authenticate-packages-github-token %}

Authenticating with a personal access token

{% data reusables.package_registry.required-scopes %}

You can authenticate to {% data variables.product.prodname_registry %} with Docker using the docker login command.

To keep your credentials secure, we recommend you save your personal access token in a local file on your computer and use Docker's --password-stdin flag, which reads your token from a local file.

{% if currentVersion == "free-pro-team@latest" %} {% raw %}

$ cat <em>~/TOKEN.txt</em> | docker login https://docker.pkg.github.com -u <em>USERNAME</em> --password-stdin

{% endraw %} {% endif %}

{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %} {% if currentVersion ver_gt "enterprise-server@2.22" %} If your instance has subdomain isolation enabled: {% endif %} {% raw %}

$ cat <em>~/TOKEN.txt</em> | docker login docker.HOSTNAME -u <em>USERNAME</em> --password-stdin

{% endraw %} {% if currentVersion ver_gt "enterprise-server@2.22" %} If your instance has subdomain isolation disabled:

{% raw %}

$ cat <em>~/TOKEN.txt</em> | docker login <em>HOSTNAME</em> -u <em>USERNAME</em> --password-stdin

{% endraw %} {% endif %}

{% endif %}

To use this example login command, replace USERNAME with your {% data variables.product.product_name %} username{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %}, HOSTNAME with the URL for {% data variables.product.product_location %},{% endif %} and ~/TOKEN.txt with the file path to your personal access token for {% data variables.product.product_name %}.

For more information, see "Docker login."

Publishing an image

{% data reusables.package_registry.docker_registry_deprecation_status %}

{% note %}

Note: Image names must only use lowercase letters.

{% endnote %}

{% data variables.product.prodname_registry %} supports multiple top-level Docker images per repository. A repository can have any number of image tags. You may experience degraded service publishing or installing Docker images larger than 10GB, layers are capped at 5GB each. For more information, see "Docker tag" in the Docker documentation.

{% data reusables.package_registry.viewing-packages %}

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

$ docker images
> <&nbsp>
> REPOSITORY        TAG        IMAGE ID       CREATED      SIZE
> <em>IMAGE_NAME</em>        <em>VERSION</em>    <em>IMAGE_ID</em>       4 weeks ago  1.11MB

2. Using the Docker image ID, tag the docker image, replacing OWNER with the name of the user or organization account that owns the repository, REPOSITORY with the name of the repository containing your project, IMAGE_NAME with name of the package or image,{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %} HOSTNAME with the hostname of {% data variables.product.product_location %},{% endif %} and VERSION with package version at build time. {% if currentVersion == "free-pro-team@latest" %}

$ docker tag <em>IMAGE_ID</em> docker.pkg.github.com/<em>OWNER/REPOSITORY/IMAGE_NAME:VERSION</em>

{% else %} {% if currentVersion ver_gt "enterprise-server@2.22" %} If your instance has subdomain isolation enabled: {% endif %}

$ docker tag <em>IMAGE_ID</em> docker.<em>HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION</em>

{% if currentVersion ver_gt "enterprise-server@2.22" %} If your instance has subdomain isolation disabled:

$ docker tag <em>IMAGE_ID</em> <em>HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION</em>

{% endif %} {% endif %} 3. If you haven't already built a docker image for the package, build the image, replacing OWNER with the name of the user or organization account that owns the repository, REPOSITORY with the name of the repository containing your project, IMAGE_NAME with name of the package or image, VERSION with package version at build time,{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %} HOSTNAME with the hostname of {% data variables.product.product_location %},{% endif %} and PATH to the image if it isn't in the current working directory. {% if currentVersion == "free-pro-team@latest" %}

$ docker build -t docker.pkg.github.com/<em>OWNER/REPOSITORY/IMAGE_NAME:VERSION</em> <em>PATH</em>

{% else %} {% if currentVersion ver_gt "enterprise-server@2.22" %} If your instance has subdomain isolation enabled: {% endif %}

$ docker build -t docker.<em>HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION</em> <em>PATH</em>

{% if currentVersion ver_gt "enterprise-server@2.22" %} If your instance has subdomain isolation disabled:

$ docker build -t <em>HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION</em> <em>PATH</em>

{% endif %} {% endif %} 4. Publish the image to {% data variables.product.prodname_registry %}. {% if currentVersion == "free-pro-team@latest" %}

$ docker push docker.pkg.github.com/<em>OWNER/REPOSITORY/IMAGE_NAME:VERSION</em>

{% else %} {% if currentVersion ver_gt "enterprise-server@2.22" %} If your instance has subdomain isolation enabled: {% endif %}

$ docker push docker.<em>HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION</em>

{% if currentVersion ver_gt "enterprise-server@2.22" %} If your instance has subdomain isolation disabled:

$ docker push <em>HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION</em>

{% endif %} {% endif %} {% note %}

Note: You must push your image using IMAGE_NAME:VERSION and not using IMAGE_NAME:SHA.

{% endnote %}

Example publishing a Docker image

{% if currentVersion ver_gt "enterprise-server@2.22" %} These examples assume your instance has subdomain isolation enabled. {% endif %}

You can publish version 1.0 of the monalisa image to the octocat/octo-app repository using an image ID.

{% if currentVersion == "free-pro-team@latest" %}

$ docker images

> REPOSITORY           TAG      IMAGE ID      CREATED      SIZE
> monalisa             1.0      c75bebcdd211  4 weeks ago  1.11MB

# Tag the image with <em>OWNER/REPO/IMAGE_NAME</em>
$ docker tag c75bebcdd211 docker.pkg.github.com/octocat/octo-app/monalisa:1.0

# Push the image to {% data variables.product.prodname_registry %}
$ docker push docker.pkg.github.com/octocat/octo-app/monalisa:1.0

{% else %}

$ docker images

> REPOSITORY           TAG      IMAGE ID      CREATED      SIZE
> monalisa             1.0      c75bebcdd211  4 weeks ago  1.11MB

# Tag the image with <em>OWNER/REPO/IMAGE_NAME</em>
$ docker tag c75bebcdd211 docker.<em>HOSTNAME</em>/octocat/octo-app/monalisa:1.0

# Push the image to {% data variables.product.prodname_registry %}
$ docker push docker.<em>HOSTNAME</em>/octocat/octo-app/monalisa:1.0

{% endif %}

You can publish a new Docker image for the first time and name it monalisa.

{% if currentVersion == "free-pro-team@latest" %}

# Build the image with docker.pkg.github.com/<em>OWNER/REPOSITORY/IMAGE_NAME:VERSION</em>
# Assumes Dockerfile resides in the current working directory (.)
$ docker build -t docker.pkg.github.com/octocat/octo-app/monalisa:1.0 .

# Push the image to {% data variables.product.prodname_registry %}
$ docker push docker.pkg.github.com/octocat/octo-app/monalisa:1.0

{% else %}

# Build the image with docker.<em>HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:VERSION</em>
# Assumes Dockerfile resides in the current working directory (.)
$ docker build -t docker.<em>HOSTNAME</em>/octocat/octo-app/monalisa:1.0 .

# Push the image to {% data variables.product.prodname_registry %}
$ docker push docker.<em>HOSTNAME</em>/octocat/octo-app/monalisa:1.0

{% endif %}

Downloading an image

{% data reusables.package_registry.docker_registry_deprecation_status %}

You can use the docker pull command to install a docker image from {% data variables.product.prodname_registry %}, replacing OWNER with the name of the user or organization account that owns the repository, REPOSITORY with the name of the repository containing your project, IMAGE_NAME with name of the package or image,{% if enterpriseServerVersions contains currentVersion or currentVersion == "github-ae@latest" %} HOSTNAME with the host name of {% data variables.product.product_location %}, {% endif %} and TAG_NAME with tag for the image you want to install.

{% if currentVersion == "free-pro-team@latest" %}

$ docker pull docker.pkg.github.com/<em>OWNER/REPOSITORY/IMAGE_NAME:TAG_NAME</em>

{% else %}

{% if currentVersion ver_gt "enterprise-server@2.22" %} If your instance has subdomain isolation enabled: {% endif %}

$ docker pull docker.<em>HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:TAG_NAME</em>

{% if currentVersion ver_gt "enterprise-server@2.22" %} If your instance has subdomain isolation disabled:

$ docker pull <em>HOSTNAME/OWNER/REPOSITORY/IMAGE_NAME:TAG_NAME</em>

{% endif %} {% endif %}

{% note %}

Note: You must pull the image using IMAGE_NAME:VERSION and not using IMAGE_NAME:SHA.

{% endnote %}

Further reading

• "{% if currentVersion == "free-pro-team@latest" or currentVersion ver_gt "enterprise-server@3.0" %}Deleting and restoring a package{% elsif currentVersion ver_lt "enterprise-server@3.1" or currentVersion == "github-ae@latest" %}Deleting a package{% endif %}"