CI/CD

pubm 旨在同时适配本地终端和 CI runner。关键点在于，正常的 pubm 流程已经知道如何在版本步骤中消耗待处理的 changeset，因此你不需要为了准备 CI 而额外增加一个 pubm changesets version 步骤。

pubm init 可以在 setup 过程中为你生成 CI 工作流。向导会提供创建 .github/workflows/release.yml（tag 触发的发布）和 .github/workflows/changeset-check.yml（PR changeset 强制检查）的选项，无需手动编写。

推荐的发布模型

使用两个阶段：

1. 在本地或受控的 release job 中运行 pubm --mode ci --phase prepare
2. 在 CI 中使用 pubm --mode ci --phase publish 发布

pubm --mode ci --phase prepare

pubm --mode ci --phase publish

CI preparation 会做什么

pubm --mode ci --phase prepare 不只是检查 token。它会把发布流程运行到真正发布之前的那一步：

• 收集 registry token 和插件凭证
• 可选地将 token 同步到 GitHub Secrets
• 运行前置条件和必要条件检查
• 运行测试和构建（除非跳过）
• 在版本步骤中消耗待处理的 changeset（如果存在）
• 创建发布提交并推送 tags 和分支更新
• 对发布任务进行 dry-run，而不执行真正发布

因此，在完成 CI preparation 之后，你不需要再运行 pubm patch --dry-run。

必需的环境变量

在 CI 中，请通过环境变量提供 registry token：

Variable	Registry
NODE_AUTH_TOKEN	npm
JSR_TOKEN	jsr
CARGO_REGISTRY_TOKEN	crates.io

插件也可以声明自己需要的凭证。pubm 会自动收集并解析这些值。在 --ci-prepare 期间，它会提示输入缺失的值并将其同步到 GitHub Secrets；在 --phase publish 期间，它只会从环境变量中读取已解析的值，如果缺少任何必需凭证就会报错。

例如，@pubm/plugin-brew 需要：

变量	用途
PUBM_BREW_GITHUB_TOKEN	用于推送 Homebrew formula 更新并创建 pull request 的 GitHub PAT。

同步 GitHub secrets

如果你已经通过 CI preparation 在本地保存了 token，可以使用以下命令推送到 GitHub Secrets：

pubm secrets sync
pubm secrets sync --registry npm,jsr

GitHub Actions 示例结构

name: Release

on:
  push:
    tags:
      - "v*"
      - "@*"

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - run: pnpm install --frozen-lockfile
      - run: pubm --mode ci --phase publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
          JSR_TOKEN: ${{ secrets.JSR_TOKEN }}
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}

在 CI 中发布 snapshot

使用 pubm snapshot 可以在 CI 中发布预览版本，而无需创建正式 release。这对于在完整发布之前测试包变更非常有用。

- name: Publish snapshot
  run: npx pubm snapshot
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

对于 monorepo，可以过滤要 snapshot 的包：

- name: Publish snapshot
  run: npx pubm snapshot --filter @acme/core --filter @acme/react
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

Snapshot 版本使用由基础版本、tag、时间戳和提交哈希派生的临时版本号发布，不会影响正常的发布版本管理。

常见 CI 陷阱

浅克隆

基于 tag 且依赖历史记录的操作需要完整的 Git 信息。发布 job 请使用 fetch-depth: 0。

缺少 registry token

pubm 在 CI 中无法交互式提示。如果缺少 token，运行会失败。

npm 2FA token 不匹配

CI 发布请使用兼容 automation 的 token。

contents 中没有构建产物

如果你从 dist/ 发布，请确保 workflow 在 pubm --mode ci --phase publish 之前确实创建了 dist/。

GitHub Release 资产

如果你的项目在 pubm.config.ts 中使用了 releaseAssets，那么 pubm --mode ci --phase publish 会运行资产流水线，并自动将构件上传到 GitHub Release。

GITHUB_TOKEN 要求

GitHub Release 创建和资产上传都会使用 GitHub API。请提供 GITHUB_TOKEN（或具备 contents: write 权限的 fine-grained token）。这个 token 不仅用于上传资产，也用于所有 GitHub Release 创建：

- run: pubm --mode ci --phase publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitHub Actions 会在每次 workflow 运行中自动注入 GITHUB_TOKEN 作为内置 secret。你不需要手动创建它，只需通过环境变量传入即可。

上传前必须存在构建产物

资产流水线在构建步骤之后运行。请确保你的 workflow 在 pubm --mode ci --phase publish 执行之前生成了二进制产物（例如 platforms/*/bin/ 中的编译产物）。如果配置的 glob 模式在上传时匹配到 0 个文件，pubm 会将其视为错误。

带 release assets 的示例

name: Release

on:
  push:
    tags:
      - "v*"

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 24

      - run: npm ci
      - run: npm run build       # Must produce platforms/*/bin/mytool
      - run: pubm --mode ci --phase publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

基于 PR 的版本升级工作流

除了直接推送版本升级提交，pubm 还可以改为创建 pull request。当基础分支受到保护或你希望在发布前增加一个审查步骤时，这非常有用。

在 config 中启用：

export default defineConfig({
  createPr: true,
});

或在运行时传入 flag：

pubm --create-pr

启用 createPr 后：

• pubm 创建包含版本升级提交的 pubm/version-packages-* 分支
• 推送该分支并向基础分支开启一个 PR
• PR 会自动添加 no-changeset 标签以跳过 changeset 检查
• PR 合并后，现有的发布工作流通过 tag push 正常触发

当直接推送到受保护的分支失败时，pubm 也会自动回退到 PR 模式。如果只需要回退行为，不必显式配置 createPr。

Changeset 检查（PR 验证）

使用 syi0808/pubm-actions GitHub Action 来强制每个 PR 都包含 changeset。当 changesets 启用时，pubm init 会自动生成此工作流。

name: Changeset Check

on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]

permissions:
  contents: read
  pull-requests: write

jobs:
  changeset-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: syi0808/pubm-actions@v1
        with:
          skip-label: no-changeset

该 action 检测 PR diff 中新增的 .pubm/changesets/*.md 文件，验证其格式，并将结果以评论形式发布。对于不需要 changeset 的 PR（如文档、CI 配置等），添加 no-changeset 标签可跳过检查。

下一步

• 阅读 Troubleshooting 了解故障诊断。
• 阅读 CLI Reference 了解 CI 中使用到的所有执行 flags。
• 阅读 Release Assets 为项目配置 releaseAssets。