CI/CD / 系统课时
向复用工作流传递密钥
向复用工作流传递密钥
复用工作流经常需要访问镜像仓库、云平台或其他受保护服务。关键不是把密钥“传进去”就结束,而是明确调用方允许传递哪些 Secret、被调用工作流如何声明和使用,以及怎样避免权限范围随着复用而失控。
学习目标
- 使用
workflow_call.secrets声明复用工作流需要的 Secret - 区分显式传递与
secrets: inherit的权限边界 - 验证 Secret 已传入,同时避免在日志中暴露敏感值
Secret 如何穿过工作流边界
复用工作流不会因为调用方拥有某个 Secret,就自动获得对它的任意访问权。推荐把边界设计成明确的接口:被调用工作流声明自己需要哪些 Secret,调用方再逐项映射实际保存的 Secret。

这种方式把 Secret 当成复用工作流的输入契约,而不是隐藏的全局变量。维护者只看 workflow_call 就能知道该工作流依赖哪些敏感凭据。
显式声明并传递 Secret
下面用两个工作流演示最常见的做法。被调用文件 .github/workflows/publish.yml 先声明 REGISTRY_TOKEN,再在步骤中引用它。
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 显式映射给复用工作流:
name: Release
on:
workflow_dispatch:
jobs:
publish:
uses: ./.github/workflows/publish.yml
secrets:
REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}这是配置文件示例。验证时从 Actions 页面手动触发 Release;如果 Secret 已配置且映射正确,publish job 中的检查步骤应成功,并出现非敏感确认信息。
预期结果
Registry token is available实际日志还会包含 runner 生成的其他内容,因此行号和时间信息可能不同。
什么时候使用 secrets inherit
同一组织或企业范围内调用复用工作流时,可以在调用 job 上使用 secrets: inherit,让被调用工作流访问调用方可用的 Secrets,而不逐项映射。
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 契约完成任务、调用方只授予所需凭据,并且日志验证不暴露值时,复用带来的维护收益才不会以扩大敏感信息访问面为代价。