CI/CD / 系统课时
用 Secrets 保存敏感凭据
用 Secrets 保存敏感凭据
流水线经常需要访问镜像仓库、云平台或第三方 API,但密码和令牌不能直接写进工作流文件。本节使用 GitHub Actions Secrets 保存敏感值,并区分仓库 Secret 与环境 Secret 的适用范围,最终让工作流只在运行时取得凭据。
学习目标
- 理解 Secrets 与工作流文件分离敏感数据的原因
- 配置并引用仓库 Secret 和环境 Secret
- 避免日志输出、权限范围和缺失 Secret 带来的常见风险
Secret 不应该进入仓库
把令牌直接写入 .github/workflows/deploy.yml,即使仓库是私有的,也会让敏感值进入 Git 历史。后续删除文件中的明文并不等于历史提交中的凭据消失,因此正确做法是让仓库保存“如何引用凭据”,而由 GitHub 单独保存实际值。
仓库级 Secret 适合多个工作流共同使用的仓库凭据。环境 Secret 则绑定到 GitHub Environment,例如 staging 或 production;当部署任务声明对应环境后,才使用该环境范围内的 Secret。环境还可以与部署保护规则结合,缩小生产凭据的使用范围。

创建仓库 Secret
可以在仓库设置中创建 Secret,也可以使用 GitHub CLI。下面假设本机已经通过 gh auth login 登录,并在目标仓库目录执行命令。命令会交互式读取 Secret 值,避免把值直接写在命令参数和 Shell 历史中。
gh secret set REGISTRY_TOKEN预期输出
? Paste your secret ********
✓ Set Actions secret REGISTRY_TOKEN for <OWNER>/<REPOSITORY>实际交互提示可能随 GitHub CLI 版本变化,<OWNER>/<REPOSITORY> 也取决于当前仓库。创建后可以用 gh secret list 确认名称存在,但命令不会显示 Secret 的明文值。
在工作流中安全引用
工作流通过 secrets 上下文引用敏感值。通常先映射到步骤级环境变量,再让命令读取变量,这样可以避免把 Secret 直接拼接到脚本正文中。
name: use-secret
on:
workflow_dispatch:
jobs:
verify:
runs-on: ubuntu-latest
steps:
- name: Verify secret is available
env:
REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
run: |
if [ -z "$REGISTRY_TOKEN" ]; then
echo "REGISTRY_TOKEN is missing"
exit 1
fi
echo "REGISTRY_TOKEN is configured"预期输出
REGISTRY_TOKEN is configured这个验证只检查变量是否非空,不打印凭据本身。如果 Secret 名称写错或没有配置,步骤会输出 REGISTRY_TOKEN is missing 并以非零状态退出,从而尽早阻止后续部署。
用环境 Secret 隔离生产凭据
生产凭据不一定应该对所有 Job 可用。创建名为 production 的 GitHub Environment,并在其中保存同名 Secret 后,可以让部署 Job 显式声明环境。以下是依赖已创建 production 环境的片段示例。
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
steps:
- name: Run deployment command
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
run: |
test -n "$DEPLOY_TOKEN"
echo "Production credential is available"预期输出
Production credential is available如果 production 配置了审批等部署保护规则,Job 还需要满足相应规则后才能继续。这样可以把“能够修改工作流”和“能够实际使用生产环境凭据”进一步分离。
不要把脱敏当成唯一防线
GitHub Actions 会对已知 Secret 值进行日志掩码处理,但安全设计仍应遵循“不主动输出凭据”。不要执行 echo "$TOKEN",也不要开启可能展开敏感变量的调试输出;第三方 Action 同样应选择可信来源并限制其获得 Secret 的范围。
配置完成后,应验证的是“任务能否完成认证”和“缺少凭据时能否安全失败”,而不是设法读取 Secret 明文。仓库 Secret 解决通用凭据存放,环境 Secret 进一步限制部署范围,两者配合可以让敏感数据脱离版本库并减少不必要的暴露。