feat: add Vercel automation bypass for protected CMS previews

Author: jhb-dev

.github/workflows/deploy.yml

@@ -16,10 +16,7 @@
 #
 # Prerequisites:
 # - Disable automatic Vercel deployments for both projects to avoid race conditions
-# - Disable Vercel Authentication for CMS preview deployments (Settings → Deployment Protection)
-#
-# TODO: Migrate to using VERCEL_AUTOMATION_BYPASS_SECRET instead of disabling authentication.
-# This would require passing the bypass header in getRedirects.ts and the PayloadSDK.
+# - Set up CMS_VERCEL_AUTOMATION_BYPASS_SECRET to allow Web builds to fetch from protected CMS previews
 
 name: Deploy
 
@@ -169,9 +166,10 @@ jobs:
           if [ "$IS_PROD" == "true" ]; then
             DEPLOYMENT_URL=$(vercel deploy --prod --yes --token=${{ secrets.VERCEL_TOKEN }})
           elif [ -n "$CMS_URL" ]; then
-            # Preview with CMS preview URL
+            # Preview with CMS preview URL and bypass secret for Vercel Authentication
             DEPLOYMENT_URL=$(vercel deploy --yes --token=${{ secrets.VERCEL_TOKEN }} \
               --build-env CMS_URL=$CMS_URL \
+              --build-env CMS_VERCEL_AUTOMATION_BYPASS_SECRET=${{ secrets.CMS_VERCEL_AUTOMATION_BYPASS_SECRET }} \
               --env CMS_URL=$CMS_URL)
           else
             # Preview without CMS override (uses production CMS from Vercel env vars)

README.md

@@ -51,6 +51,7 @@ Example: `fix(web): update styles [skip-cms]`
 | `VERCEL_ORG_ID` | Vercel Team ID (Settings → General) |
 | `VERCEL_CMS_PROJECT_ID` | CMS project ID (Project Settings → General) |
 | `VERCEL_WEB_PROJECT_ID` | Web project ID (Project Settings → General) |
+| `CMS_VERCEL_AUTOMATION_BYPASS_SECRET` | CMS bypass secret for preview builds (see below) |
 
 ### Preview Deployments
 
@@ -59,6 +60,13 @@ For pull requests, the workflow:
 2. Deploys Web to a preview URL, configured to use the CMS preview URL
 3. Posts a comment on the PR with both preview URLs
 
-**Note:** Disable Vercel Authentication for CMS preview deployments to allow the Web build to fetch data:
-- Go to **Vercel Dashboard** → **CMS Project** → **Settings** → **Deployment Protection**
-- Set Vercel Authentication to **Disabled** or **Only Production**
+#### CMS Authentication Bypass
+
+To allow the Web build to fetch data from protected CMS preview deployments:
+
+1. Go to **Vercel Dashboard** → **CMS Project** → **Settings** → **Deployment Protection**
+2. Enable **Vercel Authentication** (requires Pro plan with Advanced Deployment Protection)
+3. Copy the **Protection Bypass for Automation** secret
+4. Add it as `CMS_VERCEL_AUTOMATION_BYPASS_SECRET` in GitHub repository secrets
+
+This allows the Web build to authenticate with the CMS preview while keeping it protected from public access.

web/astro.config.mjs

@@ -28,6 +28,11 @@ export default defineConfig({
         context: 'server',
         access: 'public',
       }),
+      CMS_VERCEL_AUTOMATION_BYPASS_SECRET: envField.string({
+        context: 'server',
+        access: 'secret',
+        optional: true,
+      }),
     },
   },
 })

web/src/cms/getRedirects.ts

@@ -2,13 +2,17 @@ import { PayloadSDK } from '@payloadcms/sdk'
 import type { RedirectConfig } from 'astro'
 import type { Config } from 'cms/src/payload-types'
 import 'dotenv/config'
+import { addBypassHeader } from './sdk/bypassHeader'
 
 /** Fetches the redirects from the CMS and converts them to the Astro `RedirectConfig` format. */
 export async function getRedirects(): Promise<Record<string, RedirectConfig>> {
   // Because import.meta.env and astro:env is not available in Astro config files and this method is called from
   // the Astro config file, use process.env to access the environment variable instead.
+  const bypassSecret = process.env.CMS_VERCEL_AUTOMATION_BYPASS_SECRET
+
   const payloadSDK = new PayloadSDK<Config>({
     baseURL: process.env.CMS_URL! + '/api',
+    fetch: (input, init) => fetch(input, addBypassHeader(init, bypassSecret)),
   })
 
   const redirectsCms = await payloadSDK.find({

web/src/cms/sdk/bypassHeader.ts

@@ -0,0 +1,20 @@
+/**
+ * Adds the Vercel automation bypass header to a request if the secret is configured.
+ * This allows fetching from CMS preview deployments that have Vercel Authentication enabled.
+ */
+export function addBypassHeader(
+  init: RequestInit | undefined,
+  bypassSecret: string | undefined,
+): RequestInit {
+  if (!bypassSecret) {
+    return init ?? {}
+  }
+
+  const headers = new Headers(init?.headers)
+  headers.set('x-vercel-protection-bypass', bypassSecret)
+
+  return {
+    ...init,
+    headers,
+  }
+}

web/src/cms/sdk/cachedFetch.ts

@@ -1,3 +1,5 @@
+import { CMS_VERCEL_AUTOMATION_BYPASS_SECRET } from 'astro:env/server'
+import { addBypassHeader } from './bypassHeader'
 import { cache } from './cache'
 
 /**
@@ -20,6 +22,8 @@ export function createCachedFetch(baseFetch: typeof fetch): typeof fetch {
     input: RequestInfo | URL,
     init?: RequestInit,
   ): Promise<Response> {
+    // Add bypass header for Vercel Authentication
+    const initWithBypass = addBypassHeader(init, CMS_VERCEL_AUTOMATION_BYPASS_SECRET)
     // Convert input to URL string for caching
     const url =
       typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url
@@ -55,7 +59,7 @@ export function createCachedFetch(baseFetch: typeof fetch): typeof fetch {
       }
 
       // Make the actual request
-      const response = await baseFetch(input, init)
+      const response = await baseFetch(input, initWithBypass)
 
       if (response.ok) {
         // Clone the response so we can read it and still return it
@@ -72,6 +76,6 @@ export function createCachedFetch(baseFetch: typeof fetch): typeof fetch {
     }
 
     // For non-GET requests or when cache is not explicitly enabled, just forward the request
-    return baseFetch(input, init)
+    return baseFetch(input, initWithBypass)
   }
 }