如何将手动触发的Workflow运行关联到Pull Request状态检查？

问题原因 #

手动触发的workflow_dispatch工作流默认不会和Pull Request（PR）关联，GitHub无法识别该运行属于哪个PR的状态检查，因此结果不会被纳入PR的合并要求判定中。

解决方案：手动指定PR编号并主动更新状态检查 #

通过在工作流中添加PR编号输入项，结合GitHub API将测试结果关联到目标PR的最新commit上，具体实现如下：

1. 修改工作流配置，新增PR编号输入
   更新workflow_dispatch的输入参数，添加可选的PR编号项，同时补充状态检查更新步骤：

   name: Test
   
   on:
     workflow_dispatch:
       inputs:
         used-branch:
           description: Branch the test shall be run on
           default: master
           required: true
         pr-number:
           description: Pull Request number to associate the test result with (optional)
           required: false
     push:
       branches: ['main', 'master']
       tags: ['!**']
     pull_request:
       types: [opened, reopened, ready_for_review]
   
   jobs:
     test:
       runs-on: ubuntu-latest # 根据你的实际需求选择运行环境
       steps:
         - name: Checkout selected branch
           uses: actions/checkout@v3
           if: inputs.used-branch != ''
           with:
             ref: ${{ github.event.inputs.used-branch }}
         - name: Checkout current branch
           uses: actions/checkout@v3
           with:
             ref: ${{ github.ref }}
           if: inputs.used-branch == ''
         - name: Run test
           id: run-test
           run: |
             # 替换为你的实际测试命令，比如npm test、pytest等
             npm test
             # 根据测试命令的退出码记录结果（成功为success，失败为failure）
             echo "test-result=$([ $? -eq 0 ] && echo 'success' || echo 'failure')" >> $GITHUB_OUTPUT
         - name: Update PR status check
           if: inputs.pr-number != ''
           env:
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
             PR_NUMBER: ${{ inputs.pr-number }}
             TEST_RESULT: ${{ steps.run-test.outputs.test-result }}
             WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
           run: |
             # 获取目标PR的最新commit SHA
             COMMIT_SHA=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
               "https://api.github.com/repos/${{ github.repository }}/pulls/$PR_NUMBER" | \
               jq -r '.head.sha')
             
             # 调用GitHub API更新该commit的状态检查
             curl -X POST -H "Authorization: token $GITHUB_TOKEN" \
               -H "Content-Type: application/json" \
               "https://api.github.com/repos/${{ github.repository }}/statuses/$COMMIT_SHA" \
               -d '{
                 "state": "'"$TEST_RESULT"'",
                 "context": "test", # 必须和仓库设置的必填检查项名称完全一致
                 "description": "Manual test run triggered via workflow dispatch",
                 "target_url": "'"$WORKFLOW_URL"'"
               }'
   

2. 手动触发时关联PR
   手动启动工作流时，除了填写used-branch，在pr-number输入框中填入目标PR的编号（比如#123），工作流运行完成后，测试结果会自动同步到该PR的状态检查列表中，被仓库的合并保护规则识别。

关键注意事项 #

• context字段的值必须和仓库分支保护设置中“必填状态检查项”的名称完全匹配，否则GitHub无法将结果关联到对应的合并要求上。
• 默认的GITHUB_TOKEN已具备更新状态检查的权限（repo:status），无需额外配置密钥。
• 测试命令的退出码需正确反映测试结果（成功返回0，失败返回非0），才能确保test-result参数的准确性。

内容的提问来源于stack exchange，提问作者NotX