Forge Deploy operator runbook#

Status: local release runbook. Completing these checks does not itself push, deploy Forge, attach a domain, or change production traffic.

Authoritative records#

• SmolForge Git and the exact 40-character commit SHA are the source authority.
• deploy_projects owns each project's root, enabled state, and environments.
• A project-scoped approved provider target owns the Cloudflare account and Worker name Forge is allowed to publish.
• Immutable releases and provider artifacts own build and publication evidence. Environment pointers own promotion and rollback.
• Cloudflare remains authoritative for Worker versions, runtime secrets, inherited bindings, DNS, certificates, Custom Domains, and routes.

Work is partitioned by Forge project for builds and by provider Worker for publication, promotion, retirement, and domain reconciliation. A failure in one project must not move another project's pointer or roll it back.

Before enabling a private monorepo#

1. Resolve the repository owner, repository ID, project ID, root directory, production branch, and exact SHA separately.
2. If the repository uses .forge/config.json, validate the exact-SHA file against the repository configuration contract. Confirm the reviewed defaults, permanent project slugs, roots, binding match modes, and plan digest.
3. Confirm each intended root contains its own forgeBuild.ts.
4. Confirm the private-source entitlement and Terms receipt are current.
5. Confirm the project's exact-source projection contains its root, root package-manager files, and transitive workspace:* dependencies, but not unrelated sibling applications. For pnpm v9, confirm the frozen lockfile importer index was accepted; an unsupported importer shape must take the conservative full-tree discovery fallback instead of omitting a workspace.
6. Confirm the connected-asset entitlement. For AIE it is 1 GiB per release; per-file and file-count provider limits still apply.
7. Resolve the administrator-approved Cloudflare account, Worker name, allowed zones, active 100% production version, and binding generation.

Never place Git clone credentials, Cloudflare credentials, secret values, or DNS authority in the build sandbox.

OpenNext candidate#

1. Require a project-local registry @opennextjs/cloudflare declaration and an exact resolution in a supported npm, pnpm, or Bun root lockfile. For the vetted 1.19.11 target, require Next >=15.5.18 <16 || >=16.2.6 <17; do not publish a Next 13 project.
2. Run the frozen root dependency install before resolving the project-local OpenNext executable. Do not use npx, dlx, or an implicit latest.
3. Build in the project root.
4. Wait for build processes to stop, then bound the raw .open-next compiler input. Require worker.js, assets, and cache; permit only contained pnpm symlinks and reject special files, escapes, or compiler-input overflow.
5. Compile with Forge's credential-free Wrangler path. Inspect the generated provider module graph and assets, plus the supported R2 ISR cache layout.
6. Compare the compiled graph, assets, and cache with limits. Reject changed, unsafe, oversized, or unsupported output before provider publication.
7. Freeze source SHA, OpenNext version, Forge adapter version, Wrangler digest, binding generation, module graph, assets, cache seed, and inherited settings into the artifact identity.
8. Before installation, permit OpenNext artifact reuse only when the complete source/config/lockfile/adapter/build-environment/provider/entitlement key matches, ISR evidence is ready, and the immutable provider version still exists. Missing legacy evidence or any changed input is a normal cache miss.
9. After a full build, reuse an existing provider artifact only after its immutable identity and provider receipt are verified. Do not require two fresh OpenNext builds to be byte-identical: generated draft-mode keys and concurrent prerender-manifest ordering may differ without changing routes.

For ISR, the trusted helper may inherit only the exact R2 cache binding and an ephemeral token. It must stay at zero percent, upload bounded digest-verified objects, survive retries through its durable operation ledger, and be removed before the application candidate is published.

Asset adoption#

