# Connect Vercel

> Watch Vercel deployments, stuck builds and project domains. A failed build reaches your Mac's notch with its error, and the alert shows the failing step and the end of the build log.

Source: https://coisland.app/docs/connect-vercel/

## What you need

- **You need:** Access token, from Account Settings › Tokens (https://vercel.com/account/tokens)
- **The form asks:** Connector name, Access token
- **You can watch:** Deployments, Stuck builds, Domain problems
- **Access:** GET requests only; a Vercel token itself cannot be read-only

CoIsland calls Vercel's REST API straight from your Mac: there is no CoIsland server and no CoIsland account. The token stays in your login Keychain, and every request the Vercel connector sends is a `GET`. Vercel tokens have no read-only setting, so a token can do whatever its scope reaches; keep the scope as narrow as what you watch.

## Create a Vercel access token

1. In the Vercel dashboard, make sure the scope selector at the top left shows your **personal account**, then open **Account Settings › Tokens** (`vercel.com/account/tokens`).
2. **Token name:** one you will recognize, such as `CoIsland`.
3. **Scope:** the narrowest one that covers what you will watch (see the table below).
4. **Expiration:** pick one, then **Create**. CoIsland's **Test connector** shows the expiry, and every monitor card warns in its last week.
5. Copy the token. It starts with `vcp_` and Vercel shows it only once.

| Scope | What CoIsland can watch | `team:` in a monitor |
|---|---|---|
| Full Account | Your own projects and every team you belong to | Optional: without it, your default team |
| A team, All Projects | Every project of that team | Leave it out: Vercel infers the team |
| A team, then one project | That project only | Leave it out; name only that project |

A project-scoped token cannot read your user or your teams, so **Test connector** says "Project-scoped token" and names its project, and the Team menu in the editors falls back to a text field.

### When your team blocks the token

- **Two-factor authentication enforced:** a team can require 2FA, and then tokens of members without it stop working. CoIsland says "The team requires two-factor authentication; enable it on your Vercel account." Enable 2FA, then create the token again.
- **SAML single sign-on enforced** (Enterprise, or Pro with the SAML add-on): the team only accepts a token created after signing in through its identity provider. CoIsland says "The team requires SAML single sign-on: sign in to Vercel through SSO, then create the token again."
- A team owner cannot edit or delete your personal token, and there is no approval step: a token scoped to your own Hobby team always works.

## Connect Vercel in CoIsland

1. Open **Settings › Connectors** and click **+** (Add Connector).
2. Choose **Vercel**, fill in the two fields, then click **Test connector**.
3. Click **Add Connector**.

| Field | What to enter |
|---|---|
| Connector name | What monitors call it: letters, digits, `_` and `-`, starting with a letter. CoIsland suggests `vercel` |
| Access token | The token you copied, with no spaces or line breaks |

**Test connector** calls `GET /v5/user/tokens/current` and `GET /v2/user` and saves nothing. It shows your username and email, the token's scope, its expiry (or that it never expires), and a warning when Vercel has marked the token as leaked.

**Add Connector** keeps the connector's name in `~/Library/Application Support/CoIsland/connectors.json` and the token in your login Keychain, never in a file.

## Watch Vercel: the three monitor kinds

Open **Settings › Monitors**, click **+** (New Monitor) and choose **Vercel**. Every editor has fields for the team (from your token's teams) and the projects (searched on Vercel as you type), writes the query under them, and has a **Test** button that runs it once.

| Kind | What alerts | What CoIsland calls |
|---|---|---|
| Deployments | A deployment of the last 7 days enters a state you picked: failed unless you choose canceled, ready, blocked and others | `GET /v7/deployments`, per project, following its pages |
| Stuck builds | A deployment queued or building for longer than you allow (20 minutes unless you choose, from 5 minutes to 12 hours) | The same list, for the last day |
| Domain problems | A project domain not pointing at Vercel, not verified, or, when you ask, whose certificate expires within a number of days | `GET /v9/projects/{project}/domains`, `GET /v6/domains/{domain}/config`, and `GET /v8/certs` when certificates are asked for |

```text
team:acme project:web target:production
project:web state:error,canceled branch:main checks:failed
team:acme target:preview for:30m
project:web problem:misconfigured cert:14d
```

- `target:preview` keeps the deployments that have no production target, as Vercel lists previews.
- `checks:failed` keeps deployments whose checks concluded failed.
- A redeploy is a new deployment, so a build that fails again alerts again. A fixed domain leaves the result, and breaking it again alerts again.
- A result bigger than 10 pages of 100 deployments compares nothing: narrow the projects or the states.

Clicking a row in the notch opens the alert in CoIsland. There, a failed build shows its error, the failing step and the last lines of its build log; a misconfigured domain shows the DNS record to add. **Open in Vercel** goes to the deployment's inspector or the project's domain settings.

A Vercel monitor is a watch file like any other; its `-- kind:` is `vercel.deployments`, `vercel.stuck` or `vercel.domains`. [Watch files](https://coisland.app/docs/watch-files/) lists every header key.

## Troubleshooting Vercel connector errors

- **"The token was refused. Check it has not expired or been revoked. Create a new one at vercel.com/account/tokens."** Vercel answers a wrong, expired or revoked token with 403 `invalidToken`.
- **"project web: not allowed. The token's scope may not include it, or you left the team."** The token's scope does not reach that team or project, or a project-scoped token was asked about another project.
- **"project web: Not found, or not visible to this token."** The project was renamed or deleted, or the team named is not the one it belongs to.
- **"Rate limited; retry after 14:05."** Vercel allows 1,000 deployment lists a minute; CoIsland waits, then retries.
- **"Token expires in 3 days: create a new one at vercel.com/account/tokens."** Shown on every card of that connector during the token's last week.

## Frequently asked questions

### Can CoIsland change anything on Vercel?

No. The connector only sends `GET` requests: it never redeploys, promotes, cancels or edits a domain.

### Does it work on the free Hobby plan?

Yes. Deployments, stuck builds and domain problems all work on Hobby.

### Why is there no DDoS or firewall monitor?

Vercel's attack status endpoint is not documented as available on every plan, and CoIsland could not verify it. It is planned for a later version.