Skip to content

Classify GitHub failures by type instead of guessing - #62

Merged
dmccoystephenson merged 2 commits into
mainfrom
feature/github-error-classification
Nov 6, 2026
Merged

dmccoystephenson merged 2 commits into
mainfrom
feature/github-error-classification

Conversation

@dmccoystephenson

@dmccoystephenson dmccoystephenson commented Nov 6, 2026 •

Copy link
Copy Markdown
Member

Summary

  • GITHUB_TOKEN is now only dropped when the startup check is answered with a 401. Any other failure, such as a connection failure, a 5xx or a 403 from GET /user, is reported as Could not verify GITHUB_TOKEN and the token is kept. Previously all of them were reported as an invalid token, and a daemon was left at the anonymous rate limit until it was restarted.
  • A name is now reported as not found when FileNotFoundException is raised, which is what github-api raises for a 404, instead of when the exception message contains 404. A connection failure for a name such as team404 is no longer misreported, and a real 404 no longer depends on the digits appearing in GitHub's response body.
  • A package-private GitHubService(String token) constructor was added so the token paths can be tested whatever the environment holds. The unused orgException local was removed.
  • USER_GUIDE.md, CONFIG.md and CHANGELOG.md were updated. No flag, property or endpoint was added, so COMMANDS.md is unchanged.

Closes #60
Closes #61

Evidence

The exception types and messages the fix relies on were observed by running github-api 1.318 against a loopback stub (a scratch test, not committed). They are tabulated in #60 and #61.

Skipped issues

#8 (missing LICENSE file) was not picked: a license and copyright holder have to be chosen by the maintainer, as recorded on that issue.

Behavior note

If the startup check fails for a transient reason and the token also turns out to be invalid, later requests fail with GitHub's 401 instead of falling back to anonymous access, until the process is restarted. That was judged preferable to a silently degraded daemon, because the failure is visible in the error output.

Test plan

  • mvn test: 212 tests run, 0 failures, 1 skipped (the live-token test, which needs GITHUB_TOKEN)
  • Regression check: with the old logic restored inside the new code, 6 GitHubServiceTest tests failed; the tests passed again once it was removed
  • Build workflow is green on the PR head (build and docker-build on 8f2031a)

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code


drafted by Claude on behalf of Daniel Stephenson

dmccoystephenson and others added 2 commits November 5, 2026 23:00
Only a 401 now drops GITHUB_TOKEN; any other failed startup check keeps
the token and says it could not be verified, so a brief outage no longer
leaves a daemon anonymous until it is restarted. A name is reported as
not found on FileNotFoundException rather than when the message contains
"404", which the URL in a connection failure's message could supply.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric (head 8f2031a):

  • Scope: PASS. Only GitHubService.java, its test, and the three docs that describe the behavior were changed; all of them serve A failed token check is reported as an invalid GITHUB_TOKEN and drops the token #60 or A GitHub failure is reported as not found when its message contains 404 #61.
  • Tests-new: PASS. The package-private constructor is exercised by every new token test. The private helpers are covered through it.
  • Tests-fix: PASS. git stash could not be applied because the tests need the new constructor, so the old logic was restored inside the new code instead: 6 GitHubServiceTest tests failed (NotFoundAsOrganizationOrUser, the 404-in-URL test, and the four KeepsToken tests). They passed again once the old logic was removed.
  • Sibling structure: PASS. The test<MethodName>_<Scenario> naming, @Mock fields and openMocks setup were followed. Records had not been used in this test class before, but the helper is private to it.
  • Sibling renames: PASS. No identifier in a parallel series was renamed.
  • Docs: PASS. USER_GUIDE.md, CONFIG.md and CHANGELOG.md were updated. README.md and COMMANDS.md make no claim about the fallback, so neither was changed.
  • Issue resolution: PASS. The surface named in A failed token check is reported as an invalid GITHUB_TOKEN and drops the token #60 and A GitHub failure is reported as not found when its message contains 404 #61 was changed, and orgException was removed.
  • CI: PASS. build and docker-build succeeded on 8f2031a (run 42171988112), a separate run from the one for the previous head.
  • Config-doc parity: PASS. No property was added.
  • Command-doc parity: PASS. No flag, system property or endpoint was added.
  • Package placement: PASS. No class was added.
  • No credential leakage: PASS. The new warning prints only the exception message, which contains the URL or response body seen in the probe, and assertTokenKeptAfter asserts that the token is absent from standard error. That assertion is limited to stubbed exceptions.

Findings and limits:

  • src/main/java/com/github/backup/GitHubService.java:46 — a 5xx with an HTML body would be printed in full in the warning. The same is already true of backup errors, so it was left unchanged.
  • src/main/java/com/github/backup/GitHubService.java:43-47 — a token kept after a transient failure may still prove invalid. Later requests then fail with GitHub's 401 until a restart, instead of falling back. This trade-off is stated in the PR body.
  • UNVERIFIED: the JAR could not be started here because launching it was refused by the sandbox. Bean construction was confirmed instead through the @SpringBootTest contexts for the default, web and daemon profiles, whose output shows the real GitHubService connecting.
  • UNVERIFIED: the behavior was not exercised against the live GitHub API with a real token. The 403 from GET /user was only seen from a loopback stub, and the claim that such a response is returned for GitHub App installation tokens was not tested.
  • The Copilot reviewer could not be requested (Could not resolve user with login 'copilot'), so no independent review took place.

This review was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit 35376f9 into main Nov 6, 2026
2 checks passed
@dmccoystephenson
dmccoystephenson deleted the feature/github-error-classification branch November 6, 2026 06:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant