Skip to content

feat(backend-vercel): send a GitHub Actions job's OIDC token - #775

Merged
julianbenegas merged 13 commits into
mainfrom
jb/vercel-board-github-oidc
Nov 20, 2026
Merged

julianbenegas merged 13 commits into
mainfrom
jb/vercel-board-github-oidc

Conversation

@julianbenegas

@julianbenegas julianbenegas commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

GitHub Actions workflows use the team's board in Vercel's API with the job's own OIDC token, no stored secret, and grants there name a repository's runs or an issuer.

  • Users: in a job with permissions: id-token: write, vb, board(), and a vercel board with no Vercel login send GitHub's OIDC token to Vercel's board (source GitHub Actions OIDC); with no --scope or VERCEL_ORG_ID they fail with reason missing_scope. grants create, update, and explain with --github or --oidc reach Vercel's API instead of a client-side refusal.
  • Grants: an oidc grant names the workload by sub, on any board: an issuer signs tokens for everyone it serves, and sub is the one claim OIDC gives no two of them. Each sub is exact or a prefix ending in * right after a : or / (project_path:acme/api:*), so acme never reaches acme-evil. A grant without sub, or with a * elsewhere in it, is 400 invalid_grant; removing a principal from an older grant still works. subPrefix is exported from @vercel/board/access. A mention of a workflow by ID (@[github:repo:<id>]) is found by its handle.
  • Protocol / backends: no protocol change. vercel() reads two new API principals, github and oidc (actor kind workflow), and passes the API's unsupported_principal through as it is.
  • Performance / I/O: one request to GitHub's token endpoint per job token, kept until a minute before it expires; nothing else changes.
  • Tests: in process against the fake Vercel API, with GitHub's token endpoint faked: the token order, the audience, the cache, the team error, GitHub's refusal, and how workflows render; the CLI in process for grants, whoami, and its errors. The fake now keeps and explains GitHub and OIDC grants and names their callers as Vercel's API will. Vercel's API side isn't live yet.

Users

From the CLI in process, against the fake Vercel API, in a job with VERCEL_ORG_ID=team_test:

$ vb whoami
acme/web (github:repo:700001)
board   https://api.vercel.com/v1/messageboard/boards/brd_test?teamId=team_test
source  GitHub Actions OIDC
can     ci/  post

$ vb grants create --github acme/web --git-branch main --can 'ci/=post' --scope test
created g4  --github acme/web --git-branch main  ci/=post

With nothing naming the team (--name without --scope or VERCEL_ORG_ID):

$ vb post ci 'deploy failed' --name ops
error: A GitHub Actions token names no Vercel team, so there's no team's board to use.

  Use a team's board: add --scope <TEAM_ID>
  Or set VERCEL_ORG_ID to its ID

grants create --github on main, then against an API that still refuses it, on this branch:

error: Vercel's board takes no GitHub or OIDC principals in a grant.

  Grant an app that an OIDC exchange policy issues tokens for: --app <slug>.
error: Can't create the grant.
  Grants name no GitHub or OIDC principals.
import { board } from '@vercel/board'

// in a job with id-token: write: writes as github:repo:<repository_id>
const team = board({ team: 'team_abc123' })
await team.post('ci', 'deploy failed')

Protocol / backends

// API principals vercel() now reads, both of actor view kind `workflow`
{ type: 'github', repositoryId, repository, workflowRef?, ref?, event? }  // github:repo:<repositoryId>, handle owner/name
{ type: 'oidc', issuer, subject, claims }                                 // oidc:<issuer host and path>:<subject>, handle subject
  • A workflow the API names no default board to gets 403 board_not_granted with the --github grant to create, and makes no board.

Open

  • The CI guide runs vercel board for the team's board, which needs a Vercel CLI release that runs it with no login: it then hands board none, so the job's token goes. A board of your own at BOARD_URL keeps vb.
  • In the actors list, a workflow's agent has no via: github:repo:<id> alone doesn't say its repository.

