Skip to content

fix(controller): count unreadable scopes on /healthz instead of naming them - #53

Merged
parsilver merged 2 commits into
mainfrom
fix/51-healthz-unreadable-count
Nov 19, 2026
Merged

parsilver merged 2 commits into
mainfrom
fix/51-healthz-unreadable-count

Conversation

@parsilver

@parsilver parsilver commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Closes #51

Replaces #52, which closed without merging when #50 merged and its base branch was deleted. These are the same two commits, rebased onto main (7969a10).

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

What changed

  • controller: Status.UnreadableScopes is now an int, and /healthz writes it as unreadable_scopes: <n>. Status no longer holds the names at all, so a later handler can't leak them by accident. unreadableScopes() still returns, by name, the scopes stuck for ALERT_FAILED_CYCLES cycles, because the failing alert needs them.
  • 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. The failing alert and the missing-scope alert still name scopes, and only the operator sees them.
  • README: the /healthz paragraph now says the field is a count and where to find the names. The two troubleshooting rows 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 was never released (it is not in v0.1.0), so the entry doesn't call it breaking.

Acceptance criteria

  • With an unreadable scope configured, /healthz shows the count and no repository name. TestHealthzCountsUnreadableScopesWithoutNamingThem sets up a repo scope that answers 404 and an org scope that fails with another error, then runs ALERT_FAILED_CYCLES cycles. It checks that the raw body contains no acme anywhere and that unreadable_scopes is 2.
  • A test covers it. That same test. I ran it again against main's controller.go on the rebased branch and it fails there:
    [FAIL] TestHealthzCountsUnreadableScopesWithoutNamingThem
       healthz_names_test.go:33: /healthz body {...,"unreadable_scopes":["org:acme","repo:acme/app"]} names a scope, want only the count
    
    The original failing run is saved in docs/evidence/red-51-healthz-names.txt.
  • The log line still names the scope. The same test checks that the warn line scope not found on GitHub; skipped carries scope=repo:acme/app and that the failing alert names org:acme.

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

Checks (on the rebased branch)

go vet ./...        clean
gofmt -l .          nothing
go test -race -count=1 ./...
ok  internal/config      1.412s
ok  internal/controller  3.288s
ok  internal/ghapp       4.202s
ok  internal/railway     1.640s
ok  internal/reconcile   1.344s
ok  internal/webhook     1.580s

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

  • CRAP: unreadableScopes 5.0 and HealthHandler 6.0, both at 100% coverage. record is 8.0 and wasn't changed. Cycle is 15.2, the same as on main, and this PR doesn't touch it.
  • Duplication (dryer, threshold 0.8) on controller.go and the new test: no candidates.
  • Mutation (mutator, the sites inside the changed functions): 7 of 7 killed (6 in unreadableScopes, 1 in HealthHandler), no survivors. It ran with --no-coverage because the tool can't map Go's module-path coverage profile. unreadable++ on the changed line has no mutation site.

Risks

  • Anything that already reads unreadable_scopes as a list from an unreleased build will now get a number. The field isn't in any tag yet.
  • github_rate_limits is still keyed by installation account, which is an org or user login and never a repository name. That is outside this issue. Hiding logins too would be a separate change.

Not verified

  • I haven't run it against a deployed controller or the live GitHub API. Only the unit tests' fake client covers it.

…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 11:19

@parsilver parsilver left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

No Blocker. Status no longer holds the names, so no handler can leak them later. The new test fails against main and checks the raw body for any trace of the scope. Logs and the failing alert still name the scopes for the operator. I also read the rest of /healthz: error is a bool, not the message, and services holds Railway service names. So the last error, which carries scope keys, never reaches the public body either.

Suggestion: github_rate_limits is keyed by installation login, an org or user name and never a repo. That's fine for this issue, but a private org's login would still show there. If it matters, publish only the lowest remaining count or key it by an index. Merging.

@parsilver
parsilver merged commit 08061db into main Nov 19, 2026
14 checks passed
@parsilver
parsilver deleted the fix/51-healthz-unreadable-count branch November 19, 2026 11:27
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.

controller: /healthz should not name unreadable scopes

1 participant