Create a staging environment deployment for pull requests

Author: kasperpeulen

.github/workflows/deploy.yml

@@ -3,8 +3,12 @@ on:
   push:
     branches:
       - main
-      - dev
-  pull_request: {}
+  pull_request:
+    types: [opened, reopened, synchronize]
+  # Clean up the staging environment when a PR is closed
+  # Use pull_request_target to also run when the PR has merge conflicts
+  pull_request_target:
+    types: [closed]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -14,14 +18,18 @@ permissions:
   actions: write
   contents: read
 
+env:
+  FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+  # Change this if you want to deploy to a different org
+  FLY_ORG: personal
 jobs:
   lint:
     name: ⬣ ESLint
     runs-on: ubuntu-22.04
+    if: ${{ github.event.action != 'closed' }}
     steps:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
-
       - name: ⎔ Setup node
         uses: actions/setup-node@v4
         with:
@@ -42,10 +50,10 @@ jobs:
   typecheck:
     name: ʦ TypeScript
     runs-on: ubuntu-22.04
+    if: ${{ github.event.action != 'closed' }}
     steps:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
-
       - name: ⎔ Setup node
         uses: actions/setup-node@v4
         with:
@@ -69,10 +77,10 @@ jobs:
   vitest:
     name: ⚡ Vitest
     runs-on: ubuntu-22.04
+    if: ${{ github.event.action != 'closed' }}
     steps:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
-
       - name: ⎔ Setup node
         uses: actions/setup-node@v4
         with:
@@ -93,11 +101,11 @@ jobs:
   playwright:
     name: 🎭 Playwright
     runs-on: ubuntu-22.04
+    if: ${{ github.event.action != 'closed' }}
     timeout-minutes: 60
     steps:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
-
       - name: 🏄 Copy test env vars
         run: cp .env.example .env
 
@@ -146,8 +154,7 @@ jobs:
   container:
     name: 📦 Prepare Container
     runs-on: ubuntu-24.04
-    # only prepare container on pushes
-    if: ${{ github.event_name == 'push' }}
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
     steps:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
@@ -164,37 +171,103 @@ jobs:
       - name: 🎈 Setup Fly
         uses: superfly/flyctl-actions/[email protected]
 
-      - name: 📦 Build Staging Container
-        if: ${{ github.ref == 'refs/heads/dev' }}
+      - name: 📦 Build Production Container
         run: |
           flyctl deploy \
             --build-only \
             --push \
             --image-label ${{ github.sha }} \
             --build-arg COMMIT_SHA=${{ github.sha }} \
-            --app ${{ steps.app_name.outputs.value }}-staging
-        env:
-          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+            --build-secret SENTRY_AUTH_TOKEN=${{ secrets.SENTRY_AUTH_TOKEN }} \
+            --app ${{ steps.app_name.outputs.value }}
 
-      - name: 📦 Build Production Container
-        if: ${{ github.ref == 'refs/heads/main' }}
+  deploy-staging:
+    name: 🚁 Deploy staging app for PR
+    runs-on: ubuntu-24.04
+    # Only run for PRs from the same repository (skip forks)
+    if: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}
+    outputs:
+      url: ${{ steps.deploy.outputs.url }}
+    environment:
+      name: staging
+      url: ${{ steps.deploy.outputs.url }}
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: '50'
+      - name: 👀 Read app name
+        uses: SebRollen/[email protected]
+        id: app_name
+        with:
+          file: 'fly.toml'
+          field: 'app'
+
+      - name: 🎈 Setup Fly
+        uses: superfly/flyctl-actions/[email protected]
+
+      #  Inspired by https://github.com/superfly/fly-pr-review-apps/blob/main/entrypoint.sh
+      - name: 🚁️ Deploy PR app to Fly.io
+        id: deploy
+        if: ${{ env.FLY_API_TOKEN }}
         run: |
