# Vercel

> Connect Vercel so your deploys join the change ledger next to incidents, and Ace can propose rollbacks, promotions, redeploys and firewall changes.

Source: https://tryace.dev/docs/integrations/vercel

Every Vercel deploy joins the change ledger, Ace's per-workload record of deploys and config changes. Ace uses it to tell whether an incident started right after a release, and it can roll back or promote a deployment after approval.

| | |
| --- | --- |
| Category | Deploys |
| Ace reads | Deployments, build events, projects, domains, regions, environment variables that aren't secret |
| Ace can change | Rollback, promotion, redeploy, cancel, rolling releases, Attack Challenge Mode, firewall IP blocks, environment variables that aren't secret, only after an admin allows actions |
| Opens incidents | Yes, from Vercel alerts. Deploys also join the change ledger. |
| Setup | Settings form, plus an optional Vercel deployment webhook |

## What Ace reads

While it investigates a workload with Vercel under **Investigation sources**, Ace reads:

- Recent deployments around the incident, production by default and newest first, with commit SHA, commit message, branch and creator.
- The latest build events of a deployment.

For the System Map, Ace reads projects, function regions, the live production deployment, domains and environment variables. It reads only variables that aren't marked Sensitive or secret, to find the hosts and databases they point to. It never reads or writes Sensitive or secret variables, so keep sensitive values in those.

A **Projects** allowlist limits all reads to those projects.

## What Ace can change

Ace proposes Vercel actions only after an admin turns on **Allow Ace to run approved actions** for the connection. Each one needs approval by default, and earned autonomy can let some of them run under an Automatic policy for a workload and environment you confirm. Others always need a person. See [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals).

| Action | What it does | Approval | Undo |
| --- | --- | --- | --- |
| Instant rollback | Serves a previous ready production deployment again, without a rebuild. | Approval, or Automatic under your policy | Yes. Promotes the previous deployment again. |
| Promotion | Makes a ready production deployment the one serving production, without a rebuild. | Approval, or Automatic under your policy | Yes |
| Redeploy | Rebuilds a deployment in production, preview or a custom environment. | Approval, or Automatic under your policy | Yes |
| Cancel deployment | Cancels a build that is still queued or building. | Approval, or Automatic under your policy | No |
| Rolling release abort | Aborts a rolling release with an instant rollback. | Approval, or Automatic under your policy | No |
| Rolling release stage approval | Approves the next stage of a rolling release. | Always a person | No |
| Attack Challenge Mode | Turns it on for the project for a set time (15 to 1,440 minutes, 60 by default), or off. | Always a person | Yes |
| Firewall IP block or unblock | Adds or removes a firewall IP rule. | Always a person | Yes |
| Environment variable change | Sets one variable that isn't secret to a value a person enters, then redeploys production so it takes effect. | Always a person | Yes. Restores the previous value and redeploys. |

Ace applies these safeguards:

- Rollback and promotion switch only to a ready production deployment of the same project. Before a rollback, Ace checks the code it would remove from production (through the GitHub App when connected) and can block an unsafe rollback. If production changed after approval, Ace refuses to run.
- After a rollback, Vercel stops assigning production domains to new builds on its own. When your team's next production build arrives, Ace offers to promote it on the original incident.
- Ace changes only environment variables that apply to production, aren't tied to one Git branch and aren't secret, and it never reads or writes Sensitive, secret or system variables. A person always enters the new value, and Ace keeps the previous value for undo without showing either one in the plan.
- Each rollback Ace makes carries a description in Vercel that says whether a person or your action policy approved it.

Vercel tokens have no write scopes, so actions follow the team role of the token's owner (see [Credentials and permissions](#credentials-and-permissions)).

## What opens an incident

Vercel alerts open an incident in Ace the moment they fire, on the workload that routes Vercel. Ace also polls Vercel, so new failures still open incidents if a webhook delivery is missed.

