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 登录并推送镜像的链路

GitHub Actions 会为 Job 提供 GITHUB_TOKEN。向 GitHub Container Registry 推送包时,可以通过 Job 的 permissions 明确授予 packages: write,避免为了方便而使用权限更大的长期个人令牌。

登录并推送到 GHCR

下面的 Workflow 构建镜像后登录 ghcr.io,再推送带提交 SHA 的镜像。镜像名使用 ${{ github.repository }},即当前仓库的 owner/repository;通过 shell 转成小写,避免容器镜像引用因大写字符而无效。

yaml
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 从标准输入读取令牌,避免把密码直接放在命令参数中。

预期输出

text
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 前缀,构建与推送必须引用同一个名称和标签。可以在推送前确认本地镜像:

bash
docker image inspect "ghcr.io/<owner>/<repository>:<ID>" --format '{{.RepoTags}}'

预期输出

text
[ghcr.io/<owner>/<repository>:<ID>]

这里的 <owner>、<repository> 和 <ID> 分别替换为实际所有者、仓库名和提交 SHA。确认本地标签正确、认证成功且写权限明确后再执行推送,可以把镜像发布中的命名问题、认证问题和授权问题分开定位。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

登录镜像仓库并安全推送

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通