1. As a repository administrator, inspect the exact primary-branch SHA with GET /api/repos/:owner/:repo/sites/migration/assets?sha=<sha> or the Sites adoption card. This is read-only and does not execute repository code.
2. Review the literal tree/file entries. The v1 server reports the fixed greater-than-50-MiB public/** and greater-than-5-MiB file defaults.
3. For each object with uploaded: false, use the standard Forge LFS Batch/basic HTTP API to upload and verify the exact bytes. A local git-lfs binary is not required. Inspect again before apply.
4. Apply with the exact source/head SHA, primary branch, exact object list, and a stable idempotency key. Never reuse the key for changed input.
5. Record the immutable receipt, derived migration branch, commit, pull request, and preview_behavior: "suppressed". Confirm the production branch and all deployment pointers are unchanged.
6. Review and merge or close the pull request through the ordinary repository workflow. Creating the migration PR is not a deployment or production cutover.

Promotion and rollback#

1. Re-read project, environment, release, target, and provider state under the relevant fence.
2. Prove the candidate is ready and belongs to the same project and provider target as the environment.
3. For manual production migration, change only the selected project's active pointer and record the provider receipt.
4. Verify the immutable preview, provider version, Forge production pointer, and representative HTTP routes independently.
5. Rollback moves one project's pointer to a prior ready release. It does not rebuild and does not rewind Cloudflare resources or application data.

Automatic connected publication#

For an enabled connected project whose project and production-environment publication modes are both auto, Forge reconciles the newest ready release for the current production ref through the same provider-activation operation used by an explicit promotion. The activation must still prove the exact head SHA, ready artifact, approved target, binding generation, Forge environment generation, active deployment, and frozen provider base. A failed build or a stale candidate never reaches this reconciler. Push releases also freeze the matching Action run IDs and wait until every recorded run has completed successfully. A scheduled pass repairs an interrupted reconciliation idempotently.

An ordinary Action for a repository with an approved connected target may run tests, builds, and read-only verification, but it must not activate a plain Worker version with wrangler deploy. The runner rejects that production mutation because it would bypass the release-scoped private bindings and the Forge deployment ledger. Remove the raw deploy step from such a workflow and let Automatic publication activate the connected release, or use Forge's explicit promotion operation when the project is configured for manual publication.

Treat these as separate evidence: the repository push, its exact-SHA Action, the ready connected artifact, the succeeded provider activation and receipt, the Forge production pointer, and the live hostname. No one record implies the others.

Domains and path routes#

Repository builds receive no DNS authority. An authenticated project administrator records desired state, then uses a separate explicit apply action.

A repository may propose this desired state in .forge/config.json. Treat it as exact-SHA, statically validated intent only. Inspect first, review the plan and digests, then explicitly import. New projects remain disabled. Existing projects preserve their enabled or disabled state while reviewed roots, production branches, and publication modes are updated. A missing or disabled target stays unresolved; an already-approved target that does not allow the declared zone blocks import. Import never applies provider state, and an omitted entry never means detach. If an independent project partially imports before a later failure, repair the contract, inspect again, and approve the new plan digest before retrying.

Before apply, prove the hostname is in an approved owned zone, has no competing Forge claim or conflicting CNAME, and the path route has unambiguous precedence. Record the desired generation before calling Cloudflare. Persist the provider receipt, certificate/DNS observations, and any retryable error.

A path_route is one logical wildcard-free path with one of two match modes. exact_and_descendants is the default and preserves lexical siblings: Forge reconciles the exact path plus its / descendants. reserved_prefix is an explicit namespace reservation: Forge uses a broad provider pattern such as host/archive*, which covers the query-bearing root and descendants but also captures siblings such as /archive-old. Approve it only when one project intentionally owns that whole lexical prefix. Apply and detach inspect every expected provider pattern and fail closed on unexpected overlaps or ownership drift.

A main Worker Custom Domain and more-specific archive path bindings may share one hostname. Cloudflare evaluates the matching Worker Route before the Custom Domain, so Forge does not model the main Worker as a /* path route.

One Cloudflare matching limit remains an explicit application gate. Archive prefixes do not capture Next Pages Router data URLs such as /_next/data/<build-id>/archive.json; reviewed document navigation can avoid those client data requests. The explicit reserved_prefix mode solves the query-bearing archive root by reserving the broader lexical prefix; its sibling capture is intentional and must be reviewed before apply. Cloudflare does not support arbitrary infix Worker Route wildcards.

Detach is reversible desired state. Keep the claim until Cloudflare proves the domain or route is detached. Never delete an active domain without a confirmed replacement or an explicit detach.

Cleanup#

Retention protects the active deployment and the configured rollback candidates. Provider-version cleanup is serialized with promotion, rechecks current deployment membership, and never deletes a 100% production version. An interrupted or provider-rejected cleanup retains its receipt and returns to retryable reconciliation.

Release proof#

Report these as separate facts:

1. implemented locally;
2. focused and full tests passing;
3. phase commits created;
4. branch pushed;
5. D1 migrations applied;
6. provider targets and entitlements provisioned;
7. Worker versions uploaded;
8. traffic or environment pointers switched;
9. DNS and certificate active;
10. live HTTP and browser routes verified.