Every deploy also joins the change ledger. The deployment events Ace records are created, succeeded or ready, error or canceled, promoted, and rollback, and it adds the Git repository, branch and commit when Vercel has them. The webhook delivers every event as it happens, and Ace also polls Vercel for production deploys so they reach the ledger even without the webhook.

A deploy belongs to the workload that routes this connection or, if none does, to the workload mapped to the deployed GitHub repository. When a deploy succeeds, Ace rechecks that workload's open incidents, since the release may have fixed them.

## Before you start

- The **admin** role in Ace.
- A Vercel **Pro** or **Enterprise** team, if you want the account webhook. Without one, skip the webhook and Ace still polls for production deploys.
- For actions, a token owner whose team role allows them (see below).

## Credentials and permissions

| Credential | Where to create it | Scope or role | Why Ace needs it |
| --- | --- | --- | --- |
| Access token (needed) | **Account Settings** > **Tokens** | Scope: the team, then All Projects or a single project | Read deployments, build events and projects. Vercel tokens can't be read-only, so the scope is the limit. |
| Same token (only for deploy actions) | Same | Owner, Member, or Developer with Full Production Deployment | Rollback, promotion, redeploy, cancel, rolling releases and environment variable changes. |
| Same token (only for firewall actions) | Same | Owner, Member or Security | Attack Challenge Mode and firewall IP rules. |
| Webhook secret (only for the webhook) | Team **Settings** > **Webhooks**, in the Webhook Created dialog | None | Verifies that deliveries come from Vercel. Vercel shows it only once. |

If you enter a **Team ID**, Ace reads the token owner's team role and shows which actions it allows. For other roles, or without a Team ID, Settings shows that the permission is checked when the action runs.

## Set up

### 1. Create a token in Vercel

1. Select your personal account and open **Account Settings** > **Tokens**.
2. Name the token Ace. Under **Scope**, pick the team, then All Projects or a single project.
3. Choose an expiration, create the token and copy it.

### 2. Connect Vercel in Ace

1. Open **Settings** > **Data sources** and choose **Vercel**.
2. Fill in the form:

   | Field | What to enter |
   | --- | --- |
   | **Access token** | The token you created. |
   | **Team ID** | Only for a Full Account token. Find it under team **Settings** > **General** > **Team ID**. A team- or project-scoped token carries its team. |
   | **Projects** | Optional. A comma-separated allowlist of project IDs. |

3. Select **Connect Vercel**. Ace checks that it can read your projects before it saves.

### 3. Add the deployment webhook

1. Copy the webhook URL Ace shows.
2. In Vercel, open team **Settings** > **Webhooks** and select the Deployment events: Created, Succeeded, Error, Promoted and Rollback.
3. Choose the projects, paste the URL as the endpoint and select **Create Webhook**.
4. Copy the secret from the Webhook Created dialog, paste it into Ace and select **Save**.

### 4. Optional: allow actions

Turn on **Allow Ace to run approved actions**. To let actions earn Automatic, confirm their workload and environment on the same panel.

## Confirm it's working

- The connection's checks show how many projects the token can see and name any allowlisted project it can't see.
- The webhook badge shows **Not set up**, **Waiting for first event**, **Verified** or **Last delivery failed**. Trigger a deployment, and the badge turns **Verified** when the first signed delivery arrives.
- New production deploys appear on the workload's timeline in Ace within a few minutes, even without the webhook.

## Disconnect

1. In Ace, open the Vercel connection under **Settings** > **Data sources** and select **Disconnect**. To keep reading deploys and stop actions, turn off **Allow Ace to run approved actions** instead.
2. In Vercel, delete the Ace token under **Account Settings** > **Tokens** and the webhook under team **Settings** > **Webhooks**. Ace creates nothing else in Vercel.

## Next steps

- [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals)
- [GitHub](https://tryace.dev/docs/integrations/github)
- [All integrations](https://tryace.dev/docs/integrations)