repomatic.github.status module

Probe githubstatus.com on API failures.

When a gh or REST call fails with an opaque error, callers can ask this module whether GitHub is reporting a live incident. The status page is the source of truth for outages affecting authentication, the REST API, and Actions, so surfacing it in error messages saves operators from chasing PAT scopes that aren’t actually broken.

The HTTP probe is memoized for the lifetime of the process: a single CLI invocation that fails ten gh calls in a row hits the status endpoint once. Failures (DNS, timeout, JSON parse) collapse to None so the probe itself never masks the original error.

repomatic.github.status.GITHUB_STATUS_SUMMARY_URL = 'https://www.githubstatus.com/api/v2/status.json'

Status summary endpoint exposed by Statuspage.

Returns a JSON document with a top-level status object containing an indicator (none, minor, major, critical, maintenance) and a human-readable description.

class repomatic.github.status.GitHubStatus(indicator, description)

Bases: object

Snapshot of the githubstatus.com summary.

Parameters:

• indicator (str) – One of none, minor, major, critical, maintenance.

• description (str) – Human-readable summary (like All Systems Operational or Partial System Outage).

indicator: str

description: str

property is_incident: bool

Return True when Statuspage reports anything other than healthy.

annotation()

Render a one-line annotation suitable for appending to an error.

Returns an empty string when no incident is active, so callers can concatenate unconditionally.

Return type:

str

repomatic.github.status.get_github_status() → GitHubStatus | None

Fetch the current githubstatus.com summary.

Memoized for the lifetime of the process: only the first call hits the network. Returns None when the probe cannot complete cleanly (network error, timeout, malformed JSON, missing fields), so callers can treat the probe as best-effort and never let it mask the underlying error they were trying to annotate.

Return type:

GitHubStatus | None

repomatic.github.status.status_annotation()

Return a one-line incident annotation, or empty string when healthy.

Convenience wrapper around get_github_status() for the common case where callers want to append a string to an error message without branching on None.

Return type:

str

repomatic.github.status.with_status_annotation(msg, *, sep=' ')

Append the incident annotation to msg when one is active.

Returns msg unchanged when GitHub reports healthy or the probe fails, so callers can wrap any diagnostic without branching. The separator is load-bearing: the PAT probes annotate inline, while the gh wrapper puts the annotation on its own line under a multi-line stderr.

Return type:

str