ci: build and deploy pull request previews from CI (#82)

* ci: build pull request previews as artifacts

The site job already builds the site; hand that build and a browser build of
the desktop app to the deploy workflow as artifacts, only for pull requests.
CI jobs only read the checkout, so make that explicit.

* ci: deploy pull request previews from a trusted workflow

Publish the CI artifacts of every pull request, forks included, to the
modrex-app-pr and modrex-site-pr Pages projects with Direct Upload, and record
the outcome as preview/app and preview/site commit statuses. The workflow runs
the default-branch code with the Cloudflare token and never checks out or
executes the pull request.

The static preview comment moves here from the preview-link workflow.

* feat(preview): resolve /pr/<N> from commit statuses

Read the preview/app and preview/site statuses of the pull request's head
commit instead of parsing Cloudflare check-run HTML. The app host keeps
proxying the deployed alias; site-preview.modrex.net redirects to it. Every
other state renders a small page: building (with refresh), build failed with
its logs, no preview, or pull request not found.

* docs(preview): describe the site preview and the /pr/ states

Author: ShulhaOleh

.github/workflows/ci.yml

@@ -14,6 +14,9 @@ on:
             - '.gitignore'
             - 'LICENSE'
 
+permissions:
+    contents: read
+
 jobs:
     index:
         runs-on: ubuntu-latest
@@ -51,6 +54,42 @@ jobs:
             - run: pnpm site:test
             - run: pnpm site:build
 
+            # Consumed by preview-deploy.yml. Function tests would become routes, so they stay out.
+            - name: Stage the site preview
+              if: github.event_name == 'pull_request'
+              run: |
+                  mkdir -p preview/site/functions
+                  cp -R apps/site/dist preview/site/dist
+                  (cd apps/site/functions && find . -name '*.ts' ! -name '*.test.ts' -exec cp --parents {} ../../../preview/site/functions/ \;)
+            - uses: actions/upload-artifact@v7
+              if: github.event_name == 'pull_request'
+              with:
+                  name: site-preview
+                  path: preview/site
+                  retention-days: 3
+                  if-no-files-found: error
+
+    app-preview:
+        if: github.event_name == 'pull_request'
+        runs-on: ubuntu-latest
+        timeout-minutes: 15
+        steps:
+            - uses: actions/checkout@v7
+
+            - uses: pnpm/action-setup@v6
+            - uses: actions/setup-node@v7
+              with:
+                  node-version: 22
+                  cache: pnpm
+            - run: pnpm install --frozen-lockfile
+            - run: pnpm --filter modrex build-preview
+            - uses: actions/upload-artifact@v7
+              with:
+                  name: app-preview
+                  path: apps/desktop/out/preview
+                  retention-days: 3
+                  if-no-files-found: error
+
     test:
         runs-on: ubuntu-latest
         steps:

.github/workflows/preview-deploy.yml

@@ -0,0 +1,126 @@
+name: Preview deploy
+
+# Runs default-branch code with the deploy token; the CI artifacts are the only PR input.
+on:
+    workflow_run:
+        workflows: [CI]
+        types: [requested, completed]
+
+permissions: {}
+
+concurrency:
+    group: preview-${{ github.event.workflow_run.head_sha }}
+
+jobs:
+    preview:
+        if: github.event.workflow_run.event == 'pull_request'
+        runs-on: ubuntu-latest
+        timeout-minutes: 15
+        permissions:
+            actions: read
+            pull-requests: write
+            statuses: write
+        env:
+            GH_TOKEN: ${{ github.token }}
+            GH_REPO: ${{ github.repository }}
+            SHA: ${{ github.event.workflow_run.head_sha }}
+            CI_URL: ${{ github.event.workflow_run.html_url }}
+        steps:
+            - name: Resolve pull request
+              id: pr
+              run: |
+                  number=$(gh api "repos/$GITHUB_REPOSITORY/commits/$SHA/pulls" \
+                    --jq "[.[] | select(.state == \"open\" and .head.sha == \"$SHA\")][0].number // empty")
+                  echo "number=$number" >> "$GITHUB_OUTPUT"
+                  [ -n "$number" ] || echo "$SHA is not the head of an open pull request; nothing to do."
+
+            - name: Mark previews pending
+              if: steps.pr.outputs.number && github.event.action == 'requested'
+              env:
+                  PR: ${{ steps.pr.outputs.number }}
+              run: |
+                  for name in app site; do
+                    gh api "repos/$GITHUB_REPOSITORY/statuses/$SHA" --silent \
+                      -f context="preview/$name" -f state=pending -f description=Building -f target_url="$CI_URL"
+                  done
+
+                  marker='<!-- modrex-preview -->'
+                  found=$(gh api "repos/$GITHUB_REPOSITORY/issues/$PR/comments?per_page=100" \
+                    --jq "[.[] | select(.body | startswith(\"$marker\"))] | length")
+                  [ "$found" = 0 ] || exit 0
+                  gh pr comment "$PR" --body-file - <<EOF
+                  $marker
+                  ## Deploying Modrex previews with &nbsp;<a href="https://pages.dev"><img alt="Cloudflare Pages" src="https://user-images.githubusercontent.com/23264/106598434-9e719e00-654f-11eb-9e59-6167043cfa01.png" width="16"></a> &nbsp;Cloudflare Pages
+
+                  <table>
+                  <tr><td><strong>App preview:</strong></td><td><a href="https://app-preview.modrex.net/pr/$PR">https://app-preview.modrex.net/pr/$PR</a></td></tr>
+                  <tr><td><strong>Site preview:</strong></td><td><a href="https://site-preview.modrex.net/pr/$PR">https://site-preview.modrex.net/pr/$PR</a></td></tr>
+                  </table>
+
+                  View logs: [app](https://dash.cloudflare.com/?to=/:account/pages/view/modrex-app-pr) | [site](https://dash.cloudflare.com/?to=/:account/pages/view/modrex-site-pr)
+                  EOF
+
+            - uses: actions/download-artifact@v8
+              if: steps.pr.outputs.number && github.event.action == 'completed'
+              id: app
+              continue-on-error: true
+              with:
+                  name: app-preview
+                  path: app
+                  run-id: ${{ github.event.workflow_run.id }}
+                  github-token: ${{ github.token }}
+
+            - uses: actions/download-artifact@v8
+              if: steps.pr.outputs.number && github.event.action == 'completed'
+              id: site
+              continue-on-error: true
+              with:
+                  name: site-preview
+                  path: site
+                  run-id: ${{ github.event.workflow_run.id }}
+                  github-token: ${{ github.token }}
+
+            - name: Deploy previews
+              if: steps.pr.outputs.number && github.event.action == 'completed'
+              env:
+                  PR: ${{ steps.pr.outputs.number }}
+                  CI_CONCLUSION: ${{ github.event.workflow_run.conclusion }}
+                  APP_ARTIFACT: ${{ steps.app.outcome }}
+                  SITE_ARTIFACT: ${{ steps.site.outcome }}
+                  CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+                  CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+              run: |
+                  run_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+                  status() {
+                    gh api "repos/$GITHUB_REPOSITORY/statuses/$SHA" --silent \
+                      -f context="preview/$1" -f state="$2" -f description="$3" -f target_url="$4"
+                  }
+
+                  if [ -z "$CLOUDFLARE_API_TOKEN" ]; then
+                    for name in app site; do status "$name" error "Preview deploys are not configured" "$run_url"; done
+                    exit 0
+                  fi
+                  case "$CI_CONCLUSION" in
+                    success|failure) ;;
+                    *) for name in app site; do status "$name" error "CI $CI_CONCLUSION" "$CI_URL"; done; exit 0 ;;
+                  esac
+
+                  failed=0
+                  deploy() {
+                    local name=$1 artifact=$2 dir=$3 assets=$4 project=$5
+                    if [ "$artifact" != success ]; then
+                      status "$name" failure "CI produced no preview" "$CI_URL"
+                      failed=1
+                      return
+                    fi
+                    if (cd "$dir" && npx -y wrangler@4.135.0 pages deploy "$assets" \
+                          --project-name "$project" --branch "pr-$PR" --commit-hash "$SHA" --commit-dirty=true); then
+                      status "$name" success Ready "https://pr-$PR.$project.pages.dev"
+                    else
+                      status "$name" failure "Deploy failed" "$run_url"
+                      failed=1
+                    fi
+                  }
+                  deploy app "$APP_ARTIFACT" app . modrex-app-pr
+                  deploy site "$SITE_ARTIFACT" site dist modrex-site-pr
+                  exit $failed

.github/workflows/preview-link.yml

@@ -36,12 +36,13 @@ Every pull request has a number next to its title on GitHub. Put that number aft
 `https://app-preview.modrex.net/pr/<pull-request-number>`
 
 The `/pr/` address belongs to the pull request, not to one commit. Keep using the same address
-while the pull request is open. After a new commit is pushed and Cloudflare finishes the next
-deployment, the same address opens the updated version.
+while the pull request is open. After a new commit is pushed and its preview is built, the same
+address opens the updated version. While the build runs the address shows **Building**, and it
+says so if the build failed or no preview exists for the latest commit.
 
-The Cloudflare bot comments on the pull request when a deployment is ready. Its **Preview URL**
-keeps the version from one commit. Its **Branch Preview URL** updates with the pull request. The
-Modrex `/pr/` address is the readable link to share for ongoing review.
+A comment on every pull request lists this address together with the site preview at
+`https://site-preview.modrex.net/pr/<pull-request-number>`, which opens the same commit of
+modrex.net.
 
 Preview state parameters also work after the pull request number: