我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

Configuring Docker for use with GitHub Packages

You can configure the Docker client to use GitHub Packages to publish and retrieve docker images.

GitHub Packages 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 2.22 和 GitHub One。


GitHub Packages 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 GitHub Packages 可用于 GitHub Free、GitHub Pro、组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud 和 GitHub One。 For more information, see "[GitHub's products](/articles/github-s-products)."

本文内容

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。

About Docker and GitHub Packages

Note: The GitHub Packages Docker registry will be superseded by GitHub Container Registry. To learn how to migrate your existing Docker images and any workflows using them, see "Migrating to GitHub Container Registry for Docker images" and "Getting started with GitHub Container Registry."

When installing or publishing a docker image, GitHub Packages does not currently support foreign layers, such as Windows images.

Authenticating to GitHub Packages

Note: The GitHub Packages Docker registry will be superseded by GitHub Container Registry. To learn how to migrate your existing Docker images and any workflows using them, see "Migrating to GitHub Container Registry for Docker images" and "Getting started with GitHub Container Registry."

您需要访问令牌才能发布、安装和删除 GitHub Packages 中的包。 您可以使用个人访问令牌直接向 GitHub Packages 或 GitHub API 验证您的用户名。 创建个人访问令牌时,可根据需要为令牌分配不同的作用域。

To authenticate using a GitHub Actions 工作流程:

  • 对于包注册表 (PACKAGE-REGISTRY.pkg.github.com/OWNER/REPOSITORY/IMAGE-NAME),您可以使用 GITHUB_TOKEN
  • 对于容器注册表 (ghcr.io/OWNER/IMAGE-NAME),必须使用个人访问令牌。

Authenticating with a personal access token

您必须使用具有适当范围的个人访问令牌才可在 GitHub Packages 中发布和安装。 更多信息请参阅“关于 GitHub Packages”。

You can authenticate to GitHub Packages 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.

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

To use this example login command, replace USERNAME with your GitHub username and ~/TOKEN.txt with the file path to your personal access token for GitHub.

For more information, see "Docker login."

Authenticating with the GITHUB_TOKEN

如果您使用的是 GitHub Actions 工作流程,可以使用 GITHUB_TOKEN 发布和使用 GitHub Packages 中的软件包,而无需存储和管理个人访问令牌。 更多信息请参阅“使用 GITHUB_TOKEN 验证身份”。

Publishing a package

Note: The GitHub Packages Docker registry will be superseded by GitHub Container Registry. To learn how to migrate your existing Docker images and any workflows using them, see "Migrating to GitHub Container Registry for Docker images" and "Getting started with GitHub Container Registry."

GitHub Packages 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.

由于不支持大写字母,因此,即使您的 GitHub 用户或组织名称中包含大写字母,也必须对仓库所有者使用小写字母。

在发布包后,您可以在 GitHub 上查看该包。 更多信息请参阅“查看包”。

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

    $ docker images
    > < >
    > REPOSITORY        TAG        IMAGE ID       CREATED      SIZE
    > IMAGE_NAME        VERSION    IMAGE_ID       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, and VERSION with package version at build time.

    $ docker tag IMAGE_ID docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION
  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, and PATH to the image if it isn't in the current working directory.s

    $ docker build -t docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION PATH
  4. Publish the image to GitHub Packages.

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

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

Example publishing a Docker image

Note: The GitHub Packages Docker registry will be superseded by GitHub Container Registry. To learn how to migrate your existing Docker images and any workflows using them, see "Migrating to GitHub Container Registry for Docker images" and "Getting started with GitHub Container Registry."

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

$ docker images

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

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

# Push the image to GitHub Packages
$ docker push docker.pkg.github.com/octocat/octo-app/monalisa:1.0

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

# Build the image with docker.pkg.github.com/OWNER/REPOSITORY/IMAGE_NAME:VERSION
# 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 GitHub Packages
$ docker push docker.pkg.github.com/octocat/octo-app/monalisa:1.0

Installing a package

Note: The GitHub Packages Docker registry will be superseded by GitHub Container Registry. To learn how to migrate your existing Docker images and any workflows using them, see "Migrating to GitHub Container Registry for Docker images" and "Getting started with GitHub Container Registry."

You can use the docker pull command to install a docker image from GitHub Packages, 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, and TAG_NAME with tag for the image you want to install. 由于不支持大写字母,因此,即使您的 GitHub 用户或组织名称中包含大写字母,也必须对仓库所有者使用小写字母。

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

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

Further reading

此文档对您有帮助吗?

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。