gh-publish

gh-publish

The release runbook for shipping a package to npm and/or a site to Vercel. This skill writes and explains the commands; it does not run any credentialed step. Publishing, deploying, and anything touching a real token is the human's to execute.

Golden rule

Never run a credentialed command. Print it, explain it, and hand it to the human.

That covers npm publish, vercel --prod, writing real tokens to ~/.npmrc, and any login. If asked to "just publish it", decline the credentialed action and provide the runbook instead.

One-time setup (human runs once)

1. npm automation token (bypasses 2FA for CI/automation). Create an Automation token at npmjs.com → Access Tokens. Automation tokens skip the 2FA OTP prompt, which is what lets a non-interactive npm publish succeed.
2. Write it to ~/.npmrc (never to the repo):

   //registry.npmjs.org/:_authToken=${NPM_TOKEN}
   

   Prefer the ${NPM_TOKEN} env-var form so the literal token never lands on disk in plaintext. Export NPM_TOKEN in the shell/session that runs the publish. Do not commit .npmrc.

Per-repo publish (human runs per release)

For each package being released:

1. Preflight (safe — the agent may run these):
   • git status clean, on the release commit/tag.
   • npm run build / tests green.
   • npm pack --dry-run (or pnpm pack) — inspect the tarball file list; confirm no secrets, no junk, correct files/exports.
   • Confirm version in package.json is bumped and unpublished.
2. Publish (human runs — credentialed):

   pnpm publish --access public      # or: npm publish --access public
   

   --access public is required for scoped packages so they publish publicly.
3. Verify from the registry (safe — the agent may run after publish):

   npx <package-name>@latest --version
   

   Running via npx pulls the just-published version fresh from the registry, proving it installs and runs for a real user — not just locally.

Deploy to Vercel (human runs — credentialed)

vercel --prod --token "$VERCEL_TOKEN"

Use a $VERCEL_TOKEN env var; never inline or commit the token. After deploy, the agent may safely curl/visit the production URL to confirm it returns 200.

GitHub release check (safe)

Confirm the release exists and matches the tag:

gh release view v<X> --json tagName,name,isDraft

gh release view is read-only, so the agent may run it. If the release is missing, the human creates it (this is a credentialed step) — the agent prints the command and never runs it:

gh release create v<X> --notes-file <notes>

After a successful release — chain to launch

Once the package/site is live and verified, hand off to gh-launch-post to produce the X thread, single tweet, and Show HN — using only the real numbers from this release (version, verified install command, benchmark facts). Respect the 3-posts/day cadence.

Checklist

• Automation token in ~/.npmrc (env-var form), .npmrc not committed.
• Preflight green (build, tests, pack --dry-run clean).
• Version bumped + unpublished.
• publish --access public (human-run).
• npx <pkg>@latest verifies from registry.
• vercel --prod with token (human-run), prod URL returns 200.
• gh release view v<X> confirms the release.
• Handed off to gh-launch-post with real numbers only.