Skip to content

Release packages ​

Use this task when a change is ready to version and publish. Keep the release plan reviewable before any registry write.

To keep production documentation aligned with published packages while main updates a preview site, configure documentation publication.

Prerequisites ​

  • repo doctor reports a valid package manager and release configuration.
  • The working tree is clean except for the intended changes.
  • Every publishable change has a changeset or the repository's chosen intent file.

Smallest command ​

bash
repo release plan --markdown

Review current and planned versions, direct intents, native dependency/fixed-group reasons, lanes, private packages, publish candidates, and release-note previews. Use repo release plan --json for the versioned machine interface (schemaVersion: 1); status is ready, empty, or blocked. Blocked plans exit with code 1 and stable blocker IDs.

The plan delegates version decisions to pnpm recursive dry-run (tested with pnpm 12.8.1). It never consumes intents, changes manifests/changelogs/ledger/Git state, installs or activates pnpm, runs version/release/pnpmfile hooks, or writes to registries. Install a supported pnpm version explicitly if it is unavailable. Hooks that would change preparation inputs are intentionally excluded; rerun the plan after making those changes explicitly.

After review, use the separate preparation entry repo release ci --mode=prepare. Preview already prepared publication or recovery with repo release ci --mode=publish --dry-run. A version plan describes pending intents and does not check registry authentication or prove that publishing can succeed.

Expected result ​

The plan also validates internal dependencies of public packages: dependencies, devDependencies, and optionalDependencies must use workspace:*; peerDependencies may use workspace:*, workspace:^, or workspace:~. For a target at 2.0.1, pnpm pack produces peer ranges of 2.0.1, ^2.0.1, and ~2.0.1, respectively. Choose the declaration that expresses your compatibility contract; replacing a caret or tilde peer with an exact version changes that contract. External ranges and private consumers are outside this publishing protocol policy. Invalid protocols produce a blocked plan without rewriting manifests or running release hooks.

JSON and Markdown describe the same native version decisions. Notes use the existing release renderer and exclude already consumed intent entries. Private packages may change version but are marked as non-publish candidates. The public createReleasePlan({ cwd }) API returns the same report without writing it to disk.

Planning, automatic triggers, and version preparation recognize the same root and private-package intents. Native pnpm controls version propagation across the complete workspace. Release PR notes include only publishable child packages and require their version-specific changelogs; missing root/private changelogs do not block preparation. Root packages are not publication candidates, even when they are not marked private. Configure pnpm's versioning.ignore when a workspace package should not participate in versioning, rather than changing workspace discovery only for the apply step.

Stable and maintenance branches ​

Configure commands.release.branches in repoctl.config.*:

ts
export default {
  commands: {
    release: {
      branches: {
        stable: 'master',
        maintenance: [{ branch: '1.x', range: '1.x', tag: 'legacy-1' }],
        prerelease: [
          { branch: 'preview/1.x', lane: 'beta', tag: 'legacy-beta', target: '1.x' },
        ],
      },
    },
  },
}

Omitting this configuration preserves main plus alpha, beta, rc, and next. stable defaults to main; omitting prerelease keeps those four lanes targeting the stable branch, while prerelease: [] disables them. Stable and maintenance branches both use pnpm's native main lane. Git branch names and npm tags are separate values.

Maintenance ranges must have finite upper bounds and cannot overlap. The primary stable line owns versions outside all maintenance ranges. These ranges apply to every publishable package in the repository; packages with independent major versions must fit the chosen line together. Private packages remain native versioning participants but are not publish candidates. Branches, npm tags, and prerelease lanes must be unique. Semver-like tags such as 1.x are invalid npm tags; use legacy-1. The snapshot- tag prefix is reserved for temporary packages.

bash
repo release plan --branch 1.x --markdown
repo release plan --branch master --json

Plans expose branchRule with branch, kind, lane, range, excludedRanges, distTag, and target. An explicit --branch (or API branch) takes precedence; a matching GITHUB_REF_NAME is used next; otherwise a read-only plan targets the primary stable branch. Execution uses the actual Git branch or CI ref and rejects unconfigured branches. resolveReleaseBranches(config) exposes the same validated mapping to API callers.

