From da4e1db20d7378aaa51588d899659a3f5b5e0c5c Mon Sep 17 00:00:00 2001 From: Lyda <1829913225@qq.com> Date: Wed, 20 Aug 2025 18:39:38 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=A2=9E=E5=BC=BA=20Web=20=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E5=8F=91=E5=B8=83=E6=9E=84=E5=BB=BA=E7=9A=84=20GitHub?= =?UTF-8?q?=20Action=EF=BC=8C=E6=B7=BB=E5=8A=A0=E5=8F=91=E5=B8=83=E5=A4=B1?= =?UTF-8?q?=E8=B4=A5=E6=97=B6=E7=9A=84=E9=94=99=E8=AF=AF=E5=A4=84=E7=90=86?= =?UTF-8?q?=E9=80=89=E9=A1=B9=EF=BC=8C=E6=94=AF=E6=8C=81=E7=8A=B6=E6=80=81?= =?UTF-8?q?=E7=9B=91=E6=8E=A7=E5=92=8C=E9=80=80=E5=87=BA=E7=A0=81=E8=BE=93?= =?UTF-8?q?=E5=87=BA=EF=BC=8C=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3=E4=BB=A5?= =?UTF-8?q?=E5=8F=8D=E6=98=A0=E6=96=B0=E5=8A=9F=E8=83=BD=E5=92=8C=E4=BD=BF?= =?UTF-8?q?=E7=94=A8=E7=A4=BA=E4=BE=8B=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- release-web/README.md | 184 +++++++++++++++++++++++++++++++++++++---- release-web/action.yml | 70 +++++++++++++++- 2 files changed, 234 insertions(+), 20 deletions(-) diff --git a/release-web/README.md b/release-web/README.md index 2a24e9f..fb333f4 100644 --- a/release-web/README.md +++ b/release-web/README.md @@ -9,8 +9,10 @@ - 🚀 **自动化发布**: 支持任意发布命令进行版本管理和发布 - 🌍 **环境变量支持**: 支持传递任意数量的环境变量给发布命令 - 📦 **智能版本处理**: 自动获取版本号，确保输出格式一致（无 `v` 前缀） +- 📊 **状态监控**: 实时监控发布状态，支持成功/失败状态输出和退出码 - 🔧 **简洁配置**: 最小化配置，专注于发布核心功能 - ✅ **灵活使用**: 可配置发布命令，适应不同项目需求 +- 🛡️ **错误控制**: 可配置发布失败时的行为（中断或继续） ## 快速开始 @@ -83,11 +85,12 @@ Action 自动处理各种版本格式，确保输出一致： ## 输入参数 -| 参数名 | 描述 | 必需 | 默认值 | -| ----------------- | ------------------------- | ---- | --------------------------------- | -| `release-command` | 发布命令 | ❌ | `npm run release -- --release -V` | -| `node-debug` | 是否启用 Node.js 调试模式 | ❌ | `false` | -| `version-file` | 自定义版本文件路径 | ❌ | `/tmp/last-version` | +| 参数名 | 描述 | 必需 | 默认值 | +| ----------------- | ---------------------------- | ---- | --------------------------------- | +| `release-command` | 发布命令 | ❌ | `npm run release -- --release -V` | +| `node-debug` | 是否启用 Node.js 调试模式 | ❌ | `false` | +| `version-file` | 自定义版本文件路径 | ❌ | `/tmp/last-version` | +| `fail-on-error` | 发布失败时是否让 action 失败 | ❌ | `true` | ## 环境变量支持 @@ -120,10 +123,12 @@ Action 支持通过 `env` 传递**任意数量**的环境变量给发布命令 ## 输出参数 -| 参数名 | 描述 | -| ------------------- | ------------------------ | -| `version` | 发布的版本号 | -| `version-with-dash` | 版本号（点号替换为横线） | +| 参数名 | 描述 | +| ------------------- | -------------------------------------- | +| `version` | 发布的版本号 | +| `version-with-dash` | 版本号（点号替换为横线） | +| `release-status` | 发布命令执行状态 (`success`/`failure`) | +| `exit-code` | 发布命令退出码（仅在失败时有值） | ## 使用场景 @@ -210,16 +215,107 @@ steps: APP_ENV: ${{ matrix.app_env }} ``` +### 4. 状态检查和错误处理 + +演示如何处理发布状态和错误： + +```yaml +steps: + - uses: actions/checkout@v4 + + - name: 发布项目 + id: release + uses: actions/xgj/release-web@main + with: + fail-on-error: false # 发布失败时不中断 workflow + env: + GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }} + + # 总是执行的清理步骤 + - name: 清理临时文件 + if: always() + run: | + echo "清理临时文件..." + rm -rf temp/ dist/temp/ + + # 根据发布状态执行不同操作 + - name: 处理发布结果 + if: always() + run: | + echo "发布状态: ${{ steps.release.outputs.release-status }}" + + if [[ "${{ steps.release.outputs.release-status }}" == "success" ]]; then + echo "✅ 发布成功，版本: ${{ steps.release.outputs.version }}" + echo "开始部署流程..." + else + echo "❌ 发布失败，退出码: ${{ steps.release.outputs.exit-code }}" + echo "发送失败通知..." + # 这里可以添加通知逻辑 + fi + + # 只在成功时执行的部署步骤 + - name: 部署到生产环境 + if: steps.release.outputs.release-status == 'success' + run: | + echo "部署版本 ${{ steps.release.outputs.version }} 到生产环境" + kubectl set image deployment/app app=registry.com/app:${{ steps.release.outputs.version }} + + # 失败时的回退操作 + - name: 回退操作 + if: steps.release.outputs.release-status == 'failure' + run: | + echo "执行回退操作..." + # 回退到上一个稳定版本的逻辑 +``` + +### 5. 严格模式发布（默认行为） + +适用于生产环境，发布失败时立即停止： + +```yaml +steps: + - uses: actions/checkout@v4 + + - name: 发布项目 + id: release + uses: actions/xgj/release-web@main + with: + fail-on-error: true # 默认值，发布失败时中断 workflow + env: + GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }} + APP_ENV: "production" + + # 这个步骤只有在发布成功时才会执行 + - name: 部署到生产环境 + run: | + echo "部署版本 ${{ steps.release.outputs.version }}" + kubectl apply -f k8s/ +``` + ## 工作流程 1. **发布构建**: 执行指定的发布命令进行版本发布 -2. **智能版本获取**: 通过多种方法自动获取版本号 + + - 捕获命令执行状态和退出码 + - 设置 `release-status` 输出（`success`/`failure`） + - 失败时记录 `exit-code` 输出 + +2. **智能版本获取**: 只在发布成功时执行，通过多种方法自动获取版本号 + - 优先从版本文件读取（`/tmp/last-version` 或自定义路径） - 回退到最新 git tag（自动去除 `v` 前缀） - 回退到 `package.json` 中的版本 - 最后尝试从提交信息解析（支持 `v1.2.3` 和 `1.2.3` 格式） - **所有方法都确保输出不包含 `v` 前缀** -3. **发布总结**: 输出发布信息和结果 + +3. **发布总结**: 显示详细的发布状态信息 + + - 成功时：显示版本号和发布信息 + - 失败时：显示错误状态和退出码 + +4. **状态检查**: 根据 `fail-on-error` 参数决定最终行为 + - `true`（默认）：发布失败时让 action 失败，中断 workflow + - `false`：发布失败时继续完成，允许后续步骤执行 ## 依赖要求 @@ -282,12 +378,28 @@ CMD ["npm", "start"] ## 错误处理 -Action 会在以下情况报错并退出： +### 发布失败处理 -- 缺少必需的 `gitea-token` 参数 -- 指定的 `Dockerfile` 不存在 -- `/tmp/last-version` 文件不存在（发布命令未正确执行） -- Docker 构建失败 +Action 提供灵活的错误处理机制： + +**严格模式** (`fail-on-error: true` - 默认)： + +- 发布命令失败时，action 立即失败并中断 workflow +- 适用于生产环境，确保发布质量 + +**宽松模式** (`fail-on-error: false`)： + +- 发布命令失败时，action 继续完成并返回状态信息 +- 允许执行清理、通知等后续操作 +- 可通过 `outputs.release-status` 检查发布结果 + +### 常见错误情况 + +Action 会在以下情况报错： + +- 发布命令执行失败（返回非零退出码） +- 无法获取版本信息（所有版本获取方法都失败） +- 版本文件不存在且无其他版本源 ## 安全注意事项 @@ -300,6 +412,46 @@ Action 会在以下情况报错并退出： ### 常见问题 +### Q: 如何处理发布失败的情况？ + +A: Action 提供了多种方式处理发布失败： + +1. **检查发布状态**： + + ```yaml + - name: 发布项目 + id: release + uses: actions/xgj/release-web@main + + - name: 检查发布结果 + run: | + if [[ "${{ steps.release.outputs.release-status }}" == "failure" ]]; then + echo "发布失败，退出码: ${{ steps.release.outputs.exit-code }}" + # 执行失败处理逻辑 + fi + ``` + +2. **宽松模式处理**： + + ```yaml + - name: 发布项目 + uses: actions/xgj/release-web@main + with: + fail-on-error: false # 失败时不中断 + + - name: 清理操作 + if: always() + run: echo "总是执行清理" + ``` + +### Q: 如何获取发布失败的详细信息？ + +A: 通过输出参数获取： + +- `release-status`: `success` 或 `failure` +- `exit-code`: 失败时的命令退出码 +- 检查 action 日志中的详细错误信息 + ### Q: 无法获取版本信息 ```bash diff --git a/release-web/action.yml b/release-web/action.yml index d58452e..e1779cf 100644 --- a/release-web/action.yml +++ b/release-web/action.yml @@ -21,6 +21,11 @@ inputs: description: '自定义版本文件路径，默认为 /tmp/last-version' required: false default: '/tmp/last-version' + + fail-on-error: + description: '发布失败时是否让 action 失败 (true/false)' + required: false + default: 'true' outputs: version: @@ -30,23 +35,47 @@ outputs: version-with-dash: description: '版本号（点号替换为横线）' value: ${{ steps.get_var.outputs.version_with_dash }} + + release-status: + description: '发布命令执行状态 (success/failure)' + value: ${{ steps.release_build.outputs.status }} + + exit-code: + description: '发布命令退出码（仅在失败时有值）' + value: ${{ steps.release_build.outputs.exit_code }} runs: using: 'composite' steps: - name: 发布构建 + id: release_build shell: bash run: | echo "🚀 开始发布构建..." echo "执行命令: ${{ inputs.release-command }}" + + # 设置错误处理，防止命令失败时立即退出 + set +e ${{ inputs.release-command }} - echo "✅ 发布构建完成" + RELEASE_EXIT_CODE=$? + set -e + + # 根据退出码设置状态 + if [ $RELEASE_EXIT_CODE -eq 0 ]; then + echo "status=success" >> $GITHUB_OUTPUT + echo "✅ 发布构建完成" + else + echo "status=failure" >> $GITHUB_OUTPUT + echo "❌ 发布构建失败 (退出码: $RELEASE_EXIT_CODE)" + echo "exit_code=$RELEASE_EXIT_CODE" >> $GITHUB_OUTPUT + fi env: NODE_DEBUG: ${{ inputs.node-debug == 'true' && 'release-it:*' || '' }} - name: 获取版本信息 id: get_var shell: bash + if: steps.release_build.outputs.status == 'success' run: | echo "📝 获取版本信息..." VERSION="" @@ -108,8 +137,41 @@ runs: - name: 发布总结 shell: bash + if: always() run: | - echo "🎉 发布流程完成！" + echo "📋 发布流程总结" echo "" - echo "📋 发布信息:" - echo " - 版本号: ${{ steps.get_var.outputs.version }}" + echo "📊 发布状态: ${{ steps.release_build.outputs.status }}" + + if [[ "${{ steps.release_build.outputs.status }}" == "success" ]]; then + echo "🎉 发布构建成功完成！" + echo "" + echo "📋 发布信息:" + echo " - 版本号: ${{ steps.get_var.outputs.version }}" + echo " - 带横线版本: ${{ steps.get_var.outputs.version_with_dash }}" + else + echo "❌ 发布构建失败" + echo "" + echo "📋 错误信息:" + echo " - 状态: 失败" + if [[ -n "${{ steps.release_build.outputs.exit_code }}" ]]; then + echo " - 退出码: ${{ steps.release_build.outputs.exit_code }}" + fi + echo " - 建议: 请检查发布命令和项目配置" + fi + + - name: 检查发布结果 + shell: bash + if: always() + run: | + if [[ "${{ steps.release_build.outputs.status }}" == "failure" ]]; then + if [[ "${{ inputs.fail-on-error }}" == "true" ]]; then + echo "❌ 发布失败，根据 fail-on-error=true 设置，终止 action 执行" + exit 1 + else + echo "⚠️ 发布失败，但根据 fail-on-error=false 设置，action 将继续完成" + echo "💡 您可以通过 outputs.release-status 检查发布状态" + fi + else + echo "✅ 发布成功，action 正常完成" + fi