concourse/semver-resource

Semver Resource 镜像文档

镜像概述与主要用途

Semver Resource 是一个 Concourse CI/CD 资源镜像，用于管理语义化版本号（Semantic Versioning）。其核心用途是在 CI/CD 管道中自动化版本号的获取、递增与持久化，并支持将版本号存储到多种后端存储系统，确保版本追踪的一致性。

核心功能与特性

• 语义化版本管理：支持符合 SemVer 规范的版本号（如 1.2.3、2.0.0-alpha.1），提供主版本（major）、次版本（minor）、补丁版本（patch）的自动递增能力。
• 多后端存储支持：版本号可持久化至 Git 仓库、本地文件系统（local）、Amazon S3、Google Cloud Storage（GCS）等后端。
• 版本获取与更新：通过 Concourse 管道的 get 步骤获取当前版本，put 步骤更新版本（递增或自定义版本号）。
• 初始版本配置：支持设置初始版本号，适用于新项目从零开始的版本管理。

使用场景与适用范围

• CI/CD 管道版本自动化：在 Concourse 管道中，用于软件构建、打包、发布流程中的版本号自动管理，避免手动操作导致的版本混乱。
• 多环境版本同步：通过 Git 等后端存储，实现不同管道或环境间的版本号同步。
• 预发布与正式发布管理：支持预发布版本（如 1.0.0-beta.1）和构建元数据（如 1.0.0+build.42）的灵活配置。

使用方法与配置说明

前提条件

• 已部署 Concourse CI/CD 系统。
• 熟悉 Concourse 管道配置文件（pipeline.yml）的编写规范。

资源类型定义

在 Concourse 管道中，需先定义 Semver Resource 作为资源类型：

yaml
resource_types:
- name: semver
  type: docker-image
  source:
    repository: concourse/semver-resource
    tag: latest  # 建议指定具体版本，如 v1.1.0

资源配置（source）

定义资源实例时，通过 source 字段配置后端存储及版本规则。以下为常见后端示例：

1. Git 后端（版本存储在 Git 仓库文件中）

yaml
resources:
- name: app-version
  type: semver
  source:
    driver: git          # 后端驱动类型
    uri: https://github.com/example/version-repo.git  # Git 仓库地址
    branch: main         # 分支名
    file: VERSION        # 存储版本号的文件名（仓库根目录下）
    initial_version: 1.0.0  # 初始版本（文件不存在时使用）
    private_key: ((git-private-key))  # 私有仓库 SSH 密钥（可选）

2. S3 后端（版本存储在 S3 对象中）

yaml
resources:
- name: app-version
  type: semver
  source:
    driver: s3           # 后端驱动类型
    bucket: my-version-bucket  # S3 桶名
    key: versions/app    # S3 对象键（版本文件路径）
    access_key_id: ((s3-access-key))  # AWS 访问密钥 ID
    secret_access_key: ((s3-secret-key))  # AWS 密钥
    region_name: us-east-1  # AWS 区域（可选）
    initial_version: 0.1.0

管道作业配置（plan）

在作业中通过 get 和 put 步骤使用资源：

获取当前版本（get 步骤）

yaml
jobs:
- name: get-current-version
  plan:
  - get: app-version  # 获取当前版本
    params:
      output_file: current-version.txt  # 可选，指定版本输出文件（默认 .version）

执行后，app-version 目录下生成版本文件（如 current-version.txt），内容为当前版本（如 1.0.0）。

更新版本号（put 步骤）

通过 put 步骤递增版本或自定义版本：

示例 1：自动递增版本

yaml
jobs:
- name: bump-minor-version
  plan:
  - get: app-version
  - put: app-version  # 更新版本并推送到后端
    params:
      bump: minor  # 递增规则：major/minor/patch
      pre: beta.1  # 可选，添加预发布版本（如 1.1.0-beta.1）
      build: build.42  # 可选，添加构建元数据（如 1.1.0+build.42）
      message: "Bump version to {{version}}"  # Git 后端提交信息（{{version}} 为新版本）

示例 2：自定义版本号（通过文件指定）

yaml
jobs:
- name: set-custom-version
  plan:
  - task: generate-version
    config:
      platform: linux
      image_resource:
        type: docker-image
        source: {repository: alpine}
      outputs:
      - name: version-file
      run:
        path: sh
        args: ["-c", "echo '2.0.0' > version-file/custom-version.txt"]
  - put: app-version
    params:
      file: version-file/custom-version.txt  # 从文件读取目标版本号

配置参数说明

资源配置（source）参数

更新参数（put params）

参考链接

• 源码与完整文档：https://github.com/concourse/semver-resource