GitHub Actions 自动化发布指南

GitHub Actions 自动化发布指南：Release、Tag、Changelog 与制品仓库

GitHub Actions 不仅能自动运行测试，还能将完整的版本发布链路串联起来：代码合入主分支后自动执行 CI、根据提交历史推断版本号、生成 Changelog、创建 Git Tag，并最终发布 GitHub Release 及各类语言制品。

本文基于主流 Git 仓库的最佳实践，梳理一套可维护的自动化发布方案。我们将重点对比两种核心发布策略------由 Release Please 创建待审核的发布 PR ，以及合入主分支后立即自动发布（semantic-release），随后演示如何将构建产物同步推送至 Maven（Nexus）、Docker（GHCR）和 Python（PyPI）制品仓库。

1. 核心概念与流程拆分

在编写配置前，先理清 GitHub Actions 与版本发布中的几个核心概念：

Workflow（工作流） ：存放在 .github/workflows/ 目录下的 YAML 自动化定义文件。
Event / Trigger（触发器） ：触发工作流运行的事件，例如 push、pull_request、release 或手动触发的 workflow_dispatch。
Job（任务） ：Workflow 中一组在同一个 Runner 上运行的执行单元，多个 Job 默认并行，可通过 needs 声明依赖。
Step（步骤）：Job 内部按顺序执行的 Shell 命令或复用动作（Action）。
Runner（执行器） ：执行 Job 的虚拟环境或物理机器，例如托管环境 ubuntu-latest。
Artifact（工作流产物）：工作流运行期间生成并暂存的文件，用于跨 Job 传递或供开发者下载调试。
Tag（标签） ：指向特定 Git Commit 的不可变版本引用，例如 v1.4.0。
GitHub Release：基于某个 Git Tag 创建的正式发布页面，通常包含版本变更说明（Release Notes）与编译好的发布附件（Release Assets）。

流程拆分原则 ：一个规范的工程项目通常至少拆分为两条独立的自动化链路------日常 CI 验证流程 （在 PR 提审或分支推送时跑测试与静态检查）与正式发布流程（仅在确认发版时生成版本号、Tag 和 Release）。将日常 CI 与发布解耦，能有效避免每次常规构建都误发正式版本。

2. 版本号管理与提交规范

自动化发布的前提是让工具"读懂"代码的变更性质。业界普遍采用语义化版本（Semantic Versioning，简称 SemVer）配合约定式提交（Conventional Commits）。

2.1 语义化版本格式

版本号格式为 MAJOR.MINOR.PATCH（主版本号.次版本号.修订号），例如 2.3.1：

PATCH（修订号） ：向下兼容的问题修正，例如 2.3.1 → 2.3.2。
MINOR（次版本号） ：向下兼容的新功能迭代，例如 2.3.1 → 2.4.0。
MAJOR（主版本号） ：包含不兼容 API 变更的重大升级，例如 2.3.1 → 3.0.0。

2.2 约定式提交（Conventional Commits）

发布工具通过解析 Git Commit Message 的前缀来自动计算下一个版本号并归类 Changelog：

text 复制代码

feat: add export to CSV        # 新增功能 → 自动提升 MINOR
fix: handle empty response     # 修复缺陷 → 自动提升 PATCH
feat!: change config format    # 感叹号代表破坏性变更 → 自动提升 MAJOR
docs: update API guide         # 文档、chore、refactor、test 等默认不触发版本升级

若破坏性变更需要详细说明，也可以在提交正文或页脚中添加 BREAKING CHANGE: ...。

工程实践建议（Squash Merge） ：如果团队觉得要求开发分支上的每一次零碎提交都符合规范成本过高，可以在 GitHub 仓库中启用 Squash and Merge（压缩合并） ，并仅在 CI 中校验 PR 标题是否符合 Conventional Commits。这样合入主分支的记录始终是干净、规范的单条提交。

3. 策略一（推荐）：通过 Release Please 审核发布

对于大多数团队，最稳妥的做法是让工具先自动维护一个 Release PR（发布合并请求）。

每当常规代码合入主分支，工具会自动创建或更新这个 Release PR，在其中集中展示即将发布的版本号、CHANGELOG.md 变更摘要以及版本文件修改。维护者核对无误并点击合并后，工具才会真正打上 Git Tag 并创建 GitHub Release。这种模式兼顾了自动化效率与人工发版审核、排期控制。

3.1 添加配置文件

