手动工作流审批

暂停GitHub Actions工作流，并在继续之前要求一个或多个审批人进行手动审批。

这是部署或发布流水线中非常常见的功能。尽管GitHub提供了这种功能，但它需要使用环境，而且如果你想在私有仓库中使用，则需要GitHub Enterprise。这个action提供了无需使用环境的手动审批，并且可以在私有仓库中免费使用。

注意：审批持续时间受工作流72小时超时限制的约束。因此在确定审批人需要多快响应时请记住这一点。

此action的工作方式如下：

工作流到达manual-approval action。
manual-approval会在所属仓库中创建一个问题，并将其分配给审批人。
如果所有审批人都用批准关键词回复，工作流将继续。
如果任何审批人用拒绝关键词回复，工作流将以失败状态退出。

批准关键词 - "approve", "approved", "lgtm", "yes"
拒绝关键词 - "deny", "denied", "no"

这些关键词不区分大小写，可以选择性地在末尾加上句号或感叹号。

在所有情况下，manual-approval都会关闭最初创建的GitHub问题。

使用方法

steps:
  - uses: trstringer/manual-approval@v1
    with:
      secret: ${{ github.TOKEN }}
      approvers: user1,user2,org-team1
      minimum-approvals: 1
      issue-title: "将v1.3.5从staging部署到prod"
      issue-body: "请批准或拒绝部署版本v1.3.5。"
      exclude-workflow-initiator-as-approver: false
      additional-approved-words: ''
      additional-denied-words: ''

approvers是所有需要审批人的逗号分隔列表。审批人可以是用户或组织团队。（注意：必须授予所需审批人在仓库中设置为审批人的权限。如果添加的审批人没有此权限，运行此action时会收到HTTP/402 Validation Failed错误）
minimum-approvals是一个整数，设置继续工作流所需的最少审批数。默认为所有审批人。
issue-title是一个字符串，将附加到问题标题后。
issue-body是一个字符串，将添加到问题正文前。
exclude-workflow-initiator-as-approver是一个布尔值，表示是否应从最终审批人列表中过滤掉工作流发起人（由GITHUB_ACTOR环境变量确定）。这是可选的，默认为false。将其设置为true可以防止approvers列表中的用户能够自我批准工作流。
additional-approved-words是一个逗号分隔的字符串列表，用于扩展表示批准的词典。这是可选的，默认为空字符串。
additional-denied-words是一个逗号分隔的字符串列表，用于扩展表示拒绝的词典。这是可选的，默认为空字符串。

使用自定义词语

GitHub有丰富的表情符号库，这些都可以在额外的批准词或拒绝词中使用。GitHub会以文本版本存储一些值 - 例如:shipit:。其他表情符号，GitHub会以Unicode形式存储，如✅。为了获得无缝体验，建议您将自定义词添加到GitHub评论中，然后将其从评论复制回actions配置yaml中。

组织团队审批人

如果您想将approvers设置为组织团队，则需要采用不同的方法。默认的GitHub Actions自动令牌没有列出团队成员的必要权限。如果您想使用这个功能，则需要从具有正确权限集的GitHub App生成令牌。

创建一个对组织成员具有只读访问权限的GitHub App。创建应用后，将应用ID添加为仓库密钥。在GitHub App设置中，生成私钥并将其也添加为仓库密钥。您可以使用tibdex/github-app-token GitHub Action获取应用令牌：

注意：GitHub App令牌在1小时后过期，这意味着审批持续时间不能超过60分钟，否则作业将因凭证无效而失败。参见文档。

jobs:
  myjob:
    runs-on: ubuntu-latest
    steps:
      - name: 生成令牌
        id: generate_token
        uses: tibdex/github-app-token@v1
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.APP_PRIVATE_KEY }}
      - name: 等待审批
        uses: trstringer/manual-approval@v1
        with:
          secret: ${{ steps.generate_token.outputs.token }}
          approvers: myteam
          minimum-approvals: 1

超时

如果您想强制工作流暂停超时，可以在步骤级别或作业级别指定timeout-minutes。例如，如果你希望手动审批步骤在一小时后超时，你可以这样做：

steps:
  - uses: trstringer/manual-approval@v1
    timeout-minutes: 60
    ...

权限

为了让操作能够在你的项目中创建新的问题，请确保操作对问题有写入权限。你可能需要在工作流中添加以下内容：

permissions:
  issues: write

有关权限的更多信息，请查看GitHub文档。

限制

虽然工作流暂停时，它仍会继续消耗最大并发作业中的一个并发作业分配。
作业（包括暂停的作业）将在6小时后失败。
暂停的作业仍在运行计算/实例/虚拟机，并将继续产生费用。

开发

运行测试代码

要在操作中测试你的代码，你需要构建镜像并将其推送到不同的容器注册表仓库。例如，如果我想测试一些代码，我不会用主镜像仓库来构建镜像。在此之前，注释掉将镜像绑定到仓库的标签：

# LABEL org.opencontainers.image.source https://github.com/trstringer/manual-approval

构建镜像：

$ VERSION=1.7.1-rc.1 make IMAGE_REPO=ghcr.io/trstringer/manual-approval-test build

注意：镜像版本可以是任何你想要的，因为这个镜像不会被推送到生产环境。它只用于测试。

将镜像推送到你的容器注册表：

$ VERSION=1.7.1-rc.1 make IMAGE_REPO=ghcr.io/trstringer/manual-approval-test push

要测试镜像，你需要修改action.yaml，使其指向你正在测试的新镜像：

  image: docker://ghcr.io/trstringer/manual-approval-test:1.7.0-rc.1

然后要测试镜像，运行一个指定你的开发分支的工作流：

- name: Wait for approval
  uses: your-github-user/manual-approval@your-dev-branch
  with:
    secret: ${{ secrets.GITHUB_TOKEN }}
    approvers: trstringer

对于uses，这应该指向你的仓库和开发分支。

注意：要测试使用组织团队作为审批者的操作，请参考组织团队审批者部分的说明。

创建发布

构建新版本的镜像：$ VERSION=1.7.0 make build
推送新镜像：$ VERSION=1.7.0 make push
创建一个发布分支并修改action.yaml以指向新镜像
打开并合并PR以将这些更改添加到默认分支
确保将新更改获取到你的本地仓库：$ git checkout main && git fetch origin && git merge origin main
在本地和远程删除v1标签：$ git tag -d v1 && git push --delete origin v1
创建并推送新标签：$ git tag v1.7.0 && git tag v1 && git push origin --tags
创建GitHub项目发布