Preparation checks native pnpm's dry-run before release hooks or version writes, then checks again after verification hooks. Invalid ranges block without consuming intents. Native applied manifests and final publication candidates are rechecked; a hook that changes versions must leave them within the selected line. Arbitrary hook side effects cannot be rolled back by repoctl. The existing pnpm ledger and release checkpoints govern continuation after an interrupted preparation or publication.

Release PRs target the selected branch. The primary head remains release/pnpm-version; maintenance heads use release/pnpm-version-<encoded-branch> so multiple lines can coexist. Maintenance publication uses its own dist-tag and stable GitHub Release metadata. repo release pre enter beta selects a declared native lane. repo release pre exit returns to the target's native main lane and prints the stable/maintenance target; it does not switch Git branches.

After changing the mapping, preview repo upgrade --dry-run --json and apply the reviewed upgrade to synchronize managed Release workflow push branches. Saved plans detect changed configuration, repeated upgrades are unchanged, and custom workflows remain protected unless explicitly replaced. Workflow dispatch and source recovery must run on the intended configured branch. Keep publish workflows serialized and retain their checkpoints.

Common branches ​

  • Missing intent: add a changeset and rerun the plan.
  • Fixed group mismatch: inspect the package relationships before editing versions.
  • Registry authentication failure in CI: run the OIDC audit below from the publishing workflow and inspect npm package settings.

Audit npm trusted publishing ​

Choose oidc-audit when manually dispatching the managed Release workflow, or run this in your existing GitHub-hosted publishing job:

bash
pnpm exec repo release ci --mode oidc-audit

The job needs id-token: write, Node.js 24.22.1 and the same repository, workflow file and environment as actual publishing. A different diagnostic workflow has a different identity. The managed workflow uses a separate audit job with only contents: read and id-token: write, disables install lifecycle scripts and skips GitHub App credentials and release quality checks. Only the repoctl source workspace builds its tooling closure; consumer workflows use the installed CLI. Custom workflows should use the same isolation and install with pnpm install --frozen-lockfile --ignore-scripts.

The command independently routes before release configuration and checks every versioned public child package against the official npm registry, including packages already published. Use --package @acme/new-library or the workflow's package input to audit one exact public workspace package. It requests short-lived exchange credentials but never uploads packages, changes versions/intents, runs hooks, writes progress files, creates tags/Releases or saves tokens. source-sha, dry-run and version recovery inputs must be empty. JSON includes schemaVersion: 1, safe identity fields, each package's HTTP status/message and ok; failures complete the whole selected-package report before exiting with code 1. auditReleaseOidc({ cwd, packageNames?, env?, fetch? }) exposes the same report without printing it; callers must check ok.

An npm HTTP 404 or OIDC token exchange error - package not found does not by itself distinguish a missing package, mismatched trust or expired configuration. Check the npm package's trusted publisher status and compare repository, workflow and environment with the safe identity report. Never paste JWTs or exchange tokens into logs or support requests.

Under npm's initial validation policy, configurations without a first successful publish expire after 48 hours. Pending means that first publish is still due before the deadline shown on npm. If the npm page explicitly shows Expired, delete and recreate that package's trusted publisher, then complete the first publish within 48 hours. Editing an expired configuration does not reset it. Existing configuration, successful exchange and successful first publish are separate evidence; an audit does not reset or satisfy this clock. After the first successful publish, that initial 48-hour limit no longer applies. Use OIDC/provenance for publication and keep npm token fallbacks out of publishing jobs.

Publish one preview and validate its trusted publisher ​

The managed release.yml workflow's bootstrap mode publishes one real, usable prerelease before a formal release is prepared. Use it for a new public workspace package, or for an existing package that needs the first successful publish through a newly configured trusted publisher. All packages reuse the same workflow; npm must trust that repository, release.yml and its publishing environment. A publish through another workflow validates that other configuration only.

First upgrade to an official npm release of repoctl that includes this feature, then preview and apply repo upgrade. Review and merge the generated release.yml before dispatching it. Both bootstrap-publish and bootstrap-verify must pin REPOCTL_BOOTSTRAP_TOOL_VERSION to that exact published tool version. A source checkout, linked CLI or copied workflow does not make an unreleased tool available to the isolated jobs.

First make the package available in npm's normal package settings flow. For a new package, npm staged publishing can create a 0.0.0-stage placeholder; that placeholder is not a usable library release. Configure the trusted publisher to allow direct npm publish, then complete the real publish before the deadline shown by npm. Do not approve temporary initialization content as a substitute for the checked package artifact.

