GitHub Actions 如何用环境保护规则控制部署审批

GitHub Actions 的生产部署审批不需要把“等待人工确认”写成一个脚本步骤。更稳妥的做法是：先给仓库创建 production 环境，在环境上设置必须审批人、禁止自批与可部署分支，然后让部署 job 通过 environment 引用它。这样保护规则没有通过时，job 不会被发送到 runner，也不能读取该环境里的密钥。

官方操作说明可从下面两个地址核对：

# 环境创建与保护规则
https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments

# 审批或拒绝等待中的部署
https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/review-deployments

先确认功能范围：公有仓库在当前 GitHub 计划中普遍可使用环境、环境密钥和部署保护规则；私有或内部仓库需要相应付费计划，而 Required reviewers、Wait timer 等规则的可用性还会受到计划与仓库可见性影响。若界面中没有本文选项，应先查看官方页面的 “Who can use this feature”，不要用脚本绕过。

一、审批门禁实际控制什么

环境保护规则作用在“引用环境的 job”上，而不是作用在整个工作流文件上。假设工作流先构建、再部署，只有 deploy job 写了 environment: production，那么构建可以正常完成，部署会在保护规则处暂停。审批通过后，部署 job 才获得以下条件：

• 进入 runner 队列并开始执行步骤；
• 读取 production 环境中保存的 secrets；
• 创建与该环境关联的 deployment 和 deployment status。

这个边界很重要：只在工作流名称、job 名称或脚本参数里写“production”不会自动触发审批，必须使用 job 级 environment 字段。

二、步骤一：创建 production 环境

1. 进入目标仓库主页，点击仓库顶部的 Settings。看不到 Settings 时，可先展开仓库导航的下拉菜单。
2. 在左侧栏点击 Environments。
3. 点击 New environment。
4. 名称输入 production，点击 Configure environment。

环境名称不区分大小写，但工作流中的名称最好与界面保持完全一致，减少排查时的歧义。不要依赖“运行时自动创建环境”：官方说明指出，工作流引用一个不存在的环境时可能自动创建它，但这个新环境通常没有保护规则和密钥，不能替代管理员预先配置。

三、步骤二：设置必须审批与禁止自批

在 production 的配置页找到 Deployment protection rules，按下面顺序操作：

1. 勾选 Required reviewers。
2. 搜索并加入负责发布的用户或团队，例如 release-managers。
3. 勾选 Prevent self-review，避免工作流触发者审批自己的部署。
4. 点击 Save protection rules。

当前官方规则允许最多加入 6 个用户或团队，只要其中一名 required reviewer 批准，审批条件就通过。因此，“加入两组 reviewer”并不等于必须双人会签。如果你的制度要求两人分别确认，需要通过组织流程或自定义部署保护规则另行实现，不能把默认 Required reviewers 误解成多签。

页面若提供 Wait timer，还可以设置批准前必须等待的分钟数；如果希望管理员也不能越过保护规则，可取消 Allow administrators to bypass configured protection rules。这两项是否出现同样取决于计划与仓库类型。

四、步骤三：限制允许部署的分支或标签

审批解决“谁允许部署”，分支规则解决“哪段代码允许部署”。仍在 production 环境页，找到 Deployment branches and tags：

1. 在下拉框选择 Selected branches and tags。
2. 点击 Add deployment branch or tag rule。
3. Ref type 选择 Branch，名称模式输入 main。
4. 点击 Add rule。

分支与标签规则必须分别创建。若团队通过版本标签发版，可以再添加 Ref type 为 Tag 的规则，例如 v*；不要只写一个看似同时匹配分支与标签的模式。

五、步骤四：让 deploy job 引用 production

把部署工作流放在仓库的 .github/workflows 目录。下面示例使用手动触发，重点是 deploy job 的 environment 字段：

name: deploy-production

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    # 名称必须对应 Settings > Environments 中的 production
    environment:
      name: production
    steps:
      - name: Checkout source
        uses: actions/checkout@v4

      - name: Deploy
        # 示例命令仅表示部署入口，请替换为项目自己的安全脚本
        run: ./scripts/deploy.sh

如果只需要环境名称，也可以简写为：

jobs:
  deploy:
    runs-on: ubuntu-latest
    # 简写与 environment.name: production 等价
    environment: production
    steps:
      - name: Deploy
        run: ./scripts/deploy.sh

工作流语法还支持在环境对象中加入 url，用于把部署地址写入 deployment status。审批门禁本身只依赖环境名称，不必为了审批额外填写 URL。

六、步骤五：在运行页批准或拒绝

1. 进入仓库的 Actions，打开 deploy-production。
2. 点击 Run workflow，从符合环境分支规则的分支触发。
3. 构建完成后，deploy job 显示 Waiting，页面出现审核通知。
4. 审批人点击 Review deployments。
5. 勾选 production，可填写评论，然后选择 Approve and deploy 或 Reject。

点击 Approve and deploy 后，只有在其他保护规则也通过时 job 才继续，并从此刻起能够访问环境密钥；点击 Reject 会使工作流失败。启用了 Prevent self-review 时，触发该 workflow run 的账号不能完成自己的审批，应由另一名 required reviewer 操作。

七、如何确认配置真的生效

完成一次测试运行后，至少核对下面四个可观察结果：

• 审批前：deploy job 是 Waiting，而不是已经在 runner 中执行。
• 审批入口：运行页出现 Review deployments，并能选择 production。
• 批准后：job 状态从 Waiting 进入 Queued 或 In progress，随后执行部署步骤。
• 拒绝后：job 不执行部署脚本，workflow run 以失败状态结束。

不要用“页面上出现 production 字样”作为唯一成功标准。真正的门禁证据是 job 在审批前没有进入 runner，环境密钥也没有提前提供。

八、常见问题排查

1. 工作流直接开始部署，没有等待审批

先打开工作流 YAML，确认 environment 写在执行部署的 job 下，而不是全局 env、步骤参数或普通字符串中。再确认环境名称为 production，并且该环境已经保存 Required reviewers。

2. 找不到 Required reviewers

检查仓库是公有、私有还是内部仓库，并核对当前 GitHub 计划。官方页面明确提示：环境的基础能力、私有仓库可用性以及 Required reviewers、Wait timer 等保护规则的可用性并不完全相同。

3. 自己看得到审批按钮，但不能批准

如果该账号触发了本次运行，而环境启用了 Prevent self-review，这是预期行为。让另一名被列为 required reviewer 的用户或团队成员审批，不要关闭规则来绕过制度。

4. 显示分支不允许部署

检查运行使用的 Git ref 是否匹配 Deployment branches and tags。手动触发时要在 Run workflow 下拉框选择允许的分支；分支规则和标签规则分开匹配。

5. 审批前读不到环境 secret

这正是环境保护边界：引用环境的 job 只有在保护规则通过后才能访问环境 secrets。若构建阶段需要公共配置，应使用仓库变量或构建 job 自己的权限模型，不应提前暴露生产密钥。

九、结论

GitHub Actions 的生产审批可以归纳为三层：environment 绑定部署对象、protection rules 决定谁能放行、deployment branches and tags 决定哪些引用可进入。只要 deploy job 明确引用 production，审批前 Waiting、审批后才进 runner，并且生产密钥直到规则通过才可用，这套门禁就形成了完整闭环。

最后建议把“禁止自批、只允许 main、管理员是否可绕过、审批评论规范”写进团队发布制度。界面规则负责强制执行，制度负责解释何时批准、何时拒绝，两者结合才能让部署审批既安全又可追溯。