Repository navigation
[docs] Document authenticating from outside a Vercel deployment - #3989
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
A few newly-introduced docs statements are inconsistent with existing reference text (v4 development env) and with custom-environment support (v5), which could mislead users configuring WORKFLOW_VERCEL_ENV.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds documentation that explains how to authenticate and configure the Vercel World from outside a Vercel deployment (local scripts / CI), including required variables, proxy vs direct backend behavior, and CI examples, with supporting cross-links from configuration reference pages.
Changes:
- Add “Connecting from outside a deployment” guidance to both v4 and v5 Vercel World pages, including worked script + CI snippets.
- Cross-link the new walkthrough from the v5 “Worlds” and “CLI and Web UI” configuration reference pages.
- Fix a couple of inaccuracies in the existing v4 programmatic configuration sample (remove unsupported
baseUrl, use ID-shaped placeholders).
File summaries
| File | Description |
|---|---|
| docs/content/worlds/v5/vercel.mdx | Adds the external-auth walkthrough + references it from the env-var section. |
| docs/content/worlds/v4/vercel.mdx | Adds the external-auth walkthrough + aligns nearby programmatic config sample. |
| docs/content/docs/v5/configuration/worlds.mdx | Links the reference knobs to the new external-auth walkthrough and clarifies token/ID coupling. |
| docs/content/docs/v5/configuration/cli-and-web-ui.mdx | Notes the 4 required values and links to the walkthrough. |
| .changeset/docs-external-vercel-auth.md | Adds a docs-only (empty-frontmatter) changeset entry for the documentation update. |
Review details
- Files reviewed: 5/5 changed files
- Comments generated: 3
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
🦋 Changeset detectedLatest commit: 922ff92 The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
Pushed 82abefb (on top of 081e7ed): That reverses the compromise in my earlier reply on the v4 thread. Copilot asked for Also in this commit:
The description's OIDC-token bullet was reworded to match the callout. How I verifiedThe workspace installed on this box, so unlike the earlier commits this one got a real run of the repo's own docs typecheck. Anchors were re-checked after the rebase with the same version-space/ |
Sim WorldSimulated world deterministic testing for races. Traces 🟢 world-sim scenario book — 0 fail of 42 total
Full trace: |
Inside a deployment the Vercel World authenticates itself with the per-request OIDC token the platform injects, so the docs only described the zero-configuration case. A local script or a CI job has no such token, and the reference pages listed the WORKFLOW_VERCEL_* variables one by one without saying which ones go together or why. Adds a "Connecting from outside a deployment" section to the Vercel World page (v4 and v5) covering the token plus project ID, team ID, and environment; that projectId+teamId is what routes the client through the api-workflow proxy, which is the only path that accepts a Vercel auth token; that starting runs additionally needs VERCEL_DEPLOYMENT_ID; and a worked script and GitHub Actions example. Notes that a development-scoped VERCEL_OIDC_TOKEN from `vercel env pull` is not a substitute — the backend attributes requests to the environment in the token's claim, so it must not be used to reach production or preview data. Also drops a non-existent `baseUrl` option from the v4 programmatic configuration sample and uses ID-shaped placeholders there, since projectId/teamId are IDs rather than slugs. Signed-off-by: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com> Co-Authored-By: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com>
The new section documented custom environment slugs while the reference entries on the same pages still listed only production/preview (v5) or production/preview/development (v4), so the two disagreed. The env-var table now names the variable and defers to the reference entry for the accepted values, keeping one canonical list per page. The v5 reference entry gains custom environment slugs, matching what the proxy accepts on the projectConfig path, and the v5 configuration reference records that the proxy takes a custom environment's slug or ID but attributes the write to the slug. Signed-off-by: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com> Co-Authored-By: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com>
The external-auth section explained how the request is carried as well as what the caller has to set: the api-workflow proxy on api.vercel.com, the x-vercel-* headers derived from the config, and the direct workflow-server path taken when the two IDs are absent. None of that is something a reader can act on, and all of it is free to change without notice. The guidance itself is unchanged — same four values, same script, same CI snippet, same warnings about the pulled OIDC token and about environment alignment. What the reader now gets is the contract: authenticate with a Vercel auth token, set the token and both IDs together, name the environment you mean. "Why both IDs are required" was that reasoning in section form, so it is gone; the one actionable sentence it carried — set all three or none, and setting the IDs alone fails up front rather than as a 401 — moves inline under the sample, and the env-var tables say "Required" without pointing at a section that explains the backend's routing. Also finishes Copilot's remaining review thread on the v5 configuration reference: projectConfig.environment now lists custom environment slugs alongside production and preview, with the slug-not-ID caveat stated as a rule for the reader rather than as a description of what the proxy accepts. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com> Co-Authored-By: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com>
WORKFLOW_VERCEL_ENV was documented three ways: the external-client tables deferred to the reference entry, the v5 reference entry listed production/preview plus custom environment slugs, and the v4 entry listed production/preview/development. Copilot flagged the mismatch on all three pages, suggesting `development` be added to the tables for consistency. `development` is not an environment an external client should target, so the inconsistency is resolved by dropping it rather than by spreading it to the pages that never mentioned it: - The env-var tables on both Vercel World pages name the accepted values inline (production, preview, or a custom environment's slug) and still link to the reference entry, so a reader does not have to follow a link to learn what is allowed. - The v4 reference entry drops `development` and gains custom environment slugs, matching v5. The v4 page also gains the slug-not-ID rule the v5 page already carried. - `--env` in the CLI and web UI reference accepts the same values, so it no longer says production/preview while the world reference and projectConfig.environment say otherwise. - The "isolates data per environment" bullet on both pages now reads production, preview, and any custom environments. - The `vercel env pull` warning no longer frames the pulled VERCEL_OIDC_TOKEN as addressing "development data". It states the consequence for the reader instead: requests made with that token are attributed to the environment carried in the token itself, so authenticate with a Vercel auth token. - The getHookByToken environment sample compared hook.environment against `VERCEL_ENV || "development"`, which could never match — the local world records hooks as `local`. It now prefers VERCEL_TARGET_ENV, which carries a custom environment's slug where VERCEL_ENV reports preview, and falls back to `local`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com> Co-Authored-By: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com>
…e CI example its permissions Co-Authored-By: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com>
Co-Authored-By: Nathan Rajlich <71256+TooTallNate@users.noreply.github.com>
|
No backport to This is overwhelmingly net-new documentation — a multi-page "Connecting from outside a deployment" walkthrough plus cross-links — rather than a correction of something wrong on To override, re-run the Backport to stable workflow manually via |
Description
Inside a Vercel deployment the Vercel World authenticates itself with the per-request OIDC token the platform injects, so the docs only really described the zero-configuration case. A process that is not a deployment — a script on your laptop, a CI job driving e2e tests against a preview — has no such token, and the reference pages listed the
WORKFLOW_VERCEL_*variables one at a time without saying which ones have to be set together, or why.Adds a Connecting from outside a deployment section to the Vercel World page (both v4 and v5) covering:
projectId, andteamIdare a set — supply all three or none. Supplying both IDs with no token throws up front instead of surfacing as an opaque401.VERCEL_OIDC_TOKENwritten byvercel env pullis not a substitute: requests made with it are attributed to the environment carried in the token itself, not to theproductionorpreviewdata the script means to reach. Called out separately from the same token's legitimate use as a Trusted Sources deployment-protection bypass, since those are two different credentials and conflating them is the easy mistake.start()additionally needsVERCEL_DEPLOYMENT_ID(reads don't), plusdeploymentId: "latest"resolving from it.createWorld()/createVercelWorld()+setWorld(), and a GitHub Actions snippet shaped like this repo's own e2e lanes (wait for the deployment, hand its ID to the test step alongside the auth vars). Notes that this is what theworkflowCLI does under the hood, and that the SDK does not readWORKFLOW_VERCEL_*implicitly.getEnvironmentand no such guard.Cross-links added from
configuration/worldsandconfiguration/cli-and-web-uiso the reference entries point at the walkthrough.The section deliberately stops at the contract the reader can act on. An earlier revision also described how the request is carried — the
api-workflowproxy onapi.vercel.com, thex-vercel-*headers derived from the config, the direct workflow-server path taken when the two IDs are absent — and 45ab74b takes all of that back out, along with the Why both IDs are required subsection that existed only to explain it. None of it is actionable, and all of it is free to change without notice. The guidance is unchanged: same four values, same script, same CI snippet, same warnings.One small drive-by fix in the v4 page's existing programmatic-configuration sample, since it sits right next to the new section and contradicted it: it passed a
baseUrloption that isn't inAPIConfig, and used slug-shaped placeholders forprojectId/teamId, which are IDs.How did you test your changes?
Docs-only, no code changes. Every claim was checked against the source rather than carried over from the existing prose:
getHttpConfig/getHttpUrl/getHeadersinpackages/world-vercel/src/utils.tsfor thetoken+projectId+teamIdcoupling and the missing-token throw.resolveVercelApiTokeninhttp-core.tsandfetchRunKeyinencryption.tsforVERCEL_TOKEN's actual (narrow) role and for the run-key fetch the same token authorizes.resolveClientEnvironmentfor the two environment sources and the custom-environment slug-vs-ID note, andrefuseCrossEnvironmentDeliveryinpackages/core/src/runtime.tsfor the v5 guard callout.queue.ts'sgetDeploymentIdandresolve-latest-deployment.tsfor theVERCEL_DEPLOYMENT_IDrequirement.packages/cli/src/lib/inspect/env.ts+auth.tsfor the CLI's resolution order, and.github/workflows/tests.yml/benchmarks.ymlfor the CI shape the example is modelled on.origin/stable(createVercelWorld, nobaseUrlinAPIConfig, same header behaviour, no environment guard) so the two versions don't claim each other's behaviour.docs/scripts/lint.tsneeds bun and an installed workspace, which I didn't have here, so I re-implemented its URL/anchor resolution (version spaces,github-sluggerheading slugs, GitHub-style dedup) and ran it over the content tree — including after removing the Why both IDs are required heading, to confirm nothing still points at that anchor and that no other heading's dedup suffix shifted. Nopnpm test:docsimpact: that suite globsdocs/content/docs/**/*.mdx, and the new code samples live underdocs/content/worlds/.The YAML snippet deliberately has no
[!code highlight]annotations — there's no precedent for that notation in a non-TS block in this repo and I couldn't render the site here to confirm the transformer handles#comments, so rather than risk the marker showing up as literal text it's left plain.Docs Preview
Base:
https://workflow-docs-git-workflow-auth-docs.vercel.sh(from thevercel[bot]comment — behind deployment protection, so the links need Vercel team access).PR Checklist - Required to merge
pnpm changesetwas run to create a changelog for this PRgit commit --signoffon your commits)@vercel/workflowin a comment once the PR is ready, and the above checklist is complete🤖 Generated with Claude Code