Roadmap relationship
Outcome
Create isolated, traceable preview environments from branches or pull requests, update them on new commits, publish stable preview URLs/status, and remove them automatically according to TTL and pull-request lifecycle.
Current gap
PreviewEnvironmentManager and env:preview exist but deployment, persistence, cleanup, cost lookup, domain handling, and provider integration are placeholders. Preview state is currently in memory and uses a fake URL.
User experience
- Configure previews per application: enable, base environment, branch rules, domain pattern, TTL, resource overrides, secrets policy, and cleanup behavior.
- Show preview list/status, PR/branch/commit, creator, age/expiry, URL, latest deployment, cost estimate, and teardown errors.
- Post deployment status and URL back to supported Git providers; update in place on new commits.
- Warn before manual deletion, support extend/rebuild, and surface leaked-resource reconciliation.
Scope
- Persist preview definitions and instances; derive deterministic collision-safe names, stack/resource tags, and stable URLs.
- Clone a safe subset of base environment config with explicit resource/secret inheritance rules and size/cost caps.
- Implement create/update/destroy through existing deployment/provider primitives and durable jobs.
- React to PR open/synchronize/reopen/close and branch deletion events idempotently.
- Add scheduled TTL cleanup, keep-count limits, dry run, provider reconciliation, and cost tagging.
- Support serverless/static first and document capability requirements for server/container previews.
Technical direction
- Use immutable source SHA plus preview identity; never deploy an ambiguous moving branch without resolving a commit.
- Tag every provider resource with preview/project/expiry identifiers and discover orphaned resources by tag.
- Separate desired preview record from last observed provider state.
- Design database strategy explicitly: isolated, snapshot/clone, shared read-only, or disabled.
Safety and operability
- Default to no production secrets and no production write endpoints; require explicit per-secret opt-in.
- Apply budget/resource ceilings and block public previews when domain/TLS/auth policy is unsatisfied.
- Teardown is idempotent, audited, and does not delete untagged or shared resources.
- Untrusted fork PRs never receive privileged credentials by default.
Acceptance criteria
- A valid PR event creates one preview, later commits update it, and close/TTL removes it.
- Preview URLs and provider statuses point to the exact deployed commit.
- Fork and secret policies prevent credential exposure.
- Failed cleanup remains visible and retryable with an exact resource reconciliation report.
Verification
- Webhook lifecycle/deduplication, naming collision, TTL, orphan discovery, secret inheritance, and fork-policy tests.
- Provider-tagged create/update/destroy integration fixtures.
- End-to-end PR open → deploy → update → close flow.
Non-goals
- Full production-sized clones by default.
- Sharing mutable production databases with untrusted previews.
- Supporting every provider/resource combination in the first release.