在Azure Pipelines中为GitHub Check Run添加注释的技术问题

我正好遇到过类似的需求，要把Azure Pipelines里的构建/静态检查错误同步到GitHub的Check Run注释里，下面是我摸索出来的可行方案：

核心思路：获取GitHub Check Run ID并调用GitHub API #

Azure Pipelines本身没有直接提供添加GitHub Check Run注释的内置功能，但我们可以通过查询GitHub API拿到当前流水线对应的Check Run ID，再用GitHub的Checks API添加注释——这部分你提到用Octokit实现没问题，关键就是拿到那个ID。

步骤1：提取Azure Pipelines中的关键环境变量 #

Azure在GitHub触发的流水线中会自动设置一系列环境变量，我们需要用到这些：

• BUILD_REPOSITORY_URI：GitHub仓库的克隆地址（比如https://github.com/owner/repo.git）
• BUILD_SOURCEVERSION：触发流水线的提交SHA值
• BUILD_DEFINITIONNAME：当前Azure流水线的名称（这个会和GitHub上显示的Check Run名称对应）
• SYSTEM_PULLREQUEST_PULLREQUESTNUMBER：如果是PR触发的流水线，会有这个变量（可选，用来验证上下文）

步骤2：查询GitHub API获取Check Run ID #

我们可以通过GitHub的/repos/{owner}/{repo}/commits/{sha}/check-runs接口，过滤出当前Azure流水线对应的Check Run。这里用bash+curl+jq举个例子：

# 从仓库URI中提取owner和repo名称
REPO_FULL=$(echo "$BUILD_REPOSITORY_URI" | sed 's/https:\/\/github.com\///;s/.git$//')
OWNER=$(echo "$REPO_FULL" | cut -d'/' -f1)
REPO=$(echo "$REPO_FULL" | cut -d'/' -f2)

# 调用GitHub API查询该提交的所有Check Run，过滤出当前流水线对应的ID
CHECK_RUN_ID=$(curl -s -H "Authorization: token $GITHUB_PAT" \
  "https://api.github.com/repos/$OWNER/$REPO/commits/$BUILD_SOURCEVERSION/check-runs" \
  | jq -r --arg pipeline_name "$BUILD_DEFINITIONNAME" \
  '.check_runs[] | select(.name == $pipeline_name) | .id')

注意：GITHUB_PAT是你在GitHub创建的个人访问令牌，需要勾选checks:write权限，并且要在Azure Pipelines的库变量中设置为秘密变量，避免泄露。

步骤3：调用GitHub API添加注释 #

拿到Check Run ID后，就可以用/repos/{owner}/{repo}/check-runs/{check_run_id}/annotations接口添加注释，这个接口支持多行内容，完美适配编译器错误、clang-tidy的差异输出：

# 示例：添加一个编译器错误注释
curl -X POST -H "Authorization: token $GITHUB_PAT" \
  -H "Content-Type: application/json" \
  "https://api.github.com/repos/$OWNER/$REPO/check-runs/$CHECK_RUN_ID/annotations" \
  -d '[
    {
      "path": "source/test.cpp",
      "start_line": 7,
      "end_line": 7,
      "start_column": 20,
      "end_column": 20,
      "annotation_level": "failure",
      "title": "GCC Compilation Error",
      "message": "Undefined reference to `foo()`\n\nFull error output:\n/home/user/source/test.cpp:7:20: error: undefined reference to `foo()`\ncollect2: error: ld returned 1 exit status"
    }
  ]'

如果用Octokit（比如Node.js版本）会更简洁，处理JSON也更方便，你可以按照官方文档把上面的逻辑转成Octokit调用。

额外注意事项 #

• Check Run创建时机：确保你的脚本在流水线的后期运行（比如构建/检查任务之后），因为Azure Pipelines可能需要几秒时间在GitHub上创建Check Run，太早调用API可能查不到。
• 注释数量限制：GitHub每个Check Run最多允许添加50个注释，如果你的工具输出大量错误，建议过滤出优先级高的，或者合并同类错误。
• PR上下文验证：如果是PR触发的流水线，可以用SYSTEM_PULLREQUEST_PULLREQUESTNUMBER变量验证当前上下文，避免在非PR分支上误操作。

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