Spec versions page lists deleted branches: GitHub filter fails open

[jgeluk]

Symptom

https://ekgf.org/dprod/spec-versions/ advertises 22 branches while only 6 pull requests are open. Eleven of the listed branches no longer exist in the repository at all:

add-dprod-contracts, agent/github-issues-source-of-truth, complete-dprod-migration, contracts/lifecycle-abstract-and-reject-5.8-5.9, dependabot/…/deploy-pages-5, dependabot/…/upload-pages-artifact-5, DPROD-64, issue/214-lifecycle-status-model, issue/215-reject-odrl-request, ns-dprod-segment, spec-latestversion-iri

Not a staleness problem

The page updates correctly: a branch pushed minutes ago appears while develop has not been redeployed, so ISR and the Vercel deployments API both work. ekgf-website is also not involved — its src/middleware.ts rewrites /dprod/* verbatim to the dprod zone and holds no version logic.

Cause

fetchActiveBranches() in site/src/lib/spec-versions.ts is failing, and the caller is written to fail open:

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

GITHUB_TOKEN appears in exactly one line of the repository (spec-versions.ts:121) with no .env.example, no documentation and no workflow that sets it, while the VERCEL_* variables are clearly provisioned since deployment discovery works. Authentication is optional in the code:

if (token) headers.Authorization = `Bearer ${token}`;

so without the token the request runs unauthenticated, where GitHub permits 60 requests/hour per IP shared across Vercel's serverless egress. That is exhausted continuously → non-2xx → null → every branch is kept.

(The Vercel project's environment variables could not be read directly to confirm the token is absent, so this last step is inferred. Every observable is consistent with it, and nothing else explains a persistent filter failure alongside working Vercel API calls.)

Three defects, not one

1. The token is treated as optional when the unauthenticated path cannot work in production.
2. The failure is silent — no log, no signal, no degraded-state indicator. It has been broken indefinitely with nothing to notice.
3. The predicate is wrong. Open-PR status is not the question. issue/241-doc-metadata-drift exists upstream but has no open PR, so even a working token would hide it; conversely the eleven branches above are gone from the repository entirely. Branch existence is what the picker actually means.

Fix

• Replace the open-PR lookup with GET /repos/EKGF/dprod/branches, paginated.
• Require GITHUB_TOKEN and console.warn when it is missing or the lookup fails.
• Split the two consumers, which need opposite failure behaviour:
  • getSpecVersions() stays permissive for middleware routing — a preview URL already handed out must keep resolving during a GitHub outage;
  • getListedSpecVersions() fails closed for the picker, showing only the archive and develop when existence cannot be determined.
• Exclude dependabot/*: a dependency bump produces a valid preview deployment but is not a version of the specification.
• Document the variables in site/.env.example and site/README.md.

Simulated against live data, the listing goes from 23 entries to 8 plus the archive, with every drop attributable to a deleted branch or a dependency bump.

GITHUB_TOKEN still has to be set on the Vercel project — a fine-grained token needs only Metadata: Read-only on EKGF/dprod. Until it is, the picker will correctly show just the archive and develop, and log why.

[jgeluk]

Correction: GITHUB_TOKEN is configured on the Vercel project (added Apr 13, all environments). My earlier claim that it was unset was an inference from the code and repo — it appeared in one line with no .env.example, no docs and no workflow — and it was wrong.

What that changes and what it doesn't:

Unchanged. The filter is definitely failing. fetchActiveBranches() builds its set from open PRs only, so 6 open PRs can produce at most 7 branches; the page shows 22. It can only be returning null, which means the request is not returning 2xx.

Changed. The reason is not a missing token. A present-but-rejected token fails on exactly the same 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, and nothing is logged, so from outside they are indistinguishable. That is the actual defect here — not which of them it is.

Given the token exists, the leading candidate is expiry: it was added Apr 13, roughly four months ago, and fine-grained tokens commonly carry 30/60/90-day lifetimes. Verified failure signatures against the live API:

$ curl -s -o /dev/null -w '%{http_code}' -H 'Authorization: Bearer <invalid>' \
    https://api.github.com/repos/EKGF/dprod/branches
401   # {"message": "Bad credentials"}

$ curl -s -o /dev/null -w '%{http_code}' -A '' \
    https://api.github.com/repos/EKGF/dprod/branches
403   # GitHub requires a User-Agent; the current code sets none

I am not going to guess a third time. #250 now makes the system state the reason itself:

• GitHub's own response body is logged on failure, 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;
• the page renders a "Branch list unavailable" notice when the lookup fails, so the degraded state is visible without Vercel log access. Failing closed without saying so would only replace a silently long list with a silently short one.

To get the answer: open the #250 preview deployment's /spec-versions and check its runtime logs for [spec-versions]. If it says Bad credentials, rotate the token — Metadata: Read-only on EKGF/dprod is the only permission needed.

Worth noting for the issue record: the token has been configured since April, so whatever broke it happened after that, silently, and stayed broken with no signal. That is the part this PR is really fixing.

[jgeluk]

Correction to my earlier advice: the permission is Contents: Read-only, not Metadata.

I said Metadata was all that was needed. That was wrong. GitHub's reference for the endpoint this code calls is explicit:

List branches — "The fine-grained token must have the following permission set: Contents repository permissions (read)."

— https://docs.github.com/en/rest/branches/branches

So, when creating the token:

Field	Value
Resource owner	EKGF
Repository access	Only select repositories → EKGF/dprod
Permissions	Contents: Read-only
Expiration	366 days

Metadata: Read-only is mandatory and GitHub enables it automatically as soon as any repository permission is selected, so it is not something to choose — it just appears. The token ends up with two permissions from one selection.

Not needed: any write permission, and Pull requests. The old code queried /pulls; this PR queries /branches instead, so that permission is no longer relevant.

One nuance worth recording, since it explains why this is not merely cosmetic. The same doc note adds that the endpoint "can be used without authentication or the aforementioned permissions if only public resources are requested", and EKGF/dprod is public — so a token with no permissions at all may appear to work. It would be taking the unauthenticated path, capped at 60 requests/hour per IP shared across Vercel's egress, which is the exact failure this issue is about. Granting Contents: Read-only is what makes the request genuinely authenticated, at 5,000/hour.

site/.env.example and site/README.md have been corrected accordingly.