---
name: "convention-vercel"
type: convention
description: Conventions for Vercel in Aled's system — projects in scope, deployment setup, environment variable naming, and what requires human action. Read before any operation that involves Vercel deployments. Grown as the conventions solidify.
license: CC BY-NC-SA 4.0
---

# convention-vercel

How Vercel is used in Aled's system. Stub — grown as the conventions solidify.

## Role

Vercel is the deployment platform for all Next.js sites. Every delivery repo with a Next.js frontend connects to Vercel; each push to `main` deploys to production and each PR gets a preview URL automatically.

## Projects in scope

| Vercel project | Repo | Production URL |
| -- | -- | -- |
| aledpritchard-com | assoc-one/aledpritchard-com | aledpritchard.com |
| meirionpritchard-com | assoc-one/meirionpritchard-com | (TBC) |

## Setup — new Vercel project

New project provisioning is **not `exec:human` by default — check the surface in hand first.** The Vercel connector, where it is attached, creates a project, sets its build configuration and environment variables, adds a domain and ships a deploy, so a leg that holds it provisions rather than filing a `human` setup leaf for the Owner. **Observed** 2026-10-01 on a connector-surface session: `create_project`, `create_git_project`, `create_project_env`, `add_project_domain` and `list_billing_charges` all present and reachable. Two things stay the Owner's, and they are about consequence rather than capability: **granting the Vercel GitHub app access to a new repository**, which is a settings change needing his own yes per action; and **confirming the production URL** once the project is live, which is the human-faculties check on a public surface. Where no Vercel connector is attached to the surface in hand, the step is `exec:human` as before — the test is the surface, not the task. (This corrects a standing claim that account-level access puts provisioning beyond every agent, which was true when written and is now false: a `human` setup leaf was filed and assigned to the Owner on 2026-09-30, blocking a build leaf, for work the connector then did in a handful of calls — APP-1891, and the authoring-path rule it produced in `convention-ticket`, *Widen it the other way*. The standalone setup sequence that depends on this correction is `playbook-project-setup` — APP-1889.)

## Environment variables

- Set in the Vercel dashboard under the project → Settings → Environment Variables.
- Prefix client-accessible variables with `NEXT_PUBLIC_` (Next.js requirement).
- Keep secrets (API keys, tokens) out of the repo; they live only in Vercel.
- Three scopes: Production, Preview, Development — set appropriately per variable.
- A variable the app needs must exist in the **deployment's** set, per scope — CI cannot see it and a CI placeholder does not reach Vercel, so a green build is no evidence the variable is there (see *Gotchas*, placeholder env values).

## Deployment

