Autoship

Autoship

Drive an npm release end to end: changeset, fix loop, push, CI watch, Version Packages PR merge, publish watch, npm verification.

• IS: the full release pipeline for an existing changesets-based npm package, from writing the changeset file to confirming the new version on the registry, plus diagnosing why a release run did not version or publish.
• IS NOT: opening a feature PR (use pr-creator), monitoring a feature PR for reviews, conflicts, or CI (use pr-babysitter), general build or type fixes outside a release flow, or scaffolding a new package (use scaffold-cli, which hands off to autoship for the first release).

The Release Loop

One workflow, two successive runs. Misreading it as two workflows causes most autoship mistakes.

1. Push a commit containing a pending .changeset/*.md file to the default branch.
2. The release workflow runs: changesets/action sees pending changesets, runs changeset version in CI, and opens or updates a PR on branch changeset-release/<default-branch> (title "Version Packages", suffixed "(next)" in pre mode) carrying the package.json bump and CHANGELOG.md entry.
3. Merge that PR once every check is green.
4. The same workflow runs again. With no pending changesets left, the action runs its publish script (changeset publish), which publishes to npm and, by default, pushes the git tag and creates a GitHub release.

The local job ends at "push the changeset file". CI owns versioning and publishing; anything versioned locally breaks the loop (see Gotchas).

The action has two live majors with different input names: @v1 takes publish:, @v2 takes publish-script:. Read the uses: line before diagnosing a run that versioned but never published.

Reference Files

Intent Map

"Ship it" with no npm release context routes to pr-creator.

Safety Tiers

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

• Green (execute directly): reads: CI and PR state, npm view, pending changesets, package.json scripts, git history and status.
• Yellow (announce in one line, then execute): writing changeset files, running lint/type/test/format fixers, git add/commit/push, starting watches, and merging the Version Packages PR once its identity is confirmed and every check passes.
• Red (explicit confirmation required): force-pushes, history rewrites, repository settings changes, any destructive git operation.

Workflow

Copy this checklist to track progress:

Autoship progress:
- [ ] Step 1: Create changeset (default patch)
- [ ] Step 2: Fix lint, types, tests, format
- [ ] Step 3: Commit and push the changeset (never `changeset version` locally)
- [ ] Step 4a: Watch CI on the pushed commit
- [ ] Step 4b: Find and merge the Version Packages PR
- [ ] Step 5: Watch the publish run, verify on npm

Step 1: Create changeset (default patch)

• Load references/changeset-and-commit.md.
• Inspect pending changesets and their package coverage. Reuse those covering the requested release; add one only for uncovered changes. Ask only if unrelated pending releases make the publish scope ambiguous.
• Default to patch; minor or major only on explicit user instruction.
• Write the file directly (the interactive prompt needs a TTY); the summary is user-facing changelog text inferred from git log --oneline -10.
• npx changeset status validates the file: a misspelled package name fails here instead of in CI.

Step 2: Fix lint, types, tests, format

• Discover commands from package.json scripts (check, lint, typecheck, test, format, fix); in non-npm repos check Makefile, Cargo.toml, pyproject.toml, go.mod.
• Run lint, typecheck, test, format. After any code change, re-run from the first gate: a type fix routinely breaks lint, and a lint autofix can break a test.
• Scope auto-fixers to changed files where supported, then check git status: broad fix/format scripts reformat files outside the change (MDX is a frequent casualty). Undo only fixer changes introduced by this run, preserving pre-existing edits in the same files.
• Cap the loop at 5 fix iterations per gate, reporting the remaining error count each pass; then stop and report (Failure Recovery).

Step 3: Commit and push the changeset

• Stage the changeset file and in-scope fixes by explicit path; sweep git status --porcelain for hook artifacts (a root schema.gql is a known one) before committing.
• Commit (chore: add <type> changeset for <package>) and push.
• The pushed commit must still contain .changeset/*.md. Running changeset version locally consumes it (see Gotchas).

Step 4a: Watch CI on the pushed commit

• Load references/ci-polling.md.
• Start the commit watch on the pushed SHA. It emits a line per state change and one TERMINAL: line when every run for that commit (CI and the release workflow) completes. An idle first poll is normal; runs take time to queue.
• On failure, classify from gh run view <id> --log-failed: flaky or infra gets gh run rerun <id> --failed (max 3); a real failure gets a fix, commit, push, and a fresh watch on the new SHA.

Step 4b: Find and merge the Version Packages PR

• Load references/version-pr-and-publish.md.
• Find the open PR whose head is changeset-release/<default-branch>. If absent, run the PR-wait watch (10-minute cap).
• Merge only when all three hold:
• Head branch is changeset-release/<default-branch> (title normally "Version Packages", but pr-title can rename it). Never merge any other PR.
• gh pr checks <n> --json name,bucket reports bucket: pass for every check.
• gh pr view <n> --json mergeable reports MERGEABLE (on UNKNOWN, wait and re-query).
• Announce ("Merging Version Packages PR #N: <package>@<version>"), then gh pr merge <n> --squash --delete-branch, or the merge method the repo allows. Any failed precondition: stop and report, never merge.

Step 5: Watch the publish run, verify on npm

• Merging triggers the same workflow again; with no pending changesets it publishes.
• Take the merge SHA (gh pr view <n> --json mergeCommit --jq .mergeCommit.oid) and run the commit watch on it.
• On failure: read the log, match it against the publish failure table in references/version-pr-and-publish.md, report, and stop. Publish failures are never retried blind; every cause on that table needs a config or settings change.