Vercel

The Vercel adapter deploys web.frontend resources as Vercel projects connected to a Git repository, through the Vercel REST API. There is no OpenTofu and no state store: the Vercel project itself is the state.

A typical mix is a Next.js frontend on Vercel, PostgreSQL on Supabase and files on AWS S3. See mixing providers.

What OrkStage createsCopy Anchor Link

Each deployment converges the project, keyed by the resource name (the Vercel project name):

1. Creates the project (framework, repository, build, install and output settings, root directory, function region, preview deployments) or patches the settings that differ.
2. Writes environment variables for the production and preview environments. Template environment values and dependency connection settings (<ID>_HOST, <ID>_PORT, <ID>_URL and so on) are stored as encrypted. Dependency credentials (<ID>_PASSWORD, <ID>_URL with credentials and so on) are stored as sensitive, which Vercel never shows again. Managed variables removed from the template are deleted; variables you add by hand are left alone.
3. Attaches missing custom domains.
4. Starts a production deployment of the template branch when anything changed or the project has never been deployed. A repeat with nothing to change makes no writes.

Outputs: kind, project_id, url (first custom domain, else the vercel.app domain), dashboard_url, framework, branch, health_check_path.

Health combines the latest production deployment (READY is healthy, building or queued is degraded, ERROR is unhealthy) with an HTTP check of url plus healthCheckPath. Logs are the build and runtime events of the latest production deployment, redacted.

Target configurationCopy Anchor Link

Credential secretCopy Anchor Link

Create an access token under Account settings, Tokens:

1. Scope: the team that will own the projects, or your personal account when the target has no teamId. A token scoped to another team fails validation.
2. Expiration: pick one that matches your rotation policy. Validation reports an expired token.

The secret behind credentialRef is the bare token or a JSON object:

{ "token": "<vercel access token>" }

The token never leaves the control plane process. It is sent only as the Authorization header to api.vercel.com and is scrubbed from every error message.

Validation checks the team id format, the region, the token and project access. The identity shown is the team slug or the username.

Connect the Git repositoryCopy Anchor Link

Vercel builds from Git, so it must be able to read the repository before the first deployment:

• GitHub: install the Vercel GitHub app on the organization or account that owns the repository and grant it access to that repository. For a team target, connect the app from the Vercel team (Team settings, Git).
• GitLab or Bitbucket: connect the provider in the Vercel account settings with access to the repository.

When Vercel cannot read the repository, the deployment fails with VERCEL_GIT_NOT_CONNECTED and a message naming the repository and what to install.

RegionsCopy Anchor Link

Regions are Vercel Functions regions: arn1, bom1, cdg1, cle1, cpt1, dub1, fra1, gru1, hkg1, hnd1, iad1, icn1, kix1, lhr1, pdx1, sfo1, sin1, syd1, yul1.

The placement region becomes the project's function region. Put it next to the database, for example gru1 for a Supabase project in sa-east-1 or iad1 for us-east-1. Static assets are served from the edge network everywhere.

Actions for triggersCopy Anchor Link

triggers:
  - name: redeploy-site
    description: Rebuild the site after content changes
    resource: site
    action: redeploy
    params: { target: production }
    overridable: [ref]
    on: { manual: true, webhook: true }
  - name: nightly-purge
    resource: site
    action: purge-cache
    on: { schedule: "0 3 * * *" }

CostCopy Anchor Link

The estimate shows 0 per project. Vercel bills per team seat (Pro is about 20 USD per member per month) plus usage above the plan allowance, never per project.

Known limitsCopy Anchor Link

• The production branch follows the repository default branch. The REST API cannot change it, so set it in the project settings (Git) when the template uses another branch. Deployments started by OrkStage always build the template branch.
• Turning preview deployments off is sent at creation and with any later settings change. The API does not report the current value, so toggling it alone on an existing project waits for the next change.
• Custom domains are attached but not removed, and their DNS records are managed outside OrkStage. A domain used by another Vercel project fails with a conflict.
• Rotating the access token rewrites the managed variables once and starts one deployment.
• Deployments are started, not awaited. Health reports the build as degraded until it is ready.
• purge-cache with * relies on the project wide tag. Purges by tag need responses tagged with Vercel-Cache-Tag.
• GitLab and Bitbucket deployments use the project's Git link, so the repository must be connected when the project is created.