Release checks before trusting a JavaScript repo in 2026.

field runbook

A repo can look finished before it is ready.

The README has a screenshot. The package builds locally. The demo runs once. The launch post is drafted.

That is usually the riskiest moment, because the parts that fail in public are rarely the parts that looked exciting while building. They are the boring edges: install instructions, CI, package metadata, secret handling, publish workflows, screenshots, old config files, and the difference between a demo and something another developer can actually run.

1. Can a stranger run it?

If the answer depends on the maintainer sitting next to them, it is not ready.

• A clear install command.
• A clear local dev command.
• A clear test or check command.
• Required environment variables listed in .env.example.
• No hidden dependency on files that only exist on one machine.

For npm packages, test the package path, not only the local repo path.

npm pack --dry-run
npm exec --yes --package <package-name>@latest <bin-command>

2. Is CI proving the same thing the README promises?

A README that says npm test should have CI that runs it.

• Use a GitHub Actions workflow on pushes or pull requests.
• Run the same commands documented in the README.
• Commit a lockfile for apps and CLIs that expect repeatable installs.
• Avoid workflows that only check formatting while skipping build and test proof.

3. Does the package metadata match the project?

Bad metadata does not just look sloppy. It breaks discovery and trust.

• name, description, license, repository, homepage, and bugs.
• The bin entry for CLIs.
• The package contents included in publish.
• Version consistency across files that repeat it.

This matters even more for MCP servers because metadata can exist in multiple places. If package.json, server.json, registry metadata, and README instructions drift apart, users cannot tell which install path is current.

4. Are secrets impossible to publish by accident?

The common failure is not a committed production key. It is a repo that teaches contributors to create one.

• .env, .env.local, and local secret files ignored.
• .env.example committed.
• Docs that name required variables without including real values.
• No screenshots or demo videos showing private tokens.
• No config that encourages pasting long-lived tokens into random terminals.

Release workflows deserve the same treatment. npm's trusted publishing flow uses OIDC so public packages can publish from supported CI without long-lived npm write tokens.

5. Is the GitHub Action path safe?

For GitHub Actions, check the workflow and marketplace surface separately.

• Does the Action run on a real fixture repo?
• Does it produce the advertised output?
• If it emits SARIF, does the SARIF validate?
• Are permissions narrowed instead of using broad defaults?
• Is the marketplace listing consistent with the README?

An Action that looks good in action.yml can still fail as soon as another repo consumes it.

6. If it is an MCP server, can clients understand it?

MCP has moved from experiment to ecosystem surface. That makes launch metadata part of the product.

• Use a working install command.
• Keep the server name consistent across docs and metadata.
• Describe supported tools clearly.
• Explain credentials, filesystem access, and network access.
• Expose a smoke-test path.
• Make auth boundaries clear for remote servers.

The 2026 MCP roadmap points toward transport scalability, discoverable metadata, agent communication, governance, and enterprise readiness. Public metadata is now an interface, not just documentation.

7. If money can move, is the demo capped?

Agent-commerce and HTTP-native payment demos are getting real fast. x402 is built around HTTP 402 payment-required API calls instead of traditional account checkout.

• Sandbox or testnet mode by default.
• Explicit spend caps.
• Human approval before real payment.
• Recipient validation.
• Replay protection.
• Receipts or audit logs.
• Clear refund and failure behavior.
• Webhook or callback signature verification.
• No private payment metadata in public logs.

The mistake is treating a money-moving demo like a normal API demo. It is not normal once a bug can spend funds.

8. Is there a report someone can keep?

A written report forces launch checks to be specific.

• Verdict or score.
• Evidence from file paths.
• Top risks.
• Priority fixes.
• Exact commands that were run.
• What was not checked.

9. Does the public page match the repo?

Before sharing, compare the public surfaces.

• npm package page.
• GitHub README.
• GitHub Marketplace page if there is an Action.
• MCP registry or directory listing if there is a server.
• Product page.
• Screenshots.

Small mismatches make people hesitate. If the site says one command and npm says another, the buyer or maintainer has to do trust work before they even try the tool.

Why this became Shipcheck

Shipcheck scans JavaScript and TypeScript repos for release-readiness issues across docs, package metadata, CI, env hygiene, npm publishing, GitHub Actions, MCP metadata, MCP STDIO execution boundaries, and payment-agent demo safety.

npx --yes shipcheck-cli .

It can export text, Markdown, JSON, and SARIF, so the output can be used as a local checklist, a pull-request artifact, or a code-scanning report.