teliaoss/github-pr-resource

Github PR资源

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

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

源配置

注意：

• 若设置v3_endpoint，则必须同时设置v4_endpoint（反之亦然）。
• Webhook令牌配置请参考https://concourse-ci.org/resources.html#resource-webhook-token。
• 使用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同时推送多个提交，最新提交将作为新版本。

Webhooks注意事项： 本资源不实现缓存，因此能很好地配合Webhooks（应订阅push和pull_request事件）。但需注意，从分支打开的PR及对该分支的提交不会通过Webhook生成通知。若仓库流量小且预期有来自分支的PR，需通过check_every: 1m等方式发现版本。本资源的check操作成本不高，通常无需担心速率限制。

get

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

• .git/resource/version.json
• .git/resource/metadata.json
• .git/resource/changed_files（若启用list_changed_files）

metadata.json中的信息也作为单独文件存在于.git/resource目录中，例如base_sha可通过.git/resource/base_sha获取。完整的元数据文件列表请查看https://github.com/telia-oss/github-pr-resource/blob/master/in.go#L66。

指定skip_download时，挂载到后续任务的PR卷将为空，这在运行实际测试前设置pending状态时会出现问题。解决方法是为put使用别名（详见https://github.com/telia-oss/github-pr-resource/issues/32）：

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。更多可通过环境变量获取的元数据详见https://concourse-ci.org/implementing-resource-types.html#resource-metadata。

示例

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，这基本等同于5000次请求；而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：测试时51个开放PR，成本2
• https://github.com/torvalds/linux：305个开放PR，成本8
• https://github.com/kubernetes/kubernetes：1072个开放PR，成本22

其他两个操作的成本计算较简单：

• 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操作失败（ opinionated 设计）
• get：
  • fetch_merge：始终执行fetch_merge（ opinionated 设计）

未包含的参数：

• 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。