CI/CD / 系统课时
登录镜像仓库并安全推送
登录镜像仓库并安全推送
镜像构建成功后,要交给部署环境使用,还需要完成 Registry 认证、镜像命名和推送。本课以 GitHub Container Registry 为例,把凭据留在 GitHub Actions 的权限与 Secret 机制中,并验证镜像已经成功推送。
学习目标
- 理解 Registry 登录凭据为什么不能硬编码进 Workflow
- 使用 GitHub Actions 安全登录 GitHub Container Registry
- 为镜像添加 Registry 标签并执行
docker push
推送链路中的认证边界
推送镜像涉及 GitHub Actions Runner、Registry 和访问凭据三个关键对象。Runner 构建镜像后,需要先向 Registry 完成认证,再把带完整 Registry 地址的镜像层和清单上传。凭据只用于认证,不应该写入 Dockerfile、镜像标签或仓库源码。

GitHub Actions 会为 Job 提供 GITHUB_TOKEN。向 GitHub Container Registry 推送包时,可以通过 Job 的 permissions 明确授予 packages: write,避免为了方便而使用权限更大的长期个人令牌。
登录并推送到 GHCR
下面的 Workflow 构建镜像后登录 ghcr.io,再推送带提交 SHA 的镜像。镜像名使用 ${{ github.repository }},即当前仓库的 owner/repository;通过 shell 转成小写,避免容器镜像引用因大写字符而无效。
name: Build and push image
on:
push:
branches:
- main
permissions:
contents: read
packages: write
jobs:
push-image:
runs-on: ubuntu-latest
steps:
- name: Checkout source
uses: actions/checkout@v4
- name: Set image name
run: echo "IMAGE_NAME=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_ENV"
- name: Build image
run: docker build --tag "$IMAGE_NAME:${{ github.sha }}" .
- name: Log in to GHCR
run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username "${{ github.actor }}" --password-stdin
- name: Push image
run: docker push "$IMAGE_NAME:${{ github.sha }}"这是可运行的 Workflow 片段,但仓库根目录必须已有有效 Dockerfile,且仓库与组织策略需要允许对应的包写入操作。--password-stdin 让 Docker 从标准输入读取令牌,避免把密码直接放在命令参数中。
预期输出
Login Succeeded
...
<ID>: Pushed
<ID>: Pushed
...
<ID>: digest: sha256:<ID> size: <ID><ID> 表示镜像层、摘要和大小等运行时动态值,实际内容会不同。推送成功的关键判断是 docker push 以成功状态退出并返回镜像摘要,而不是要求日志中的层数或顺序与示例完全一致。
凭据应该放在哪里
对于 GHCR,同一仓库 Workflow 通常优先使用 GitHub 自动提供的 GITHUB_TOKEN,并通过 permissions 收窄能力。不要把令牌直接写成 docker login ... --password my-token,也不要提交到 .env、Dockerfile 或 Workflow 明文字段。
如果目标是其他 Registry,则把用户名、密码或访问令牌配置为 GitHub Actions Secrets,并通过 ${{ secrets.NAME }} 引用。即使日志通常会对 Secret 做遮罩,也不应主动输出凭据,因为经过编码、拼接或转换后的值不一定能被可靠遮罩。
推送失败的定位顺序
出现 denied、unauthorized 或权限相关错误时,先区分“没有登录”和“登录成功但没有写权限”。前者检查 Registry 地址、用户名和令牌是否匹配;后者检查 Job 的 packages: write、包权限以及组织策略。
镜像引用错误则应检查完整名称。GHCR 镜像应包含 ghcr.io/owner/repository:tag 这样的 Registry 前缀,构建与推送必须引用同一个名称和标签。可以在推送前确认本地镜像:
docker image inspect "ghcr.io/<owner>/<repository>:<ID>" --format '{{.RepoTags}}'预期输出
[ghcr.io/<owner>/<repository>:<ID>]这里的 <owner>、<repository> 和 <ID> 分别替换为实际所有者、仓库名和提交 SHA。确认本地标签正确、认证成功且写权限明确后再执行推送,可以把镜像发布中的命名问题、认证问题和授权问题分开定位。