Choose Actions → Release → Run workflow, select the repository default branch, and set mode=bootstrap, the exact package, an explicit prerelease version, and tag (default alpha). Preview the plan first:

bash
gh workflow run release.yml --ref main -f mode=bootstrap -f package=@acme/new-library -f version=0.1.0-alpha.0 -f tag=alpha -F dry-run=true

Replace main with the actual default branch. Repeat without dry-run=true to prepare and publish. The version must be a SemVer prerelease; stable release tags are not accepted. Source versions, intents, changelogs, the ledger and Git tags remain unchanged. Preparation archives the frozen default-branch commit, checks the selected package, builds its dependency closure and creates one tarball. Only that package is uploaded. Required internal runtime dependencies must already be installable from npm; missing versions fail instead of expanding the upload to more packages.

Preparation has read-only permissions. The publisher receives OIDC and uploads the verified tarball without candidate lifecycle scripts. It checks the exact version, archive integrity, tag and provenance, then verifies an isolated registry installation, public entries, types and npm signatures. Existing stable tags must stay unchanged. npm may move latest from the initialization placeholder to the first real prerelease; this initialization exception is reported explicitly, and never permits replacing an existing stable release.

If npm accepted the upload but confirmation or consumer verification failed, keep the original run and its artifacts. Reuse the same package, version and tag with verify-run-id:

bash
gh workflow run release.yml --ref main -f mode=bootstrap -f package=@acme/new-library -f version=0.1.0-alpha.0 -f tag=alpha -f verify-run-id=123456789

This path verifies the original source and immutable artifact, then repeats confirmation and consumer checks without OIDC, a rebuild or another upload. It preserves the original failure and the new verification result. An existing version is never overwritten, and incrementing the version is not a recovery mechanism. Only a successful publish by the configured workflow satisfies npm's initial validation requirement; full release acceptance also requires the post-publish checks to pass.

Inside the frozen GitHub workflow context, repo release bootstrap --package @acme/new-library --version 0.1.0-alpha.0 --tag alpha --dry-run --json exposes the same plan through the CLI. It requires a clean checkout at the frozen commit and matching GitHub identity; use the workflow's dry run from a normal local terminal. Its default prepare stage builds checked artifacts without publishing when --dry-run is absent. The managed workflow coordinates prepare, publish and verify stages; use it for the real OIDC publication and retained evidence. --verify-run-id selects verification even if a caller also requests publication.

Programmatic APIs are createBootstrapPlan(options), prepareBootstrap(options), publishBootstrap(options), verifyBootstrapPublication(options) and the stage coordinator releaseBootstrap(options). They return the public BootstrapPlan / BootstrapReport models; the cross-job BootstrapManifest carries the checked artifact and entry metadata. BootstrapOptions.packageName selects the exact package, while the CLI uses --package. Preparation can accept an explicit frozen BootstrapSource for controlled local integration, but that identity does not grant publication authority. CLI --output selects the artifact directory; --out writes an additional JSON report. --run-id and --run-attempt bind the original preparation run.

Partial publication and registry visibility ​

The publisher attempts uploads at most three times, waiting 20 and 40 seconds before refreshing registry state and selecting retry packages. An exact version with explicit upload acceptance is never uploaded again during that invocation, even if npm view cannot find it yet. Ordinary permission errors and 404 responses without transient-failure evidence fail immediately. Conflicts require read-only registry confirmation.

Upload acceptance means npm received the version; registry queries can still take several minutes to show it. Accepted uploads must become queryable before post-publish hooks, Git tags, GitHub Releases, or prerelease pushes proceed. Visibility checks query pending versions every 10 seconds for up to 15 minutes. A timeout exits unsuccessfully and lists pending versions while preserving the acceptance evidence.

Two files remain in the workspace root:

  • pnpm-publish-summary.json: cumulative publishedPackages, including accepted uploads and registry-confirmed versions. On failure, this file alone does not prove that every listed version is available.
  • repoctl-publish-progress.json: schemaVersion: 1, candidates, acceptedPackages, confirmedPackages, and status (publishing, confirming, complete, or failed). Accepted versions missing from confirmedPackages still need visibility confirmation.

