GitHub Actions 作者的自动版本化

抱歉，我需要您提供要翻译的完整文本内容（除代码块和链接外的文字）。请把文章的正文粘贴在这里，我会按照要求保留源链接并将其余部分翻译成简体中文。

概览

作为三个 GitHub Actions 的维护者，我一直在版本管理上有些困扰。GitHub 的文档提供了一些指引，但没有简单的方法来验证一切是否正确。快速浏览 Marketplace 我发现我并不孤单——甚至 GitHub 自己的一些 Action 也存在不一致的情况。

正因如此，我在几年前凑合写出了 v1 版的 Actions Semver Checker。它当时满足了我的需求，但最初的实现存在一些 bug，维护起来很困难，而且任何改动都让人感到风险，因为我无法轻松测试是否破坏了什么。

从 v1 到 v2

我让 Copilot Agent 以 v1 代码为蓝图，并在以下约束条件下进行重构：

我向 Copilot 提供了相关的 GitHub 文档和博客链接（CLI 发布命令、Releases REST API、Tags REST API、GraphQL API、不可变发布、Actions 版本管理）。Claude Opus 帮助生成了详细计划，我在让 Copilot 花约 45 分钟编码前对其进行了微调。

最终得到的是一个 first‑vibe‑coded 的 GitHub Action，基本实现了所需功能，同时也暴露了计划中的几个缺口，并在两个实现之间产生了一些有趣的交织。

在构建了 90+ 测试 的测试套件后，我对调整行为充满信心。经过多轮与 Copilot 的来回交流以及在 VS Code 中的动手实践，我很自豪地发布 v2 版的 GitHub Actions Semver Checker。

操作的功能

该操作旨在安装在托管 GitHub Action 的仓库内部（例如 actions/checkout 或 jessehouwing/actions-semver-checker）。它会分析所有分支、标签和发布，并根据一套规则进行验证。

核心验证规则（v1）

新验证规则（v2）

对于几乎所有这些验证，autofix 选项会自动纠正发现的问题。如果操作无法修复某个问题，它会在工作流的摘要页面记录手动修复步骤。

自动修复功能

其他改进

• 可配置的规则套件 – 选择要运行的规则组。
• 无需完整检出 – 此操作不再需要检出整个仓库。
• 重试与速率限制处理 – 为 API 速率限制提供内置重试逻辑。
• PowerShell Gallery 模块 – 可作为 PowerShell Gallery 上的模块使用。

破坏性更改 (v1 → v2)

现在必须将机密 ${{ secrets.GITHUB_TOKEN }} 传递给操作的 token: 输入。

入门

1. 安装此 Action 在你的 action 仓库中使用默认设置。它会分析仓库并报告任何规则违规。

2. 调整设置 以匹配你期望的行为：

示例工作流

name: Check SemVer

on:
  push:
    branches: ['main']
    tags:
      - '*'
  workflow_dispatch:

permissions: {}

jobs:
  check-semver:
    permissions:
      contents: write   # needed for validations & autofix
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
      cancel-in-progress: true
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository (shallow)
        uses: actions/checkout@v4
        with:
          fetch-depth: 1   # no need for full history

      - name: Run SemVer Checker (v2)
        uses: jessehouwing/actions-semver-checker@v2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          floating-versions-use: tags
          check-minor-version: warning
          check-releases: error
          check-release-immutability: warning
          ignore-preview-releases: true
          ignore-versions: |
            0.0.1
            1.0.0-beta

摘要

• v2 添加了许多新的验证规则和强大的自动修复系统。
• 该动作 完全可配置，无需完整检出，并且包含 重试和速率限制处理。
• 它以 PowerShell Gallery 模块 形式提供，并且可以 与 v1 并行运行，便于比较。

随意尝试，调整输入以适应你的工作流，让该动作保持你的 GitHub Action 发布清洁、一致且不可变！

GitHub 工作流示例

# Example job fragment
{{ github.workflow }}:
  cancel-in-progress: true

  runs-on: ubuntu-latest

  steps:
    - uses: jessehouwing/actions-semver-checker@v2
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        check-release-immutability: none

⚠️ 重要:
在启用 autofix 之前，请格外小心 check-release-immutability 设置。大多数自动修复可以通过 Git 命令行轻松撤销，但一旦发布被设为不可变，就无法恢复。

1️⃣ 清理已有标签

在清理完现有标签并了解其影响后，启用 release‑immutability 检查：

steps:
  - uses: jessehouwing/actions-semver-checker@v2
    with:
      token: ${{ secrets.GITHUB_TOKEN }}
      check-release-immutability: error

2️⃣ 以只读模式运行

在只读模式下使用该 Action 一段时间，手动执行建议的修复步骤。

3️⃣ 启用 autofix（可选）

当你确信该 Action 能满足需求时，可考虑打开 autofix：

steps:
  - uses: jessehouwing/actions-semver-checker@v2
    with:
      token: ${{ secrets.GITHUB_TOKEN }}
      autofix: true

autofix 的工作原理

打开 autofix 后，发布新版本并更新所有标签和发布唯一需要做的事就是 推送一个新标签（例如 vX.Y.Z）。这将触发 Action：

1. 创建一个名称正确的新发布。
2. 自动更新所有相关标签。

就这么简单——无需再进行任何手动步骤！