Vercel Preview

Configure QA.tech to bypass Vercel deployment protection for automated testing

When testing Vercel preview deployments that are protected with Password Protection, Vercel Authentication, or Trusted IPs, you need to configure QA.tech to bypass these protection mechanisms. This guide shows you how to set up automated testing with Vercel’s Protection Bypass for Automation feature.

This guide is for testing protected Vercel preview deployments from CI/CD pipelines. To run QA.tech from CI, see PR Testing and Regression Testing. For Vercel Firewall / WAF rules, see Vercel Firewall.

Overview

Vercel’s Protection Bypass for Automation allows automated tools like QA.tech to access protected deployments using a special secret. This bypasses all deployment protection methods including:

• Password Protection
• Vercel Authentication
• Trusted IP restrictions

Do not put the secret in the environment URL. Store it as custom headers on the environment so the platform attaches them to matching browser, crawler, and API requests.

Setting Up Vercel Protection Bypass

Step 1: Enable Protection Bypass in Vercel

1. Navigate to Project Settings

   Go to your Vercel project dashboard and navigate to Settings → Deployment Protection

2. Enable Protection Bypass

   Find the Protection Bypass for Automation section and enable it. This will generate a secret token.

3. Copy the Secret

   Copy the generated secret - you’ll need this for configuring QA.tech

The secret is automatically added to your Vercel deployments as the environment variable VERCEL_AUTOMATION_BYPASS_SECRET. Regenerating the secret will invalidate previous deployments, requiring a redeploy to use the new value.

Step 2: Add custom headers on the environment

Add the bypass headers on the QA.tech environment that points at the protected Vercel URL:

1. Open the environment

   Go to Settings → Applications & Envs, open the application, and edit the environment (or create one for the preview URL).

2. Set the environment URL

   Use the clean preview URL only, for example https://example-vercel-protected-git-branch-qa-tech.vercel.app. Do not append bypass query parameters.

3. Add a custom header rule

   Under Custom headers, add a rule with domain pattern *.vercel.app (or your preview host pattern) and these headers:

   Name	Value
   x-vercel-protection-bypass	The secret from Step 1
   x-vercel-set-bypass-cookie	true

   Use x-vercel-set-bypass-cookie for browser tests so Vercel sets a bypass cookie for the rest of the session. For API tests, send only x-vercel-protection-bypass. Do not send x-vercel-set-bypass-cookie on API tests: the sandbox has no cookie jar, so that header loops and the request fails.

4. Save

   Save the environment. Matching hosts receive these headers on browser, crawler, and API requests.

See Environment custom headers for domain patterns and how headers are applied. Device preset custom headers are for test-scenario headers (locale, feature flags), not deployment-protection bypass.

Persist headers from CI

When you create or reuse a preview environment from GitHub Actions or the Start Run API, pass the same headers in customHeaders:

{
  "url": "https://pr-123.vercel.app",
  "name": "PR-123",
  "customHeaders": [
    {
      "domains": ["*.vercel.app"],
      "headers": {
        "x-vercel-protection-bypass": "YOUR_SECRET",
        "x-vercel-set-bypass-cookie": "true"
      }
    }
  ]
}

Passing customHeaders writes them to the environment. Omit the field to leave stored headers unchanged. Pass [] to clear them. See GitHub and Environment custom headers.

Header reference

Header	Value	When to use
x-vercel-protection-bypass	Your Protection Bypass for Automation secret	Always
x-vercel-set-bypass-cookie	true	Browser tests only