The managed Release workflow uploads both files as npm-publish-progress-<run_id>-<run_attempt> on success or failure, retained for 14 days. Missing reports are ignored. After upgrading repoctl, run repo upgrade to refresh managed workflows; custom workflows can add the same upload step.

After a visibility timeout, keep the durable checkpoint on repoctl-release-state and resume with repo release ci --mode publish --source-sha <full-release-line-commit-sha>, previewing with --dry-run first. Recovery uses the original prepared versions and saved acceptance evidence to confirm visibility and finish missing metadata without uploading accepted versions again.

Recovery across runners ​

repo release ci --mode=publish tracks release targets separately from new npm uploads. Before uploading, the built-in GitHub client writes exact versions, original commits, accepted-upload evidence, metadata progress, and individual hook states to the repository's repoctl-release-state branch. The key includes repository, dist-tag, and candidate versions. Writes compare the file SHA to reject concurrent changes. Keep this branch, grant contents: write, and serialize all workflows that publish the same packages.

repoctl-release-progress.json is an archived diagnostic copy. Its complete: true requires npm version/dist-tag visibility, tags pointing to the original commits, published GitHub Releases, and all required hooks. The older npm progress file only describes the npm stage.

Reruns query the registry and GitHub and finish missing stages without reuploading accepted versions or repeating completed hooks. Prereleases push the version commit before uploading. Source discovery requires complete Git history (fetch-depth: 0), and recovery checks the original manifest and changelog. If a later commit changed the changelog, check out the reported original commit before recovery.

When .changeset/ledger.yaml records a package version, its first appearance along Git's first-parent history identifies the prepared release, including a first release that keeps the package's initial version. A release merged without squashing belongs to the mainline merge commit. Versions without ledger entries, such as dependency-propagated bumps, fall back to manifest history on the same first-parent chain. Uncommitted ledger entries cannot establish a release source. Recovery also rejects adding or deleting a changelog relative to that source; it permits a missing changelog only when both the source and current checkout omit it.

Legacy releases without a checkpoint use npm gitHead; if absent, verify the source manually and set REPO_RELEASE_SOURCE_SHA. Never substitute the rerun HEAD. Historical targets with existing Releases remain no-ops. Hooks for legacy targets with missing metadata have unknown outcomes.

bash
repo release ci --mode=publish --dry-run
repo release ci --mode=publish

Dry-run queries remote state and shows versions, original commits, npm stage, missing tags/Releases, and hook states without uploads, hooks, or checkpoint writes. Unknown registry states fail after bounded retries. Tag conflicts and unknown source commits fail without moving tags. GitHub requests have a 30-second timeout and bounded backoff.

Hook outcomes ​

Hook script names must be unique; retain the original script set when recovering. Each hook is checkpointed as running before execution and complete after success. Optional failures become ignored. Unknown non-idempotent outcomes require manual review. Set idempotent: true on an afterPublish hook only when repeated execution is safe. After verifying external completion, REPO_RELEASE_ACKNOWLEDGE_HOOKS=script-name acknowledges it without execution (comma-separated for multiple scripts).

If a runner disappears during upload before responses are persisted, recovery performs read-only visibility confirmation for up to 15 minutes. It fails with evidence if versions remain unknown, rather than blindly uploading again. After manually verifying that a version was never uploaded, use the existing exact publish-unpublished entry, then rerun the original target set to finish its hooks. Arbitrary external hooks cannot be guaranteed exactly-once.

Legacy injected GitHubOperations adapters retain their previous behavior. Recovery-capable adapters must implement readReleaseState, writeReleaseState, listReleases, and ensureTag; readTagTarget is recommended. Enforce revision comparison on writes and throw on query errors. A local summary is not a remote checkpoint.

No-release intents and original-source recovery ​

An intent containing only none (or empty frontmatter) records that no release is needed. It does not open a version PR or block publishing an already prepared release. Consumed intents resurrected by a merge are not versioned twice. pnpm cleans these files during the next effective version operation.

Release PRs use the applied package list returned by pnpm, not arbitrary Git changes. A new package can keep its initial version; it still appears in the release notes. Cleanup alone never opens a release PR.

If an existing prepared version has not completed publication, new version preparation stops before consuming intents and prints its source commit and recovery command. Finish that release first, then run preparation again:

