GitHub Actions 怎样按环境保护部署任务

如果 staging 和 production 共用一个部署任务，最容易出现的风险是：代码已经合并，production job 也已经启动，审批却只能靠口头约定。GitHub Actions 的环境（Environment）可以把审批、分支范围和配置作用域放到同一个边界里。实际做法是先在仓库设置中创建 production，再给部署 job 写入 environment: production；配置了必需审查者后，job 会先处于等待状态，通过审批后才进入 runner。

官方文档：https://docs.github.com/en/actions/concepts/workflows-and-actions/deployment-environments

下面用一个“合并到 main 后部署 production”的场景说明设置路径。文中的界面图是原创操作说明图，不是 GitHub 实际截图。

先把 production 变成一个受保护环境

进入仓库的 Settings → Environments，点击 New environment，创建名为 production 的环境。环境名称要和工作流中的值完全一致；prod、production 是两个不同的名称。

在 production 的配置页，优先设置三类边界：

• Required reviewers：选择真正有发布权限的个人或团队。部署 job 在批准前不会开始。
• Deployment branches and tags：限制只有 main 或受保护分支可以进入 production。
• Environment secrets and variables：把 production 专用配置放在环境下，而不是复制到每个仓库级任务。

保存后，读者应能在环境页看到 Required reviewers 已列出审查者、允许分支已生效，并能区分 Environment secrets 与 Environment variables。这一步只负责定义规则，还没有让任何工作流使用它。

只给部署 job 绑定环境

打开仓库中的工作流文件，在部署 job 级别添加 environment。测试 job 不必绑定 production，这样测试仍可以正常运行，而发布动作会被环境保护规则拦住：

name: deploy

on:
  push:
    branches: [main] # 只让 main 分支触发这个示例

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4 # 拉取待测试的提交
      - name: Run tests
        run: ./scripts/test.sh # 测试失败时不要进入部署 job

  deploy-production:
    needs: test # 先通过测试，再等待 production 规则
    runs-on: ubuntu-latest
    environment:
      name: production # 绑定仓库中已经配置的环境
      url: https://example.com/ # 可选：在部署记录中显示目标地址
    steps:
      - uses: actions/checkout@v4 # 部署前取得同一份代码
      - name: Deploy
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }} # secret 由环境审批后提供
          API_BASE: ${{ vars.API_BASE }} # 非敏感地址使用变量
        run: ./scripts/deploy.sh # 脚本中不要打印 DEPLOY_TOKEN

这里的关键位置是 jobs.deploy-production.environment。把它写在 step 里，或者只在 workflow 顶层写一个同名字段，都不能替代 job 对环境的引用。needs: test 负责测试依赖，environment: production 负责部署保护，两者解决的是不同问题。

在 Actions 页面确认审批真的卡住部署

提交工作流文件后，进入仓库的 Actions，打开对应运行记录。正确的可见状态是：测试 job 先执行；部署 job 显示等待环境审批，而不是已经显示 runner 日志。点击 Review deployments，选择 production，填写必要说明后点击 Approve and deploy，部署 job 才会继续。

批准前看不到部署步骤的 runner 输出，通常就是保护规则正在生效；批准后才会看到部署 step。若 job 已经直接运行，先检查它是否确实引用了正确的环境名称，以及环境的审查规则是否保存成功。

变量和 secret 要按敏感程度分开

环境变量适合放部署目标名、区域标识或公开 API 地址；secret 适合放令牌、密码和私钥。工作流只引用名称，不把真实值写进 YAML：

• ${{ vars.API_BASE }}：读取环境变量，值不应被当作凭据。
• ${{ secrets.DEPLOY_TOKEN }}：读取环境 secret，批准前 job 不应获得它。
• 不要用 echo 输出 secret，也不要把 secret 拼接到命令行参数中；必须传给脚本时，优先使用环境变量。

如果同名变量同时存在于组织、仓库和环境层级，环境层级的变量优先；但环境变量是在 job 启动后才进入 runner，不能拿它去替换 job 派发前就要解析的配置。

两个容易误判的边界

• 审批不是分支保护的替代品：环境可以限制允许部署的分支，但合并前的代码评审仍应由分支保护规则负责。
• 并发不是环境自带的锁：如果需要同一时间只允许一个 production 部署，应另外配置 workflow 或 job 的 concurrency，并使用稳定的组名。
• 测试 job 不会自动继承 production 配置：只有引用环境的 job 才会受该环境规则和配置影响。

常见问题

为什么已经批准了，部署 job 仍然失败？

先分开看两件事：审批只说明环境保护规则通过，不代表部署脚本、runner 网络或凭据本身正确。查看 job 的第一条失败 step，并确认 secret 名称、分支限制和 runner 访问目标都没有写错。

为什么变量在表达式里读不到？

环境级变量只有在引用该环境的 job 启动后才可用。若配置是在 job 派发前解析的字段中使用，应改用仓库或组织层级配置，或者把值放到 job 启动后的 step 中读取。

最终可以用一句话验收：测试可以独立完成，production 部署在 Actions 中先显示等待审批，批准后才进入 runner，并且部署脚本只通过 secrets 和 vars 获取 production 配置。这样环境保护和变量范围才真正形成了同一条部署边界。