> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/get-started/cloud-and-runtime/vercel.md).

# Vercel

Connect Vercel with an access token so Heeler knows which commit is live on every project, and links it back to the repository that built it.

Heeler connects to [Vercel](https://vercel.com/) to see what you actually have in production — every project, every deployment, and the exact commit behind it. You create an **access token** in Vercel, register it in Heeler, and lineage builds itself.

{% hint style="success" %}
**Vercel is the easiest runtime to link.** Vercel publishes the git origin of every project and the commit SHA of every deployment through its own API, so Heeler establishes repository lineage directly from that metadata — no code analysis or runtime correlation required. Vercel-hosted applications get full code-to-cloud lineage even when nothing is running in a cloud account Heeler can see.
{% endhint %}

## What Heeler collects

<table><thead><tr><th width="230">Capability</th><th>What it does</th></tr></thead><tbody><tr><td><strong>Repository lineage</strong></td><td>Each Vercel project is matched to its onboarded Heeler repository from the project's git link.</td></tr><tr><td><strong>Live commit tracking</strong></td><td>The current production (and staging) deployment becomes a service deployment carrying the deployed commit SHA.</td></tr><tr><td><strong>Project inventory</strong></td><td>Projects with their framework, Node version, production branch, and build configuration — root directory, build and install commands, output directory, and serverless function region — plus whether the project is live, paused, or publicly sourced.</td></tr><tr><td><strong>Deployment protection settings</strong></td><td>Each project's SSO protection, password protection, and git fork protection are recorded with the project, alongside the rest of its configuration.</td></tr><tr><td><strong>Deployment history</strong></td><td>A rolling 90-day window of deployments, plus each project's current production deployment however old it is.</td></tr><tr><td><strong>Environment assignment</strong></td><td>Vercel states its deployment target explicitly, so <code>production</code> and <code>staging</code> map straight to Heeler environments — no tag mapping needed.</td></tr><tr><td><strong>Teams &#x26; members</strong></td><td>Vercel teams and their members, for ownership context.</td></tr><tr><td><strong>Marketplace storage</strong></td><td>Stores provisioned through the Vercel Marketplace are inventoried as data stores and linked to the projects that use them, so a Vercel app's data appears in the graph alongside its code.</td></tr><tr><td><strong>Uploaded deployments as repositories</strong></td><td>Deployments pushed straight to Vercel rather than built from a connected repository are modeled as source repositories in their own right, and get the full SCA, SAST, endpoint, and secrets analysis. See <a href="#deployments-without-a-connected-repository">Deployments without a connected repository</a>.</td></tr></tbody></table>

## Before you start

* A Vercel account with access to the team you want Heeler to see.
* **Administrator** in Heeler (see [Roles and Permissions](/mrecEO40m5D6bt7Pq5pE/get-started/users-and-access/roles-and-permissions.md)).
* The repositories behind your Vercel projects should already be [connected to Heeler](/mrecEO40m5D6bt7Pq5pE/get-started/source-code-scm.md) and scanned. Lineage matches Vercel projects to the repositories Heeler has onboarded, so connecting them first is what gives you full code-to-cloud context. A project pointing at a repository Heeler doesn't know about still appears — see [Deployments without a connected repository](#deployments-without-a-connected-repository).

## Step 1 — Create a Vercel access token

{% stepper %}
{% step %}

### Open token settings

In Vercel, go to **Account Settings → Tokens** and click **Create Token**.
{% endstep %}

{% step %}

### Scope it to the right team

Give the token a recognizable name (e.g. `Heeler`), and set its **Scope** to the team you want Heeler to harvest. Choose an expiration that fits your rotation policy.

{% hint style="warning" %}
Scope matters. A token created under a different scope authenticates successfully but returns nothing for your team — which would otherwise look like an empty harvest rather than a permissions problem. Heeler checks for this when you save and rejects the connection with a clear error.
{% endhint %}
{% endstep %}

{% step %}

### Copy the token

Copy the token value immediately — Vercel shows it only once.
{% endstep %}

{% step %}

### Grab your team ID or slug

If you're connecting a team account, copy the **Team ID** from **Team Settings → General**. The URL slug works too. Skip this step for a personal (hobby) account.
{% endstep %}
{% endstepper %}

## Step 2 — Add the connection in Heeler

Go to **Administration → Connections → Hosting Platforms → Add Hosting Platform → Vercel**, then enter and **Save**:

<table><thead><tr><th width="240">Field</th><th>Value</th></tr></thead><tbody><tr><td><strong>Connection Name</strong></td><td>A descriptive name that uniquely identifies the connection in Heeler (e.g. <code>Vercel Production</code>).</td></tr><tr><td><strong>Access Token</strong></td><td>The token from Step 1.</td></tr><tr><td><strong>Team ID or Slug</strong> (optional)</td><td>Your Vercel team ID (<code>team_…</code>) or its slug. <strong>Leave blank for a personal (hobby) account.</strong></td></tr></tbody></table>

Heeler validates the token against the Vercel API before saving — and, when you've named a team, confirms the token can actually see that team. On success, harvesting begins in the background.

## You're done when…

* [ ] The connection shows **Healthy** under **Hosting Platforms**.
* [ ] Your Vercel projects and deployments appear in the [Catalog](/mrecEO40m5D6bt7Pq5pE/catalog/deployments.md).
* [ ] Vercel-hosted services show a deployed commit, and findings on those repositories start reflecting that they're live in production.

## Polling and lineage

Heeler polls Vercel on a per-resource cadence, then a lineage job turns that inventory into Heeler services and deployments:

<table><thead><tr><th width="300">Job</th><th width="140">Cadence</th><th>What it does</th></tr></thead><tbody><tr><td><strong>Deployment harvester</strong></td><td>1 hour</td><td>Sweeps the last 90 days of deployments, and always fetches each project's current production deployment.</td></tr><tr><td><strong>Lineage job</strong></td><td>1 hour</td><td>Matches projects to repositories and writes service deployments.</td></tr><tr><td><strong>Project harvester</strong></td><td>2 hours</td><td>Projects and their git origin, framework, and build root.</td></tr><tr><td><strong>Team harvester</strong></td><td>12 hours</td><td>The teams the token can see.</td></tr><tr><td><strong>Member harvester</strong></td><td>12 hours</td><td>Team membership. Personal accounts have none.</td></tr><tr><td><strong>Store harvester</strong></td><td>2 hours</td><td>Marketplace storage provisioned in your account.</td></tr><tr><td><strong>Store-project harvester</strong></td><td>2 hours</td><td>Which projects use which store. Storage is connected by hand, so it changes on human timescales rather than per-push.</td></tr></tbody></table>

### How a project becomes a service

For each Vercel project, Heeler:

1. Reads the project's **git link** to get the provider, org, and repo. GitHub, GitLab, and Bitbucket are supported — these are the providers Vercel builds from that Heeler also models as SCMs.
2. Matches those coordinates to an **onboarded Heeler repository**, case-insensitively (Vercel echoes back whatever casing the git provider reported).
3. Finds the **code root** the project builds from, using the project's root directory. If a monorepo project leaves its root directory unset, Heeler falls back to the repository root.
4. Promotes the project's current **production** and **staging** deployments to service deployments, each carrying the deployed commit SHA.

{% hint style="info" %}
**Preview deployments stay in inventory.** Vercel creates a preview deployment per pull request. Those are recorded and visible, but they don't become services — only `production` and `staging` targets do. Previews are pruned after 90 days; production and staging deployments are kept indefinitely so the record of what shipped survives.
{% endhint %}

## Deployments without a connected repository

Not every Vercel deployment comes from a git repository. Deployments pushed straight from the Vercel CLI, or imported, have no git link — so there is no existing Heeler repository for them to resolve to.

Heeler models those deployments as **source repositories in their own right**. The uploaded deployment becomes a repository in the Catalog and gets the same analysis a connected repository does — modules and dependencies (**SCA**), source-code weaknesses (**SAST**), API endpoints, and **secrets** — and it rolls up under Vercel the way repositories roll up under an SCM provider.

The only difference is where the source comes from: the file tree is fetched from Vercel's API instead of cloned over git. Code that never lands in a connected SCM is fully assessed rather than being a gap in coverage.

For the full walkthrough — finding these projects, triaging them, and deciding whether to link them to a repository — see [Secure Deployments on Vercel](/mrecEO40m5D6bt7Pq5pE/solutions-and-use-cases/secure-what-you-ship-on-vercel.md).

{% hint style="info" %}
**Connecting the git repository is still better.** A deployment analyzed on its own gives you its dependencies and secrets. A project linked to an onboarded repository gives you all of that plus commit history, contributors, ownership, and guardrails on the pull requests that change it.
{% endhint %}

## Troubleshooting

<table><thead><tr><th width="330">Symptom</th><th>Fix</th></tr></thead><tbody><tr><td>Saving fails with a message that the token can't access the team</td><td>The token was created under a different scope. Re-create it in Vercel with its <strong>Scope</strong> set to that team.</td></tr><tr><td>Projects harvest, but none get lineage</td><td>Their repositories aren't onboarded in Heeler. Connect the org under <a href="/mrecEO40m5D6bt7Pq5pE/get-started/source-code-scm.md">Connect Your Code</a> — Heeler logs the specific repositories it couldn't resolve.</td></tr><tr><td>A project resolves to a repository but still has no deployment</td><td>The repository hasn't been scanned yet, so it has no code root to attach to. Wait for the first scan to finish.</td></tr><tr><td>A CLI-deployed project has no repository lineage</td><td>Expected — there's no git link to follow. The deployment is still modeled as its own source repository and analyzed; see <a href="#deployments-without-a-connected-repository">Deployments without a connected repository</a>. Connect the project to a git repository in Vercel if you want it to resolve to an existing Heeler repository instead.</td></tr><tr><td>A stable site shows no production deployment</td><td>Shouldn't happen — the current production deployment is fetched regardless of age. Check the connection health. If the deployment is still missing after the next scheduled harvest, contact Heeler Support.</td></tr><tr><td>Team members are empty</td><td>Expected for a personal (hobby) account. Confirm you meant to connect a team, and that <strong>Team ID or Slug</strong> is set.</td></tr></tbody></table>

## Related

* [Connect Your Cloud and Runtime](/mrecEO40m5D6bt7Pq5pE/get-started/cloud-and-runtime.md) — the spine and what runtime context unlocks.
* [Connect Your Code](/mrecEO40m5D6bt7Pq5pE/get-started/source-code-scm.md) — lineage needs the repository onboarded first.
* [Deployments](/mrecEO40m5D6bt7Pq5pE/catalog/deployments.md) — where Vercel deployments show up in the Catalog.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/get-started/cloud-and-runtime/vercel.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.