bash
repo release ci --mode publish --source-sha <full-release-line-commit-sha> --dry-run
repo release ci --mode publish --source-sha <full-release-line-commit-sha>
repo release ci --mode prepare

The managed Release workflow exposes the same source-sha input for publish and publish-unpublished. Current tooling checks out the original commit into an isolated directory, installs its locked dependencies, builds and verifies that source, and recovers the full set of versions introduced by its manifests or ledger, including dependency propagation. Package/version inputs validate membership; they do not split the original release. The SHA must belong to origin/<selected-branch>; the dispatch configuration determines the line, including when the historical source had a different configuration. Dry-run only inspects the source and remote release state; it does not install, upload, run hooks, or write checkpoints. Later changes stay pending for a new version. The original source must already include all intended version changes; no versions are changed during recovery.

Recovery preserves GitHub's workflow environment for trusted publishing and provenance: its signed identity refers to the workflow run's commit. The isolated checkout, release checkpoint, Git tags, and Release targets refer to source-sha. Do not overwrite GITHUB_SHA to recover an older source; npm rejects provenance that disagrees with the signed workflow identity.

Validation scripts (qualityScripts and hooks.verify) do not inherit control inputs for the current release, such as its mode or recovery source. They retain ordinary CI and authentication environment variables. Other lifecycle hooks keep their release context.

Managed nightly publication ​

The managed Release workflow includes a manual nightly entrypoint. Open Actions → Release → Run workflow, select the repository's default branch, and choose nightly. Leave the source-sha, package and version recovery inputs empty. The optional dry-run input inspects source and provider state without building or publishing. Nightly selects all public workspace packages from the snapshot plan and does not consume release intents or change stable versions, ledger, changelogs or Git tags.

New projects include this manual workflow without an automatic schedule. To enable a daily check at 03:17 Asia/Shanghai (19:17 UTC), add:

ts
export default {
  commands: {
    release: {
      nightly: {
        provider: 'npm',
        schedule: '17 19 * * *',
        qualityTimeoutMs: 60 * 60_000,
      },
    },
  },
}

provider defaults to npm. Omit schedule to keep manual runs only; schedules use five-field UTC cron expressions and GitHub may delay them. After changing either setting, preview and apply the managed asset upgrade:

bash
pnpm exec repo upgrade --json > ../repoctl-upgrade-plan.json
# Review the saved plan before applying it.
pnpm exec repo upgrade --apply ../repoctl-upgrade-plan.json

Commit the configuration, workflow and .repoctl/baselines/root records to the default branch. Existing projects first need a repoctl version that includes nightly and an updated lockfile. Fresh scaffolds record a Release workflow baseline; preserve it for future merges. Missing baselines and conflicting local edits require explicit resolution; --yes does not bypass them. Custom workflows stay protected, and preset-owned workflows are updated through repo presets plan / repo presets apply. repo init --preset standard does not install workflows; --overwrite-release is an explicit full replacement of a custom Release workflow. Remove schedule and synchronize again to disable automatic runs. repo doctor checks provider, schedule and workflow drift.

Choose a provider ​

ProviderInstallationSame-commit manual runRequirements
npm (default)<package>@snapshot-nightlyNew build identity and date versionsnpm Trusted Publisher for every public package, matching the repository, release.yml and environment; contents: read, id-token: write
pkg-pr-newFull-commit URLs from the reportVerify existing bytes, reuse identical artifacts and upload only missing packagesOfficial pkg.pr.new GitHub App installed for the repository; contents: read; no npm token or npm Trusted Publisher

For npm, run the oidc-audit workflow mode before first use and check every package's npm settings. Nightly repeats the audit for its exact package plan before uploading, uses OIDC/provenance, confirms exact versions and snapshot-nightly tags, and verifies that latest did not change. Install one of your project's published packages with:

bash
pnpm add -D <package>@snapshot-nightly

To use pkg-pr-new, install the official GitHub App, grant it access to this repository, set provider: 'pkg-pr-new' and synchronize the workflow. This provider returns URLs shaped like https://pkg.pr.new/<owner>/<repo>/<package>@<full-commit-sha> and rewrites internal dependencies to the same batch. It does not publish npm dist-tags. Existing URL metadata or bytes that disagree with the prepared artifact fail the run rather than being overwritten.

