concourse/git-resource

Git Resource 镜像文档

一、镜像概述和主要用途

Git Resource 是 Concourse CI/CD 系统的核心资源类型之一，用于与 Git 仓库交互，实现对代码仓库提交历史的跟踪、代码拉取及变更检测。其主要用途包括：在 Concourse 流水线中作为代码源，触发流水线执行（基于代码变更），以及获取构建、测试或部署所需的源代码。

二、核心功能和特性

1. 提交跟踪
   自动跟踪 Git 仓库的提交历史，记录分支、标签或特定提交的元数据（如提交哈希、作者、时间戳）。
2. 代码拉取
   支持拉取指定分支、标签、提交哈希对应的代码，支持部分拉取（fetch_depth）以优化性能。
3. 多认证方式
   支持 SSH 密钥、HTTPS 用户名密码、个人访问令牌（PAT）等多种 Git 仓库认证方式。
4. 子模块支持
   可配置是否拉取 Git 子模块（include_submodules），支持递归拉取子模块。
5. 变更检测
   作为 Concourse 资源，可自动检测代码变更并触发下游任务执行。

三、使用场景和适用范围

1. CI/CD 流水线代码源
   在 Concourse 流水线中定义为代码输入源，用于获取构建、测试或部署所需的源代码。
2. 变更触发流水线
   当 Git 仓库指定分支/标签有新提交时，自动触发流水线执行（需配合 check 操作）。
3. 多版本代码获取
   拉取特定历史版本（如标签、提交哈希）的代码，用于版本回溯构建或多版本测试。

四、使用方法和配置说明

4.1 资源定义方式

在 Concourse 流水线配置文件（pipeline.yml）中，通过 resources 字段定义 Git Resource，指定资源类型（type: git）、名称及源配置（source）。

4.2 核心配置参数

4.2.1 源配置（source）

4.2.2 操作参数（params）

在流水线任务（jobs）中使用该资源时，可通过 params 配置拉取行为，常见参数：

4.3 输入输出说明

• 输入（get）：通过 get: <resource-name> 在任务中拉取代码，支持配置 params 自定义拉取行为。
• 输出（put）：通常不用于主动推送代码（需配合 Git 命令），主要用于传递代码变更元数据（如提交哈希）给下游任务。

五、配置示例

5.1 基础配置（公开仓库，HTTPS 认证）

yaml
resources:
- name: my-git-repo
  type: git
  source:
    repo: https://github.com/example/my-project.git  # 公开仓库 URL
    branch: main                                   # 跟踪 main 分支
    fetch_depth: 10                                # 仅拉取最近 10 次提交

5.2 SSH 认证（私有仓库）

yaml
resources:
- name: private-git-repo
  type: git
  source:
    repo: git@github.com:example/private-project.git  # SSH 格式仓库 URL
    branch: dev                                       # 跟踪 dev 分支
    private_key: |                                    # SSH 私钥（注意换行符转义）
      -----BEGIN RSA PRIVATE KEY-----
      MIIEogIBAAKCAQEAv...（完整私钥内容）...
      -----END RSA PRIVATE KEY-----
    include_submodules: true                          # 拉取子模块

5.3 拉取指定标签的代码

yaml
resources:
- name: tagged-git-repo
  type: git
  source:
    repo: https://github.com/example/my-project.git
    tag: v1.0.0  # 固定拉取 v1.0.0 标签的代码（忽略 branch 配置）

5.4 任务中拉取代码示例

yaml
jobs:
- name: build-project
  plan:
  - get: my-git-repo  # 拉取上述定义的 my-git-repo 资源
    params:
      path: src       # 代码拉取到任务容器的 src 目录
  - task: compile
    config:
      platform: linux
      image_resource:
        type: registry-image
        source: {repository: golang, tag: 1.21}
      inputs:
      - name: my-git-repo  # 依赖拉取的代码作为输入
      run:
        path: sh
        args:
        - -c
        - |
          cd src/my-git-repo  # 进入代码目录
          go build -o app     # 执行构建命令

六、注意事项

1. 认证安全性：私有仓库的认证信息（如 private_key、password）建议通过 Concourse Credentials Manager（如 Vault、CredHub）存储，避免明文写在配置中。
2. 版本兼容性：需确保 Concourse 版本与 Git Resource 版本兼容，推荐使用官方最新版本（参考 https://github.com/concourse/git-resource/%EF%BC%89%E3%80%82
3. 大型仓库优化：通过 fetch_depth 限制拉取深度，或使用 include_submodules: false 减少子模块拉取，提升性能。