xgj/trigger-version/README.md

Trigger Version Info Action

这个 GitHub Action 用于检测工作流的触发方式并提取版本信息，支持标签触发、版本分支触发和常规分支触发。

功能特性

• 🏷️ 标签触发检测：自动识别版本标签（如 v1.2.3）并提取版本号
• 🔄 版本分支检测：识别版本分支（如 v1.2.x）并提取版本信息
• 🆕 常规分支处理：对于非版本分支提供基础信息
• 📦 最新版本获取：始终获取仓库中的最新版本号，无论触发方式如何
• 🎯 灵活的版本前缀：支持自定义版本前缀（默认为 v）
• 🔍 标签过滤功能：支持通配符模式匹配和排除特定标签
• 🔧 版本格式转换：自动生成横线格式的版本号（如 v1.2.3 → v1-2-3）
• 📤 环境变量输出：自动设置环境变量供后续步骤使用
• 📊 详细的输出信息：提供完整的引用信息和触发状态

输入参数

参数名	描述	必需	默认值
version-prefix	版本前缀，用于匹配版本标签或分支	否	v
use-latest-version	在非版本触发时是否使用最新版本	否	false
tag-match	标签匹配模式，支持通配符（如：v*.*.* 或 v[0-9]*），用于进一步过滤标签	否	""
tag-exclude	标签排除模式，支持通配符（如：*-alpha* 或 *-beta*），匹配的标签将被排除	否	""

输出参数

参数名	描述	示例值
ref-type	引用类型	tag 或 branch
ref-name	引用名称	v1.2.3、main、feature/xxx
is-version-trigger	是否为版本触发	true 或 false
trigger-version	触发的版本号（标准化格式）	v1.2.3
version-with-dash	版本号，点替换为横线	v1-2-3
trigger-source	触发源	tag 或 branch
full-ref	完整的 Git 引用	refs/tags/v1.2.3
latest-version	仓库中的最新版本号	v1.2.3
latest-version-with-dash	最新版本号，点替换为横线	v1-2-3

环境变量

Action 会自动设置以下环境变量：

• IS_VERSION_TRIGGER: 是否为版本触发（true/false）
• TRIGGER_VERSION: 触发的版本号
• VERSION_WITH_DASH: 版本号，点替换为横线
• TRIGGER_SOURCE: 触发源（tag/branch）

使用示例

基本用法

name: Build and Deploy
on:
  push:
    branches: ["main", "v*"]
    tags: ["v*"]