+          FLY_APP_NAME="${{ steps.app_name.outputs.value }}-pr-${{ github.event.number }}"
+          FLY_REGION=$(flyctl config show | jq -r '.primary_region')
+
+          # Create app if it doesn't exist
+          if ! flyctl status --app "$FLY_APP_NAME"; then
+            # change org name if needed
+            flyctl apps create $FLY_APP_NAME --org $FLY_ORG
+            flyctl secrets --app $FLY_APP_NAME set SESSION_SECRET=$(openssl rand -hex 32) HONEYPOT_SECRET=$(openssl rand -hex 32)
+            flyctl consul attach --app $FLY_APP_NAME
+            # Don't log the created tigris secrets!
+            flyctl storage create --app $FLY_APP_NAME --name epic-stack-$FLY_APP_NAME --yes > /dev/null 2>&1
+          fi
+
+          flyctl secrets --app $FLY_APP_NAME set SENTRY_DSN=${{ secrets.SENTRY_DSN }} RESEND_API_KEY=${{ secrets.RESEND_API_KEY }}
+
           flyctl deploy \
-            --build-only \
-            --push \
+            --ha=false \
+            --regions $FLY_REGION \
+            --vm-size shared-cpu-1x \
+            --env APP_ENV=staging \
+            --env ALLOW_INDEXING=false \
+            --app $FLY_APP_NAME \
             --image-label ${{ github.sha }} \
             --build-arg COMMIT_SHA=${{ github.sha }} \
             --build-secret SENTRY_AUTH_TOKEN=${{ secrets.SENTRY_AUTH_TOKEN }} \
-            --app ${{ steps.app_name.outputs.value }}
-        env:
-          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
 
+          echo "url=https://$FLY_APP_NAME.fly.dev" >> $GITHUB_OUTPUT
+
+  cleanup-staging:
+    name: 🧹 Cleanup staging app
+    runs-on: ubuntu-24.04
+    if: ${{ github.event.action == 'closed' }}
+    steps:
+      - name: 👀 Read app name
+        uses: SebRollen/[email protected]
+        id: app_name
+        with:
+          file: 'fly.toml'
+          field: 'app'
+
+      - name: 🎈 Setup Fly
+        uses: superfly/flyctl-actions/[email protected]
+
+      - name: 🧹 Cleanup resources
+        if: ${{ env.FLY_API_TOKEN }}
+        run: |
+          FLY_APP_NAME="${{ steps.app_name.outputs.value }}-pr-${{ github.event.number }}"
+          flyctl storage destroy epic-stack-$FLY_APP_NAME --yes || true
+          flyctl apps destroy "$FLY_APP_NAME" -y || true
   deploy:
-    name: 🚀 Deploy
+    name: 🚀 Deploy production
     runs-on: ubuntu-24.04
     needs: [lint, typecheck, vitest, playwright, container]
-    # only deploy on pushes
-    if: ${{ github.event_name == 'push' }}
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+    environment:
+      name: production
+      url: https://${{ steps.app_name.outputs.value }}.fly.dev
     steps:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
@@ -211,19 +284,7 @@ jobs:
       - name: 🎈 Setup Fly
         uses: superfly/flyctl-actions/[email protected]
 
-      - name: 🚀 Deploy Staging
-        if: ${{ github.ref == 'refs/heads/dev' }}
-        run: |
-          flyctl deploy \
-            --image "registry.fly.io/${{ steps.app_name.outputs.value }}-staging:${{ github.sha }}" \
-            --app ${{ steps.app_name.outputs.value }}-staging
-        env:
-          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
-
       - name: 🚀 Deploy Production
-        if: ${{ github.ref == 'refs/heads/main' }}
         run: |
           flyctl deploy \
             --image "registry.fly.io/${{ steps.app_name.outputs.value }}:${{ github.sha }}"
-        env:
-          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

docs/database.md

@@ -148,14 +148,24 @@ migrations.
 ## Seeding Production
 
 In this application we have Role-based Access Control implemented. We initialize
-the database with `admin` and `user` roles with appropriate permissions.
+the database with `admin` and `user` roles with appropriate permissions. This is
+done in the `migration.sql` file that's included in the template.
 