在仓库根目录创建 release-please-config.json：

json 复制代码

{
  "packages": {
    ".": {
      "release-type": "simple"
    }
  }
}

接着创建 .release-please-manifest.json，首次接入时填入项目当前的基准版本号：

json 复制代码

{
  ".": "1.0.0"
}

simple 类型适用于只需维护 CHANGELOG.md 和 Git Tag 的通用项目。
如果是特定语言项目，可将 release-type 设为 node、python、maven、go 或 rust 等，工具会在开启 Release PR 时自动同步修改 package.json、pyproject.toml 或 pom.xml 中的版本号。

3.2 配置工作流与附加构建产物

创建 .github/workflows/release-please.yml：

yaml 复制代码

name: Release Please

on:
  push:
    branches:
      - main

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    outputs:
      release_created: ${{ steps.release.outputs.release_created }}
      tag_name: ${{ steps.release.outputs.tag_name }}
    steps:
      - name: Create or update release PR
        id: release
        uses: googleapis/release-please-action@v4
        with:
          config-file: release-please-config.json
          manifest-file: .release-please-manifest.json

  # 当 Release PR 被合并、正式创建 Release 时，自动构建并上传附件
  build-assets:
    needs: release-please
    if: ${{ needs.release-please.outputs.release_created == 'true' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.release-please.outputs.tag_name }}
      - name: Build release artifacts
        run: |
          # 替换为项目实际的构建命令
          mkdir -p dist
          echo "build output for ${{ needs.release-please.outputs.tag_name }}" > dist/app-bundle.txt
      - name: Upload assets to GitHub Release
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ needs.release-please.outputs.tag_name }}
        run: gh release upload "$RELEASE_TAG" dist/* --clobber

3.3 这条工作流的完整生命周期

累积变更 ：日常功能或修复合入 main 分支后，Release Please 扫描自上一个版本以来的提交记录。
创建/更新发布 PR ：若存在 feat 或 fix 等有效提交，Action 会自动创建或更新一个 Release PR，实时计算最新版本号并更新 CHANGELOG.md（此时 release_created 为 false，不会执行后续构建）。
人工审核与合并：团队决定发版时，由维护者审查该 Release PR（甚至可以直接在 PR 分支上微调 Changelog 措辞），随后点击合并。
打标与发布产物 ：Release PR 合并入 main 后，再次触发该工作流。此时 Release Please 识别到发布提交，自动创建对应的 Git Tag 和 GitHub Release，并将 release_created 置为 true，紧接着触发 build-assets 任务完成产物编译与附件上传。

为什么推荐把构建任务写在同一个 Workflow 中？

根据 GitHub Actions 的防递归安全机制，使用默认 GITHUB_TOKEN 创建的 Tag 或 Release 不会触发 其他监听 on: release 或 on: push: tags 的工作流。利用 release_created 输出在同一工作流内通过 needs 串联构建任务，无需额外配置个人访问令牌（PAT）或 GitHub App 即可开箱即用。

4. 策略二：合入即发布的持续交付（semantic-release）

如果团队采用高频持续交付模式，希望每次代码合并到 main 分支后无需人工二次确认 ，立即自动计算版本、生成 Changelog、打 Tag 并发布，可以使用 semantic-release。

以 Node.js 项目为例，配置 .github/workflows/semantic-release.yml：

yaml 复制代码

name: Semantic Release

on:
  push:
    branches:
      - main

permissions:
  contents: write
  issues: write
  pull-requests: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'
      - run: npm ci
      - run: npm test
      - name: Run semantic-release
        run: npx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

注意事项：

完整历史检出 ：必须设置 fetch-depth: 0，以便工具拉取完整的 Git 提交历史与 Tag 记录进行比对。
插件生态 ：项目需预先配置好 .releaserc 及所需插件（如 @semantic-release/commit-analyzer、@semantic-release/release-notes-generator、@semantic-release/github）。如果需要将更新后的 CHANGELOG.md 或 package.json 推回主分支，还需引入 @semantic-release/git 插件。
严格的前置门禁 ：由于代码一旦进入 main 就会立刻发出正式版，仓库必须开启严格的分支保护策略（Branch Protection Rules），强制要求通过 PR 合并且所有 CI 检查绿灯后方可合入。

5. 发布策略对比与选型

对比维度	Release Please（发布 PR 模式）	semantic-release（直接发布模式）	手写 `git tag` 触发工作流
核心机制	自动维护待合并的 Release PR	合入主分支后直接在 CI 中发版	开发者手动打 Tag 推送触发
Tag / Release 时机	维护者手动合并 Release PR 后	代码合入主分支且包含有效提交时	执行 `git push --tags` 时
Changelog 可控性	高（发版前可在 PR 中人工润色）	完全依赖 Commit Message 自动生成	需自行编写或借助原生生成工具
适用场景	有发版排期、需人工确认版本的多数团队	高频迭代、全自动持续交付的基础库或微服务	发布逻辑极简、版本节奏完全人工控制的项目

唯一事实来源原则 ：无论选择哪种方式，切勿在同一个仓库中混用多个版本管理工具，否则极易出现 Tag 重复创建、版本号互相覆盖或工作流死循环冲突。

6. 进阶：将制品发布到包管理仓库

GitHub Release 的附件适合提供给终端用户直接下载；而供团队内部复用的 SDK、依赖库或服务端容器，通常还需要发布到专门的制品仓库（Artifact Registry）：例如 Java 包发布到 Maven 仓库（如 Nexus），容器镜像推送到 Docker Registry（如 GHCR），Python 包发布到 PyPI 或企业私有源。

以下示例演示独立监听 release: [published] 事件的标准写法（适用于手动点击发布 Release、或使用 GitHub App Token 触发 Release 的场景；若与第 3 节搭配且使用默认 GITHUB_TOKEN，可直接将下方的 steps 作为后续 Job 合并到 release-please.yml 中）。

6.1 Java：构建 JAR 并发布到 Nexus

在企业 Nexus Repository 中，通常会区分三类仓库：

Hosted（宿主仓库）：用于接收内部项目的上传与发布。
Proxy（代理仓库）：用于代理并缓存 Maven Central 等外部公共源。
Group（组合仓库）：将多个 Hosted 与 Proxy 聚合为一个统一地址，供开发者下载依赖。

注意：CI 发布的上传目标 URL 必须指向 Hosted 仓库 （例如 maven-releases），而不能填写供下载使用的 Group 或 Proxy 地址。

在 GitHub 仓库的 Settings → Secrets and variables → Actions 中配置专用部署账号凭据：
- NEXUS_USERNAME
- NEXUS_PASSWORD
- NEXUS_MAVEN_URL（如 [https://nexus.example.com/repository/maven-releases/](https://nexus.example.com/repository/maven-releases/)）
在项目的 pom.xml 中配置 distributionManagement，确保 <id> 与工作流中的 server-id 保持一致：

xml 复制代码

<distributionManagement>
  <repository>
    <id>nexus-releases</id>
    <url>${env.NEXUS_MAVEN_URL}</url>
  </repository>
</distributionManagement>

配置发布工作流 .github/workflows/publish-maven.yml：

yaml 复制代码

name: Publish Maven Package

on:
  release:
    types: [published]

permissions:
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.release.tag_name }}
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: '21'
          cache: maven
          server-id: nexus-releases
          server-username: NEXUS_USERNAME
          server-password: NEXUS_PASSWORD
      - name: Publish to Nexus
        env:
          NEXUS_USERNAME: ${{ secrets.NEXUS_USERNAME }}
          NEXUS_PASSWORD: ${{ secrets.NEXUS_PASSWORD }}
          NEXUS_MAVEN_URL: ${{ secrets.NEXUS_MAVEN_URL }}
        run: mvn --batch-mode --no-transfer-progress deploy -DskipTests

actions/setup-java 会自动生成包含认证信息的 settings.xml。
请确保 Git Tag 检出的 pom.xml 中已是正式版本号（不含 -SNAPSHOT），或通过 Maven CI Friendly Versions（${revision}）在构建时传入与 Tag 一致的版本号。Nexus 的 Release 宿主仓库默认禁止重复覆盖同一版本。
若使用 Gradle ，可配置 maven-publish 插件并从环境变量读取仓库地址与凭据，通过 ./gradlew publish 完成上传，切勿将凭据硬编码在 build.gradle 中。

6.2 Docker：构建并推送容器镜像

容器镜像通常推送到 GitHub Container Registry（GHCR）、Docker Hub 或企业私有 Harbor。以下示例将镜像推送至 GHCR，并同时打上版本 Tag 与 latest 标签：

yaml 复制代码

name: Publish Container Image

on:
  release:
    types: [published]

permissions:
  contents: read
  packages: write

jobs:
  docker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.release.tag_name }}
      - name: Normalize image name to lowercase
        id: image
        run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
      - name: Log in to GHCR
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${GITHUB_ACTOR}" --password-stdin
      - name: Build and push image
        env:
          IMAGE: ${{ steps.image.outputs.name }}
          TAG: ${{ github.event.release.tag_name }}
        run: |
          docker build -t "$IMAGE:$TAG" -t "$IMAGE:latest" .
          docker push "$IMAGE:$TAG"
          docker push "$IMAGE:latest"

镜像名小写规范 ：OCI 规范要求镜像仓库路径必须全部为小写字母，因此使用 ${GITHUB_REPOSITORY,,} 将仓库名称转换为小写。
生产级进阶 ：在复杂生产项目中，推荐使用官方的 docker/login-action 搭配 docker/build-push-action 与 Docker Buildx，以便轻松开启层缓存（GitHub Cache）、多架构构建（linux/amd64,linux/arm64）以及 SBOM / Provenance 签名证明。
部署建议 ：生产环境部署切勿仅依赖可变的 latest 标签，应当固定使用不可变的语义化版本 Tag（如 v1.2.3）或镜像 Digest（@sha256:...），以保障回滚与审计的确定性。

6.3 Python：构建并发布到 PyPI 或企业私有源

现代 Python 项目的标准发布产物为源码包（sdist）与预编译包（wheel）。我们可以借助 uv 快速完成构建，并使用 twine 上传至私有仓库：

yaml 复制代码

name: Publish Python Package

on:
  release:
    types: [published]

permissions:
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.release.tag_name }}
      - uses: astral-sh/setup-uv@v5
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Build distributions (sdist and wheel)
        run: uv build
      - name: Publish to private PyPI repository
        env:
          TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
          TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
          TWINE_REPOSITORY_URL: ${{ secrets.PYPI_REPOSITORY_URL }}
        run: uvx twine upload dist/*

Python 制品发布的几个关键细节：

区分下载源与上传源 ：pip 或 uv 配置的 index-url 决定了从哪里下载安装依赖 （通常指向企业 Mirror 镜像代理或 Group 聚合源）；而 TWINE_REPOSITORY_URL 决定了把包上传到哪里 ，必须指向允许写入的 PyPI Hosted 端点。切勿尝试向只读的公共 PyPI 镜像站上传内部包。
公共 PyPI 免密发布（Trusted Publishing） ：如果是开源项目发布到官方公共 PyPI，推荐使用基于 OIDC 的 Trusted Publishing 机制，配合 pypa/gh-action-pypi-publish 并声明 permissions: id-token: write，无需在 GitHub 中手动保存任何长期 API Token。
版本号一致性 ：Python 包版本必须符合 PEP 440 规范。可通过 Release Please 在发版 PR 中自动更新 pyproject.toml，或借助 hatch-vcs / setuptools-scm 在构建时直接从 Git Tag 动态读取版本号。
区分 PyPI 与 Conda ：若团队需要分发 Conda 包，则属于另一套工具链（需通过 conda-build 构建 .conda 产物并上传至 Anaconda.org 或企业自建 Conda Channel）。

6.4 制品发布的通用工程准则

构建与源码严格对齐 ：始终基于正式的 Release Tag（ref: ${``{ github.event.release.tag_name }}）检出代码进行构建，杜绝"用主分支最新散落提交打包，却冠以旧版本 Tag"的错位现象。
一次构建，多处分发：如果同一个产物需要同时上传到 GitHub Release 和多个制品仓库，建议在独立构建 Job 中编译一次并上传为 Workflow Artifact，后续各发布 Job 下载同一份产物进行分发，保证二进制完全一致。
版本不可变性（Immutability） ：已发布的正式版本号绝不应被静默覆盖。若发现发布包有缺陷，应当修复代码后递增 PATCH 版本号（如发布 1.2.4），而不是删除并重写 1.2.3。
生产环境审批保护 ：可在 GitHub Environments 中创建 release 或 production 环境，配置必选审批人（Required Reviewers）与仅允许受保护分支/Tag 部署的限制，并将发布凭据收敛为 Environment Secrets。

7. GitHub Token 机制与安全权限实践

最小权限原则 ：在 Workflow 顶层或 Job 级别显式声明 permissions，只授予必需的最小权限（例如 Release Please 仅需 contents: write 和 pull-requests: write；普通构建上传包到外部仓库仅需 contents: read）。
检查仓库全局开关 ：首次接入时，需进入仓库 Settings → Actions → General → Workflow permissions ，确认已勾选 Read and write permissions ，以及 Allow GitHub Actions to create and approve pull requests（否则 Release Please 无法自动创建发版 PR）。
理解 GITHUB_TOKEN 的防递归限制 ：为了防止工作流死循环，GitHub 规定由默认 GITHUB_TOKEN 触发的任何事件（如推送提交、创建 Tag、发布 Release）均不会触发新的 Workflow 运行 。如果需要跨工作流触发，推荐以下两种方案：
1. 同文件 Job 串联（首选） ：将下游构建与发布任务作为同一个 YAML 文件中的后续 Job，通过 needs 与 if 条件衔接（见 3.2 节示例）。
2. 使用 GitHub App Token ：在组织或仓库中创建专用 GitHub App，在工作流中通过 actions/create-github-app-token 换取短期令牌来替代默认 GITHUB_TOKEN，避免使用绑定个人账号的长期 PAT。
第三方 Action 供应链安全 ：生产项目引入第三方 Action 时，建议先审查其源码与维护状态；对安全合规要求较高的团队，可将 Action 版本固定到经过审计的完整 Commit SHA（如 uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2），防止上游标签被恶意篡改。

8. 常见问题排查（FAQ）

Q1：代码合入主分支后，为什么没有生成 Release PR？

请按以下顺序排查：

推送的目标分支名称是否与 YAML 中的 branches 完全一致。
本次合入的 Commit Message 是否包含触发版本升级的前缀（默认仅 feat:、fix: 或带 ! / BREAKING CHANGE 的提交会触发发版；纯 chore:、docs:、ci: 不会触发）。
仓库 Settings → Actions → General 中是否勾选了允许 GitHub Actions 创建 Pull Request。
.release-please-manifest.json 的 JSON 语法及路径配置是否正确。

Q2：生成的 Changelog 为空，或者条目分类不符合预期？

Changelog 生成器高度依赖规范的 Commit 格式。若团队成员在开发分支提交记录较随意，建议开启仓库的 Squash and Merge 并配置 PR Title Linter。若单次发版中出现分类遗漏，维护者可以直接在合并 Release PR 之前手动编辑该 PR 中的 CHANGELOG.md 文件。

Q3：为什么生成的 Tag 前缀（如带不带 `v`）与项目历史习惯不一致？

检查工具的标签前缀配置。例如在 release-please-config.json 中可通过 "include-v-in-tag": true 或 "include-component-in-tag": false 控制 Tag 格式。如果是老项目迁移，务必先对齐历史 Tag 命名格式，避免工具无法识别上一个基准版本。

Q4：发版后发现严重 Bug，如何撤回已发布版本？

在 GitHub 页面删除 Release 或删除 Git Tag 并不会自动撤回已经同步到 Nexus、PyPI 或 GHCR 的包，更无法清除外部用户已经拉取到本地的缓存。正确做法是：

在包管理平台将该问题版本标记为 Yanked / Deprecated（弃用但保留记录，避免破坏已有锁定依赖的构建）。
提交修复代码，立即按流程发布下一个 PATCH 修正版本（如 v1.2.4）。
切勿删除旧版本后重新发布同名版本号。

9. 上线前自检清单

在将自动化发布流程投入生产仓库前，建议逐项核对以下清单：

分支对齐 ：Workflow 监听的默认分支名（如 main）与仓库实际默认分支一致。
提交规范：团队已对齐 Conventional Commits 规范，或已配置 Squash Merge 校验 PR 标题。
基准版本 ：.release-please-manifest.json（及项目自身配置文件）中的初始版本号与最新已发布版本一致。
仓库权限：已在仓库 Actions 设置中开启读写权限及允许 Action 创建 PR 的开关。
职责单一：确认全仓仅保留一套工具管理版本号、Git Tag 与 GitHub Release，无冲突脚本。
质量门禁：主分支已配置分支保护规则，要求通过 CI 测试后方可合入。
制品指向：Maven / PyPI / Docker 的上传地址均已确认为可写的 Hosted 仓库，且凭据已妥善存入 GitHub Secrets 或配置好 OIDC。
沙箱演练 ：首次接入时，已先在测试仓库或 alpha/rc 预发布分支走通完整的端到端发布链路。

GitHub Actions 自动化发布指南