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`    |

## 输出参数

| 参数名               | 描述                     | 示例值                          |
| -------------------- | ------------------------ | ------------------------------- |
| `ref-type`           | 引用类型                 | `tag` 或 `branch`               |
| `ref-name`           | 引用名称                 | `v1.2.3`、`main`、`feature/xxx` |
| `is-version-trigger` | 是否为版本触发           | `true` 或 `false`               |
| `trigger-version`    | 触发的版本号（去除前缀） | `1.2.3`                         |
| `version-with-dash`  | 版本号，点替换为横线     | `1-2-3`                         |
| `trigger-source`     | 触发源                   | `tag` 或 `branch`               |
| `full-ref`           | 完整的 Git 引用          | `refs/tags/v1.2.3`              |

## 环境变量

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

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

## 使用示例

### 基本用法

```yaml
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 }}
      version-with-dash: ${{ steps.version-info.outputs.version-with-dash }}
      trigger-source: ${{ steps.version-info.outputs.trigger-source }}
    steps:
      - name: 获取版本信息
        id: version-info
        uses: actions/xgj/trigger-version@v1

      - name: 显示版本信息
        run: |
          echo "是否版本触发: ${{ steps.version-info.outputs.is-version-trigger }}"
          echo "版本号: ${{ steps.version-info.outputs.trigger-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 }}"
```

### 自定义版本前缀

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

### 完整的 CI/CD 流程

```yaml
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. **Docker 标签**：使用 `version-with-dash` 作为 Docker 镜像标签（避免点号问题）
4. **环境区分**：根据触发源选择不同的部署环境
5. **日志记录**：记录详细的版本信息用于追踪和调试

## 注意事项

- 版本前缀区分大小写
- 空的版本号会被设置为空字符串
- 确保工作流触发条件与你的版本策略一致
- 在使用输出参数时注意布尔值的字符串比较（使用 `== 'true'`）

## 故障排除

如果 Action 没有按预期工作：

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