autoship

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Autoship

Automate npm releases with a changeset -> fix -> push -> monitor -> merge -> publish workflow.

通过变更集（changeset）→ 修复 → 推送 → 监控 → 合并 → 发布的工作流自动化npm包发布。

Reference Files

参考文件

File	Read when
`references/changeset-and-commit.md`	Creating a changeset, fixing quality issues, or committing and pushing
`references/ci-polling.md`	Watching CI with the Monitor tool, diagnosing failures, or handling retries
`references/version-pr-and-publish.md`	Searching for the Version Packages PR, merging it, or watching the release workflow

文件	读取时机
`references/changeset-and-commit.md`	创建变更集、修复质量问题、提交并推送代码时
`references/ci-polling.md`	使用Monitor工具监控CI、诊断失败或处理重试时
`references/version-pr-and-publish.md`	搜索Version Packages PR、合并PR或监控发布工作流时

Intent Map

意图映射

Intent	Steps	Notes
Full autoship (ship / release / publish)	1 through 5	Default entry point. Runs end-to-end through publish without intermediate prompts
Create changeset only	Step 1	Stage a release without pushing
Fix quality and push	Steps 1-2	Changeset + fixes + commit, no CI watch
Watch CI only	Steps 3-5	When changes are already pushed
Merge version PR only	Steps 4-5	When CI already passed. Auto-merges once preconditions are met

意图	步骤	说明
完整自动发布（ship/release/publish）	步骤1至5	默认入口点。无需中间提示，端到端执行直至发布完成
仅创建变更集	步骤1	暂存发布但不推送代码
修复质量问题并推送	步骤1-2	变更集+修复+提交，不监控CI
仅监控CI	步骤3-5	代码已推送时使用
仅合并版本PR	步骤4-5	CI已通过时使用。满足前置条件后自动合并

Safety Tiers

安全等级

Invoking autoship is standing consent for the full release flow. Do not pause mid-flow for re-confirmation; gate risky steps with objective preconditions instead.

GREEN -- execute directly:

gh run list

gh run view

gh pr list

gh pr checks

npm view

, reading CI status, listing changesets, reading

package.json

scripts,

git log

git status

```
YELLOW -- announce then execute:
```
```
npm run changeset
```
/ writing changeset files, running lint/typecheck/test/format fixers,
```
git add/commit/push
```
, starting
```
Monitor
```
background watches, and
```
gh pr merge
```
of the Version Packages PR opened by
```
changesets/action
```
once its identity is confirmed and all checks are green.
```
RED -- explicit confirmation required:
```
force-pushing, history rewrites, and any destructive git operations.

调用Autoship即表示同意完整发布流程。流程中途请勿暂停请求再次确认；需通过客观前置条件管控高风险步骤。

GREEN -- 直接执行：

gh run list

、

gh run view

、

gh pr list

、

gh pr checks

、

npm view

、读取CI状态、列出变更集、读取

package.json

脚本、

git log

、

git status

。

```
YELLOW -- 告知后执行：
```
```
npm run changeset
```
/ 写入变更集文件、运行lint/类型检查/测试/格式修复工具、
```
git add/commit/push
```
、启动
```
Monitor
```
后台监控，以及在确认
```
changesets/action
```
创建的Version Packages PR身份且所有检查通过后，执行
```
gh pr merge
```
。
```
RED -- 需要明确确认：
```
强制推送、重写提交历史以及任何破坏性git操作。

Workflow

工作流

Copy this checklist to track progress:

text

Autoship progress:
- [ ] Step 1: Create changeset (default patch)
- [ ] Step 2: Fix lint, types, tests, format
- [ ] Step 3: Commit + push changeset (do NOT run `changeset version`)
- [ ] Step 4: Monitor CI and find/merge the Version Packages PR
- [ ] Step 5: Watch release workflow to completion

复制以下检查清单跟踪进度：

text

Autoship 进度：
- [ ] 步骤1：创建变更集（默认patch版本）
- [ ] 步骤2：修复lint、类型检查、测试、格式问题
- [ ] 步骤3：提交并推送变更集（请勿运行`changeset version`）
- [ ] 步骤4：监控CI并查找/合并Version Packages PR
- [ ] 步骤5：监控发布工作流直至完成

Step 1: Create changeset (default patch)

步骤1：创建变更集（默认patch版本）

Load
```
references/changeset-and-commit.md
```
.

Check for existing pending changesets:

