关于 Container registry
Container registry 将容器映像存储在组织或个人帐户中,并允许你将映像与存储库相关联。 可以选择是从存储库继承权限,还是独立于存储库设置精细权限。 你也可以匿名访问公共容器映像。
Container registry的 URL
如果在 GitHub.com 访问 GitHub,则会将包发布到 ghcr.io。 本文中的示例使用此 URL。
如果在另一个域(例如 octocorp.ghe.com
)访问 GitHub,请将“ghcr.io”替换为 https://containers.SUBDOMAIN.ghe.com
,其中 SUBDOMAIN
是企业的唯一子域。
关于 Container registry 支持
Container registry 目前支持以下容器映像格式:
在安装或发布 Docker 映像时,Container registry 支持外部层,如 Windows 映像。
向 Container registry 验证
Note
GitHub Packages 仅支持使用 personal access token (classic) 进行身份验证。 有关详细信息,请参阅“管理个人访问令牌”。
需要访问令牌才能发布、安装和删除专用、内部和公共包。
可使用 personal access token (classic) 向 GitHub Packages 或 GitHub API 进行身份验证。 创建 personal access token (classic) 时,可根据需要为令牌分配不同的作用域。 有关 personal access token (classic) 的包相关范围的详细信息,请参阅“关于 GitHub Packages 的权限”。
要在 GitHub Actions 工作流程内向 GitHub Packages 注册表验证,您可以使用:
GITHUB_TOKEN
发布与工作流存储库相关联的包。- 范围至少为
read:packages
的 personal access token (classic),用于安装与其他专用存储库(GITHUB_TOKEN
无法访问)关联的包。
在 GitHub Actions 工作流中进行身份验证
此注册表支持精细权限。 对于支持精细权限的注册表,如果 GitHub Actions 工作流使用 personal access token 向注册表进行身份验证,则强烈建议更新工作流以使用 GITHUB_TOKEN
。 有关如何更新通过 personal access token 向注册表进行身份验证的工作流的指南,请参阅“使用 GitHub Actions 发布和安装包”。
Note
GitHub Actions 工作流使用 REST API 删除和还原包的功能目前为 公共预览版,可能随时更改。
如果令牌具有对包的 admin
权限,可以在 GitHub Actions 工作流中使用 GITHUB_TOKEN
,通过 REST API 来删除或还原包。 使用工作流发布包的存储库,以及已经显式连接到包的存储库,会自动获得对存储库中包的 admin
权限。
有关 GITHUB_TOKEN
的详细信息,请参阅“自动令牌身份验证”。 有关在操作中使用注册表时的最佳做法的详细信息,请参阅“GitHub Actions 的安全强化”。
还可以选择为 GitHub Codespaces 和 GitHub Actions 单独授予对包的访问权限。 有关详细信息,请参阅“配置包的访问控制和可见性”和“配置包的访问控制和可见性”。
使用 personal access token (classic)
进行身份验证
Note
GitHub Packages 仅支持使用 personal access token (classic) 进行身份验证。 有关详细信息,请参阅“管理个人访问令牌”。
-
针对要完成的任务,新创具有适当作用域的 personal access token (classic)。 如果您的组织需要 SSO,则必须为新令牌启用 SSO。
Note
默认情况下,在用户界面中为 personal access token (classic) 选择
write:packages
作用域时,repo
作用域也将被选中。repo
作用域提供了不必要和广泛的访问权限,我们建议你尤其避免将其用于 GitHub Actions 工作流。 有关详细信息,请参阅“GitHub Actions 的安全强化”。 解决方法是在以下 URL 的用户界面中仅为 personal access token (classic) 选择write:packages
作用域:https://github.com/settings/tokens/new?scopes=write:packages
。- 选择
read:packages
范围以下载容器映像并读取其元数据。 - 选择
write:packages
范围以下载和上传容器映像并读写其元数据。 - 选择
delete:packages
范围以删除容器映像。
有关详细信息,请参阅“管理个人访问令牌”。
- 选择
-
保存 personal access token (classic)。 建议将令牌保存为环境变量。
export CR_PAT=YOUR_TOKEN
-
使用容器类型的 CLI,登录到
ghcr.io
上的 Container registry 服务。$ echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin > Login Succeeded
推送容器映像
此示例推送最新版本的 IMAGE_NAME
。
docker push ghcr.io/NAMESPACE/IMAGE_NAME:latest
将 NAMESPACE
替换为你希望作为映像限定范围的个人帐户或组织的名称。
此示例推送映像的 2.5
版本。
docker push ghcr.io/NAMESPACE/IMAGE_NAME:2.5
首次发布包时,默认可见性是私有的。 要更改可见性或设置访问权限,请参阅“配置包的访问控制和可见性”。 可以使用用户界面或命令行将已发布的包链接到存储库。 有关详细信息,请参阅“将仓库连接到包”。
从命令行推送容器映像时,默认情况下,该映像不会链接到存储库。 即使使用与存储库名称匹配的命名空间(例如 ghcr.io/octocat/my-repo:latest
)标记映像,也是如此。
将存储库连接到容器包的最简单方法是使用 ${{secrets.GITHUB_TOKEN}}
从工作流发布包,因为包含工作流的存储库会自动链接。 请注意,如果之前已将包推送到同一命名空间,但尚未将包连接到存储库,则 GITHUB_TOKEN
将无权推送包。
要在从命令行发布映像时连接存储库,并确保 GITHUB_TOKEN
在使用 GitHub Actions 工作流时具有适当的权限,建议将标签 org.opencontainers.image.source
添加到 Dockerfile
。 有关详细信息,请参阅本文中的“标记容器映像”和“使用 GitHub Actions 发布和安装包”。
拉取容器映像
通过摘要拉取
为确保始终使用相同的映像,可以通过 digest
SHA 值指定要拉取的确切容器映像版本。
-
若要查找摘要 SHA 值,请使用
docker inspect
或docker pull
并在Digest:
之后复制 SHA 值docker inspect ghcr.io/NAMESPACE/IMAGE_NAME
将
NAMESPACE
替换为要作为映像限定范围的个人帐户或组织的名称。 -
按需要在本地删除映像。
docker rmi ghcr.io/NAMESPACE/IMAGE_NAME:latest
-
拉取映像名称后带有
@YOUR_SHA_VALUE
的容器映像。docker pull ghcr.io/NAMESPACE/IMAGE_NAME@sha256:82jf9a84u29hiasldj289498uhois8498hjs29hkuhs
按名称拉取
docker pull ghcr.io/NAMESPACE/IMAGE_NAME
将 NAMESPACE
替换为要作为映像限定范围的个人帐户或组织的名称。
按名称和版本拉取
显示按名称和 1.14.1
版本标记拉取的映像的 Docker CLI 示例:
$ docker pull ghcr.io/NAMESPACE/IMAGE_NAME:1.14.1
> 5e35bd43cf78: Pull complete
> 0c48c2209aab: Pull complete
> fd45dd1aad5a: Pull complete
> db6eb50c2d36: Pull complete
> Digest: sha256:ae3b135f133155b3824d8b1f62959ff8a72e9cf9e884d88db7895d8544010d8e
> Status: Downloaded newer image for ghcr.io/NAMESPACE/IMAGE_NAME/release:1.14.1
> ghcr.io/NAMESPACE/IMAGE_NAME/release:1.14.1
将 NAMESPACE
替换为要作为映像限定范围的个人帐户或组织的名称。
按名称和最新版本拉取
$ docker pull ghcr.io/NAMESPACE/IMAGE_NAME:latest
> latest: Pulling from NAMESPACE/IMAGE_NAME
> Digest: sha256:b3d3e366b55f9a54599220198b3db5da8f53592acbbb7dc7e4e9878762fc5344
> Status: Downloaded newer image for ghcr.io/NAMESPACE/IMAGE_NAME:latest
> ghcr.io/NAMESPACE/IMAGE_NAME:latest
将 NAMESPACE
替换为要作为映像限定范围的个人帐户或组织的名称。
构建容器映像
此示例生成 hello_docker
映像:
docker build -t hello_docker .
标记容器映像
-
找到要标记的 Docker 映像的 ID。
$ docker images > REPOSITORY TAG IMAGE ID CREATED SIZE > ghcr.io/my-org/hello_docker latest 38f737a91f39 47 hours ago 91.7MB > hello-world latest fce289e99eb9 16 months ago 1.84kB
-
使用映像 ID 以及所需的映像名称和托管目标标记 Docker 映像。
docker tag 38f737a91f39 ghcr.io/NAMESPACE/NEW_IMAGE_NAME:latest
将 NAMESPACE
替换为你希望作为映像限定范围的个人帐户或组织的名称。
标记容器映像
可以使用预定义的注释键向容器映像添加元数据,包括说明、许可证和源存储库。 支持的密钥的值将显示在映像的“包”页面中。
对于大多数映像,可以使用 Docker 标签将注释密钥添加到映像。 有关详细信息,请参阅 Docker 官方文档中的“标签”和 opencontainers/image-spec
存储库中的“预定义的注释密钥”。
对于多架构映像,可以通过将适当的注释密钥添加到映像清单中的 annotations
字段来为映像添加说明。 有关详细信息,请参阅“向多架构映像添加说明”。
Container registry 支持以下注释密钥。
密钥 | 说明 |
---|---|
org.opencontainers.image.source | 与包关联的存储库的 URL。 有关详细信息,请参阅“将仓库连接到包”。 |
org.opencontainers.image.description | 纯文本说明,限制在 512 个字符以内。 此说明将显示在包页中的包名称下方。 |
org.opencontainers.image.licenses | SPDX 许可证标识符,如“MIT”,限制在 256 个字符以内。 许可证将显示在包页的“详细信息”边栏中。 有关详细信息,请参阅 SPDX 许可证列表。 |
若要添加密钥作为 Docker 标签,建议在 Dockerfile
中使用 LABEL
指令。 例如,如果你是用户 octocat
,拥有 my-repo
,并且映像是根据 MIT 许可证的条款分发的,可以在 Dockerfile
中添加以下行:
LABEL org.opencontainers.image.source=https://github.com/octocat/my-repo
LABEL org.opencontainers.image.description="My container image"
LABEL org.opencontainers.image.licenses=MIT
Note
如果发布链接到存储库的包,该包会自动继承链接存储库的访问权限,链接存储库中的 GitHub Actions 工作流会自动获得对包的访问权限,除非你的组织已禁用访问权限的自动继承。 有关详细信息,请参阅“配置包的访问控制和可见性”。
或者,可以使用 docker build
命令在生成时向映像添加标签。
$ docker build \
--label "org.opencontainers.image.source=https://github.com/octocat/my-repo" \
--label "org.opencontainers.image.description=My container image" \
--label "org.opencontainers.image.licenses=MIT"
向多架构映像添加说明
多架构映像是支持多种体系结构的映像。 它的原理是在单一清单中引用一系列映像,其中每个映像都支持不同的体系结构。
多架构映像的“包”页面中的说明是从映像清单中的 annotations
字段获取的。 与 Docker 标签一样,注释提供了一种将元数据与映像相关联的方法,并支持预定义的注释密钥。 有关详细信息,请参阅 opencontainers/image-spec
存储库中的注释。
若要为多架构映像提供说明,请在清单的 annotations
字段中为 org.opencontainers.image.description
键设置一个值,如下所示。
"annotations": {
"org.opencontainers.image.description": "My multi-arch image"
}
例如,以下 GitHub Actions 工作流步骤生成并推送多架构映像。 outputs
参数设置映像的说明。
# 此工作流使用未经 GitHub 认证的操作。
# 它们由第三方提供,并受
# 单独的服务条款、隐私政策和支持
# 文档。
- name: Build and push Docker image
uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
with:
context: .
file: ./Dockerfile
platforms: ${{ matrix.platforms }}
push: true
outputs: type=image,name=target,annotation-index.org.opencontainers.image.description=My multi-arch image
故障排除
- Container registry 的每个层的大小限制为 10 GB。
- Container registry 的上传超时限制为 10 分钟。