Skip to main content
Atoll records Vercel deployments as External References in project and task Context. The integration reads provider data. It does not deploy, promote, roll back, move tasks, or mark work accepted.

​
Connect a team and project

You need a signed-in workspace owner or admin, a verified repository from the read-only GitHub App, a Vercel team API token, and permission to create a Vercel account webhook. Vercel account webhooks require its Pro or Enterprise plan. The Atoll operator must configure a server-only VERCEL_DEPLOYMENT_SECRET_KEY of at least 32 characters before credentials can be saved. Keep this key stable: changing it makes existing credentials unreadable until the connections are configured again.
  1. Open Settings > Integrations > Vercel deployments > Connect Vercel.
  2. Copy the proposed Webhook URL. It uses https://atollhq.com/api/webhooks/vercel/{connectionId} and stays inactive until you save.
  3. In Vercel, create an account webhook for the selected team and project with that URL. Select deployment.created, deployment.ready, deployment.succeeded, deployment.error, deployment.canceled, and deployment.promoted. Copy the once-visible signing secret.
  4. Enter the Vercel team and project IDs. Select the Atoll project and its verified GitHub repository. Enter the API token and webhook secret, then select Validate and save.
  5. Check the saved mapping and health state. Select Reconcile deployments to inspect recent deployments that predate the webhook.
Atoll verifies the Vercel project’s immutable numeric GitHub repository ID against the selected verified repository. Names, branches, webhook metadata, and URLs do not establish lineage. Tokens and webhook secrets are encrypted with organization, connection, and purpose binding. Settings never returns them. Atoll makes only authenticated GET requests to Vercel; scope the token to the required team and use the least provider access available. An organization supports at most 50 team connections, including disabled connections. At that limit, reconnect an existing connection; adding another team returns connection_limit. A team connection supports at most 20 project mappings. Use Add mapping or Edit mapping and enter both credentials again. In Vercel, add every mapped project to the existing webhook’s project scope (or use its all-projects scope). Keep the same callback URL and signing secret for this team connection. Atoll does not update webhook scope in Vercel. Editing the Atoll project or repository does not change that scope. Mapping removal is not available in this slice; to stop all ingestion, disable the connection and then its Vercel webhook. Once a mapping has observations, its Atoll project and repository cannot change. A concurrent credential or mapping edit returns configuration_changed; reload the settings before another attempt.

​
Read deployment evidence

Each deployment has one current card and immutable observation history. Cards show preview, staging, or production, the effective state, an exact revision when proven, provider time, and when Atoll observed the evidence. The inspector link comes from Vercel and opens its dashboard. Atoll always links a deployment to its mapped project. It links a task only when exactly one unarchived task in that project has a PR link with the same numeric repository ID and exact 40-character SHA. An older deployed SHA stays project evidence unless it matches such a task. Missing identity shows Revision unavailable; conflicting repository identity stays project-only. A later complete identity can resolve missing identity without changing deployment state. Missing fields do not erase known proof. A contradictory known repository or SHA rejects the observation without changing history or current state. Partial observations never combine into a complete identity proof. Preview and staging supersession use ready deployments within the same mapping and environment. Production supersession uses the latest successfully observed authenticated Vercel project production target. A rollback can make an older build current again. A staged production deployment is not proof of current traffic, and a deployment that once had production traffic is not necessarily current now. Unknown production targets do not clear the last known pointer. Rolling releases and unsupported custom environments are not projected by this integration. Provider time is the signed webhook event time or a documented state-specific Vercel timestamp. Atoll’s snapshot time is used only to reject late responses; it is not a provider revision or promotion time. A delayed preview event cannot rewrite the current environment as preview after a newer authenticated production snapshot. Deployment ready, PR merged, application deployed, Production Testing, and human acceptance are separate facts. This integration changes none of the other stages. Reconcile deployments reads one page of at most 50 deployments per mapping and environment. If a rollback target is older than that page, recovery also reads that one current production target. The maximum is 151 deployments per mapping. This extra read does not clear history truncation. It checks each discovered deployment through the same canonical identity and projection path as webhooks. The result reports discovered, ingested, skipped, failed, truncated, and safe codes. skipped includes an unchanged replay or work deferred by the request time budget. It does not follow pagination and does not claim complete history. Any failed, truncated, unsupported, or unresolved result sets complete=false. A project without a known production target also reports incomplete. Disable clears stored credentials and marks the connection’s evidence unavailable. It preserves history. Reconnect requires fresh credentials and successful validation. Disable the webhook in Vercel separately if you also want its deliveries to stop. Unlink removes only the selected task or project association. It does not delete the canonical deployment or suppress future updates. A later verified update can restore the association. Agents can use the existing external-reference list|get CLI commands and atoll_list_external_references / atoll_get_external_reference MCP tools. Manual link remains GitHub-pull-request-only. Vercel connection setup, disable, and recovery are owner/admin Settings actions; typed CLI/MCP parity for safe management operations is deferred while the public tool surface is frozen (follow-up AH-3061). See API fields and webhook responses.