ls .changeset/*.md 2>/dev/null | grep -v README.md

If changesets exist, ask the user whether to create an additional one or skip.
Default to
```
patch
```
bump type. Only use
```
minor
```
or
```
major
```
when the user explicitly requests it.
Write the changeset file directly for non-interactive agent mode.
Infer the changeset summary from recent commits with
```
git log --oneline -10
```
.

加载
```
references/changeset-and-commit.md
```
。

检查是否存在待处理的变更集：

ls .changeset/*.md 2>/dev/null | grep -v README.md

。

若已存在变更集，询问用户是否创建新的变更集或跳过。
默认使用
```
patch
```
版本升级类型。仅当用户明确要求时才使用
```
minor
```
或
```
major
```
。
在非交互式Agent模式下直接写入变更集文件。
通过
```
git log --oneline -10
```
从最近的提交中推断变更集摘要。

Step 2: Fix lint, types, tests, format

步骤2：修复lint、类型检查、测试、格式问题

Load
```
references/changeset-and-commit.md
```
.
Discover available scripts from
```
package.json
```
.
Run quality gates in order: lint, typecheck, test, format.
If any gate fails, attempt to auto-fix (e.g.,
```
--fix
```
,
```
prettier --write
```
).
Retry each gate up to 3 times after applying fixes.
If a gate still fails after retries, stop and report to the user.

加载
```
references/changeset-and-commit.md
```
。
从
```
package.json
```
中发现可用脚本。
按顺序运行质量检查：lint、类型检查、测试、格式。
若任一检查失败，尝试自动修复（如
```
--fix
```
、
```
prettier --write
```
）。
应用修复后，最多重试3次检查。
若重试后仍失败，停止操作并向用户报告。

Step 3: Commit + push changeset

步骤3：提交并推送变更集

Stage the changeset file and any auto-fixes, commit, and push.
Do NOT run
```
npx changeset version
```
locally. CI's
```
changesets/action
```
runs it inside the Version Packages PR.
The pushed commit must contain the pending
```
.changeset/*.md
```
file so CI's "Changeset Status" check passes.

暂存变更集文件和所有自动修复内容，提交并推送。
请勿在本地运行
```
npx changeset version
```
。CI的
```
changesets/action
```
会在Version Packages PR中执行该命令。
推送的提交必须包含待处理的
```
.changeset/*.md
```
文件，以便CI的"Changeset Status"检查通过。

Step 4: Monitor CI and find/merge the Version Packages PR

步骤4：监控CI并查找/合并Version Packages PR

Load

references/ci-polling.md

and

references/version-pr-and-publish.md

After pushing, start a
```
Monitor
```
watch that emits a line each time the latest workflow run on the current branch reaches a terminal state (
```
completed
```
). The agent reacts to each emitted line; no
```
/loop
```
re-prompt needed.
Do not stop prematurely. A single idle snapshot does not mean CI is done — keep the monitor running until at least one workflow run reports
```
completed
```
.
On failure: read logs, classify as flaky or real. Retry flaky failures up to 3 times with
```
gh run rerun <id> --failed
```
. For real failures: fix, commit, push, restart the monitor.
Once CI is green, search for an open PR titled "Version Packages" or on branch
```
changeset-release/main
```
. If not found immediately, start a second
```
Monitor
```
watch that polls for the PR for up to 10 minutes (the changesets bot needs time).
Before merging, verify ALL of the following preconditions:
- PR title is exactly "Version Packages" OR head branch is
```
changeset-release/main
```
  (do not merge any other PR).
- Every check on the PR shows
```
state: completed
```
  and
```
conclusion: success
```
  .
- PR is mergeable (
```
mergeable: MERGEABLE
```
  , not
```
CONFLICTING
```
  or
```
UNKNOWN
```
  ).
Announce in one short line ("Merging Version Packages PR #N — <package>@<version>"), then merge with
```
gh pr merge <number> --squash --delete-branch
```
. Do not pause for confirmation; invoking autoship is the consent.
If any precondition fails, stop and report — do not merge.

加载

references/ci-polling.md

和

references/version-pr-and-publish.md

。

推送后，启动
```
Monitor
```
监控，当当前分支的最新工作流运行进入终端状态（
```
completed
```
）时输出一行信息。Agent会响应每条输出信息；无需
```
/loop
```
重新提示。
请勿提前停止监控。单次空闲快照不代表CI已完成——需保持监控直至至少一个工作流运行报告
```
completed
```
。
若失败：读取日志，分类为偶发故障或真实问题。偶发故障最多重试3次，使用
```
gh run rerun <id> --failed
```
。若为真实问题：修复、提交、推送，重启监控。
CI通过后，搜索标题为"Version Packages"或分支为
```
changeset-release/main
```
的开放PR。若未立即找到，启动第二个
```
Monitor
```
监控，最多轮询10分钟（changesets机器人需要时间创建PR）。
合并前，验证以下所有前置条件：
- PR标题恰好为"Version Packages" 或源分支为
```
changeset-release/main
```
  （请勿合并其他PR）。
- PR上的所有检查均显示
```
state: completed
```
  且
```
conclusion: success
```
  。
- PR可合并（
```
mergeable: MERGEABLE
```
  ，而非
```
CONFLICTING
```
  或
```
UNKNOWN
```
  ）。
用一行简短信息告知（"正在合并Version Packages PR #N — <package>@<version>"），然后使用
```
gh pr merge <number> --squash --delete-branch
```
合并。请勿暂停等待确认；调用Autoship即表示同意。
若任一前置条件不满足，停止操作并报告——请勿合并。

Step 5: Watch the publish run to completion

步骤5：监控发布运行直至完成

Load

references/version-pr-and-publish.md

and

references/ci-polling.md

Merging the Version Packages PR triggers the SAME release workflow again. Because no pending changesets remain,
```
changesets/action
```
now executes the
```
publish:
```
script (
```
changeset publish
```
).

Identify the workflow file (commonly

release.yml

npm-publish.yml

, or

publish.yml

) in

.github/workflows/

Start a
```
Monitor
```
watch on that workflow's latest run on
```
main
```
, emitting a line when it reaches a terminal state.
Terminal conditions: workflow succeeds (report published version) or fails (report with logs).
Do NOT auto-retry publish failures. These typically need human investigation (npm auth, registry, OIDC/provenance, tag conflict).
On success, verify with
```
npm view <package> version
```
and stop any remaining
```
Monitor
```
watches.

加载

references/version-pr-and-publish.md

和

references/ci-polling.md

。

合并Version Packages PR会再次触发相同的发布工作流。由于没有待处理的变更集，
```
changesets/action
```
现在会执行
```
publish:
```
脚本（
```
changeset publish
```
）。

在

.github/workflows/

中识别工作流文件（通常为

release.yml

、

npm-publish.yml

或

publish.yml

）。

启动
```
Monitor
```
监控
```
main
```
分支上该工作流的最新运行，当进入终端状态时输出一行信息。
终端状态：工作流成功（报告发布的版本）或失败（附带日志报告）。
请勿自动重试发布失败。这些问题通常需要人工排查（npm认证、注册表、OIDC/溯源、标签冲突）。
成功后，使用
```
npm view <package> version
```
验证，停止所有剩余的
```
Monitor
```
监控。

Anti-patterns

反模式

Running
```
npm publish
```
directly instead of using the changesets workflow.
Merging the Version Packages PR before its CI checks pass.
Stopping CI monitoring after the first poll shows no runs (workflows take time to queue).
Creating a changeset with
```
major
```
bump without explicit user instruction.
Force-pushing to the default branch.
Auto-retrying publish failures (these are typically real auth, registry, OIDC/provenance, or tag-conflict issues).
Polling tighter than ~30s, which wastes GitHub API rate limit. Monitor scripts should
```
sleep 30
```
or longer between
```
gh
```
calls.
Never run
npx changeset version
locally. CI's
```
changesets/action
```
runs it inside the Version Packages PR. Running it locally consumes the changeset file, the pushed commit has no pending changeset, CI's "Changeset Status" check fails, and no Version Packages PR is opened.
Hand-editing
```
CHANGELOG.md
```
or
```
package.json
```
```
version
```
as part of autoship — CI generates both.

直接运行
```
npm publish
```
而非使用changesets工作流。
在Version Packages PR的CI检查通过前合并它。
首次轮询显示无运行时停止CI监控（工作流需要时间排队）。
未获得用户明确指示就创建
```
major
```
版本升级的变更集。
向默认分支强制推送。
自动重试发布失败（这些通常是真实的认证、注册表、OIDC/溯源或标签冲突问题）。
轮询间隔小于约30秒，这会浪费GitHub API速率限制。监控脚本在
```
gh
```
调用之间应
```
sleep 30
```
或更长时间。
请勿在本地运行
npx changeset version
。CI的
```
changesets/action
```
会在Version Packages PR中执行该命令。在本地运行会消耗变更集文件，推送的提交中没有待处理的变更集，CI的"Changeset Status"检查失败，且不会创建Version Packages PR。
在Autoship流程中手动编辑
```
CHANGELOG.md
```
或
```
package.json
```
的
```
version
```
——两者均由CI生成。