Skip to content

fix(controller): /healthz counts unreadable scopes instead of naming them - #52

Closed
parsilver wants to merge 2 commits into
fix/49-not-found-scopesfrom
fix/51-healthz-scope-count
Closed

parsilver wants to merge 2 commits into
fix/49-not-found-scopesfrom
fix/51-healthz-scope-count

Conversation

@parsilver

@parsilver parsilver commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Closes #51

Builds on #50 and targets its branch (fix/49-not-found-scopes); GitHub moves the base to main when #50 merges.

/healthz is public, and unreadable_scopes listed every scope the last cycle could not read by name, so a private repository in RUNNER_SCOPES that failed to read leaked its name to anyone who called the endpoint.

What changed

  • controller: Status.UnreadableScopes is now a count (int), and /healthz writes it as unreadable_scopes: <n>. The names are not kept in Status at all, so a future handler can't expose them by accident. unreadableScopes() still returns the scopes stuck for ALERT_FAILED_CYCLES cycles by name, for the failing alert.
  • Logs and alerts are unchanged: a 404 scope still logs scope not found on GitHub; skipped with scope=<key>, any other read error still logs cycle failed with the scope key in the error, and the failing and missing-scope alerts still name scopes. They reach only the operator.
  • README: the /healthz paragraph says the field is a count and where the names are; the two troubleshooting rows now say unreadable_scopes above 0 and point at the log lines. CHANGELOG [Unreleased]: both entries that mention unreadable_scopes describe it as a count. The field has never been released (not in v0.1.0), so it is not marked as breaking.

Acceptance criteria

  • With an unreadable scope configured, /healthz shows the count and no repository name. TestHealthzCountsUnreadableScopesWithoutNamingThem configures a 404 repo scope and an org scope that fails with another error, runs ALERT_FAILED_CYCLES cycles, and asserts the raw body contains no acme at all and unreadable_scopes is 2.
  • A test covers it. Same test; the failing run is kept in docs/evidence/red-51-healthz-names.txt:
    healthz_names_test.go:32: /healthz body {...,"unreadable_scopes":["org:acme","repo:acme/app"]}
         names a scope, want only the count
    
  • The log line still names the scope. The same test asserts the warn line scope not found on GitHub; skipped carries scope=repo:acme/app, and the failing alert names org:acme.

The existing tests that compared unreadable_scopes to a list of names now compare the count (health_test.go, notfound_test.go).

Checks

go vet ./...        clean
gofmt -l .          nothing
go test -race -count=1 ./...
ok  internal/config      1.482s
ok  internal/controller  3.229s
ok  internal/ghapp       5.024s
ok  internal/railway     1.491s
ok  internal/reconcile   1.390s
ok  internal/webhook     1.436s

Quality gates on the changed functions (this repo has no .quality/gate.py, so I ran the tools locally):

  • CRAP: unreadableScopes 5.0, HealthHandler 6.0, record 8.0 (not changed itself). Cycle is 15.2, the same as on fix(controller): a 404 scope in RUNNER_SCOPES no longer fails the cycle #50's head; this PR does not touch it.
  • Duplication (dryer, threshold 0.8) on controller.go and the new test: no candidates.
  • Mutation (mutator, changed lines only): 7 of 7 killed (unreadableScopes 6, HealthHandler 1), no survivors. It ran with --no-coverage because the tool can't map Go's module-path coverage profile; CRAP shows both functions at 100% coverage.

Risks

  • Anyone who already reads unreadable_scopes from an unreleased build as a list will get a number. The field is not in any tag yet.
  • github_rate_limits is still keyed by the installation account (an org or user login, never a repository name). That is outside this issue; if logins should be hidden as well, it would be a separate change.

Not verified

  • Not run against a deployed controller or the live GitHub API; covered by the unit tests' fake client only.

…names

The endpoint is public, so naming an unreadable private repository
leaks it. Fails now: the body lists the scope keys.
…g them

/healthz is public, so listing an unreadable private repository in
unreadable_scopes leaked its name. Status now holds only the count;
the names stay in the warn and cycle-failed log lines and in the
failing alert. The field was never released, so the CHANGELOG entries
are reworded rather than marked breaking.

Proved by TestHealthzCountsUnreadableScopesWithoutNamingThem (red run
kept in docs/evidence).
@parsilver
parsilver marked this pull request as ready for review November 19, 2026 06:55
@parsilver
parsilver deleted the branch fix/49-not-found-scopes November 19, 2026 08:08
@parsilver parsilver closed this Nov 19, 2026
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