mkocus/semver-resource

Semver Resource

Concourse的语义化版本管理资源，用于管理版本号，支持将版本号存储在git仓库、S3兼容存储、OpenStack Swift或Google Cloud Storage中，提供版本的语义化更新和原子操作能力。

资源配置

• initial_version：可选，初始化版本号（当源中无版本时使用）。
• driver：可选，默认S3，版本存储驱动类型，支持git、s3、swift、gcs四种。

Git驱动

通过修改仓库中的文件来更新版本，支持原子更新。

• uri：必填，仓库URL。
• branch：必填，文件所在分支。
• file：必填，存储版本的文件名。
• private_key：可选，SSH私钥（用于仓库认证）。
• username/password：可选，HTTP(S)认证的用户名/密码。
• git_user：可选，提交时使用的git身份（格式："姓名 <>"或）。
• depth：可选，浅克隆深度（正整数）。
• skip_ssl_verification：可选，跳过git端点SSL验证。
• commit_message：可选，自定义提交消息（支持%version%和%file%变量）。
• git_tag_commit：可选，是否为提交打轻量标签（默认false）。

S3驱动

通过S3兼容存储桶中的文件管理版本。

• bucket：必填，存储桶名称。
• key：必填，版本文件的对象键。
• access_key_id/secret_access_key：必填，AWS访问密钥。
• session_token：可选，AWS会话令牌。
• region_name：可选，默认us-east-1，存储桶所在区域。
• endpoint：可选，自定义S3兼容端点。
• disable_ssl：可选，禁用SSL（适用于无SSL的S3兼容服务）。
• skip_ssl_verification：可选，跳过S3端点SSL验证。
• server_side_encryption：可选，服务端加密算法（如AES256、aws:kms）。
• use_v2_signing：可选，使用v2签名（默认false）。

Swift驱动

通过OpenStack Swift容器管理版本。

• openstack：必填，包含以下子参数：
  • container：必填，容器名称。
  • item_name：必填，版本文件的项名称。
  • region：必填，容器所在区域。
  • 其他认证参数（如identity_endpoint、username、password等）：参考gophercloud的auth_options.go。

GCS驱动

通过Google Cloud Storage桶管理版本。

• bucket：必填，存储桶名称。
• key：必填，版本文件的对象键。
• json_key：必填，GCP服务账号JSON密钥内容（示例见下文）。

使用示例

Concourse资源配置

yaml
resources:
- name: version
  type: semver
  source:
    driver: git
    uri: git@github.com:concourse/concourse.git
    branch: version
    file: version
    private_key: {{concourse-repo-private-key}}

版本更新流程

分步更新（get + put）

yaml
plan:
- get: version
  params: {bump: minor}
- task: build-artifact
- put: version
  params: {file: version/version}

原子更新（直接put）

yaml
plan:
- put: version
  params: {bump: minor}
- task: build-artifact

核心行为

check：获取当前版本

从源读取版本文件，若为空则返回initial_version；否则返回文件中的版本（需大于等于当前版本）。

in：提供版本文件（可选本地bump）

将版本号作为version文件输出到构建目录，支持本地bump（仅修改输出版本，不更新源）。 参数：

• bump：可选，语义化bump类型（major/minor/patch/final）。
• pre：可选，预发布版本前缀（如alpha、rc）。
• pre_without_version：可选，预发布版本是否不带数字（默认false）。

out：更新版本（文件或bump）

通过文件或bump策略更新源版本，支持原子操作（部分驱动）。 参数：

• file：可选，包含目标版本的文件路径。
• bump/pre：可选，语义化bump策略（同in）。
• pre_without_version：可选，预发布版本是否不带数字（默认false）。

语义化版本bump规则

• bump类型：
  • major：主版本+1（如1.0.0→2.0.0）。
  • minor：次版本+1（如0.1.0→0.2.0）。
  • patch：补丁版本+1（如0.0.1→0.0.2）。
  • final：移除预发布标签（如1.0.0-rc.1→1.0.0）。
• pre前缀：
  • 若版本已为该前缀的预发布：预发布号+1。
  • 若版本为其他前缀的预发布：切换前缀并重置预发布号为1。
  • 若版本非预发布：添加前缀并设置预发布号为1。
• pre_without_version：预发布版本不带数字（如SNAPSHOT保持不变）。

测试与贡献

本地测试

通过Dockerfile构建镜像时自动运行测试：

sh
# Alpine镜像
docker build -t semver-resource -f dockerfiles/alpine/Dockerfile .
# Ubuntu镜像
docker build -t semver-resource -f dockerfiles/ubuntu/Dockerfile .

集成测试（S3驱动）

需提供AWS密钥、存储桶和区域：

sh
docker build . -t semver-resource -f dockerfiles/alpine/Dockerfile \
  --build-arg SEMVER_TESTING_ACCESS_KEY_ID="your-key" \
  --build-arg SEMVER_TESTING_SECRET_ACCESS_KEY="your-secret" \
  --build-arg SEMVER_TESTING_BUCKET="your-bucket" \
  --build-arg SEMVER_TESTING_REGION="your-region"

贡献指南

请提交PR到master分支，并确保本地测试通过。