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 的作用范围

创建仓库 Secret

可以在仓库设置中创建 Secret,也可以使用 GitHub CLI。下面假设本机已经通过 gh auth login 登录,并在目标仓库目录执行命令。命令会交互式读取 Secret 值,避免把值直接写在命令参数和 Shell 历史中。

bash
gh secret set REGISTRY_TOKEN

预期输出

text
? Paste your secret ********
✓ Set Actions secret REGISTRY_TOKEN for <OWNER>/<REPOSITORY>

实际交互提示可能随 GitHub CLI 版本变化,<OWNER>/<REPOSITORY> 也取决于当前仓库。创建后可以用 gh secret list 确认名称存在,但命令不会显示 Secret 的明文值。

在工作流中安全引用

工作流通过 secrets 上下文引用敏感值。通常先映射到步骤级环境变量,再让命令读取变量,这样可以避免把 Secret 直接拼接到脚本正文中。

yaml
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"

预期输出

text
REGISTRY_TOKEN is configured

这个验证只检查变量是否非空,不打印凭据本身。如果 Secret 名称写错或没有配置,步骤会输出 REGISTRY_TOKEN is missing 并以非零状态退出,从而尽早阻止后续部署。

用环境 Secret 隔离生产凭据

生产凭据不一定应该对所有 Job 可用。创建名为 production 的 GitHub Environment,并在其中保存同名 Secret 后,可以让部署 Job 显式声明环境。以下是依赖已创建 production 环境的片段示例。

yaml
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"

预期输出

text
Production credential is available

如果 production 配置了审批等部署保护规则,Job 还需要满足相应规则后才能继续。这样可以把“能够修改工作流”和“能够实际使用生产环境凭据”进一步分离。

不要把脱敏当成唯一防线

GitHub Actions 会对已知 Secret 值进行日志掩码处理,但安全设计仍应遵循“不主动输出凭据”。不要执行 echo "$TOKEN",也不要开启可能展开敏感变量的调试输出;第三方 Action 同样应选择可信来源并限制其获得 Secret 的范围。

配置完成后,应验证的是“任务能否完成认证”和“缺少凭据时能否安全失败”,而不是设法读取 Secret 明文。仓库 Secret 解决通用凭据存放,环境 Secret 进一步限制部署范围,两者配合可以让敏感数据脱离版本库并减少不必要的暴露。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 Secrets 保存敏感凭据

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

登录哪都通