feat: 添加触发版本信息的 GitHub Action，支持标签、版本分支和常规分支触发，提供详细的输出信息和环境变量，更新文档以反映新功能和使用示例。

2025-10-14 11:23:37 +08:00 · 2025-08-20 20:38:33 +08:00
parent e4063690cd
commit 84f608690b
6 changed files with 887 additions and 0 deletions
--- a/trigger-version/README.md
+++ b/trigger-version/README.md
@@ -0,0 +1,194 @@
+# Trigger Version Info Action
+
+这个 GitHub Action 用于检测工作流的触发方式并提取版本信息，支持标签触发、版本分支触发和常规分支触发。
+
+## 功能特性
+
+- 🏷️ **标签触发检测**：自动识别版本标签（如 `v1.2.3`）并提取版本号
+- 🔄 **版本分支检测**：识别版本分支（如 `v1.2.x`）并提取版本信息
+- 🆕 **常规分支处理**：对于非版本分支提供基础信息
+- 🎯 **灵活的版本前缀**：支持自定义版本前缀（默认为 `v`）
+- 📤 **环境变量输出**：自动设置环境变量供后续步骤使用
+- 📊 **详细的输出信息**：提供完整的引用信息和触发状态
+
+## 输入参数
+
+| 参数名           | 描述                             | 必需 | 默认值 |
+| ---------------- | -------------------------------- | ---- | ------ |
+| `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`                         |
+| `trigger-source`     | 触发源                   | `tag` 或 `branch`               |
+| `full-ref`           | 完整的 Git 引用          | `refs/tags/v1.2.3`              |
+
+## 环境变量
+
+Action 会自动设置以下环境变量：
+
+- `IS_VERSION_TRIGGER`: 是否为版本触发（true/false）
+- `TRIGGER_VERSION`: 触发的版本号
+- `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 }}
+      trigger-source: ${{ steps.version-info.outputs.trigger-source }}
+    steps:
+      - 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.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 }}"
+```
+
+### 自定义版本前缀
+
+```yaml
+- name: 获取版本信息（自定义前缀）
+  id: version-info
+  uses: ./trigger-version
+  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: ./trigger-version
+
+      - 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`
+- `trigger-source`: `tag`
+
+### 版本分支触发
+
+当推送到版本分支时（如 `v1.2.x`）：
+
+- `is-version-trigger`: `true`
+- `trigger-version`: `1.2.x`
+- `trigger-source`: `branch`
+
+### 常规分支触发
+
+当推送到普通分支时（如 `main`、`feature/xxx`）：
+
+- `is-version-trigger`: `false`
+- `trigger-version`: `""`
+- `trigger-source`: `branch`
+
+## 最佳实践
+
+1. **条件部署**：使用 `is-version-trigger` 来决定是否执行生产部署
+2. **版本标记**：在构建产物中使用 `trigger-version` 进行版本标记
+3. **环境区分**：根据触发源选择不同的部署环境
+4. **日志记录**：记录详细的版本信息用于追踪和调试
+
+## 注意事项
+
+- 版本前缀区分大小写
+- 空的版本号会被设置为空字符串
+- 确保工作流触发条件与你的版本策略一致
+- 在使用输出参数时注意布尔值的字符串比较（使用 `== 'true'`）
+
+## 故障排除
+
+如果 Action 没有按预期工作：
+
+1. 检查触发条件是否正确设置
+2. 确认版本前缀配置是否正确
+3. 查看 Action 日志中的调试信息
+4. 验证 Git 引用格式是否符合预期