mirror of
https://git.bjxgj.com/xgj/xgj-actions.git
synced 2025-10-14 23:03:37 +08:00
6fff7a90e1
新增 `tag-match` 和 `tag-exclude` 输入参数，支持通过通配符模式匹配和排除特定标签 更新 README 文档并添加示例配置文件展示标签过滤功能的使用场景
348 lines
12 KiB
Markdown
348 lines
12 KiB
Markdown
# 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 引用格式是否符合预期
|