List only branches that still exist as spec versions

[jgeluk]

Fixes #249.

The page was never stale

A branch pushed minutes earlier already appeared on the live page while develop had not been redeployed, so ISR and the Vercel deployments API were both working. ekgf-website is not involved either: its src/middleware.ts rewrites /dprod/* verbatim to the dprod zone and holds no version logic.

What failed was the GitHub lookup — and the caller was written to keep every branch when it did:

// Fail open: when the GitHub lookup failed, keep every branch.
if (activeBranches && !activeBranches.has(branch)) continue;

GITHUB_TOKEN is configured on the Vercel project (added Apr 13) — I initially inferred it was missing, which was wrong. It makes no difference to the diagnosis, because a present-but-rejected token fails on the identical code path:

missing token      -> unauthenticated -> 403 rate limit -> null
expired/revoked    -> 401 Bad credentials               -> null
missing scope      -> 403 Resource not accessible       -> null
no User-Agent      -> 403                               -> null

All four collapse into if (!res.ok) return null with nothing logged, so they are indistinguishable from outside. That is the defect: not which one it is.

Changes

Branch existence instead of open PRs. Existence is what the picker means. A merged branch is normally deleted and its preview is no longer a version of anything; conversely issue/241-doc-metadata-drift exists upstream with no open PR, and the old predicate would have hidden it even with a working token. Paginated, so a growing repository cannot silently truncate.

The failure is now audible. console.warn on a missing token and on a failed lookup, visible in the Vercel runtime logs. Previously there was no signal of any kind, which is why this ran broken indefinitely.

Two consumers, opposite failure behaviour. This is the part worth reviewing:

• getSpecVersions() stays permissive — middleware resolves explicit /spec/<slug> URLs with it, and a preview URL someone already holds must keep working during a GitHub outage.
• getListedSpecVersions() fails closed — the picker shows only the archive and develop when existence cannot be determined.

Failing closed everywhere would break routing during an outage; failing open everywhere is what produced this bug.

dependabot/* excluded from the picker. A dependency bump produces a valid preview deployment but is not a version of the specification. Flagging this as the one judgement call here — trivially reverted by dropping EXCLUDED_BRANCH_PREFIXES if you disagree.

The failure now diagnoses itself. GitHub's own response body is logged, which separates Bad credentials from a rate limit from a missing scope. An explicit User-Agent is sent, eliminating one of the four candidates outright — GitHub returns 403 without one, and runtimes differ in whether they supply a default.

The degraded state is visible. getListedSpecVersions() reports completeness and the page renders a "Branch list unavailable" notice. Failing closed without saying so would only trade a silently long list for a silently short one.

Documented in site/.env.example and a new site/README.md.

Verification

tsc --noEmit clean, pnpm build clean. Simulated against live data:

BEFORE (live page): 23 branches
AFTER  (new logic):  8 branches + archive

LISTED:  develop, fix/retire-github-pages-urls, issue/184-schedule-model,
         issue/198-reuse-odrl-collections, issue/238-unified-evaluation-context,
         issue/239-duty-only-properties, issue/241-doc-metadata-drift,
         issue/246-jsonld-context

DROPPED: 11 branches deleted upstream, 4 dependabot bumps

Action still required

The token exists but is not being accepted. The leading candidate is expiry — added Apr 13, ~4 months ago, and fine-grained tokens commonly carry 30/60/90-day lifetimes — but rather than guess a third time, this PR makes the system say so itself.

To get the answer: open this PR's preview deployment at /spec-versions and check its runtime logs for [spec-versions]. If it reports Bad credentials, rotate the token; Metadata: Read-only on EKGF/dprod is the only permission required.

Note for the record: the token has been configured since April, so whatever broke it happened after that, silently, and stayed broken with no signal anywhere.

Note

pnpm lint fails on develop too: there is no eslint.config.js, and ESLint 9 no longer reads .eslintrc.*. Pre-existing and untouched here, but worth its own issue.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VHbek1ZojYktiTaeFqChqA

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
dprod	Ready	Preview	Aug 21, 2026 12:24pm

[jgeluk]

The preview deployment settles it: the token is present but not being accepted.

https://issue-249-spec-versions-branch-filter.dprod-preview.ekgf.org/dprod/spec-versions/ renders:

Branch list unavailable

and lists exactly two entries — DPROD 1.0 (Beta) and Develop (latest).

That combination is conclusive:

• The Vercel API works. Develop (latest) only appears because fetchDeployments() returned a READY deployment for the develop branch. If the Vercel credentials were the problem, the archive would be the only entry.
• The GitHub lookup fails. Every branch came back with existsUpstream === null, which is why the notice renders and the fail-closed path applies.
• GITHUB_TOKEN is available to this deployment — it is set for All Environments, including previews.
• The missing User-Agent hypothesis is eliminated. This build sends User-Agent: ekgf-dprod-site explicitly, and the lookup still fails.

By elimination, the token is reaching GitHub and being rejected: expired, revoked, or lacking Metadata: Read-only on EKGF/dprod. Given it was added Apr 13 and fine-grained tokens commonly carry 30/60/90-day lifetimes, expiry is the likely one — but the runtime log now carries GitHub's own message, so it does not need to be guessed. Look for [spec-versions] GitHub branch lookup failed: in this preview's logs; Bad credentials means rotate, Resource not accessible means fix the scope.

Two things worth drawing out of this:

The behaviour on display in that screenshot is the fix working as intended. Two honest entries plus a notice explaining why, instead of 22 entries of which 11 were branches deleted months ago. It stays that way until the token is rotated, and then the full list returns automatically.

And it makes the real failure plain: the token has been configured since April, so it broke sometime after that, silently, and nothing anywhere reported it. A credential that expires on a schedule with no alarm attached will do this again — which is why the logging and the on-page notice matter more here than the token rotation itself.

[jgeluk]

Token permission correction (details on #249): the fine-grained token needs Contents: Read-only on EKGF/dprod, not Metadata as I said earlier — that is what List branches requires. Metadata: Read-only is added automatically by GitHub and is not a choice. site/.env.example and site/README.md are corrected in the latest commit.

[jgeluk]

Decision on ballot branches: leave as is. A branch deleted from origin drops off the listing, ballot/* included.

All three ballot branches (ballot/3, ballot/4, ballot/5) have been deleted from origin and survive only in local clones, so ballot/5 disappears from the picker with this change. Their Vercel deployments still exist and /spec/ballot-5 still resolves — any already-published URL keeps working, it is simply no longer advertised.

Recorded in site/README.md so the disappearance is not later rediscovered as a regression. If a ballot ever needs to stay listed, the fix is to keep its branch on origin rather than special-casing it in code.

Verified on the same data at the same moment: production (develop) lists 25 branch entries, this PR's preview lists 9.