jobs:
  get-version-info:
    runs-on: ubuntu-latest
    outputs:
      is-version-trigger: ${{ steps.version-info.outputs.is-version-trigger }}
      trigger-version: ${{ steps.version-info.outputs.trigger-version }}
      latest-version: ${{ steps.version-info.outputs.latest-version }}
      version-with-dash: ${{ steps.version-info.outputs.version-with-dash }}
      trigger-source: ${{ steps.version-info.outputs.trigger-source }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 必需：获取完整历史以获取所有标签

      - name: 获取版本信息
        id: version-info
        uses: ./trigger-version

      - name: 显示版本信息
        run: |
          echo "是否版本触发: ${{ steps.version-info.outputs.is-version-trigger }}"
          echo "触发版本: ${{ steps.version-info.outputs.trigger-version }}"
          echo "最新版本: ${{ steps.version-info.outputs.latest-version }}"
          echo "横线版本号: ${{ steps.version-info.outputs.version-with-dash }}"
          echo "触发源: ${{ steps.version-info.outputs.trigger-source }}"

  deploy:
    needs: get-version-info
    runs-on: ubuntu-latest
    if: needs.get-version-info.outputs.is-version-trigger == 'true'
    steps:
      - name: 部署版本
        run: |
          echo "部署版本: ${{ needs.get-version-info.outputs.trigger-version }}"
          echo "Docker标签: myapp:${{ needs.get-version-info.outputs.version-with-dash }}"

使用最新版本功能

- name: 获取版本信息（启用最新版本）
  id: version-info
  uses: ./trigger-version
  with:
    use-latest-version: true  # 在非版本触发时使用最新版本

- name: 使用最新版本进行构建
  run: |
    if [[ -n "${{ steps.version-info.outputs.latest-version }}" ]]; then
      echo "构建镜像标签: myapp:${{ steps.version-info.outputs.latest-version-with-dash }}"
      # docker build -t myapp:${{ steps.version-info.outputs.latest-version-with-dash }} .
    else
      echo "未找到版本标签，使用默认标签"
      # docker build -t myapp:latest .
    fi

### 自定义版本前缀

```yaml
- name: 获取版本信息（自定义前缀）
  id: version-info
  uses: actions/xgj/trigger-version@v1
  with:
    version-prefix: "release-"
```

### 标签过滤功能

#### 排除预发布版本

```yaml
- name: 获取稳定版本（排除预发布）
  id: stable-version
  uses: ./trigger-version
  with:
    version-prefix: "v"
    use-latest-version: true
    tag-exclude: "*-alpha*"  # 排除包含 alpha 的版本

- name: 显示稳定版本
  run: |
    echo "最新稳定版本: ${{ steps.stable-version.outputs.latest-version }}"
```

#### 匹配特定版本模式

```yaml
- name: 获取标准语义版本
  id: semver
  uses: ./trigger-version
  with:
    version-prefix: "v"
    use-latest-version: true
    tag-match: "v[0-9]*.[0-9]*.[0-9]*"  # 只匹配 v1.2.3 格式

- name: 显示语义版本
  run: |
    echo "语义版本: ${{ steps.semver.outputs.latest-version }}"
```

#### 复合过滤条件

```yaml
- name: 获取 v2.x 稳定版本
  id: v2-stable
  uses: ./trigger-version
  with:
    version-prefix: "v"
    use-latest-version: true
    tag-match: "v2.*.*"      # 只匹配 v2.x.x 版本
    tag-exclude: "*-*"       # 排除所有预发布版本（包含连字符）

- name: 显示 v2.x 稳定版本
  run: |
    echo "v2.x 最新稳定版本: ${{ steps.v2-stable.outputs.latest-version }}"
```

#### 获取预发布版本

```yaml
- name: 获取最新 beta 版本
  id: beta-version
  uses: ./trigger-version
  with:
    version-prefix: "v"
    use-latest-version: true
    tag-match: "*-beta*"     # 只匹配包含 beta 的版本

- name: 显示 beta 版本
  run: |
    echo "最新 beta 版本: ${{ steps.beta-version.outputs.latest-version }}"

完整的 CI/CD 流程

name: Complete CI/CD
on:
  push:
    branches: ["main", "develop", "v*"]
    tags: ["v*"]

jobs:
  analyze:
    runs-on: ubuntu-latest
    outputs:
      is-version-trigger: ${{ steps.version-info.outputs.is-version-trigger }}
      trigger-version: ${{ steps.version-info.outputs.trigger-version }}
      should-deploy: ${{ steps.check-deploy.outputs.should-deploy }}
    steps:
      - name: 获取版本信息
        id: version-info
        uses: actions/xgj/trigger-version@v1

      - name: 检查是否需要部署
        id: check-deploy
        run: |
          if [[ "${{ steps.version-info.outputs.is-version-trigger }}" == "true" ]]; then
            echo "should-deploy=true" >> $GITHUB_OUTPUT
          elif [[ "${{ steps.version-info.outputs.ref-name }}" == "main" ]]; then
            echo "should-deploy=true" >> $GITHUB_OUTPUT
          else
            echo "should-deploy=false" >> $GITHUB_OUTPUT
          fi

  build:
    needs: analyze
    runs-on: ubuntu-latest
    steps:
      - name: 构建应用
        run: |
          echo "构建中..."
          # 你的构建逻辑

  deploy-staging:
    needs: [analyze, build]
    runs-on: ubuntu-latest
    if: needs.analyze.outputs.should-deploy == 'true' && needs.analyze.outputs.is-version-trigger == 'false'
    steps:
      - name: 部署到测试环境
        run: echo "部署到测试环境"

  deploy-production:
    needs: [analyze, build]
    runs-on: ubuntu-latest
    if: needs.analyze.outputs.is-version-trigger == 'true'
    steps:
      - name: 部署到生产环境
        run: |
          echo "部署版本 ${{ needs.analyze.outputs.trigger-version }} 到生产环境"

标签过滤功能详解

通配符模式支持

tag-match 和 tag-exclude 参数支持 bash 通配符模式：

• *：匹配任意字符序列
• ?：匹配单个字符
• [...]：匹配括号内的任意字符
• [!...]：匹配不在括号内的任意字符

常用过滤模式

模式	描述	示例匹配
v*.*.*	匹配标准三段式版本号	v1.2.3, v2.0.1
v[0-9]*.[0-9]*.*	匹配数字开头的版本号	v1.2.3, v10.0.1
*-alpha*	匹配包含 alpha 的版本	v1.0.0-alpha1
*-beta*	匹配包含 beta 的版本	v1.0.0-beta2
*-rc*	匹配包含 rc 的版本	v1.0.0-rc1
*-*	匹配所有包含连字符的版本	v1.0.0-alpha, v1.0.0-1
v2.*	匹配 v2 开头的所有版本	v2.0.0, v2.1.5
v[12].*.*	匹配 v1 或 v2 开头的版本	v1.0.0, v2.3.1

过滤优先级

1. 首先应用 version-prefix 过滤（获取匹配前缀的标签）
2. 然后应用 tag-match 过滤（保留匹配模式的标签）
3. 最后应用 tag-exclude 过滤（排除匹配模式的标签）
4. 对剩余标签进行版本排序，选择最新版本

注意事项

• 标签过滤主要影响 latest-version 的获取，不影响当前触发版本的识别
• 当通过标签触发时，trigger-version 始终是触发的标签，过滤只影响 latest-version
• 如果过滤后没有匹配的标签，latest-version 将为空
• 建议在使用过滤功能时设置 fetch-depth: 0 以获取完整的标签历史

触发场景

标签触发

当推送版本标签时（如 v1.2.3）：

• is-version-trigger: true
• trigger-version: 1.2.3
• version-with-dash: v1-2-3
• trigger-source: tag

版本分支触发

当推送到版本分支时（如 v1.2.x）：

• is-version-trigger: true
• trigger-version: 1.2.x
• version-with-dash: v1-2-x
• trigger-source: branch

常规分支触发

当推送到普通分支时（如 main、feature/xxx）：

• is-version-trigger: false
• trigger-version: ""
• version-with-dash: ""
• trigger-source: branch

最佳实践

1. 条件部署：使用 is-version-trigger 来决定是否执行生产部署
2. 版本标记：在构建产物中使用 trigger-version 进行版本标记
3. 最新版本获取：使用 latest-version 输出来获取仓库的最新版本，适用于回滚或版本比较
4. Docker 标签：使用 version-with-dash 作为 Docker 镜像标签（避免点号问题）
5. 环境区分：根据触发源选择不同的部署环境
6. 完整历史获取：在工作流中使用 fetch-depth: 0 确保能获取所有标签
7. 日志记录：记录详细的版本信息用于追踪和调试

注意事项

• 版本前缀区分大小写
• 空的版本号会被设置为空字符串
• latest-version 输出始终获取仓库的最新版本，无论触发方式如何
• 获取最新版本需要完整的 Git 历史，建议使用 fetch-depth: 0
• 最新版本按语义化版本排序，确保标签格式符合版本规范
• 确保工作流触发条件与你的版本策略一致
• 在使用输出参数时注意布尔值的字符串比较（使用 == 'true'）

故障排除

如果 Action 没有按预期工作：

1. 检查触发条件是否正确设置
2. 确认版本前缀配置是否正确
3. 查看 Action 日志中的调试信息
4. 验证 Git 引用格式是否符合预期