Files
xgj/trigger-version/README.md
Lyda 6fff7a90e1 feat(trigger-version): 添加标签过滤功能支持通配符匹配和排除
新增 `tag-match` 和 `tag-exclude` 输入参数,支持通过通配符模式匹配和排除特定标签
更新 README 文档并添加示例配置文件展示标签过滤功能的使用场景
2025-08-22 13:22:31 +08:00

348 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
## 使用示例
### 基本用法
```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 }}
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 }}"
```
### 使用最新版本功能
````yaml
- 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 流程
```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 }} 到生产环境"
```
## 标签过滤功能详解
### 通配符模式支持
`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 引用格式是否符合预期