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

输出参数

参数名	描述	示例值
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-"

完整的 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 }} 到生产环境"

触发场景

标签触发

当推送版本标签时（如 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 引用格式是否符合预期