Documentation
¶
Overview ¶
Package githubclient is the narrow seam between toaster-ready's checkers and GitHub.
Keeping this an interface means dimensions 4 (CI status) and 5 (branch protection) are testable without a network, and the backend (go-github, added in Phase B) is swappable without touching callers. Every method returns a Result whose Status may be no-data — e.g. a 403 on branch protection for a non-admin token — which the checkers surface as a reason rather than a 0.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client interface {
// LatestRunGreen reports whether the most recent CI run on the default
// branch concluded successfully.
LatestRunGreen(slug string) Result
// BranchProtected reports whether the default branch has protection rules.
BranchProtected(slug string) Result
}
Client is the minimal surface toaster-ready needs from GitHub.
type GoGitHub ¶
type GoGitHub struct {
// contains filtered or unexported fields
}
GoGitHub is the Phase-B backend: a real go-github client. Every lookup that fails for any reason (no token, permission, network, missing data) returns a no-data Result with a reason — it never fails the scoring run.
func New ¶
New builds a GoGitHub client, resolving a token from GITHUB_TOKEN and falling back to `gh auth token`. Returns (client, sourceDescription). If no token is available the client still works for public repos (unauthenticated, lower rate limit); auth'd calls that need a token will surface as no-data.
func (*GoGitHub) BranchProtected ¶
BranchProtected reports whether the default branch has protection rules. A 404 means "no protection" (a real determination); a 403 means we lack the admin permission to read it (no-data).
func (*GoGitHub) LatestRunGreen ¶
LatestRunGreen reports whether the most recent CI run on the default branch concluded successfully.
Two decisions here are load-bearing, and both came from getting it wrong.
It asks only for COMPLETED runs. Asking for the newest run of any status meant the answer depended on whether anything happened to be running: a repo with two workflows on `push: main` has runs racing, and if the newest was in progress the whole category went no-data. That bit hardest when toaster ran inside Actions, because the workflow doing the scoring is itself a run on the default branch and cannot be complete while it is running — the scoring run docked the repo for its own existence, and the score flipped between two values on identical commits.
It then prefers a run from a workflow that looks like CI. Filtering to completed runs alone would have swapped a flake for a lie: when tests fail and a release or publish workflow succeeds a minute later, the newest completed run is green and the repo reads green with red tests. A false green is worse than no answer.
type Result ¶
type Result struct {
OK bool // the determination, when Available
NoData bool // true if the fact could not be retrieved
Reason string // why, when NoData
Detail string // human note (e.g. "conclusion=success")
}
Result is the three-state outcome of an API lookup, mirroring scorecard's no-data discipline at the source.
type Stub ¶
type Stub struct {
Reason string
}
Stub is the Phase-A implementation: it makes no network calls and reports every fact as no-data. This lets the full pipeline — including the no-data rendering — run before the go-github backend lands.
Source Files