On Vercel's board, a GitHub Actions job with id-token: write now goes as
its own OIDC token, made out to https://api.vercel.com/v1/messageboard and
sent as a Bearer token: after an app's login, the deployment's OIDC token,
and BOARD_TOKEN, and before vercel login. A GitHub token names no team, so
with no --scope or VERCEL_ORG_ID a request fails before it's sent with
missing_team.

Grants naming --github or --oidc, and explains for them, go to Vercel's API
as they are: the client no longer rewrites unsupported_principal into a
hint about apps and exchange policies. vercel() reads the API's github and
oidc principals and shows them as workflows, by repository and by subject.
@vercel

vercel Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
vboard-preview-publisher Ready Ready Preview Nov 20, 2026 4:11pm UTC

The CI guide's GitHub Actions and GitLab steps for the team's board now run
vercel board, with the team's ID in --scope or VERCEL_ORG_ID, and note that
this needs a Vercel CLI release that runs vercel board without a login.
With none on the runner, it hands board no login, so the job's own token
goes. A board of your own at BOARD_URL keeps vb.
…es with to its team and Vercel's API

The missing-team check ran in team(), so a board({ fetch }) with credentials of its own, which can use their default team, failed with missing_team in any GitHub Actions job. It now runs where the job's token is sent, and that same place sends the token only to Vercel's API, which it's made out to: a vercel({ api }) pointing anywhere else fails with wrong_audience before GitHub is asked for one.
Vercel's API now takes a GitHub Actions run's team by slug as well as by ID, so the CI guide, the CLI reference, SPEC, and the missing-team hint say --scope <team>.
@julianbenegas
julianbenegas marked this pull request as ready for review November 20, 2026 14:33

@vercel vercel Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read the diff; CI is green. The client side looks right to me: the token only goes to api.vercel.com, it's cached until a minute before exp and dropped on failure, a missing team fails before GitHub is asked for a token, and the grant hint quotes the board name. Two things to look at, neither blocking:

  1. The job's OIDC token now beats VERCEL_AUTH_TOKEN. asGithubActions() sits above the login, so any job with id-token: write that already sends VERCEL_AUTH_TOKEN switches to the workflow principal. id-token: write is common for npm provenance and AWS. On upgrade, those jobs stop acting as the user and hit board_not_granted / missing_team until someone adds a --github grant. The test at vercel-github-actions.test.ts:68 makes this deliberate. If you keep it, it should go in the changeset as a behavior change. Otherwise, putting an explicit VERCEL_AUTH_TOKEN ahead of the job token keeps those workflows working as before.
  2. githubTokenGoesTo also accepts http://localhost|127.0.0.1. That's a test hook in shipped code. It's low risk because the audience pins the token to Vercel's API, but it would be tidier to inject the allowed origin through the test's environment.

vercel Bot and others added 4 commits November 20, 2026 15:08
… job's OIDC token

A job with id-token: write often has it for something else (npm provenance, cloud OIDC), so a workflow that already sets VERCEL_AUTH_TOKEN keeps acting as that login.

Co-authored-by: Julian Benegas <40034115+julianbenegas@users.noreply.github.com>
An issuer like GitLab.com signs tokens for every customer it serves under one iss, so a grant for a claim like ref=main let in anyone's job. sub is unique within an issuer and never reassigned, so every oidc grant names one: exact, or a prefix whose * follows a : or /. Removals don't need one, so an older grant can still be taken apart.

@vercel vercel Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at Julian Benegas's request. I read the full diff at c3c52e3, including the three new commits that require sub on oidc grants. CI is green. One of the commits is mine (VERCEL_AUTH_TOKEN going ahead of the job's token).

Not blocking, but worth a follow-up: subPrefix only requires one character before the : or /, so sub=project_path:* (or repo:*) passes validation. On gitlab.com that still matches every project, which is the case this change is meant to close. An extra claim like project_id narrows it, but nothing requires one. Requiring at least two segments in the pattern would close it, as would refusing a prefix that is only the issuer's own claim-type label.

@julianbenegas
julianbenegas merged commit c935700 into main Nov 20, 2026
8 checks passed
@julianbenegas
julianbenegas deleted the jb/vercel-board-github-oidc branch November 20, 2026 17:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant