🚁 Create a staging environment deployment for pull requests

[kasperpeulen]

Closes #1067

Summary

Implements per-PR staging environments using Fly.io's PR preview feature, resolving the staging bottleneck issue discussed in #1067.

Problem

Previously, the Epic Stack used a single shared staging environment (app-name-staging) which created several issues:

• Staging bottleneck: Only one PR could be properly tested at a time
• Unclear test failures: Hard to determine if QA failures were from your PR or conflicting changes
• Serial workflow: Teams couldn't perform parallel quality assurance
• Extra setup: Required creating and maintaining a separate staging app during initial deployment

Solution

Each pull request now gets its own isolated staging environment with:

• Unique Fly app per PR (e.g., app-name-pr-123)
• Automatic provisioning of database, secrets, object storage, and Consul
• Pre-seeded test data for immediate testing
• Automatic cleanup when PRs are closed
• GitHub environment integration with deployment URLs

Changes

CI/CD Pipeline (.github/workflows/deploy.yml):

• Added deploy-staging job using superfly/fly-pr-review-apps@1.5.0
• Staging apps use GitHub environment secrets instead of Fly secrets
• Production deployments only run on pushes to main (removed dev branch)
• Automatic resource provisioning: SQLite volume, Tigris storage, Consul, and secrets
• Uses pull_request_target instead of pull_request to allow PR deployments from forks. This event runs in the base repository's context with access to secrets (like FLY_API_TOKEN) required for Fly.io deployments, whereas pull_request from forks has no secret access.

Database Seeding (prisma/seed.staging.sql, other/litefs.yml):

• Created SQL seed file with test users and notes similar to the seed for local development
• Automatically seeds staging databases on first deployment

Documentation Updates:

• docs/deployment.md: Removed staging app setup, added GitHub CLI instructions
• docs/secrets.md: Updated for GitHub environment secrets
• docs/email.md, docs/monitoring.md: Updated secret commands for new workflow
• docs/database.md: Added staging seed documentation

Benefits

• ✅ Parallel QA: Multiple PRs can be tested simultaneously
• ✅ Isolated testing: Each PR has its own environment without conflicts
• ✅ Simplified setup: No separate staging app to configure during initial deployment
• ✅ Automatic cleanup: Resources freed when PRs close
• ✅ Better reviews: Reviewers get direct links to live preview environments

Test Plan

I tested this in my own deployed fork of the epic stack.

Checklist

• Tests updated
• Docs updated

Screenshots

[Copilot]

Pull request overview

This PR implements per-PR staging environments using Fly.io's PR preview feature, replacing the previous single shared staging environment to enable parallel testing and eliminate staging bottlenecks.

Key Changes:

• Automated per-PR staging deployments with isolated resources (database, secrets, storage)
• Removed manual staging app setup from initialization process
• Migrated staging secrets from Fly.io to GitHub environment secrets

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
.github/workflows/deploy.yml	Added deploy-staging job for per-PR environments, removed dev branch deployments, automated resource provisioning
remix.init/index.mjs	Removed staging app creation and setup prompts from initialization script
prisma/seed.staging.sql	New staging database seed file with test users and notes data
other/litefs.yml	Added automatic seeding of staging databases on first deployment
docs/deployment.md	Updated deployment instructions removing staging app setup, added GitHub CLI requirement
docs/secrets.md	Updated to use GitHub environment secrets for staging instead of Fly secrets
docs/email.md	Updated secret management commands for new workflow
docs/monitoring.md	Updated Sentry DSN configuration for staging environments
docs/database.md	Added documentation for staging database seeding
docs/decisions/047-pr-staging-environments.md	Decision record documenting the rationale and impact of the change
prisma/migrations/migration_lock.toml	Formatting change (no functional impact)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.