Review changes before they ship

On a review-required registry, publishing and promoting are two separate acts. A publish still creates the immutable, content-hashed version — the bytes are stored and addressable. But the version's dist-tag (usually latest) is withheld: it stays null until an admin reviews the change and approves the promotion. Nobody, not even the person who published, can move latest themselves.

This guide walks the whole loop across both surfaces: a publisher ships a version from the CLI, an admin reads the server-computed diff in the dashboard review queue, and the tag lands only on approval. If you want the concept first, read Review-required registries; this page is the hands-on walkthrough.

The two halves of a review-required publish

A normal registry moves the tag the moment a publish finalizes. A review-required registry splits that in two:

1. Publish creates the version and stores its bytes. This part is unchanged — same skillhub publish command, same immutable snapshot.
2. Promotion — moving latest (or any release tag) onto that version — is held back for a reviewer. Until an admin approves, the tag is null.

The version is safe and durable the instant publish succeeds. It just isn't the one your teammates install yet, because latest hasn't moved.

Step 1 — Publish into a review-required registry

skillhub publish --to @studio/design-systems

skillhub publish --to @studio/design-systems --json

{
  "ok": true,
  "data": {
    "published": [
      {
        "ref": "@studio/design-systems/tokens-workflow",
        "version": "2.1.0",
        "tag": null,
        "scanStatus": "pending",
        "warnings": []
      }
    ],
    "skipped": []
  }
}

skillhub publish --to @studio/design-systems --tag beta

Step 2 — Find the version in the review queue

Review and promotion are a dashboard flow — there is no CLI review or approve command. Open the registry's dashboard page to reach its queue. You can jump straight there from the terminal:

skillhub open @studio/design-systems

The review queue is a registry-level list of the prerelease versions awaiting promotion. The just-published version shows up here as an awaiting submission:

Step 3 — Read the change as a diff, like code

Because every version is a content-hashed snapshot, a reviewer can read the change between the pending version and what's currently promoted as a server-computed red/green diff — reviewing a skill update exactly like a code review. Open the pending version's comparison to see what actually moved.

The diff has two layouts, and you can toggle between them:

• Unified — additions and removals interleaved in one column.
• Split — the old version on the left, the new on the right, side by side.

Step 4 — Approve (or request changes)

From the queue, an admin acts on the pending version:

• Approve — moves the release tag onto the version, optionally with a comment. This is the promotion that makes it the new latest.
• Request changes — notifies the publisher that the version needs work before it can be promoted.

Approval is a dist-tag move: latest lands on the approved version in the registry's version timeline, exactly like a manual tag move from the Versions tab.

The whole chain — publish, review, and the approval or change request — is recorded in the registry's audit log. Nothing about a promotion is silent; there's a durable record of who approved what, and when.

The CLI side of the two roles

There's no approve subcommand, but the CLI still has a role on each side of the gate. The publisher publishes; an admin can move the tag from the terminal once a version is approved, which is the same dist-tag move the dashboard performs on approval.

skillhub publish --to @studio/design-systems
skillhub publish --to @studio/design-systems --tag beta

skillhub tag @studio/design-systems/tokens-workflow@2.1.0 latest

Where to go next