feat(ci): add maintainer-approved pull request previews

Author: FelixTJDietrich

.changeset/previews-deploy-on-purpose.md

@@ -0,0 +1,9 @@
+---
+"hephaestus": minor
+---
+
+Pull request previews now start only after a maintainer requests one. Once started, each new approved head deploys after its current CI run passes, appears through GitHub's native deployment link, and is removed when the pull request closes.
+
+Preview stacks use their own database, message broker, credentials, and Docker networks. They run signed CI images without the staging Docker socket, data, or integration credentials.
+
+**Operators:** follow the preview runbook before enabling the Coolify application. It requires a preview-only environment, two scoped Coolify secrets, a forced-command SSH cleanup key, and the repository variables listed there. Keep Coolify's automatic repository webhook disabled.

.github/workflows/cicd.yml

@@ -167,93 +167,6 @@ jobs:
               - '!webapp/src/**/*.stories.*'
               - '!webapp/src/test/**'
 
-  # Coolify creates previews for trusted same-repository pull requests. This job waits for the
-  # immutable application-server image, then updates the preview to the exact head commit. Coolify's
-  # deploy API only accepts a pull request that already has a preview, so a missing preview remains a
-  # safe no-op. Instance identifiers come from repository variables; forks never receive credentials.
-  preview:
-    name: "Preview / Coolify"
-    runs-on: ubuntu-latest
-    # Wait for Docker so SOURCE_COMMIT always names an image that already exists in GHCR. `always`
-    # preserves the link/no-op behavior when the Docker workflow is legitimately skipped.
-    needs: [detect-changes, Docker]
-    if: >-
-      always() &&
-      github.event_name == 'pull_request' &&
-      vars.COOLIFY_URL != '' &&
-      vars.COOLIFY_APP_UUID != '' &&
-      (needs.Docker.result == 'success' || needs.Docker.result == 'skipped')
-    permissions:
-      statuses: write
-    timeout-minutes: 2
-    env:
-      COOLIFY_URL: ${{ vars.COOLIFY_URL }}
-      COOLIFY_APP_UUID: ${{ vars.COOLIFY_APP_UUID }}
-      COOLIFY_PROJECT_UUID: ${{ vars.COOLIFY_PROJECT_UUID }}
-      COOLIFY_ENVIRONMENT_UUID: ${{ vars.COOLIFY_ENVIRONMENT_UUID }}
-    steps:
-      - name: Link the preview deployments page on the PR
-        if: vars.COOLIFY_PROJECT_UUID != '' && vars.COOLIFY_ENVIRONMENT_UUID != ''
-        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
-        with:
-          script: |
-            const { COOLIFY_URL, COOLIFY_PROJECT_UUID, COOLIFY_ENVIRONMENT_UUID, COOLIFY_APP_UUID } = process.env;
-            await github.rest.repos.createCommitStatus({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              sha: context.payload.pull_request.head.sha,
-              state: 'success',
-              target_url: `${COOLIFY_URL}/project/${COOLIFY_PROJECT_UUID}/environment/${COOLIFY_ENVIRONMENT_UUID}/application/${COOLIFY_APP_UUID}/preview-deployments`,
-              description: 'Click Details to view Coolify preview deployments',
-              context: 'Preview / Coolify',
-            });
-
-      # Forks are skipped deliberately: a preview runs with the instance's real credentials.
-      - name: Update this PR's preview deployment, if it has one
-        if: >-
-          (github.event.action == 'opened' ||
-           github.event.action == 'reopened' ||
-           github.event.action == 'synchronize') &&
-          github.event.pull_request.head.repo.full_name == github.repository
-        env:
-          COOLIFY_TOKEN: ${{ secrets.COOLIFY_API_TOKEN }}
-          PR_NUMBER: ${{ github.event.pull_request.number }}
-          APP_SERVER_PUBLISHED: ${{ needs.Docker.outputs.application-server-published }}
-        run: |
-          set -euo pipefail
-
-          if [ -z "${COOLIFY_TOKEN}" ]; then
-            echo "::notice::COOLIFY_API_TOKEN is not configured; skipping preview update."
-            exit 0
-          fi
-
-          # Coolify pins the preview to SOURCE_COMMIT, so without that tag the deployment can only
-          # fail on `manifest unknown` — under a green check, since queueing one always succeeds.
-          if [ "${APP_SERVER_PUBLISHED}" != 'true' ]; then
-            echo "::notice::No application-server image for this commit; skipping preview update."
-            exit 0
-          fi
-
-          body=$(mktemp)
-          status=$(curl -sS -o "${body}" -w '%{http_code}' -X POST \
-            -H "Authorization: Bearer ${COOLIFY_TOKEN}" \
-            -H 'Accept: application/json' \
-            --retry 3 --retry-connrefused --max-time 30 \
-            "${COOLIFY_URL}/api/v1/deploy?uuid=${COOLIFY_APP_UUID}&pr=${PR_NUMBER}")
-
-          if [ "${status}" -ge 400 ]; then
-            echo "::error::Coolify returned HTTP ${status}: $(cat "${body}")"
-            exit 1
-          fi
-
-          deployment=$(jq -r '.deployments[0].deployment_uuid // empty' "${body}")
-          if [ -z "${deployment}" ]; then
-            echo "::notice::PR #${PR_NUMBER} has no preview deployment ($(jq -r '.deployments[0].message // "no deployment queued"' "${body}"))."
-            exit 0
-          fi
-
-          echo "::notice::Queued Coolify deployment ${deployment} for PR #${PR_NUMBER}."
-
   Quality:
     uses: ./.github/workflows/ci-quality-gates.yml
     needs: [detect-changes]
