Test in a preview environment

Outcome#

The current repository commit is live in an isolated test environment, with the exact hostnames and apply result recorded before production is touched.

Prerequisites#

• A clean managed repository checkout with the intended preview change.
• An environment name and env/* branch that are not already used for another purpose.
• Any preview-only backend origins or variables required by the change. With no origin override, a declared backend slug resolves to its production binding; all Business SDK contract state still comes only from the preview branch.

Create the environment#

farthershore env create acme \
  --name pricing-preview \
  --branch env/pricing-preview \
  --format json

Environment creation has no side-effect-free preview. Resolve the name and branch first. If the result is ambiguous, list environments and repeat the same request; creation converges on current environment and branch state rather than replaying a stale attempt result.

A successful create has created or resolved the exact managed branch; it never returns a branchless environment. Explicit creation accepts only the reserved preview namespace (normally env/) and claims that exact ref before GitHub is called, so deletion later removes the associated managed branch even after a create retry. A newly created result reports branchCreated; a converged existing result omits it. Webhook and PR environments remain builder-managed source branches. If GitHub cannot create or resolve the branch, the command fails safely: restore GitHub access and repeat the same request.

git fetch origin env/pricing-preview
git switch --track origin/env/pricing-preview
farthershore build --format json
git push

Verify the exact push#

farthershore env list acme --format json
farthershore apply-timeline inspect acme "$(git rev-parse HEAD)" \
  --env pricing-preview \
  --format json

Use the returned runtime and portal hostnames rather than constructing them. For an API business, create a test persona and exercise the returned runtime:

farthershore persona bootstrap acme --env pricing-preview --plan pro --format json --idempotency-key <persisted-persona-bootstrap-attempt-key>

A persona's key is scoped to the environment's current contract. Pushing a contract change to the preview branch rebuilds the environment, which deletes its subscriptions and the keys they own: the persona survives, but persona list then reports it with revokedAt set and revokedReason: "env_reset", and the old key is denied 401 credential_env_reset. Bootstrap a new persona after such a push. A push that does not change the contract — a comment, a frontend-only edit, a re-push — leaves the persona and its key working; the apply says ENVIRONMENT_CONTRACT_UNCHANGED. See Environments for the full rule.

For a hosted frontend, wait by environment name or id and verify the active release:

farthershore frontend status acme --env pricing-preview \
  --ref "$(git rev-parse HEAD)" --wait --format json

Open the returned preview portal hostname, sign in as the persona, complete managed onboarding, and require /me to report an active compiled plan before the application becomes available. Then make one SDK route call and assert a backend-produced response marker. A generic 404 or a gateway-generated Unknown project response is not readiness, even though it is an HTTP response.

Public bootstrap for the preview must return the preview runtime hostname. If the browser targets the production gateway, stop: the environment is not safe to certify.

If the apply fails, fix the repository and push again. Do not mutate the accepted contract through a platform write.

Recovery and teardown#

farthershore env delete acme pricing-preview --yes --format json

env delete also attempts docs, edge, and workflow cleanup, and removes the branch when the explicit managed create claimed that exact reserved ref. If it returns ENVIRONMENT_CLEANUP_FAILED, retry the same command; do not delete the environment row by another route.

See Preview environments.

Agent prompt#

Create or reuse one environment branch, build and push the exact current commit,
then verify its Apply Timeline entry and returned hostnames. Exercise it with a
test persona when applicable and delete it only after testing is complete.