GitHub Release Resource 技术文档

1. 概述和主要用途

GitHub Release Resource 是 Concourse CI 的资源类型（Resource Type），用于在流水线中与 GitHub Releases 进行交互。该资源支持两种核心操作：获取（in） GitHub Release 中的版本化资产或元数据，以及创建/更新（out） GitHub Release（包括标签、描述和资产文件）。其主要用途是实现流水线与 GitHub Releases 的自动化集成，满足版本化资源的获取和发布需求。

2. 核心功能和特性

• 获取 Release 资产：支持通过标签或正则表达式过滤，获取指定 GitHub Release 的资产文件（如二进制包、安装器）及元数据（名称、描述、提交记录等）。
• 创建新 Release：可指定标签、名称、描述、提交指向（commitish）等，创建新的 GitHub Release，并支持上传资产文件。
• 更新现有 Release：支持更新现有 Release 的名称、描述、资产文件，或修改草稿/预发布状态。
• 灵活的标签管理：支持通过精确标签（如 v1.0.0）或正则表达式（如 v.*）筛选 Release，满足版本匹配需求。
• GitHub 认证支持：通过个人访问令牌（PAT）实现安全认证，支持私有仓库及写操作（如创建 Release）。
• GitHub Enterprise 兼容：支持配置自定义 API 地址和基础 URL，适配 GitHub Enterprise 环境。

3. 使用场景和适用范围

适用于 Concourse CI 流水线中需与 GitHub Releases 交互的场景，典型包括：

• 自动发布流程：流水线构建完成后，自动创建 GitHub Release 并附加构建产物（如编译后的二进制文件）。
• 依赖版本管理：从指定 GitHub Release 获取依赖资产（如工具包、配置文件），作为流水线输入。
• 版本化部署触发：通过监听 GitHub Release 标签更新，触发下游部署流程，确保部署版本可追溯。
• Release 信息同步：获取最新 Release 元数据（如版本号、变更日志），用于流水线中的版本展示或配置生成。

4. 使用方法和配置说明

4.1 资源类型定义

在 Concourse 流水线中，需先定义该资源类型：

resource_types:
- name: github-release
  type: registry-image
  source:
    repository: concourse/github-release-resource  # 官方镜像地址

4.2 资源配置

4.2.1 基础配置（source）

资源的 source 段定义与 GitHub 仓库的连接信息，通用配置如下：

resources:
- name: my-github-release  # 资源名称（自定义）
  type: github-release     # 关联上述定义的资源类型
  source:
    owner: my-github-username  # GitHub 仓库所有者（用户名或组织名，必填）
    repo: my-repo-name         # GitHub 仓库名称（必填）
    access_token: ((github-pat))  # GitHub 个人访问令牌（PAT），需 `repo` 权限（私有仓库或写操作时必填）
    # api_url: [***]  # GitHub API URL（可选，默认官方 API，GitHub Enterprise 需修改，如 [***]
    # base_url: [***]     # GitHub Web 基础 URL（可选，默认官方地址，GitHub Enterprise 需修改，如 [***]

4.2.2 获取操作（in）配置

用于从 GitHub Release 获取资产或元数据，配置在流水线的 get 步骤中：

jobs:
- name: fetch-release-assets
  plan:
  - get: my-github-release  # 关联上述定义的资源
    params:
      # 可选参数：筛选和获取配置
      globs: ["*.tar.gz", "*.exe"]  # 资产文件 glob 模式（默认获取所有资产）
      include_source_tarball: true  # 是否包含源码 tarball（source.tar.gz，默认 false）
      include_source_zip: true      # 是否包含源码 zip（source.zip，默认 false）
      download: true                # 是否下载资产文件（false 仅生成元数据文件 `release.json`，默认 true）
      tag: v1.0.0                   # 精确标签（如 "v1.0.0"，默认获取最新 Release）
      # tag_filter: v*               # 标签正则表达式（如 "v.*"，与 tag 二选一）

4.2.3 创建/更新操作（out）配置

用于创建新的 GitHub Release 或更新现有 Release，配置在流水线的 put 步骤中：

jobs:
- name: create-github-release
  plan:
  - put: my-github-release  # 关联上述定义的资源
    params:
      # 核心参数（创建 Release 时必填）
      name: "Release v1.0.0"  # Release 名称（必填）
      tag: v1.0.0             # Release 标签（如 "v1.0.0"，创建新 Release 时必填）
      # tag_prefix: v         # 标签前缀（与 tag 二选一，自动生成标签，如基于版本文件）
      commitish: main         # 标签指向的提交 SHA 或分支（可选，默认当前 HEAD）
      body: |                 # Release 描述（支持 Markdown，可选）
        ## v1.0.0
        - 新增功能 A
        - 修复 Bug B
      # 资产上传配置（可选）
      globs: ["dist/*.tar.gz"]  # 要上传的资产文件 glob 模式（如构建产物路径）
      # 可选参数
      draft: false             # 是否标记为草稿（默认 false）
      prerelease: false        # 是否标记为预发布（默认 false）
      # overwrite: true        # 是否覆盖现有同名标签的 Release（默认 false，谨慎使用）
      # asset_name: custom-name.tar.gz  # 资产自定义名称（默认原文件名，仅单资产时生效）

4.3 完整流水线示例

以下是一个包含 "获取 Release 资产" 和 "创建 Release" 的 Concourse 流水线示例：

resource_types:
- name: github-release
  type: registry-image
  source:
    repository: concourse/github-release-resource

resources:
- name: app-repo  # 源码仓库（示例）
  type: git
  source:
    uri: [***]
    branch: main

- name: app-release  # GitHub Release 资源
  type: github-release
  source:
    owner: my-username
    repo: my-app
    access_token: ((github-pat))  # 存储在 Concourse 中的密钥

jobs:
- name: build-and-release
  plan:
  - get: app-repo  # 获取源码
    trigger: true  # 源码更新时触发流水线
  - task: build-app  # 构建产物（示例任务）
    config:
      platform: linux
      image_resource:
        type: registry-image
        source: {repository: alpine}
      inputs: [{name: app-repo}]
      outputs: [{name: dist}]  # 输出构建产物到 dist 目录
      run:
        path: sh
        args: ["-c", "cd app-repo && mkdir -p ../dist && echo 'built asset' > ../dist/app-v1.0.0.tar.gz"]
  - put: app-release  # 创建 GitHub Release 并上传资产
    params:
      name: "v1.0.0 Release"
      tag: v1.0.0
      body: "Initial stable release with build assets."
      globs: ["dist/*.tar.gz"]  # 上传 dist 目录下的资产

5. 配置参数说明

5.1 资源源配置（source）

5.2 获取操作（in）参数

5.3 创建/更新操作（out）参数

6. 注意事项

• 令牌权限：access_token 需根据操作类型配置权限：仅读取公共仓库 Release 时无需令牌；读取私有仓库需 public_repo 或 repo 权限；创建/更新 Release 需 repo 权限。
• 标签唯一性：创建 Release 时，tag 必须唯一。若需覆盖现有标签，需显式设置 overwrite: true（会删除原标签及 Release）。
• 资产大小限制：GitHub 对单个资产大小限制为 2GB，超过限制将导致上传失败。
• 元数据文件：获取操作（in）会生成 release.json 文件，包含 Release 完整元数据（如 tag_name、body、assets 列表），可在流水线中解析使用。