Vercel
Automatically run QA against every Vercel preview deployment and report the result as a deployment check.
The Vercel integration watches preview and production deployments via webhook. When a deployment reaches the ready state, Autonomy runs the configured test case or test plan against the preview URL and reports a pass/fail check directly on the Vercel deployment using the Checks v2 API.
What it does
- Receives a webhook on every deployment state change.
- Filters by deployment context (preview, production, or branch) and branch name.
- Runs the configured test case or test plan against the preview URL.
- Reports the result as a Vercel Checks v2 deployment check visible in the Vercel dashboard and on the GitHub pull request.
- Optionally blocks deployment promotion until the check concludes (
blocks: deployment-promotion). - Supports check re-request — clicking "Re-run" on a check in the Vercel dashboard triggers a new Autonomy run via the
deployment.check-rerequestedwebhook. - When a GitHub repository is also linked, results are posted to both the Vercel check and a GitHub check run on the commit.
Setup
Before you start
- A Vercel account or team with at least one project that produces preview deployments.
- At least one Autonomy test case that passes against a web target.
- An Autonomy environment with a web target (the base URL will be overridden by the preview URL).
- The Vercel integration must have the deployment-check scope to create and update checks.
- For self-hosted Autonomy: VERCEL_CLIENT_ID and VERCEL_CLIENT_SECRET configured on the Convex backend.
- Open Settings → Integrations in the Autonomy dashboard.
- Click Connect on the Vercel card. You are redirected to Vercel to authorize the integration.
- Select the Vercel team or personal account and grant the requested permissions. The integration requires the
deployment-checkscope. - Back in Autonomy, click Link Project. Autonomy lists the Vercel projects visible to your connected account — pick the one you want to test. A project-level check definition is created automatically at link time.
- Choose a Test Case or Test Plan as the default run target.
- Choose the Environment whose configuration (browser, viewport, runtime values) should apply.
- Under Trigger contexts, select which deployment types start a run — typically
preview. Add Branch filters if you want to limit runs to certain branches (glob patterns likemain,release/*). - If you want results reported back to Vercel, enable Report checks. Enable Block deployment promotion until check completes to hold deployment promotion until the check concludes.
- Open a pull request with a code change and confirm that a run starts when the Vercel preview is ready.
How a run is triggered
When Vercel sends a deployment.ready webhook:
- Autonomy looks up the linked project by the Vercel project ID.
- The deployment context (
preview,production, orbranch) is checked against the project's trigger contexts. - The deployment branch is checked against the project's branch filters.
- If a default test case or test plan is configured, Autonomy creates a run targeting the preview URL.
- The run uses the linked environment's configuration for browser, viewport, and runtime values.
Protected previews
If Vercel Deployment Protection is enabled, the runner cannot reach the preview URL without a bypass. To configure it:
- In the Vercel dashboard, open Settings → Deployment Protection for your project.
- Copy the Protection Bypass for Automation secret (a UUID-v4 value).
- In Autonomy, open the linked project's settings and paste the secret into Preview access secret.
Autonomy sends the secret as a x-vercel-protection-bypass header and a x-vercel-set-bypass-cookie header on every request to that project's preview URL. The secret never leaves the backend — the runner receives it as an opaque header injection.
Status reporting
Vercel is the only deploy provider with a native check surface. When Report checks is enabled:
- A project-level check definition is created when the project is linked. This definition carries the blocking policy and applies to all deployments.
- When a deployment reaches
ready, a check run is created against the definition, visible in the Vercel dashboard under the deployment's Checks tab. - When all runs complete, the check is updated to
succeeded,failed,canceled,neutral, ortimeout. - The check links back to the Autonomy evidence workspace so reviewers can inspect screenshots, traces, and step-level results.
- If the GitHub App is also installed on the repository, the same result appears as a GitHub check run on the commit.
When Block deployment promotion is enabled, Vercel holds the deployment from being promoted to production until the Autonomy check concludes. The check has a 15-minute timeout — if the run does not complete within that window, Vercel marks the check as timed out.
Check re-request
Clicking "Re-run" on a check in the Vercel dashboard sends a deployment.check-rerequested webhook. Autonomy creates a new run against the same deployment, using the current project configuration. This is useful for retrying a flaky test or re-running after a configuration change.
Monorepo and multiple projects
A single GitHub repository can be linked to multiple Vercel projects. Autonomy links each Vercel project independently — each gets its own test target, environment, trigger contexts, and branch filters.
When Vercel sends a webhook for a monorepo deployment, Autonomy matches it to the correct linked project by the Vercel project ID, not the repository. If you have three Vercel projects (web app, docs site, admin panel) in one repo, you can link all three with different test plans.
Environment variables (self-hosted)
| Variable | Required | Description |
|---|---|---|
| VERCEL_CLIENT_ID | Yes | OAuth client ID from the Vercel integration settings. |
| VERCEL_CLIENT_SECRET | Yes | OAuth client secret. Also used as the webhook signing secret for integration lifecycle events. |
| NEXT_PUBLIC_VERCEL_INTEGRATION_SLUG | Yes | The integration slug, used to build the Vercel Marketplace install URL. |
Troubleshooting
No run starts when a preview deploys
The deployment must reach the ready state. Check the following:
- The Vercel account is connected and showing Active in Autonomy.
- The Vercel project is linked. Autonomy only watches linked projects.
- The project is enabled — a disabled project records the event but skips the run (
project disabled). - The deployment context (preview/production) is in the project's trigger contexts. If not, the event is skipped with
context <x> not enabled. - The branch matches the project's branch filters. A mismatch skips with
branch <x> filtered. - A default test case or test plan is selected. Without one the event is skipped with
no default test target. - The preview URL is present in the webhook payload. A missing URL skips with
no preview URL.
The run cannot reach the preview
The preview URL is blocked by Vercel Deployment Protection. The run fails with a protection page if the bypass secret is missing or expired. Add or refresh the Preview access secret in the linked project settings.
The Vercel check shows "neutral"
A neutral conclusion means the run was skipped — typically because of a capacity or quota limit. Check the event detail in Autonomy for the skip reason.
The Vercel check shows "timeout"
The check has a 15-minute timeout. If the Autonomy run takes longer than 15 minutes to complete, Vercel marks the check as timed out. The run may still complete in Autonomy, but the Vercel check will not be updated.
Duplicate runs for the same deployment
Autonomy deduplicates by a key that includes the Vercel deployment ID and state. A redelivered webhook produces no second run. If you see duplicates, confirm that two separate Vercel projects are not both linked to the same Autonomy test target.