Skip to content
Forge
Menu
Guides and policiesView source on GitHub ↗

Peer upgrade automation

Forge treats integration peer ranges as tested compatibility claims. The Peer Compatibility Updates workflow checks the npm registry each Friday at 06:07 UTC and can be dispatched manually for an exact package version. When a version falls outside the current content-model peer range, it prepares one focused pull request that updates the root test dependency, extends the bounded peer range through the newly validated minor, updates the lockfile, and prepares the next content-model patch version and changelog entry. A validated compatibility-only update does not add or change public API, so it is released as a patch rather than reserving a minor version for new backward-compatible capabilities. Sveltia’s compatibility floor is 0.193.2, the earliest version supported by the published content model. Automation keeps that lower bound and moves the upper bound to the minor immediately following the newly validated Sveltia version. This produces one continuous range rather than an ever-growing list of individual minor ranges.

Friday preparation runs roughly three days before Monday’s normal Dependabot updates. No routine dependency schedules or cooldown settings change.

After a reviewed compatibility PR merges, the package release workflow publishes the content-model patch, verifies npm integrity and provenance, and triggers published template synchronization. That synchronization pins the published content model and newest stable supported Sveltia version, prepares a create-forge patch and changelog, and enables auto-merge behind the required project and consumer checks. Its merge then publishes create-forge through the same release workflow. If Sveltia is already supported, the weekly workflow synchronizes the currently published content model without creating an unnecessary model release.

GitHub App setup

Create and install a repository-scoped GitHub App with only these repository permissions:

  • Contents: read and write.
  • Pull requests: read and write.
  • Metadata: read, granted automatically by GitHub.

Store its client ID in the PEER_UPGRADE_APP_CLIENT_ID repository variable and its private key in the PEER_UPGRADE_APP_PRIVATE_KEY Actions secret. The workflow requests only Contents and Pull requests access when it creates its short-lived installation token. The token is revoked when the job ends. Do not substitute a personal access token or expose either value to pull-request code.

The workflow uses an exact Node.js release whose bundled npm version matches the root packageManager field, and verifies that match before regenerating the lockfile. This avoids both ad-hoc package-manager installation and unrelated lockfile normalization. Compatibility CI still tests every supported Node.js line without writing to the lockfile.

Pull requests created with the App token trigger the repository’s normal checks. Branch protection and human review remain responsible for deciding whether the tested peer range should become a published compatibility claim. Preparation reinstalls the proposed lockfile before testing so the target integration is actually installed.

Local and manual operation

Inspect a proposed version without changing files:

npm run peer:prepare -- @sveltia/cms --version 0.197.1

Add --write to update the two manifests, then regenerate the root lockfile:

npm run peer:prepare -- @sveltia/cms --version 0.197.1 --write
npm install --package-lock-only --ignore-scripts
npm ci

The local command requires an exact --version and performs no network access. When a manual workflow dispatch leaves its version empty, the workflow resolves the package’s current npm latest tag before passing that exact version to the file-writing command. The command returns structured JSON and makes no changes when the supplied version already satisfies the peer range.

Each run writes a job summary containing the proposed development range, peer range, content-model version, validation status, and resulting pull-request link. Action annotations call out registry failures, validation failures, missing GitHub App configuration, and no-op compatible releases.

Recovery

The workflow maintains one automation/peer-* branch and open pull request per peer. Re-running it updates that branch rather than creating a competing PR. If registry lookup or validation fails, no token is created and nothing is pushed. If branch or pull-request creation fails after validation, rerun the workflow; the same deterministic branch is reused.

Close an update pull request when upstream behavior is incompatible, and record the rejected version and reason in the pull request. The current peer range then remains authoritative. Never widen the range merely to make dependency installation succeed. If adopting the peer requires a public API change or a consumer migration, close the generated patch pull request and prepare the appropriate minor or major release manually.

Automatic publication boundary

Only merged, same-repository PRs from the configured GitHub App and the existing peer/template automation branches qualify. Automatic publication requires a stable, consecutive patch version, the expected metadata/lockfile/changelog file set, and an already published predecessor. Unreleased package implementation or shipped template changes since that predecessor require a separate manual baseline release. Reviewed dependency updates, including action pins mirrored from Forge workflows at build time, may accompany these patches; the workflow job definitions themselves are not shipped to consumers. Stable generator publication excludes prerelease template pins. Every publication retains the quality, tarball identity, registry integrity and provenance gates. Existing tags are verified rather than replaced.

The first create-forge baseline is prepared separately as 1.1.0 to account for the new CI features. Publish that reviewed release through the existing manual tag and approval process before relying on unattended generator patches.

Manual package tags retain the npm-release environment and its reviewer gate. Automatic main-branch patches use npm-release-auto, restricted to the main branch without a publication reviewer. A manual package workflow dispatch remains a preparation-only operation.

One-time trusted publisher setup

Keep the existing npm publisher connection for manual releases. For both @rm-industries/content-model and @rm-industries/create-forge, add another GitHub trusted publisher connection with these values:

  • Organization: rm-industries.
  • Repository: forge.
  • Workflow filename: package-release.yml.
  • Environment: npm-release-auto.
  • Allow direct npm publish.

npm supports multiple connections, so the manual identity remains intact. New connections must complete their first publish within two days; add them close to the first approved compatibility merge, after the workflow changes and baseline release are ready. No long-lived npm token is required. See npm trusted publishing.

Review the weekly compatibility PR and merge it after its checks pass. The publication, stable template PR auto-merge and generator publication then proceed without further publication approvals. An incompatible peer, failed consumer check, missing baseline or registry mismatch stops the chain and leaves the relevant workflow/PR for investigation. Retry failed workflow jobs for an approved commit; immutable tags and registry integrity checks make publication retries safe.