buildo/github-pr-resource

Github PR资源

概述和主要用途

一个用于GitHub拉取请求(PR)的Concourse资源，采用Go语言编写，基于GitHub V4 (GraphQL) API。受原始资源启发，但具有重要差异：通过GraphQL API减少API调用次数、获取时合并PR特定提交到最新基础分支、提供PR和基础分支的提交SHA元数据、支持Webhook且无缓存机制。

核心功能和特性

• 高效API调用：check操作使用GraphQL API，每100个开放PR仅需1次API调用，显著降低GitHub API速率限制压力
• 精确合并机制：get操作将PR的特定提交合并到最新基础分支，确保测试和状态设置基于准确提交
• 详细元数据输出：get和put操作提供PR及基础分支的提交SHA等元数据，可通过JSON文件或单独文件供任务使用
• 原生Webhook支持：无缓存设计，配合Webhook（订阅push和pull_request事件）高效触发，适合低流量仓库及来自fork的PR
• 灵活配置选项：支持路径过滤、忽略草稿PR、设置所需审核批准数、git-crypt解密、基础分支限制等多种场景配置

使用场景和适用范围

适用于Concourse CI/CD管道，用于监控GitHub仓库的拉取请求，自动触发构建、测试流程，并更新PR状态（如pending、success、failure）或添加评论。特别适合需要高效处理PR、依赖准确合并测试结果的开发团队，支持公共和私有仓库。

源配置（Source Configuration）

注意：

• 如果设置了v3_endpoint，则必须同时设置v4_endpoint（反之亦然）
• 有关Webhook令牌配置，请查看Concourse资源文档
• 使用required_review_approvals时，建议启用GitHub的分支保护规则，以https://help.github.com/en/articles/enabling-required-reviews-for-pull-requests

行为

check

为所有提交（自上次版本后）生成新版本，按提交日期排序。版本表示结构：

• pr：拉取请求编号
• commit：提交SHA
• committed：提交时间戳（用于过滤后续检查）
• approved_review_count：PR的批准审核数量

若多个提交同时推送到某个PR，最后一个提交将成为新版本。

Webhook注意事项： 资源不实现缓存，配合Webhook使用时需订阅push和pull_request事件。注意：从fork打开的PR及对该fork的提交不会通过Webhook生成通知，低流量仓库且预期有fork PR时，建议设置check_every: 1m主动发现版本。

get

功能说明： 克隆基础分支（如master）的最新提交，并将PR的指定提交合并到基础分支。确保测试和状态设置基于输入请求的确切提交。元数据通过以下文件供任务使用：

• .git/resource/version.json：版本信息
• .git/resource/metadata.json：元数据信息
• .git/resource/changed_files：更改文件列表（若启用list_changed_files）

元数据也作为单独文件存在于.git/resource目录（如base_sha可通过.git/resource/base_sha获取），完整列表见https://github.com/telia-oss/github-pr-resource/blob/master/in.go#L66%E3%80%82

使用skip_download的 workaround：

yaml
put: update-status  # 为pull-request资源使用别名
resource: pull-request
params:
    path: pull-request
    status: pending
get_params: {skip_download: true}

put

环境变量展开：comment、comment_file和target_url支持环境变量展开（如$ATC_EXTERNAL_URL），详见Concourse元数据文档。

示例配置

yaml
resource_types:
- name: pull-request
  type: docker-image
  source:
    repository: teliaoss/github-pr-resource

resources:
- name: pull-request
  type: pull-request
  check_every: 24h
  webhook_token: ((webhook-token))
  source:
    repository: itsdalmo/test-repository
    access_token: ((github-access-token))

jobs:
- name: test
  plan:
  - get: pull-request
    trigger: true
    version: every
  - put: pull-request
    params:
      path: pull-request
      status: pending
  - task: unit-test
    config:
      platform: linux
      image_resource:
        type: docker-image
        source: {repository: alpine/git, tag: "latest"}
      inputs:
        - name: pull-request
      run:
        path: /bin/sh
        args:
          - -xce
          - |
            cd pull-request
            git log --graph --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s" > log.txt
            cat log.txt
    on_failure:
      put: pull-request
      params:
        path: pull-request
        status: failure
  - put: pull-request
    params:
      path: pull-request
      status: success

API成本说明

GitHub API速率限制为每小时5000次请求（每用户）：

• V3 API：直接计为请求次数
• V4 API（GraphQL）：按查询复杂度计算，详情见https://developer.github.com/v4/guides/resource-limitations/#calculating-a-rate-limit-score-before-running-the-call

操作成本示例：

• check：大型仓库测试成本
  • concourse/concourse（51个开放PR）：成本2
  • torvalds/linux（305个开放PR）：成本8
  • kubernetes/kubernetes（1072个开放PR）：成本22
• get：固定成本1（获取指定提交的PR）
• put：基础成本1，每增加status/comment/comment_file等操作+1

从原始资源迁移

若从[jtarchie/github-pullrequest-resource][original-resource]迁移，需注意以下差异：

新增参数

• source：v4_endpoint
• put：comment

参数重命名

• source：
  • repo → repository
  • ci_skip → disable_ci_skip（逻辑反转，默认true）
  • api_endpoint → v3_endpoint
  • base → base_branch
  • base_url → target_url
  • require_review_approval → required_review_approvals（从bool改为int）
• get：git.depth → git_depth
• put：comment → comment_file（因新增comment参数）

不再需要的参数

• src：uri、private_key、username、password、only_mergeable
• get：fetch_merge（强制合并）

未包含的参数

• src：authorship_restriction、label、git_config（信息从元数据文件获取）
• get：git.*（git_depth除外）
• put：merge.*、label

Concourse v5.0.0以下迁移注意：可能出现failed to unmarshal request: json: unknown field "ref"错误，解决方法是重命名资源以清除历史记录，详见https://github.com/telia-oss/github-pr-resource/issues/64%E3%80%82