Site protection for QA

Some deployments sit behind a gate that loads before your app does: a Vercel preview protection page, HTTP Basic Auth on a staging host, or a WAF that only lets through requests carrying a specific header. Matcha QA can't test what it can't reach, so Site protection lets you hand Matcha the credential that unlocks the deployment.

This is different from a test account (the run-as identity Matcha signs in with inside your app). Site protection unlocks the door; a test account walks through it. You can use both together.

Configure one method per project, from the Site protection button on the Matcha QA screen. Matcha also sends X-Coldtea-QA: true on protected requests so your app or WAF can recognize and allowlist test traffic (define a custom header with that name to override the value).

Vercel protection bypass

Use this when your preview URLs are gated by Vercel Deployment Protection (you hit a Vercel login/authentication page instead of your app).

Where to get the secret: in the Vercel dashboard, open your project → Settings → Deployment Protection → Protection Bypass for Automation → Add Secret (or copy the existing one). It's a long random string.

Paste that string into the Vercel protection bypass field. On the first request to the deployment host, Matcha sends it as x-vercel-protection-bypass; Vercel then sets a first-party bypass cookie so the rest of the run stays authenticated. The secret is only ever sent to the deployment host in the run's target URL.

HTTP Basic Auth

Use this when the host shows a browser username/password prompt before your app loads (the classic 401 Basic Auth dialog on a staging site).

Enter the username and password your host expects. Matcha sends them as an Authorization: Basic header to unlock the site. This is site-level protection only — if your app has its own login form, use a test account for that.

Custom headers

Use this for anything header-based: a WAF bypass policy, a Cloudflare Access service-token header, or a "this is test traffic" tag your backend recognizes.

Add one or more header name/value pairs. Matcha sends them (host-scoped) on every request to the target host. Header names must be valid HTTP tokens; values can't contain line breaks.

How it stays safe

• Encrypted at rest. Secrets are encrypted with a dedicated key and are never returned to the UI — you'll see only the last four characters, and re-enter a secret to replace it.
• Host-scoped. The credential is sent only to the host of the run's target URL. Requests to third-party hosts — OAuth providers, CDNs, analytics — never receive it.
• Never in URLs or logs. The secret rides in request headers, not the target URL, and is never written to run logs or the report.

Set it up

1. Open the Matcha QA screen for your project and click Site protection.
2. Pick a method and enter its credential (each method links here for details).
3. Save. It applies automatically to every run for that project — manual, scheduled, and PR-triggered.
4. Start a run against the protected URL. If it loads the app instead of the protection wall, you're set.

Notes and limits

• The target URL's host must be the protected host. If you test a custom domain but the deployment is served from a different host (or a cross-host redirect), the bypass cookie may not apply — point the run at the protected host.
• If your app itself reads the Authorization header, prefer Custom headers over HTTP Basic Auth so the two don't collide.
• Site protection applies to web runs. Mobile app runs don't pass through these deployment gates.