Documentation
¶
Overview ¶
Package checks owns CI check-suite + check-run orchestration. The API layer (internal/web/handlers/api/checks.go) calls into Create and Update; the merge gate at internal/pulls/pulls.go calls EvaluateRequiredChecks.
No work in this package executes user code — shithub is a receiver of check status from external systems (and, post-MVP, shithub Actions). The API surface is GitHub-shaped so existing CI adapters port cleanly.
Index ¶
- Constants
- Variables
- func Create(ctx context.Context, deps Deps, p CreateParams) (checksdb.CheckRun, error)
- func DeriveSuiteRollup(runs []checksdb.CheckRun) (status, conclusion string)
- func MarkStaleForPreviousHead(ctx context.Context, deps Deps, repoID int64, prevHeadSHA string) (int, error)
- func Update(ctx context.Context, deps Deps, p UpdateParams) (checksdb.CheckRun, error)
- type CreateParams
- type Deps
- type GateInputs
- type GateResult
- type Output
- type UpdateParams
Constants ¶
const ( MaxOutputTextBytes = 256 * 1024 MaxOutputSummaryBytes = 64 * 1024 )
MaxOutputTextBytes / MaxOutputSummaryBytes cap the output payload per spec section "Open questions".
Variables ¶
var ( ErrEmptyName = errors.New("checks: name is required") ErrNameTooLong = errors.New("checks: name too long (max 200)") ErrInvalidStatus = errors.New("checks: status must be queued, in_progress, completed, or pending") ErrInvalidConclusion = errors.New("checks: invalid conclusion") ErrCompletedNeedsConclusion = errors.New("checks: completed status requires conclusion") ErrOutputTextTooLarge = errors.New("checks: output.text exceeds 256 KiB cap") ErrOutputSummaryTooLarge = errors.New("checks: output.summary exceeds 64 KiB cap") ErrShortHeadSHA = errors.New("checks: head_sha must be at least 7 hex chars") ErrCheckRunNotFound = errors.New("checks: run not found") ErrSuiteNotFound = errors.New("checks: suite not found") )
Errors surfaced to API + handlers.
Functions ¶
func Create ¶
Create inserts (or returns existing-by-external-id) a check run, auto-creating the matching suite. Suite rollup is recomputed inside the same tx so the API response reflects the latest derived state.
`external_id` semantics:
- When empty: always insert a new run.
- When non-empty: lookup by (repo, head_sha, name, external_id); if found, return existing without insert. This makes retries by external CI safe.
func DeriveSuiteRollup ¶
DeriveSuiteRollup is the pure-function form of the rollup so tests can exercise the priority order without a DB. Public so the API layer can preview the rollup if needed.
func MarkStaleForPreviousHead ¶
func MarkStaleForPreviousHead(ctx context.Context, deps Deps, repoID int64, prevHeadSHA string) (int, error)
MarkStaleForPreviousHead flips suites on `prevHeadSHA` whose status is not yet completed to (completed, conclusion='stale'). Called from push:process when a head ref moves AND the matching protection rule has `dismiss_stale_status_checks_on_push = true`.
"Status complete + conclusion stale" preserves the audit trail — the runs themselves stay readable, but the suite no longer counts as in-progress.
Types ¶
type CreateParams ¶
type CreateParams struct {
RepoID int64
HeadSHA string
AppSlug string // "" → "external"
Name string
Status string // "" → "queued"
Conclusion string // optional
StartedAt time.Time
CompletedAt time.Time
DetailsURL string
Output Output
ExternalID string // optional; enables idempotent retry-create
}
CreateParams describes a check-run create request. Defaults (per spec): status='queued', app_slug='external'.
type GateInputs ¶
type GateInputs struct {
RepoID int64
HeadSHA string
RequiredNames []string // from branch_protection_rules.status_checks_required
}
GateInputs is the small struct the merge gate cares about.
type GateResult ¶
type GateResult struct {
Satisfied bool
Reason string // "" when Satisfied; otherwise human-readable cause
// Missing is the subset of RequiredNames that haven't yet succeeded
// or returned neutral on HeadSHA. Populated for UI tooltips.
Missing []string
}
GateResult mirrors the spec's blocked-with-reason vocabulary.
func EvaluateRequiredChecks ¶
func EvaluateRequiredChecks(ctx context.Context, pool *pgxpool.Pool, in GateInputs) (GateResult, error)
EvaluateRequiredChecks returns Satisfied=true when every required check name has a `success` or `neutral` conclusion on HeadSHA. A missing run, an in-progress run, or any other conclusion (failure / stale / cancelled / etc.) is unsatisfied.
The evaluator is the same one consulted by `pulls.Mergeability` and `pulls.Merge` — composes with `review.Evaluate` at the call site.
type Output ¶
type Output struct {
Title string `json:"title,omitempty"`
Summary string `json:"summary,omitempty"`
Text string `json:"text,omitempty"`
}
Output is the JSON shape stored in `check_runs.output`. Matches GitHub's `output` shape: title + summary + text. Bodies are bounded at the orchestrator (256 KiB on text, 64 KiB on summary) per spec.
type UpdateParams ¶
type UpdateParams struct {
RunID int64
Status string
Conclusion string
StartedAt time.Time
CompletedAt time.Time
DetailsURL string
Output Output
HasStatus bool
HasConclusion bool
HasStartedAt bool
HasCompletedAt bool
HasDetailsURL bool
HasOutput bool
}
UpdateParams describes a check-run patch. Empty optional fields keep the existing value (rather than clearing); callers that want to clear a field set it to the zero string explicitly via the dedicated *Set boolean — keeps the JSON contract simple while avoiding pointer-everywhere fields.
Status transitions are validated: queued/pending → in_progress → completed; completed requires a conclusion. Re-applying the same status is a no-op, which makes external-system retries safe.
Source Files
Directories