n7docker/concourse-bitbucket-pr

concourse-bitbucket-pr

ConcourseCI管道资源镜像，用于简化BitBucket Cloud拉取请求(PR)的管理。可实现获取打开的PR列表、检出PR引用的提交以及设置PR的构建状态等功能。镜像托管于Docker Hub：https://hub.docker.com/r/n7docker/concourse-bitbucket-pr%E3%80%82

镜像概述

该镜像作为ConcourseCI的资源类型，专为BitBucket Cloud的PR管理设计。核心解决现有类似工具因频繁调用BitBucket API（如/commits端点）导致超出API请求限制（每小时1000次）的问题，通过优化实现最小化API调用，确保CI流程稳定运行。

核心功能与特性

• 获取PR列表：通过BitBucket API v2获取指定仓库所有打开的PR，支持分页处理
• 检出提交：基于PR引用的提交哈希执行Git检出，使用libgit2实现高效操作
• 设置构建状态：为PR关联的提交设置构建状态（如进行中、成功、失败等）
• 减少API调用：通过直接检出Git仓库获取提交哈希，避免频繁调用BitBucket API
• 子模块支持：可选递归检出仓库子模块，使用父仓库配置的凭据
• 调试模式：支持开启额外日志输出，便于问题排查

使用场景与适用范围

适用于使用ConcourseCI构建CI/CD管道，且需要与BitBucket Cloud集成管理PR的团队。特别适合多项目（20+）并行构建场景，可有效避免因API调用限制导致的CI中断问题。

使用方法与配置说明

资源类型定义

首先在Concourse管道中定义资源类型：

yaml
resource_types:
  - name: bitbucket-pr
    type: registry-image
    source:
      repository: n7docker/concourse-bitbucket-pr

资源配置

源配置参数

资源定义示例

yaml
resources:
  - name: pull-request
    type: bitbucket-pr
    check_every: 1m  # 每分钟检查一次PR更新
    source:
      workspace: n7mobile  # BitBucket组织
      slug: pr-test-repo   # 仓库名称
      username: ((ci_user))  # 凭据引用
      password: ((ci_pass))  # 凭据引用
      debug: true  # 开启调试日志

作业配置示例

yaml
jobs:
  - name: process-pr
    plan:
      - get: pull-request
        trigger: true  # PR更新时触发作业
        version: every  # 获取所有PR版本
      - task: run-tests
        config:
          platform: linux
          image_resource:
            type: registry-image
            source: {repository: alpine}
          inputs:
            - name: pull-request  # 从PR资源获取代码
          run:
            path: sh
            args: ["-c", "cd pull-request && echo 'Running tests...'"]
      - put: pull-request  # 设置PR构建状态
        params:
          repo_path: pull-request  # 代码所在路径（与get步骤名称一致）
          action: set:commit.build.status  # 操作类型（当前仅支持此值）
          status: SUCCESSFUL  # 构建状态（STOPPED/INPROGRESS/FAILED/SUCCESSFUL）
          url: https://ci.example.com/builds/((BUILD_ID))  # 构建结果URL
          name: "PR测试 #((BUILD_ID))"  # 状态名称
          description: "自动测试完成"  # 状态描述

行为说明

check：获取打开的PR列表

通过BitBucket API v2获取仓库所有打开的PR，处理分页。为获取PR最新提交的完整SHA1，执行最小化Git裸克隆（而非调用API），生成版本对象：

json
{
    "ref": "完整提交SHA1",
    "id": "PR标识符"
}

in：检出提交

执行git clone && git checkout <commit-hash>操作（基于libgit2实现），将Concourse传递的版本对象存储为.concourse.version.json，供后续out步骤使用。

out：设置构建状态

为PR关联的提交设置构建状态，参数说明：

开发指南

环境要求

• golang：1.15.x及以上
• docker：17.05.x及以上
• make：GNU make 4.1及以上
• libgit2：1.1.0及以上

开发操作

所有开发任务通过Makefile定义，可执行make help查看详细任务列表。

许可证

MIT License

Copyright (c) [year] [fullname]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

维护者

由N7Mobile sp. z o.o.积极维护。