Connect a site
Connect Vercel
When you need the Vercel connection, what Ulika sets up on your Vercel project, which environment variables it uses, and how to connect or disconnect.
Last updated
Vercel is the best supported host for Ulika. Connecting your Vercel account lets Ulika check the preview of its pull request, set up what your build needs, and remove it all again when you disconnect. For many sites it is optional. This page explains when you need it, what Ulika does on your Vercel project, and how to connect it.
Do you need it?#
It depends on how your connector delivers published content.
| Your connector | Vercel connection | Why |
|---|---|---|
| Vite or React, connected today (Git delivery) | Optional | Publishing commits content to your repository and your normal Git deployment rebuilds. No token and no deploy hook are needed. |
| Vite or React with an older connector (before version 1.1) | Required | The build fetches published content with a build token, so Ulika must place that token on your Vercel project. |
| Next.js App Router | Required | The runtime adapter reads published content while your site builds, so Ulika must prepare the Vercel project. ulika connect stops before it changes anything when no connected Vercel account serves the site (see below). |
When Vercel is needed and missing#
For a Next.js site, ulika connect checks Vercel before it writes anything to your repository. If it cannot continue, the site waits with one of four reasons and a link to connect (/dashboard/connect?connection=<id>). Nothing is lost: the import, your repository choice and the connection are kept.
| Reason | What it means | What to do |
|---|---|---|
vercel-not-connected | No Vercel account is connected to this workspace. | Open the link and connect Vercel. |
vercel-wrong-account | The connected accounts cannot see this site's project, or one can see it but has no permission on it. The message names every account searched. | Open the link and add the account or team that owns the project. |
vercel-token-invalid | A connected account was revoked or expired. The message names it. | Reconnect that account. |
vercel-unavailable | Vercel did not answer after several tries. | Wait, then run ulika connect again. |
When you connect or replace an account within 24 hours, waiting sites continue by themselves: follow them with ulika connect --resume <batchId>. After 24 hours, run ulika connect again; it does not import twice. ulika connect --check decides from the repository's package.json alone and cannot see the connector version, so it only holds back a Next.js site; the connect itself decides for a Vite or React site when it imports.
When the connection is optional, the dashboard shows a card titled Connect Vercel to verify private previews with this note: "Optional. Your site connects without it. If your previews ask for a sign-in, connecting Vercel lets Ulika read them before anything merges. Your live site doesn't change."
When it is required, the Turn on live editing button says Connect Vercel first, with a link to the Vercel step.
What Ulika does on your Vercel project#
When it connects or activates a site, Ulika works through these steps. Each is checked first, so running it again changes nothing.
Finds the project that serves your site. It looks up your site's address (and its
wwwor apex twin) in Vercel and proves that the project deploys the repository and production branch you selected. If not, it stops before changing anything.Binds that project to your Ulika project. A Vercel project can be used by only one live Ulika project at a time.
Makes sure the branch is built. Ulika reuses the preview Vercel already created for the connector commit. If Vercel did not build it (for example, automatic previews are off), Ulika starts a deployment from that commit.
Reads the result. It reads the state of the deployment for that commit. A failure is only ever Vercel's own failed or canceled build, never a timeout.
Prepares private previews. It tries to create a Protection Bypass for Automation secret named Ulika preview verification and, when you connected with an access token, registers a webhook so Vercel can report deployment events. See Private previews.
For older connectors only, it sets the build token and creates the deploy hook (see below).
After the merge, it records your site's address as the project's preview origin, so the editor can draw your real site.
Ulika also cleans up. It releases or adopts its own leftovers from projects that were deleted, and it never touches a variable, hook, webhook or secret that you created, even if the name is the same.
Environment variables#
New Vite and React installs use none. Older connectors, and the Next.js App Router connector, read a build token while your site builds.
| Variable | Where | What it does |
|---|---|---|
ULIKA_BUILD_TOKEN | Your Vercel project, production and preview | A secret token that lets your build read published content from Ulika. Ulika issues it, sets it, and stores only a hash. |
ULIKA_CONNECTOR_TOKEN | Your Vercel project | The same token, under a different name. Used when a variable called ULIKA_BUILD_TOKEN already exists that Ulika did not create. The build reads this one first. |
What the build does with it depends on the connector:
The Vite and React build adapter on Vercel, with the older delivery, refuses to build without a token. The message is:
ULIKA_CONNECTOR_TOKEN (or ULIKA_BUILD_TOKEN) is required on Vercel. Re-run ulika init.This is on purpose, so a build can never silently publish stale content.The Next.js App Router connector falls back to the content committed in your repository. A fork or a build before the token was set still builds.
If your project already had a ULIKA_BUILD_TOKEN made by another tool (usually an earlier CLI install), Ulika leaves it alone and warns you. You can delete the old one in Vercel whenever convenient.
The deploy hook#
Older connectors rebuild your site after Publish through a deploy hook. Ulika creates it on your Vercel project with the name Ulika followed by the project id. If Vercel does not show Ulika's access the list of deploy hooks, Ulika cannot tell which are its own. Earlier runs may have left duplicates, and Ulika tells you where to delete the extras (Vercel Settings, Git, Deploy Hooks). New Git-delivery connectors need no deploy hook because the push is the rebuild.
If the connector is active but Ulika could not set up the hook, you see: "The connector is active, but Ulika could not set up the deploy hook that rebuilds your site. Content published in Ulika will not go live until a hook is added in your hosting settings."
Two ways to connect#
Open the connect flow and find the Vercel card. Which options you see depends on what the Ulika you use has set up. If neither is available you see: "Connecting Vercel is not set up on this deployment. You can still create the branch and open the pull request; open the preview from Vercel yourself."
Connect with the integration#
Click Connect Vercel. You go to Vercel to install the Ulika integration on the account or team that owns the project, then return to Ulika. The card shows the badge Integration.
Connect with an access token#
Under Use an access token instead (advanced):
Open Vercel account tokens (the link Create a token on Vercel) and choose Create Token.
Set Scope to the single team that owns this website. Avoid a token for all teams, because Ulika only needs the one.
Give it a short expiry, copy it and paste it into Vercel access token.
Optionally fill in Team (optional) with a team name or id, such as the one in your Vercel URL. Leave it empty to search every team the token can see.
Click Connect with token. The card shows the badge Access token.
The token is stored encrypted and is never shown again. The field is cleared whether or not the connection succeeds. Ulika uses it only to do the steps listed above.
Statuses#
The card title tells you the state of the connection.
| Card title | Meaning | What to do |
|---|---|---|
| Connect Vercel | Not connected yet. | Use one of the two ways above. |
| Vercel is connected | Connected. The card names the Vercel project and the site it serves, and says Ulika can build a preview there. | Nothing. |
| Vercel did not accept the token | The token was rejected, revoked or expired. | Create a new token scoped to your team and paste it again. |
| We cannot find this website on Vercel | No project in that account serves your domain. | Connect the account or team that owns the project. |
| This Vercel project deploys a different repository | The project serving the domain is linked to another repository or branch than the one you selected. | Pick the right repository, or fix the project's Git settings. |
| This Vercel project is not linked to GitHub | The project is deployed outside Git, so nothing would build a change. | Link the project to your GitHub repository in Vercel. |
| This token cannot reach the project | The token is valid but is missing access to the project. | Use a token from the team that owns the project. |
When you come back from Vercel's own install page, you may instead see a notice such as That Vercel link could not be used (the link works once and expires after a few minutes), That Vercel account cannot see this website, That Vercel account has no permission on this project or Vercel could not be connected. Each says that nothing was stored or changed on your account. Connect again from the card.
More fixes are in Troubleshooting Vercel.
Disconnecting Vercel#
Click Disconnect Vercel on the card. The card is part of the connect screen (the step before Turn on live editing), so that is where the button lives. Ulika removes only what it created and recorded, per project:
the build token variable,
the deploy hook,
the webhook,
a protection bypass secret it created,
and, if you connected through the integration, the Ulika integration itself, which also removes its webhooks and variables.
It shows a summary such as Disconnected account. Removed N items Ulika had added to your Vercel projects. If something could not be removed, it lists it under These could not be removed and are still on your Vercel account and tells you to remove it in the project's Vercel settings.
With an access token, Ulika cannot revoke the token itself. The summary tells you the token still works until you revoke it at vercel.com/account/tokens.
Disconnecting does not take your site offline, and it does not remove the connector from your repository.
Teams and permissions#
If your project belongs to a Vercel team, connect that team. A token scoped to a single team is enough. Ulika may not be able to read your personal account details with such a token, and that is fine, because the project lookup is what proves access. See Roles for who in your Ulika workspace can connect it.
Was this page helpful?