Scheduled npm checks skip only when every current public package is already available for the current commit and the same build identity, including historical snapshot versions. Missing or partially published packages require preparation; registry/query failures fail the run. A new manual npm run or attempt starts a new batch, even for the same commit. Both scheduled and manual pkg-pr-new runs rebuild and compare bytes, reusing only identical artifacts at that commit's URLs and uploading only missing packages.

Nightly version numbers ​

npm defaults to commands.release.nightly.versioning: 'date', producing versions such as 7.1.0-dev.20261112.1. The base comes from the native pnpm release plan, or the current manifest version for packages without a planned change. The date uses UTC, independently of the cron's local-time interpretation. All public packages in a batch share one date and sequence, while retaining their own base versions.

The sequence is one greater than the highest dev.YYYYMMDD.N counter found in that day's npm version history across the selected packages, including other base versions and versions no longer pointed to by a dist-tag. The first batch of a new UTC date starts at .1. Planning freezes the date before building; a build that crosses midnight keeps that date. A dry run does not reserve a counter. If another publisher occupies the planned version, conflicting identity or integrity stops publication; prepared artifacts are never silently renumbered.

Resuming the same run_id-run_attempt after a partial publication reuses the published date and counter, including on a later day, and verifies exact metadata and tarball integrity before skipping an existing upload. Use a new run or attempt for a changed build. Full commit SHA and build identity remain in repoctlSnapshot metadata and JSON reports.

Set commands.release.nightly.versioning: 'snapshot' to retain <base>-snapshot.nightly.c<commit>.b<digest>. pkg-pr-new defaults to this deterministic format and rejects versioning: 'date' because its full-commit URLs are immutable. The snapshot-nightly install tag stays the same for both npm formats. Versioning is read from configuration at runtime; changing it does not require regenerating the workflow.

Checks and diagnostics ​

Nightly runs configured qualityScripts and hooks.verify, prepares real tarballs from committed source outside the checkout, and validates package exports, types and isolated installation. The default npm version contains the base, UTC date and daily sequence; source SHA and build digest remain in package metadata. After publication, a clean consumer installs the actual tags or URLs and checks identities, entrypoints and types. Formal versioning and post-publication hooks remain part of the normal release flow.

Each quality script and verify hook has its own timeout, defaulting to 2_700_000 milliseconds (45 minutes). Set commands.release.nightly.qualityTimeoutMs to a positive safe integer number of milliseconds to override it; the example above allows 60 minutes per script. The workflow's job timeout still limits the whole run, so increase that separately if the combined work needs more time. A timeout stops publication and retains the command's output in the diagnostic report.

To share one budget across all quality scripts and verify hooks, set REPOCTL_NIGHTLY_QUALITY_DEADLINE_EPOCH to an absolute Unix timestamp in seconds before running nightly. This overrides each quality command's timeout with the remaining time, capped at 2_147_483_647 milliseconds. The value must contain only digits, be positive and convert safely to integer milliseconds. An invalid or exhausted deadline stops quality before the next command starts. Build, upload and consumer commands retain their independent timeouts; omitting this variable preserves qualityTimeoutMs.

The workflow uses Node.js 24.22.1, the workspace's pinned pnpm, checkout without persisted credentials and the existing publication concurrency group. Reports, tarballs and consumer diagnostics are retained for 14 days, including failed runs; the Actions summary contains the result and install commands.

The workflow command is:

bash
REPOCTL_SNAPSHOT_PUBLISH=1 pnpm exec repo release nightly \
  --publish --output "$RUNNER_TEMP/repoctl-nightly" --json

repo release nightly, createNightlyPlan(options) and releaseNightly(options) require a complete GitHub Actions schedule or nightly dispatch context on the default branch, even for a dry run. Without --publish, execution prepares artifacts; --dry-run only inspects and emits an external report. Use the snapshot command below for local preparation.

PR and nightly snapshots ​

Use a snapshot for downstream validation before a stable release. Commit the source first and preview the complete set of public workspace packages:

bash
repo release snapshot --kind pr --pr 123 --commit <full-HEAD-sha> --build-id <run-id>-<attempt> --dry-run --json
repo release snapshot --kind nightly --commit <full-HEAD-sha> --build-id <run-id>-<attempt> --output /tmp/repoctl-artifacts