@@ -308,9 +221,9 @@ jobs:
     # Image builds consume the detected source tree, not Quality outputs. Running both branches at
     # once keeps image and preview confidence without adding Docker as a second CI stage.
     needs: [detect-changes]
-    # Every same-repository pull request gets a Coolify preview pinned to SOURCE_COMMIT, so it needs
-    # an application-server tag at its head commit even when it touches only docs or the preview
-    # stack. The path filters below therefore gate fork pull requests only — forks get no preview.
+    # Any same-repository pull request can be opted into a preview after CI, so it needs signed,
+    # commit-addressed image tags even when it touches only docs or the preview stack. The path
+    # filters below therefore gate fork pull requests only; forks never receive a preview.
     if: |
       needs.detect-changes.outputs.should_skip != 'true' && (
         github.event_name != 'pull_request' ||

.github/workflows/cleanup-preview.yml

@@ -1,51 +1,94 @@
 name: Preview cleanup
 
+# pull_request_target loads the trusted default-branch workflow. It signs a close event for Coolify,
+# then uses a forced SSH command to prove that the matching host resources are gone.
 on:
-  pull_request:
+  pull_request_target:
     branches: ["**"]
     types: [closed]
 
 permissions:
   contents: read
+  deployments: write
+
+concurrency:
+  group: hephaestus-preview-lifecycle
+  queue: max
 
 jobs:
   cleanup:
-    name: "Preview / Delete Coolify resources"
-    if: >-
-      vars.COOLIFY_URL != '' &&
-      vars.COOLIFY_APP_UUID != '' &&
-      github.event.pull_request.head.repo.full_name == github.repository
+    name: "Preview / Remove and verify resources"
+    if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
-    timeout-minutes: 3
+    timeout-minutes: 8
     env:
       COOLIFY_URL: ${{ vars.COOLIFY_URL }}
       COOLIFY_APP_UUID: ${{ vars.COOLIFY_APP_UUID }}
-      COOLIFY_TOKEN: ${{ secrets.COOLIFY_API_TOKEN }}
       PR_NUMBER: ${{ github.event.pull_request.number }}
+      PR_URL: ${{ github.event.pull_request.html_url }}
+      PR_TITLE: ${{ github.event.pull_request.title }}
+      AUTHOR_ASSOCIATION: ${{ github.event.pull_request.author_association }}
+      HEAD_REF: ${{ github.event.pull_request.head.ref }}
+      HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+      BASE_REF: ${{ github.event.pull_request.base.ref }}
+      ENVIRONMENT: preview/pr-${{ github.event.pull_request.number }}
     steps:
-      - name: Delete preview containers, volumes, and network
+      - name: Load the trusted preview adapter
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+          sparse-checkout: |
+            .github/actions/setup-bun
+            package.json
+            scripts
+
+      - name: Set up the repository's Bun version
+        uses: ./.github/actions/setup-bun
+
+      - name: Request Coolify cleanup through the signed close event
+        id: close
+        continue-on-error: true
+        env:
+          COOLIFY_WEBHOOK_SECRET: ${{ secrets.COOLIFY_PREVIEW_WEBHOOK_SECRET }}
+        run: bun scripts/coolify-preview.ts close
+
+      - name: Wait for the Coolify deployment queue to drain
+        id: drain
+        if: always()
+        continue-on-error: true
+        env:
+          COOLIFY_TOKEN: ${{ secrets.COOLIFY_PREVIEW_READ_TOKEN }}
+        run: bun scripts/coolify-preview.ts drain
+
+      - name: Remove and verify matching host resources
+        id: host_cleanup
+        if: always()
+        env:
+          PREVIEW_HOST: ${{ vars.PREVIEW_HOST }}
+          PREVIEW_HOST_KEY: ${{ vars.PREVIEW_HOST_KEY }}
+          PREVIEW_SSH_USER: ${{ vars.PREVIEW_SSH_USER }}
+          PREVIEW_SSH_PRIVATE_KEY: ${{ secrets.PREVIEW_SSH_PRIVATE_KEY }}
+        run: bun scripts/preview-ssh.ts cleanup "${PR_NUMBER}"
+
+      - name: Keep a verified cleanup tombstone
+        if: >-
+          always() &&
+          steps.close.outcome == 'success' &&
+          steps.drain.outcome == 'success' &&
+          steps.host_cleanup.outcome == 'success'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const controller = await import('${{ github.workspace }}/scripts/preview-controller.ts');
+            await controller.inactivate({ github, context, core });
+
+      - name: Fail if cleanup could not be verified
+        if: >-
+          always() &&
+          (steps.close.outcome != 'success' ||
+           steps.drain.outcome != 'success' ||
+           steps.host_cleanup.outcome != 'success')
         run: |
-          set -euo pipefail
-
-          if [ -z "${COOLIFY_TOKEN}" ]; then
-            echo "::notice::COOLIFY_API_TOKEN is not configured; preview cleanup must be done manually."
-            exit 0
-          fi
-
-          body=$(mktemp)
-          status=$(curl -sS -o "${body}" -w '%{http_code}' -X DELETE \
-            -H "Authorization: Bearer ${COOLIFY_TOKEN}" \
-            -H 'Accept: application/json' \
-            --retry 3 --retry-connrefused --max-time 60 \
-            "${COOLIFY_URL}/api/v1/applications/${COOLIFY_APP_UUID}/previews/${PR_NUMBER}")
-
-          if [ "${status}" -eq 404 ]; then
-            echo "::notice::PR #${PR_NUMBER} had no Coolify preview to clean up."
-            exit 0
-          fi
-          if [ "${status}" -ge 400 ]; then
-            echo "::error::Coolify preview cleanup returned HTTP ${status}: $(cat "${body}")"
-            exit 1
-          fi
-
-          echo "::notice::Deleted Coolify preview and persistent volumes for PR #${PR_NUMBER}."
+          echo "::error::Preview cleanup was not fully verified; the nightly reconciler will retry."
+          exit 1