- Every push to `main` triggers an automatic Production deployment.
- Every PR auto-generates a Preview deployment URL (useful for skill-review-pr).
- **Vercel adds `X-Robots-Tag: noindex` to every Preview deployment itself, so a header acceptance criterion about indexability is unobservable on a preview by construction — the discriminator is the value, not the header's presence.** A QA leg that reads the header naively on a preview URL bounces a correct PR: the platform's own header is the bare `noindex`, while a repo that sets its own typically sets something longer (`noindex, nofollow` on the observed case), so *absent* and *the repo's value* are distinguishable but *absent* and *the platform's value* are not. Test the **value** against what the repo configures, or test on a surface that is not a preview — Vercel omits the header where a custom domain is assigned to a non-production branch, which is the other reason a noindexed staging custom domain is the better QA surface (see *Deployment Protection* below). (Verified **observed** against Vercel's own guide *are-vercel-preview-deployment-indexed-by-search-engines*, fetched 2026-11-02: *"Vercel adds an `X-Robots-Tag: noindex` HTTP response header to every Preview Deployment automatically."* The A1-849 QA leg that hit it — `assoc-one/a1-advisory` PR #11, head `8554541`, 2026-10-30, repo header `noindex, nofollow` against the platform's `noindex` — is that leg's **report** and is unverified here, no repo being readable from the authoring surface. Resolved on that run with one web search, at the cost of the turn it took to work out which of the two headers was being read — APP-2796.)
- Build command default: `next build`. Output directory: `.next`. Install command: `npm install`.
- On **Next.js 16+**, set the build script to `next build --webpack` for any repo running Sanity or other bundler-sensitive libraries — see the Turbopack gotcha below.

**A branch-alias preview exists only where a deployment exists, and pushing a branch at an already-deployed commit creates neither.** Vercel builds per **commit**, not per ref: push a new branch pointing at a SHA the project has already deployed and no new deployment is created, so the predictable branch-alias URL resolves to nothing. The **reference-branch** move — cut a branch at an old signed-off commit so the Owner has a stable copy of a build to compare against — therefore produces a dead link every time, and handing one over costs an Owner round and a second explanation. **Serve a past build from the original deployment's own immutable URL instead.** Find it by listing the project's deployments: `list_deployments` with `branch` set to the branch the commit was **first** deployed on, or with `sha` set to the commit. Each row carries `url` — the immutable `<project>-<hash>-<scope>.vercel.app` host, which is stable and never re-points — plus `state`, `inspectorUrl`, and `meta.githubCommitSha` / `githubCommitRef` / `githubCommitMessage`; take the `url` of the row whose SHA matches. Two mechanics of the connector are worth knowing before the call, because both fail *silently as an empty list* and an empty list reads exactly like "never deployed": **`sha` must be the full 40-character SHA** — a 7-character short SHA matches nothing — and a **preview deployment carries `target: null`**, so a `target` filter drops every preview. (Verified first-hand 2026-10-05 against `meirionpritchard-com`: branch `claude/a1-576-r4-reference` → 0 deployments; `sha=e1bf50b` → 0; `sha=e1bf50bdc4f8e2caedc5bca69bc8e6c70c95cd81` → exactly one READY deployment, `meirionpritchard-4o06e14ww-aled-s-projects.vercel.app`, on `claude/a1-576`. Observed A1-589 session, 2026-10-02 — APP-1990. Distinct from APP-1465, which covers *handing over* a preview link where the Owner's sign-off is needed; this is whether the link exists at all.)

**Merged is not deployed — and nothing in the agent toolchain notices the difference.** The auto-deploy on push to `main` is reliable in general but has failed twice on **aledpritchard-com** (2026-07-16 and 2026-07-17, both merges of A1-220 via `mcp__github__merge_pull_request`): the merge landed, the code was correct on `main`, and **no deployment record was created at all** — not Ready, not Error, not Canceled, absent from the Deployments tab with all seven status filters on. GitHub's own commit check reported a generic *"Deployment failed"*, which is actively misleading: nothing was attempted, so there was no failure to read logs for.

The consequence is a silent gap in the autonomous-merge path. `skill-merge-pr` treats *merged to `main`* as *will go live*, Linear shows the ticket Done, GitHub shows it merged, and the site is unchanged — with **no signal in either connector** that would catch it. The sandbox's egress proxy blocks both the production URL and the Vercel dashboard, so an agent session cannot verify a deploy even if it thought to.

- **Remedy when it happens — on a connector surface the leg performs it; without one it is the Owner's.** A *Create Deployment* / *Redeploy* against the current `main` tip clears it, and has done so immediately on every instance so far. Where a Vercel connector is attached to the surface in hand, that redeploy is an agent action: `create_deployment` ships it — the previous deployment's `deploymentId` to redeploy, or a `gitSource` for the merge commit — and `list_deployments` with `sha` set to the **full 40-character merge SHA** then confirms a deployment exists and reached READY. Read the branch-alias row above before that confirm call, because both of its silent-empty-list mechanics apply here: a 7-character short SHA matches nothing, and a `target` filter drops a preview. Where no Vercel connector is attached, the redeploy stays `exec:human` — the test is the surface, not the task, exactly as *Setup — new Vercel project* above reads it. (This corrects the standing claim that the remedy is a human action with no agent path, which was true when written and is now false — **reported**: a leg on `assoc-one/hackneyshowrooms` redeployed through the connector on 2026-10-21 after the push trigger produced nothing, and the deployment went READY. APP-2555.)
- **Ship-critical work on this project is verified by eye until the trigger is fixed.** Where a ticket's outcome is "it is live", the Owner confirms the production URL after merge; do not treat the merge comment as proof of deployment.
- **Suspects worth checking on the project, in order:** Settings → Git for a paused or disconnected integration on the production branch; an *Ignored Build Step* script skipping the commit; the Vercel GitHub App's recent webhook deliveries for the repo; and whether the trigger only misses on **API squash-merges** (both incidents were `merge_pull_request`, not a click in the GitHub UI) — that last one would make it a delivery-loop-wide risk rather than one project's misconfiguration, so it is the one worth ruling out first.
- **The post-merge deploy check now lives in `skill-merge-pr` step 3, and the signature is not one project's.** The prerequisite this bullet named — a Vercel connector on the merge leg's toolset — is met wherever the connector is attached, so the check is written rather than deferred: after the merge is confirmed landed, `list_deployments` on the full merge SHA, and `create_deployment` where the list is empty. On a surface with no connector the check still has nothing to read, and there the Owner's eye-check below remains the whole of it. **And the second project settles what the suspects bullet above called the question worth ruling out first**: the same signature — merge landed, code correct on the branch, no deployment record created at all — has now been seen on `aledpritchard-com` and on `hackneyshowrooms`, three instances in total, and every one of them followed an **API squash-merge** rather than a click in the GitHub UI. So read this as a delivery-loop-wide risk on the autonomous-merge path rather than one project's misconfiguration, and keep the per-project suspects above as the second line of enquiry rather than the first. (**Reported**: the `hackneyshowrooms` instance, 2026-10-21 — PR #6's merge commit had no production deployment and no commit status after about eleven minutes, while the same project's API squash-merge forty minutes earlier had deployed within seconds. The repo, PR, commit and timing figures are that leg's report; **premise unverified — no repo, GitHub or Vercel surface is readable from the authoring surface.** APP-2555, extending APP-576.)

(APP-576. The code shipped correctly both times — this is a deploy-trigger gap between GitHub and Vercel on one project, not a build defect.)

## Review addresses — staging and per-version

**Two review addresses, two different jobs, and a certificate step in between the DNS record and a page that loads.** A site that needs a surface the Owner can look at before production carries two address shapes, and they are not interchangeable. `next.<site>` is the **rolling** staging address: it is assigned to the latest staged commit and re-points as that branch moves, so a link handed over today shows something else tomorrow. `vX-Y.<site>` is **pinned per tag**: one address per released version, assigned to that version's own deployment and never re-pointed, which is the shape to hand over when the Owner has to compare two builds or sign one off. **The dot in a version number is written as a hyphen** — `v1-2.<site>`, not `v1.2.<site>` — because a dot adds a second subdomain level, and the certificate and the alias then do not describe the same host.

**What the number means — the size of the change, never the act of shipping it (Owner ruling, Aled, 2026-11-16).** The two shapes above consume a version number and no canon artefact said what one meant, so a repo running the staging method read *MAJOR is a go-live cut to production* literally and numbered three consecutive production cuts `v1.0`, `v2.0` and — nearly — `v3.0`. The Owner ruled it twice in one sitting: *"any cut to live doesn't have to be a major change. that's insane."* and *"we're still working on the 'landing page' so this is all still v1."* So a cut to production takes **whichever of the three the change itself earns**, and shipping is not one of the three: **MAJOR** is a change to what the site *is* — a replatform, a new information architecture, a redesign the Owner would want to compare build against build; **MINOR** is something added inside that same thing, a page, a section, a feature or a copy pass; **PATCH** is a fix that leaves nothing a reader would call new. A site still being built out therefore stays at `v1.x` until what it is stops moving, however many times it goes live in between. Tag mechanics and changelog shape stay the repo's own and are not fixed here; what is fixed is the meaning of the number `vX-Y.<site>` pins, because that address is handed to the Owner as *this version* and a number that only counts deployments tells him nothing about what changed. (Worked case, **reported** from `assoc-one/agents-site` read at origin/next `2498085`, 2026-11-16: `v1.0` was the landing page going live on 2026-11-10, a cut two days later that only pointed the install line at the real plugin was logged `v2.0` in `CHANGELOG.md`, and the cut after it — a simplified install section, an `/install` page and a new "Set up with Claude" message — was about to be `v3.0`; `assoc-one/agents-site#45` renumbered those two `v1.1` and `v1.2`, and because the `v2.0` tag had never been pushed nothing public changed. That repo's `docs/staging-versioning.md` also drops the patch number and gives a hotfix a minor bump on `main`, which this paragraph does not adopt. **Premises unverified, and this flag covers exactly these:** that repo's contents, its `CHANGELOG.md`, its `docs/staging-versioning.md`, the `assoc-one/agents-site#45` renumber, and whether `assoc-one/aledpritchard-com`'s `docs/convention-staging-versioning.md` carries the same literal go-live-is-major rule — no repository is readable from this surface: `gh api repos/<any>` returns 403 *not enabled for this session* identically for a public control and a private one, so the gate is per-session repository attachment, and `add_repo` is absent from the roster, which makes the probe unformable. `APP-3134`.)

**The certificate is a step, not a detail.** A subdomain that is attached to the project and reads as verified still fails in the browser until Vercel has issued a certificate for that exact name, and on the per-version shape the failure is explicit rather than silent: the alias assignment returns `cert_missing`. So the recipe for a pinned version address is ordered — **issue the certificate for the exact host, then assign the alias to the tagged deployment** — and where DNS is already at Vercel there is **no DNS step at all**, which is the part a leg expecting one is most likely to re-derive from first principles.

**DNS for these sites moves to Vercel** (Owner ruling, 2026-11-06, taken over keeping per-version records at the registrar). The move is executed **record by record, with every value compared character by character against the registrar's own export**, with **DNSSEC confirmed off before the nameserver change** — a nameserver change made with DNSSEC still enabled breaks resolution for the whole zone rather than one record — and with **mail tested in both directions after the cutover**, because an MX or SPF value transcribed with a trailing dot moved or a priority dropped fails silently until somebody tries to send. One **CAA** note, because CAA is the record that can block the certificate step above rather than a page: a zone permitting only Let's Encrypt, `pki.goog` and Sectigo covers Vercel's own issuance and **blocks any service that issues through a different authority**, so a zone set that narrowly is read before a new service is attached to it, not after that service fails.

**A staging or version address on a custom domain is indexable by default — the site itself has to send the header.** Vercel's automatic `noindex` applies to its own `*.vercel.app` preview hosts and to nothing else, so `next.<site>` and `vX-Y.<site>` are ordinary public hosts a crawler may reach. The site therefore sends `X-Robots-Tag: noindex, nofollow` **for the `next` and `vX-Y` hosts only**, never for production, and the rule is checked by reading the header off the deployed host with `curl -I` while varying the `Host` header across the staging, version and production names — a header applied unconditionally noindexes production, which is the expensive failure in the other direction. The two paragraphs this leans on are already in this file and are **not restated here**: the preview `X-Robots-Tag` paragraph under *Deployment*, for why a preview host cannot be used to test indexability at all, and the custom-domain exemption under *Deployment Protection* in *Gotchas*, for why a bound staging subdomain is the reachable surface in the first place.

**Pinning is done by hand, one address per tag, and the automation is the Owner's open call.** Issuing the certificate and assigning the alias on each release is a manual pair of actions today. Automating it needs a `VERCEL_TOKEN` repo secret, which is a credential decision and is **explicitly still open with the Owner** — so a run proposes it as his call, never stands it up as a default, and never writes a workflow that assumes the secret exists. (Worked case, **reported** and not re-observed from this surface: one site taken end to end through both address shapes, with the certificate ordering, the `cert_missing` failure on the first per-version attempt and the CAA restriction all found on that run. One instance. **Premises unverified, and this flag covers exactly these:** the pull requests, the repo's own `headers()` noindex rule, the zone's records and its DNSSEC state, and the per-address browser results are the filing leg's and the Owner's account — no repo, DNS or Vercel surface is readable from the authoring surface, and no Vercel connector call was made from it. `APP-2923`.)

## Gotchas

- `NEXT_PUBLIC_*` variables are inlined at build time — changing them requires a new deployment, not just a config update.
- Build failures surface in the Vercel dashboard and the GitHub PR check. If a PR deploy fails, check the Vercel build logs (via the GitHub PR check detail link).
- New projects need the Vercel GitHub App to have access to the repo before deployments will trigger.
- **CI that supplies placeholder environment values can go green while the deployment lacks them — the build gate and the deploy gate test different worlds.** A workflow that sets placeholder Sanity (or any) identifiers in its job `env:` buys build-independence from a provisioned project at the cost of environment coverage: GitHub Actions builds the commit green, Vercel's Preview build of the *same commit* fails with `Missing environment variable: NEXT_PUBLIC_…`, and once a build-time read is (correctly) deferred to request time the build stops failing altogether — leaving a runtime 500 on a page nobody has loaded as the only remaining signal. So on a repo that uses placeholders, the deployment's own variable set is verified separately, because CI cannot see it; and "the Vercel build succeeded" is evidence about the build only, never that the page renders (`skill-review-pr` reads it the same way). Where a route depends on a runtime variable, prefer a check that fails visibly on the deployment — a smoke request against the preview after deploy, or a startup assertion that the variable is present — over trusting the build. Same false-green family as APP-693 / APP-941 / APP-970: a green produced by an instrument that never exercised the thing under test. (Worked case: A1-350 / `assoc-one/assoc-one` PR #7, 2026-09-03 — CI green on `22525ef`, Preview red on the same commit, reproduced deliberately in an isolated clone — APP-1114.)
- **Next.js 16 defaults to Turbopack.** From Next.js 16.2.x, `next build` with no flags silently uses the Turbopack bundler — a breaking change from 15, where Turbopack was opt-in. Turbopack's module resolution differs from webpack's and breaks Sanity's schema registry: the symptom is a runtime `SchemaError: _original.types: []` (surfacing at runtime, not at build time, which makes it slow to diagnose). Until the ecosystem catches up, set the build script to `next build --webpack` for any repo running Sanity or other bundler-sensitive libraries. (Observed A1-75 / aledpritchard-com PR #31, 2026-06-25.)
- **A subfolder deployed as its own Vercel project installs only its own folder, so a `tsconfig` that does not cover that folder's generated files resolves against the repo root and fails the build.** Where a repo deploys a subfolder as a separate Vercel project — a Sanity Studio in `studio/` with its own `package.json` and the project's root directory set to `studio/` is the standing case — Vercel installs that folder's dependencies and nothing else. A build step that looks up a tsconfig for files the subfolder's own `include` does not name walks **up** the tree, finds the repo-root `tsconfig.json`, and tries to resolve whatever that file `extends` — a package installed at the root and therefore absent from the deployment. The error names the root's `extends` target, so it reads as a missing dependency in a package the deployment never had, which points the diagnosis at the wrong folder. Two rules follow, and they are the separate-project layout that neither this file nor `convention-sanity` covered. **Widen the subfolder's own `include` to cover every file its build touches, generated output included**, so the lookup never leaves the folder. And **verify a subfolder project's build in a clean copy of the repo with no root `node_modules` before trusting a local green** — a local build passes on a root install the deployment will not have, which puts it in the same false-green family as the placeholder-env bullet above: a green produced by an instrument that never exercised the thing under test. (Worked case, **reported**: `assoc-one/hackneyshowrooms` A1-749, 2026-10-21 — the Studio's first Vercel build failed with `Tsconfig not found astro/tsconfigs/base` while its Vite build sought a tsconfig for the generated `.sanity` runtime files; widening `studio/tsconfig.json`'s `include` to `**/*.js`, `**/*.jsx` and `.sanity/**/*` fixed it, and the failure reproduced in a clean `git archive` copy. One instance. **Premise unverified — the repo's tsconfig files, the build output and the reproduction are that leg's report; no repo is readable from the authoring surface.** APP-2532.)
- **Vercel's own Deployment Protection is a second wall, independent of the sandbox's egress proxy, and its exemption is keyed on custom domains rather than on preview-vs-production.** "An agent cannot load the preview" has two distinct causes on this platform, and they take different fixes, so the cause is read before a fix is proposed. Deployment Protection is a **project-level** setting: `get_project` returns `ssoProtection` and `passwordProtection`, each carrying an `enabled` flag and a `deploymentType`. At `deploymentType: "all_except_custom_domains"` every deployment URL is SSO-walled **except a domain bound to the project**, and a bound staging subdomain sits in the same exemption a production custom domain does. An auto-generated per-deployment URL (`<project>-<hash>-<scope>.vercel.app`) is **never** exempt under that setting, however the project is otherwise configured, because it is never a bound domain. The tell on the wire is a `302` to `vercel.com/sso-api?url=…` setting a `_vercel_sso_nonce` cookie — Vercel's own login redirect, reached from a working connection, not a block; the sandbox's egress proxy fails differently and earlier, with `403` / `CONNECT tunnel failed` and no response from the origin at all. Two consequences. A **noindexed staging custom domain is a materially more reachable surface than an ephemeral preview URL**, and is worth proposing where an agent-readable staging environment is what is wanted — only the sandbox allowlist would then need widening, and not the protection setting. And where an **ephemeral** preview specifically has to be reachable, the mechanism is Vercel's **Protection Bypass for Automation** rather than a protection change: a per-project secret sent as the `x-vercel-protection-bypass` header, or the same-named query parameter where headers cannot be set, exposed to the deployment as `VERCEL_AUTOMATION_BYPASS_SECRET` and managed through `update_project_protection_bypass`. **This is an addition, not a correction**: nothing in this file previously named Deployment Protection at all, and APP-412 — *Vercel preview SSO blocks headless QA visual verification*, Done — named the general phenomenon without the custom-domain exemption that makes the two surfaces differ, so there was no false clause here to repair. (Worked case: the A1-329 environments spike, 2026-10-26 — the ticket asserted the proxy blocked `vercel.app` outright, and a live read found an SSO redirect instead. APP-2677. **Verified from this surface rather than taken on report**: `get_project` on `assoc-one` returns `ssoProtection: { enabled: true, deploymentType: "all_except_custom_domains" }` and `passwordProtection: { enabled: false }`, with `www.assoc.one`, `assoc.one` and `assoc-one-iota.vercel.app` among its bound domains, read 2026-10-27 through the attached Vercel connector; the bypass header, the environment-variable name and the bypass tool are from Vercel's published documentation, read the same day. The per-URL status codes and the nonce cookie remain the spike session's report — `web_fetch_vercel_url` cannot re-check them, because it reaches a protected deployment by minting a share link and so bypasses the wall it would be testing.)