The command reuses the native pnpm release plan for candidate explanations and base versions, then snapshots every public package together. Versions include the full source SHA and a deterministic digest of the PR/nightly build identity. repo release snapshot --kind nightly retains this format; the date default above applies only to repo release nightly. The only tags are snapshot-pr-<number> and snapshot-nightly; there is no option to target a stable tag. Reuse a build identity only to recover the same source and artifacts. The report contains exact pnpm add instructions.

Snapshot planning through the CLI and API does not load or execute repoctl.config.*. It uses committed pnpm metadata independently of stable release configuration; ordinary release commands still validate their configuration before running.

Without --publish, the command prepares installable tarballs. It extracts committed HEAD outside the repository, installs the frozen lockfile, rewrites internal references to exact snapshot versions, runs the root build script, and checks the packed files with publint, Are the Types Wrong, and isolated consumers. Original manifests, intents, ledger, changelogs and Git refs stay unchanged on success, failure or interruption. Failed and completed runs retain snapshot-report.json, tarballs, and diagnostic consumers under the reported directory. A hard interruption can leave partial output; rerun the same identity to reconcile registry evidence. Source symlinks, Git submodules and publishConfig.directory are currently rejected; the root build script and frozen lockfile are required.

Add --publish only in an explicitly authorized GitHub Actions job with REPOCTL_SNAPSHOT_PUBLISH=1. GITHUB_SHA must match the requested commit and the event repository must match GITHUB_REPOSITORY. PR publication requires a same-repository pull_request event; forks and pull_request_target cannot publish. Nightly publication accepts schedule or workflow_dispatch. Keep fork jobs on preparation only and scope credentials to the trusted publishing job. The snapshot command does not edit workflow files.

Publication defaults to the public npm registry; --registry <https-url> explicitly selects another registry (HTTP is supported only for a local test registry). Uploads reuse the bounded publication/recovery adapter and never create GitHub Releases or Git tags. Repeated identities compare exact package metadata and SHA-512 tarball integrity before skipping an upload. Unknown registry state or conflicting bytes stop publication. A changed or non-reproducible build needs a new --build-id.

The public APIs are createSnapshotPlan(options) and releaseSnapshot(options). Both expose schemaVersion: 1, the native plan, snapshot identity, candidates, exact versions, target tag and install instructions. releaseSnapshot adds retained artifacts and validation results; preparation failures return status: failed with error, and the CLI exits with code 1.

Publish a prepared PR snapshot from a separate trusted workflow ​

For PR snapshots, export the approved builder and independent publisher together:

bash
repo release snapshot workflow --out .github/workflows --pnpm-version 12.21.0 --dry-run --json
repo release snapshot workflow --out .github/workflows --pnpm-version 12.21.0

Select the exact pnpm 12 version declared by the workspace's packageManager. The command creates repoctl-snapshot-build.yml and repoctl-snapshot-publish.yml; it protects existing different files and treats identical files as a no-op. To upgrade or customize the recipe, export into an empty directory, review both files together, and replace the reviewed pair. The publisher embeds the SHA256 of the exact builder bytes, so changing only the builder makes verification fail. Export pins the installed repoctl version; merge the reviewed pair into the default branch before use. This recipe is opt-in and does not change the ordinary PR CI or Release workflow.

Create a pr-snapshot environment with required reviewers and administrator bypass disabled. Configure each package's npm Trusted Publisher for this repository and repoctl-snapshot-publish.yml. The publisher uses the built-in GitHub token and npm OIDC; no GitHub App or PAT is needed. The freeze job waits for environment approval before obtaining a runner. Dispatch repoctl PR snapshot build on the default branch with an open, ready, mergeable, same-repository PR number. Fork PRs cannot use this publisher.

The same exporter can match an existing publisher identity and approval environment:

bash
repo release snapshot workflow --out reviewed-workflows \
  --environment package-review \
  --builder-workflow .github/workflows/pr-packages.yml \
  --publisher-workflow .github/workflows/release.yml \
  --builder-name "Approved PR packages" \
  --publisher-name "Publish PR packages"

