Deploy a Cloudflare Pages preview for pull requests (#498)

Pull requests now get a Cloudflare Pages preview deployment after the site build succeeds, and the preview URL is written back as the last line of the pull request description.

- `concurrency` cancels the previous preview build when a pull request is pushed again.
- After `make build`, the workflow copies `cloudflare/_headers` into `build/` (same as the production deployment, so the file is never published to S3/CloudFront) and runs `wrangler pages deploy build --project-name docs-gitea-com --branch pr-<number>`, then extracts the `*.pages.dev` URL from the wrangler output.

Notes:
- Pull requests from forks do not receive the secrets, in that case the preview steps are skipped with a log message and the build check still runs.
- Requires `CLOUDFLARE_ACCOUNT_ID` / `CLOUDFLARE_API_TOKEN` (Pages edit permission) and `DEPLOY_TOKEN` (pull request write permission).

<!-- cloudflare-preview --> Preview: https://pr-498.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/498
Reviewed-by: Zettat123 <[email protected]>

.gitea/workflows/test.yaml

@@ -3,6 +3,11 @@ name: checks
 on:
   - pull_request
 
+# a new push to the same pull request replaces the running preview build
+concurrency:
+  group: checks-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
   build-docs:
     runs-on: ubuntu-latest
@@ -23,3 +28,69 @@ jobs:
       - name: build site
         run: |
           make build
+      - name: deploy the preview to Cloudflare Pages
+        id: preview
+        env:
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+
+          # pull requests from forks do not get the secrets, the build above is
+          # then the only check and the preview is silently skipped
+          if [ -z "${CLOUDFLARE_API_TOKEN:-}" ] || [ -z "${CLOUDFLARE_ACCOUNT_ID:-}" ]; then
+            echo "no Cloudflare credentials available, skipping the preview deployment"
+            exit 0
+          fi
+
+          # same as the production deployment: _headers only belongs to the
+          # Cloudflare Pages output, so it is copied in right before uploading
+          cp cloudflare/_headers build/_headers
+
+          pnpm dlx wrangler@4 pages deploy build \
+            --project-name docs-gitea-com \
+            --branch "pr-$PR_NUMBER" | tee wrangler.log
+
+          url="$(grep -Eo 'https://[A-Za-z0-9.-]+\.pages\.dev' wrangler.log | tail -n 1)"
+          if [ -z "$url" ]; then
+            echo "could not read the preview URL from the wrangler output"
+            exit 1
+          fi
+          echo "url=$url" >> "$GITHUB_OUTPUT"
+      - name: update the pull request with the preview URL
+        if: steps.preview.outputs.url != ''
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+          PREVIEW_URL: ${{ steps.preview.outputs.url }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+
+          if [ -z "${DEPLOY_TOKEN:-}" ]; then
+            echo "secrets.DEPLOY_TOKEN is missing, the preview is at $PREVIEW_URL"
+            exit 0
+          fi
+
+          api="${GITHUB_API_URL:-$GITHUB_SERVER_URL/api/v1}/repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER"
+          curl --silent --show-error --fail --output pull.json \
+            -H "Authorization: token $DEPLOY_TOKEN" "$api"
+
+          marker='<!-- cloudflare-preview -->'
+          # drop the line written by an earlier run, so the URL is updated in
+          # place instead of piling up at the end of the description
+          body="$(jq -r '.body // ""' pull.json | grep -vF "$marker" || true)"
+          body="$(printf '%s\n' "$body" | sed -e :a -e '/^\n*$/{$d;N;ba' -e '}')"
+          if [ -n "$body" ]; then
+            body="$(printf '%s\n\n%s Preview: %s\n' "$body" "$marker" "$PREVIEW_URL")"
+          else
+            body="$(printf '%s Preview: %s\n' "$marker" "$PREVIEW_URL")"
+          fi
+
+          jq -n --arg body "$body" '{body: $body}' > patch.json
+          curl --silent --show-error --fail --output /dev/null \
+            -X PATCH "$api" \
+            -H "Authorization: token $DEPLOY_TOKEN" \
+            -H 'Content-Type: application/json' \
+            --data @patch.json
+          echo "the pull request now points at $PREVIEW_URL"