deploy: provision gated staging and development environments

[chrisbbreuer]

Context

The current production deployment is the only provisioned deployment target and must remain mapped to main. Existing CI branch cases for stage, dev, and beta tags imply environments and credentials that are not currently provisioned. They are being removed from active push-to-deploy routing so an unconfigured branch cannot select a misleading or unsafe target.

This issue preserves the intended multi-environment capability as explicit follow-up work rather than silently deleting it.

Scope

• Provision protected GitHub staging and development environments.
• Define branch ownership (stage, dev, or successor names) and promotion policy.
• Provision isolated ts-cloud accounts/projects, credentials, state, DNS, and rollback policy for each environment.
• Extend the tested deployment-target resolver only after infrastructure exists.
• Add smoke tests and retained deployment evidence per environment.

Acceptance criteria

• Every non-production branch mapping names a provisioned GitHub environment and isolated ts-cloud target.
• Required credentials and environment protection rules are documented and validated before deployment.
• Resolver tests reject unknown branches and map each approved branch deterministically.
• Push-to-deploy runs are retained and include rollback/smoke-test evidence.
• Production remains main -> production throughout the rollout.

Related: #2060 and implementation PR #2064.

[chrisbbreuer]

Production is now proven on merged main at https://github.com/stacksjs/stacks/actions/runs/29891194353. The resolver accepts only refs/heads/main and maps it to production plus --prod; stage, dev, tags, and unknown refs fail closed. This issue intentionally remains open only for provisioning and policy decisions for future staging/development environments.

[chrisbbreuer]

The GitHub production environment is now independently restricted to the custom main branch policy. This complements the checked-in resolver and prevents a future workflow edit from deploying a non-main ref into production without an explicit environment-policy change. Historical staging/development environment objects and deployment records were preserved; neither is mapped by current code.

[chrisbbreuer]

Two of the five criteria are met; the other three need infrastructure that does not exist yet.

Met

• Resolver tests reject unknown branches and map each approved branch deterministically. Hardened in 865aca41eb. The suite already covered stage, dev and a beta tag, but not the case that actually guards the implementation:

  'refs/heads/' is 11 characters
  'refs/tags/xmain'.slice(11) === 'main'
  'refs/pull/1main'.slice(11) === 'main'
  

  A tag or PR ref whose 12th character onward spells main resolves to production the moment the startsWith check is skipped. Verified by deleting that line: the suite passed before the commit and fails after it. Arbitrary branches (production, master, release, feature/x, main-2, mainline, empty) and non-branch refs are covered too.

• Production remains main -> production throughout. Unchanged, and pinned by the first test.

Still blocked on provisioning

The remaining three all require real accounts and secrets rather than code: protected GitHub staging/development environments, isolated ts-cloud targets with their own credentials, state, DNS and rollback policy, and retained per-environment deploy evidence. Nothing in the repo can create those.

Worth flagging for whenever that provisioning happens: the deploy path now assumes the target's bun can read a lockfileVersion 2 bun.lock. The production box was provisioned with bun 1.3.14 and could not, which broke deploys until ed2e8ec64f added a guarded upgrade to preStart. Any new environment provisioned from the same cloud-init inherits that, so it is worth folding the bun version into provisioning rather than repeating the preStart workaround per environment.

applyEnvironmentToSites already rewrites site hosts and URL env values per environment, so the config-side model for staging/dev is in place ahead of the infrastructure.

[chrisbbreuer]

Status check as part of the 1.0 sweep. The repository half is done and correct; the issue is blocked on infrastructure, which is what it was filed to preserve.

.github/scripts/deploy/resolve-target.ts maps exactly one branch:

main: { environment: 'production', flag: '--prod' }

and refuses everything else by name rather than falling through to something plausible:

No provisioned push-to-deploy target for <ref>; see stacksjs/stacks#2068

That is the property this issue was created to protect - an unconfigured branch cannot select a misleading or unsafe target - and resolve-target.test.ts covers it, 6/6 passing, run as its own CI step.

Everything remaining needs infrastructure that does not exist yet, and none of it can be created from the repository:

• Protected GitHub staging and development environments
• Isolated ts-cloud accounts/projects, credentials, state and DNS per environment
• Branch ownership and promotion policy decided (stage, dev, or successor names)
• The resolver extended - after the infrastructure exists, not before, which is the whole point of the current shape
• Smoke tests and retained deployment evidence per environment

Production remains main → production throughout, as required, and is exercised on every push to main.

Leaving open. Nothing here is waiting on code.

[chrisbbreuer]

Progress in 8c48450. The half that is code is done; the half that is provisioning is not, and cannot be from here.

Done

"Required credentials and environment protection rules are documented and validated before deployment."

They were not validated at all. The deploy job installed, built, and ran buddy deploy — and a missing DOTENV_PRIVATE_KEY_PRODUCTION surfaced inside it minutes later. For that secret in particular the symptom is not an error: the env file simply fails to decrypt and every configured value is silently its default.

DeploymentTarget now carries a requires list, checked by resolve-target.ts --preflight in the deploy job before the install — the earliest point that can see that environment's secrets at all.

An empty value counts as missing. A GitHub secret that was never set arrives as the empty string rather than being absent, so name in env passes for a secret nobody configured — which is exactly the case this is for. Asserted, and verified to fail against the in form.

Only fatal values are listed. DEPLOY_SSH_KEY, SSH_KNOWN_HOSTS and the Cloudflare pair each degrade deliberately and the workflow says so at each; requiring them would turn a documented degradation into a failed deploy. That is asserted too, so a later "make it stricter" has to argue with a test.

"Resolver tests reject unknown branches and map each approved branch deterministically." Already true before this issue was picked up — resolve-target.test.ts covers unprovisioned branches, non-branch refs, and the prefix-slicing case where refs/tags/xmain would slice to main without the startsWith guard. Now also covers the requirements and an end-to-end preflight invocation. 14 tests.

"Production remains main -> production." Still the only mapping, and the resolver rejects everything else.

docs/guide/ci.md gains the runbook: what an environment declares, and the order for adding one — provision first, then map, because a mapping without the infrastructure is the thing this design exists to prevent. Including the trap that GitHub does not expose a secret the workflow has not named, so a requires entry the preflight step does not pass will read as missing.

Not done, and not code

• Provisioning the protected staging and development GitHub environments
• Provisioning isolated ts-cloud projects, credentials, state, DNS and rollback policy for each — an environment sharing production's state is not a separate environment
• Retained push-to-deploy runs with rollback and smoke-test evidence, which needs the environments to exist first

Once those are provisioned, adding each is: a row in branchTargets with its requires, the secrets passed to the preflight step, and the environment union extended so an unknown name is a type error. The runbook spells it out.