[AS-222] Tech note: Ephemeral environments with GraphOS

[ilan-bel]

Summary

Adds docs/ephemeral-environments.md — a reference for the per-PR variant pattern (one GraphOS variant per pull request, ephemeral Router + subgraphs deployed against it, automatic cleanup on PR close).

Covers: topology diagram, rover lifecycle commands keyed on PR number, Router pointed at the per-PR variant via APOLLO_GRAPH_REF, PR-comment URL plumbing, required API key scopes, and cost/quota gotchas (usage reporting from PR routers polluting prod dashboards, variant limits on usage-based plans).

Tracks AS-222.

Note

Placement: apollographql/docs archived, apollographql/platform-docs needs SAML grant. Landing in apollosolutions/reference-architecture/docs/ as interim home.

Test plan

• Renders cleanly
• rover commands match current CLI surface
• All Apollo docs links resolve

🤖 Generated with Claude Code

[apollo-solutions-reviewer]

The doc structure and lifecycle framing are solid and the per-PR variant pattern is the right approach. One blocking issue: the teardown command is wrong.

rover variant delete is not a real Rover command. To delete a variant you use rover graph delete my-graph@<variant> --confirm, which deletes the variant and all its subgraphs. This is load-bearing: the teardown step is a core acceptance criterion, and a CI job running rover variant delete will fail. The command appears twice (the topology diagram and Step 1).

Secondary correctness issue on the same teardown block: the comment claims the delete is "idempotent: safe to run if the variant was never created." rover graph delete returns a non-zero exit on a nonexistent variant, so a re-run (or a closed PR whose variant never got created) will fail the cleanup step. Either guard the step (e.g. || true, or check existence first) or drop the idempotency claim.

Minor (non-blocking): the prose uses em dashes in several places (lines 5, 47, 64, 116); Apollo docs style prefers avoiding them. Worth a pass before this gets upstreamed.

Fix the variant-delete command and the idempotency note and this is good to merge as the interim reference.

[apollo-solutions-reviewer]

rover variant delete is not a real command. Use rover graph delete my-graph@pr-${PR_NUMBER} --confirm (deletes the variant and all its subgraphs). Also, the comment above says this is idempotent/safe when the variant was never created, but rover graph delete exits non-zero on a missing variant and will fail the CI teardown step; guard it (e.g. || true) or remove the idempotency claim.

[apollo-solutions-reviewer]

Verified at 81f0912: Step 1 teardown now uses rover graph delete my-graph@pr-${PR_NUMBER} --confirm || true, and the surrounding comment correctly states the command exits non-zero on a missing variant and is guarded with || true rather than claiming idempotency. This thread can be resolved.

[apollo-solutions-reviewer]

Same command error in the diagram: rover variant delete should be rover graph delete.

[apollo-solutions-reviewer]

Verified at 81f0912: the topology diagram teardown line now reads rover graph delete my-graph@pr-142, matching the corrected Step 1 command. This thread can be resolved.

[apollo-solutions-reviewer]

Re-reviewed at 81f0912. The blocking teardown issue from the prior review is fully fixed. rover variant delete is gone in both locations: the topology diagram now uses rover graph delete my-graph@pr-142, and Step 1 uses rover graph delete my-graph@pr-${PR_NUMBER} --confirm. The idempotency claim has been corrected; the comment now notes the command exits non-zero on a missing variant and the step is guarded with || true. Acceptance criterion (working teardown) is met and no new blockers. The non-blocking em dash note still applies in a few spots and can be cleaned up before upstreaming, but it does not gate this interim reference. Approving.