-This is done in the `migration.sql` file that's included in the template. If you
-need to seed the production database, modifying migration files manually is the
-recommended approach to ensure it's reproducible.
+For staging we create a new database for each PR. To make sure that this
+database is already filled with some seed data we manually run the following
+command:
+
+```sh
+npx prisma db execute --file ./prisma/seed.staging.sql --url $DATABASE_URL
+```
+
+If you need to seed the production database, modifying migration files manually
+is the recommended approach to ensure it's reproducible.
 
 The trick is not all of us are really excited about writing raw SQL (especially
-if what you need to seed is a lot of data), so here's an easy way to help out:
+if what you need to seed is a lot of data). You could look at `seed.staging.sql`
+for inspiration or create a custom sql migration file with the following steps.
+You can also use these steps to modify the seed.staging.sql file to your liking.
 
 1. Create a script very similar to our `prisma/seed.ts` file which creates all
    the data you want to seed.
@@ -300,7 +310,6 @@ You've got a few options:
      re-generating the migration after fixing the error.
 3. If you do care about the data and don't have a backup, you can follow these
    steps:
-
    1. Comment out the
       [`exec` section from `litefs.yml` file](https://github.com/epicweb-dev/epic-stack/blob/main/other/litefs.yml#L31-L37).
 

docs/decisions/047-pr-staging-environments.md

@@ -0,0 +1,48 @@
+# Per-PR Staging Environments
+
+Date: 2025-12-24
+
+Status: accepted
+
+## Context
+
+The Epic Stack previously used a single shared staging environment deployed from the `dev` branch. This approach created several challenges for teams working with multiple pull requests:
+
+- **Staging bottleneck**: Only one PR could be properly tested in the staging environment at a time, making parallel development difficult.
+- **Unclear test failures**: When QA testing failed, it was hard to determine if the failure was from the specific PR being tested or from other changes that had been deployed to the shared staging environment.
+- **Serial workflow**: Teams couldn't perform parallel quality assurance, forcing them to coordinate who could use staging at any given time.
+- **Extra setup complexity**: During initial deployment, users had to create and configure a separate staging app with its own database, secrets, and resources.
+
+Fly.io provides native support for PR preview environments through their `fly-pr-review-apps` GitHub Action, which can automatically create, update, and destroy ephemeral applications for each pull request.
+
+This pattern is common in modern deployment workflows (Vercel, Netlify, Render, etc.) and provides isolated environments for testing changes before they reach production.
+
+## Decision
+
+We've decided to replace the single shared staging environment with per-PR staging environments using Fly.io's PR review apps feature. Each pull request now:
+
+- Gets its own isolated Fly.io application (e.g., `app-name-pr-123`)
+- Automatically provisions all necessary resources (SQLite volume, Tigris object storage, Consul for LiteFS)
+- Generates and stores secrets (SESSION_SECRET, HONEYPOT_SECRET)
+- Seeds the database with test data for immediate usability
+- Provides a direct URL to the deployed app in the GitHub PR interface
+- Automatically cleans up all resources when the PR is closed
+
+Staging environment secrets are now managed as GitHub environment secrets and passed to Fly in Github Actions.
+
+The `dev` branch and its associated staging app have been removed from the deployment workflow. Production deployments continue to run only on pushes to the `main` branch.
+
+## Consequences
+
+**Positive:**
+
+- **Isolated testing**: Each PR has its own complete environment, making it clear which changes caused any issues
+- **Simplified onboarding**: New users only need to set up one production app, not both production and staging
+- **Better reviews**: Reviewers (including non-technical stakeholders) can click a link to see and interact with changes before merging
+- **Automatic cleanup**: Resources are freed when PRs close, reducing infrastructure costs
+- **Realistic testing**: Each PR tests the actual deployment process, catching deployment-specific issues early
+
+**Negative:**
+
+- **Increased resource usage during development**: Each open PR consumes Fly.io resources (though they're automatically cleaned up)
+