The output directory receives pr-packages.yml and release.yml. Review these files before placing them at the configured repository paths; existing files are never merged or overwritten. The exported builder source command, publisher verification policy, workflow_run name, npm publisher identity and exact builder SHA256 all agree. Paths must be distinct YAML files directly under .github/workflows; names and the environment must be static values. A hand-maintained publisher can pass snapshot publish-prepared --publisher-workflow .github/workflows/release.yml along with its matching builder and environment options. The workflow must still run as the trusted default-branch workflow_run publisher. Each npm package can have up to ten trusted publishers, so retaining the default snapshot publisher alongside an existing release publisher is also an option.

The protected freeze job reads the current PR head/base/merge and immutable run identity, checks the merge parents, and creates the package/version/dependency plan using the pinned tool without installing or executing candidate code. It uploads snapshot-plan.json and records its artifact ID, digest and plan digest in its own job log. A separate job checks out the frozen merge commit, builds and validates the exact package closure with read-only permissions, and uploads only snapshot-manifest.json and its declared tarballs. Schema version 1 records repository and PR identity, full head/base/merge SHAs, workflow/run/attempt, exact snapshot versions and dependency edges, SHA512 integrity, and build/package checks.

The default-branch workflow_run publisher verifies the trusted builder bytes, reviewer environment, approval, successful freeze/build jobs from the same attempt, the trusted freeze log, immutable artifact IDs and ZIP digests, and the current PR revision. It compares every package and dependency with the frozen plan and checks every tarball before requesting npm credentials. Extra or missing packages, altered bytes, unsafe paths, dangerous publishConfig, forks and stale revisions fail before upload. Missing or expired approval logs/artifacts require a fresh approved build.

The publishing job has no candidate checkout and never installs, imports or runs candidate code or package scripts. It uses the public OIDC audit with the real publisher identity, then publishes only the checked tarballs under snapshot-pr-<number>. It preserves latest, confirms registry integrity and the snapshot tag, and retries existing exact versions only when their integrity matches. A per-PR publication lock prevents competing uploads; an older build cannot roll the tag back. Npm publication is not an atomic batch: a failed run can leave confirmed packages, and retrying the same unchanged artifact reconciles them. Re-run all builder jobs for a new approval after a build failure; a publisher retry reuses the original builder run, attempt and immutable artifacts. Changes to PR head/base/merge require a new build.

A separate consumer job without OIDC or write permissions installs the confirmed exact versions and checks their integrity, runtime entrypoints and types. A trusted reporting job writes the exact install command and the GitHub consumer job result to the PR. Consumer failures leave the workflow failed while reporting the packages that were already published. Provenance identifies the actual default-branch publisher; the manifest and report retain the separately verified candidate build source. The workflow never rewrites GitHub event or SHA variables to impersonate the builder.

The workflow uses these public CLI/API boundaries:

TaskCLIAPI
Resolve frozen GitHub sourcesnapshot source --pr <N> --out <source.json>freezeSnapshotSource(options)
Plan checked-out metadatasnapshot freeze --source <source.json> --out <snapshot-plan.json>createSnapshotBuildPlan(options)
Build portable artifactssnapshot prepare --plan <snapshot-plan.json> --output <external-directory>prepareSnapshot(options)
Verify completed buildsnapshot verify --run-id <id> --run-attempt <attempt> --builder-sha256 <trusted-hash>verifySnapshotRun(options)
Publish the verified bundlesnapshot publish-prepared --run-id <id> --run-attempt <attempt> --builder-sha256 <trusted-hash> --output <external-directory>publishPreparedSnapshot(options)
Verify exact installed packagessnapshot verify-consumer --report <publication.json> --output <external-directory>verifyPreparedSnapshotConsumer(options)

Prefix the CLI entries above with repo release. The source and verifier infer the repository from GITHUB_REPOSITORY, or accept --repository <owner/repo>. --json emits structured results and --out writes a new result file. snapshot seal binds the uploaded plan to the trusted freeze log. getSnapshotWorkflows({ pnpmVersion?, environment?, builderWorkflowPath?, publisherWorkflowPath?, builderWorkflowName?, publisherWorkflowName? }) returns the matched workflow strings using the same settings as the exporter. The prepared publisher supports public npm only; the existing local snapshot and nightly APIs remain compatible. All snapshot subcommands skip executable release configuration and leave formal changesets, versions, changelogs and the release ledger untouched.

Next ​

Read publishing and changelogs for repository policy and reports and output for CI artifacts.