tenjaa/github-pr-resource

Github PR资源

一个用于GitHub拉取请求(PR)的Concourse资源，采用Go语言编写并基于https://developer.github.com/v4。受https://github.com/jtarchie/github-pullrequest-resource启发，但具有以下重要差异：

• GitHub V4 API：check操作每100个开放PR仅需1次API调用（详见#成本）。
• 拉取/合并：get操作始终将PR中的特定提交合并到最新基础分支。
• 元数据：get和put操作提供PR与基础分支的提交SHA等信息。
• Webhook：借助GraphQL无需实现缓存，因此能很好地与Webhook配合使用。

配置

认证

支持个人访问令牌或https://developer.github.com/apps/%E4%B8%A4%E7%A7%8D%E8%AE%A4%E8%AF%81%E6%96%B9%E5%BC%8F%E3%80%82

个人访问令牌

需设置access_token。若用于私有仓库，访问令牌需具备repo:full权限；公共仓库则repo:status权限足够。

GitHub应用

适用于组织环境，无需共享个人访问令牌。需提供app_id和private_key，并需以下权限：

• 内容 - 只读（必填）
• 拉取请求 - 只读（必填）
• 拉取请求 - 读写（用于PR评论的写入/删除）
• 提交状态 - 读写（用于设置提交状态）

源参数

注意：

• 若设置v3_endpoint，则必须同时设置v4_endpoint（反之亦然）。
• Webhook令牌配置详见Concourse资源文档。
• 使用required_review_approvals时，建议启用GitHub分支保护规则以https://help.github.com/en/articles/enabling-required-reviews-for-pull-requests%E3%80%82

行为

check

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

• pr：PR编号。
• commit：提交SHA。
• committed：提交时间戳，用于过滤后续检查。

若同一PR同时推送多个提交，最新提交将作为新版本。

Webhook注意事项：
本资源不实现缓存，因此能很好地与Webhook配合（需订阅push和pull_request事件）。但需注意，从分叉仓库创建的PR及对分叉仓库的提交不会通过Webhook生成通知。若仓库流量低且需处理分叉PR，建议设置check_every: 1m。本资源的check操作成本较低，通常无需担心速率限制。

get

克隆基础分支（如master）的最新提交，并将PR的指定提交合并到该分支。确保测试和状态设置针对输入请求的确切提交。由于check输出的版本未锁定PR基础分支的特定提交，新的get操作将始终使用基础分支的最新提交，并在元数据中报告该提交的SHA。版本信息和元数据可通过以下JSON文件供任务使用：

• .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时，后续任务挂载的PR卷将为空（如在运行测试前设置pending状态时）。解决方法是为put使用别名（详见https://github.com/telia-oss/github-pr-resource/issues/32%EF%BC%89%EF%BC%9A

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

当源配置中设置git_crypt_key时，git-crypt加密的仓库将自动解密。

注意：若重新触发构建以测试PR的最新提交与基础分支的较新版本，Concourse若仍存在卷将重用该卷（不触发新的get），可能导致意外结果（#5）。因此，最好通过向PR推送空提交来重新测试PR与基础分支的较新版本。

put

注意：comment、comment_file和target_url会展开环境变量，例如$ATC_EXTERNAL_URL将替换为Concourse ATC的公共URL。更多元数据环境变量详见[***]

示例

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

成本

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的成本示例：

• https://github.com/concourse/concourse%EF%BC%9A%E6%B5%8B%E8%AF%95%E6%97%B651%E4%B8%AA%E5%BC%80%E6%94%BEPR%EF%BC%8C%E6%88%90%E6%9C%AC2%E3%80%82
• https://github.com/torvalds/linux%EF%BC%9A305%E4%B8%AA%E5%BC%80%E6%94%BEPR%EF%BC%8C%E6%88%90%E6%9C%AC8%E3%80%82
• https://github.com/kubernetes/kubernetes%EF%BC%9A1072%E4%B8%AA%E5%BC%80%E6%94%BEPR%EF%BC%8C%E6%88%90%E6%9C%AC22%E3%80%82

其他操作成本：

• get：固定成本1（拉取指定提交的PR）。
• put：使用V3 API，基础成本1，status、comment、comment_file等每增加一项成本+1。

迁移

若从https://github.com/jtarchie/github-pullrequest-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：直接从GitHub API获取URI。
  • private_key：通过HTTPS使用访问令牌克隆。
  • username：同上。
  • password：同上。
  • only_mergeable：若无法合并则get操作失败（强制合并）。
• get：
  • fetch_merge：始终执行fetch_merge（强制）。

未包含的参数

• src：
  • authorship_restriction
  • label
  • git_config：PR/作者信息可从.git/resource/metadata.json获取
• 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%EF%BC%89%E3%80%82