Xray中如何通过测试计划RUN按钮触发GitHub Actions自动化测试

前提：已完成GitHub Actions测试结果回传Xray的链路打通，以下配置完全复用现有回传逻辑，不需要重构已有代码。

1. Xray侧自定义RUN按钮触发规则 #

• 进入Xray后台自定义UI动作配置页，新建绑定在「Test Plan」实体的操作项，将其挂载到测试计划详情页的RUN按钮位（可替换原有默认手动执行逻辑，也可放在按钮下拉选项中作为自动化执行入口）
• 动作类型选择Webhook请求，请求方法设置为POST
• 请求目标地址填写对应GitHub仓库的workflow_dispatch触发接口，请求头添加鉴权字段：Authorization: Bearer <你的GitHub鉴权令牌，需开通workflow读写权限>
• 请求体固定传以下结构，自动注入当前点击的测试计划标识：

{
  "ref": "your-test-branch",
  "inputs": {
    "xray_test_plan_id": "${entity.id}",
    "xray_test_plan_key": "${entity.key}",
    "trigger_from": "xray_test_plan_run"
  }
}

• 配置触发成功/失败的前端提示：接口返回204状态码时提示「自动化测试已触发，结果将自动同步至当前测试计划」，请求报错时直接透传错误信息方便排查。

2. GitHub Actions工作流适配 #

• 在现有自动化测试的workflow配置文件中新增workflow_dispatch触发声明，接收Xray传入的测试计划参数：

on:
  workflow_dispatch:
    inputs:
      xray_test_plan_id:
        type: string
        required: true
      xray_test_plan_key:
        type: string
        required: true
      trigger_from:
        type: string
        required: false
        default: "xray_test_plan_run"

• 调整现有结果回传逻辑：执行完成回传Xray时，直接绑定入参里的xray_test_plan_key，确保本次执行结果自动关联到对应触发的测试计划下，不会出现数据错位。
• 可选优化：工作流启动后先拉取当前测试计划下关联的用例清单，只执行计划内绑定的自动化用例，避免全量执行浪费资源。

3. 常见问题排查 #

• 点击RUN无响应：先检查Xray部署网络是否能访问GitHub接口，再确认鉴权令牌是否过期、是否开通了workflow操作权限
• 触发成功但结果没关联到测试计划：检查回传逻辑里是否正确读取了传入的测试计划Key，不要写死固定值
• 触发返回404：检查请求体里的ref字段是否填了workflow文件真实存在的分支，分支名写错会直接触发失败

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