ci-version Docker镜像文档

镜像概述

ci-version是一个CLI工具，用于在CI/CD工作流中自动确定当前构建或提交应分配的新版本号。该工具通过分析仓库中的现有标签、配置文件（如package.json或composer.json）版本信息，遵循语义化版本规则计算并返回合适的新版本，便于自动创建仓库标签。

核心功能与特性

• 自动版本计算：根据仓库历史标签自动递增版本号（默认从1.0.0开始，递增minor版本）
• 兼容性校验：支持与package.json或composer.json中的版本进行兼容性校验，确保生成版本符合配置文件版本约束
• 灵活版本控制：提供--next选项获取下一个建议标签版本，--prefix选项支持带前缀的标签管理（如区分多应用仓库）
• CI友好设计：无需本地安装依赖，直接通过Docker镜像运行，支持只读挂载仓库目录

使用场景

• CI/CD流水线中自动版本管理，替代手动版本号维护
• 需要基于仓库标签和配置文件版本双重约束的版本控制场景
• 多应用共存仓库中通过标签前缀区分不同应用版本
• 自动化构建流程中动态生成版本标签

使用方法

基本要求

• 需将目标仓库目录挂载至容器内/repo路径（只读模式推荐）
• 仓库需初始化Git并包含提交历史（用于标签分析）

Docker运行示例

基础用法（无配置文件约束）

bash
# 分析仓库并返回新版本（基于历史标签递增）
docker run --rm -v /本地仓库路径:/repo:ro softonic/ci-version
#> 1.2.0

指定配置文件兼容性校验

bash
# 基于package.json版本兼容性计算
docker run --rm -v /本地仓库路径:/repo:ro softonic/ci-version --compatible-with package.json
#> 1.2.0

# 基于composer.json版本兼容性计算
docker run --rm -v /本地仓库路径:/repo:ro softonic/ci-version --compatible-with composer.json
#> 1.2.0

获取下一个建议标签版本

bash
# 返回当前应创建的下一个标签版本
docker run --rm -v /本地仓库路径:/repo:ro softonic/ci-version --next
#> 1.3.0

使用标签前缀（多应用仓库）

bash
# 仅识别"app-"前缀标签并生成带前缀的新版本
docker run --rm -v /本地仓库路径:/repo:ro softonic/ci-version --prefix "app-"
#> app-1.2.0

工作原理

无--compatible-with选项时

1. 当前提交已包含版本标签（如1.0.0或v1.0.0）：返回空值（不生成新版本）
2. 当前提交无标签：
   • 若仓库无历史标签：返回1.0.0
   • 若仓库有历史标签：在最新标签基础上递增minor版本（如历史最新为1.2.0，返回1.3.0）

示例

• 首次构建：

  当前提交标签：<none>
  历史标签：<none>
  => 新版本：1.0.0
  

• 新提交构建：

  当前提交标签：<none>
  历史标签：1.1.0 1.2.0 1.3.0
  => 新版本：1.4.0
  

带--compatible-with选项时

（需指定package.json或composer.json，以配置文件中的版本为基准）

1. 当前提交已包含标签：
   • 若标签版本与配置文件版本兼容：返回空值
   • 若不兼容：在仓库中最新兼容版本基础上递增
2. 当前提交无标签：在仓库中最新兼容配置文件版本的标签基础上递增

示例

• 首次构建：

  当前提交标签：<none>
  历史标签：<none>
  package.json/composer.json：1.0.0
  => 新版本：1.0.0
  

• 配置文件版本升级后首次构建：

  当前提交标签：<none>
  历史标签：1.1.0 1.2.0 1.3.0
  package.json/composer.json：2.0.0
  => 新版本：2.0.0
  

带--prefix选项时

• 仅识别以指定前缀开头的标签（如--prefix "app-"仅处理app-1.0.0类标签）
• 生成的新版本标签自动添加该前缀（如计算版本为1.4.0，返回app-1.4.0）

示例

bash
docker run --rm -v /repo:/repo:ro softonic/ci-version --prefix "service-"
# 历史标签：service-1.1.0 service-1.2.0
#> service-1.3.0