CI/CD / 系统课时

向复用工作流传递密钥

向复用工作流传递密钥

复用工作流经常需要访问镜像仓库、云平台或其他受保护服务。关键不是把密钥“传进去”就结束,而是明确调用方允许传递哪些 Secret、被调用工作流如何声明和使用,以及怎样避免权限范围随着复用而失控。

学习目标

  • 使用 workflow_call.secrets 声明复用工作流需要的 Secret
  • 区分显式传递与 secrets: inherit 的权限边界
  • 验证 Secret 已传入,同时避免在日志中暴露敏感值

Secret 如何穿过工作流边界

复用工作流不会因为调用方拥有某个 Secret,就自动获得对它的任意访问权。推荐把边界设计成明确的接口:被调用工作流声明自己需要哪些 Secret,调用方再逐项映射实际保存的 Secret。

调用工作流向复用工作流传递密钥的边界

这种方式把 Secret 当成复用工作流的输入契约,而不是隐藏的全局变量。维护者只看 workflow_call 就能知道该工作流依赖哪些敏感凭据。

显式声明并传递 Secret

下面用两个工作流演示最常见的做法。被调用文件 .github/workflows/publish.yml 先声明 REGISTRY_TOKEN,再在步骤中引用它。

yaml
name: Reusable Publish

on:
  workflow_call:
    secrets:
      REGISTRY_TOKEN:
        required: true

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Verify token is available
        env:
          REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
        run: |
          test -n "$REGISTRY_TOKEN"
          echo "Registry token is available"

这是配置文件示例。生效行为是:如果调用方没有提供必需的 REGISTRY_TOKEN,工作流无法按该接口正常调用;步骤只检查变量是否非空,不打印 Secret 本身。

调用方可以把仓库中保存的 REGISTRY_TOKEN 显式映射给复用工作流:

yaml
name: Release

on:
  workflow_dispatch:

jobs:
  publish:
    uses: ./.github/workflows/publish.yml
    secrets:
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

这是配置文件示例。验证时从 Actions 页面手动触发 Release;如果 Secret 已配置且映射正确,publish job 中的检查步骤应成功,并出现非敏感确认信息。

预期结果

text
Registry token is available

实际日志还会包含 runner 生成的其他内容,因此行号和时间信息可能不同。

什么时候使用 secrets inherit

同一组织或企业范围内调用复用工作流时,可以在调用 job 上使用 secrets: inherit,让被调用工作流访问调用方可用的 Secrets,而不逐项映射。

yaml
jobs:
  publish:
    uses: example-org/ci/.github/workflows/publish.yml@main
    secrets: inherit

这是片段示例,依赖 example-org/ci 中已经存在可调用的 publish.yml,且调用关系满足 GitHub 对 secrets: inherit 的范围要求。它减少重复配置,但也扩大了被调用工作流可接触的 Secret 集合。

因此,对通用基础设施工作流或由多个团队维护的工作流,优先显式列出 Secret 通常更容易审计。只有调用方与被调用方处于清晰的信任边界,而且确实需要传递较多 Secrets 时,再考虑 inherit。

Secret 与环境权限的边界

不要把复用工作流的 Secret 接口和 Environment Secret 混为一谈。workflow_call 不支持通过调用方传入 environment 关键字来替被调用 job 选择环境;如果被调用工作流的 job 自己指定了 environment,该环境关联的 Secret 可能参与该 job 的执行。

还应遵循最小权限原则:Secret 只解决凭据传递问题,GITHUB_TOKEN 的权限则由 permissions 控制。两者需要分别设计,不能因为安全地传递了 Secret,就认为整个工作流已经拥有最小权限。

安全验证而不是打印密钥

排查 Secret 是否传入时,不要使用 echo "$TOKEN" 输出真实内容。更安全的方法是检查变量是否为空,或调用目标服务执行一个不会泄露凭据的认证请求。GitHub 会对已知 Secret 做日志遮蔽,但不应把遮蔽机制当成主动打印凭据的理由。

当一个复用工作流能够用显式的 Secret 契约完成任务、调用方只授予所需凭据,并且日志验证不暴露值时,复用带来的维护收益才不会以扩大敏感信息访问面为代价。

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

目录与阅读设置

阅读设置

17

记录一个想法

向复用工作流传递密钥

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

登录哪都通