GitHub

API reference for chia.github. These pages are generated from the docstrings in the source, so they stay in sync with the code.

Github Client

Shared read-only GitHub REST client plumbing.

Base class + typed exceptions used by the repo-bound nodes (GithubIssuesNode and GithubPullsNode). Bind to one repo at construction; all calls are synchronous and raise the typed exceptions below on failure (no in-band success: bool). Head-node only — not a Ray task.

exception chia.github.github_client.GithubError

Bases: Exception

Base class for all GitHub client errors.

exception chia.github.github_client.GithubAuthError

Bases: GithubError

401 Unauthorized — missing or bad token for a private resource.

exception chia.github.github_client.GithubRateLimitError(reset_time: int, message: str = '')

Bases: GithubError

403 with X-RateLimit-Remaining: 0. reset_time is a unix timestamp.

exception chia.github.github_client.GithubNotFoundError

Bases: GithubError

404 — repo, issue, or pull request not found.

exception chia.github.github_client.GithubRequestError

Bases: GithubError

422 or other 4xx that doesn’t fall into auth / rate-limit / not-found.

exception chia.github.github_client.GithubServerError

Bases: GithubError

5xx after one retry, or a network timeout.

class chia.github.github_client.GithubClient(repo: str, token: str | None = None, timeout_seconds: int = 30, logging_level: int = 10)

Bases: object

Repo-bound read-only GitHub REST client.

Holds the session, auth header, and the retrying _request() helper. Subclasses add resource-specific read methods (issues, pulls, …). Pass a token or set GITHUB_TOKEN in the environment for private repos and a higher rate limit.

Github Issues Node

Read-only GitHub issues client, exposed as a chia service-pattern node.

Bind to one repo at construction and expose a small, synchronous API. Errors are raised as typed exceptions (no in-band success: bool); see GithubError and its subclasses (defined in chia.github.github_client and re-exported here for backwards compatibility). For pull-request reviews/comments, see chia.github.github_pulls_node.GithubPullsNode.

class chia.github.github_issues_node.GithubIssuesNode(repo: str, token: str | None = None, state: str = 'open', timeout_seconds: int = 30, logging_level: int = 10)

Bases: GithubClient

Read-only client for one GitHub repo’s issues.

Service-pattern node (head-node only, not a Ray task). Bind to one repo at construction; fetch via recent() or get_issue(). All calls are synchronous and raise typed exceptions on failure. Pull requests live on chia.github.github_pulls_node.GithubPullsNode.

recent(n: int = 1, after: int | None = None, fetch_comments: bool = True) → list[GithubIssue]

Return up to n most-recent issues (sorted by created desc).

With after=None, returns the n newest issues. With after=K, returns the n newest issues whose number is strictly less than K. Pull requests are excluded — to list PRs use chia.github.github_pulls_node.GithubPullsNode.recent().

fetch_comments defaults to True (one extra paginated request per issue that has comments). Pass False to skip that N+1 cost when you only need list-payload fields (title/body/labels) — e.g. to filter a large pool cheaply, then re-fetch comments for the few survivors via get_issue().

get_issue(number: int, allow_pull_request: bool = False) → GithubIssue

Fetch one ISSUE by number.

GitHub serves pull requests through the issues endpoint too (shared number space), so the endpoint CAN return a PR — but a PR-as-issue is a degraded view (no head/base/branch data) and almost never what an issues-node caller wants, so by default a PR number raises GithubRequestError instead of silently succeeding. Pass allow_pull_request=True to opt in (the result’s is_pull_request field will be True). For a proper PR view use chia.github.github_pulls_node.GithubPullsNode.get_pull().

get(number: int) → GithubIssue

Deprecated alias for get_issue() with allow_pull_request=True (the historical permissive behavior). Prefer get_issue(), or GithubPullsNode.get_pull() for pull requests.

linked_pull_requests(number: int, open_only: bool = False) → list[dict]

Pull requests attached to issue number, via its timeline.

A PR that references the issue (Fixes #N, or a manual link) leaves a cross-referenced timeline event whose source is a PR; we collect those. Each result is {"number": int, "state": str} (state is the PR’s open/closed, deduped by number). open_only keeps just open PRs.

Note: relies on cross-reference events (the common case, incl. the closing-keyword link). A PR linked ONLY via the sidebar with no cross-reference may not appear.

Github Pulls Node

Read-only GitHub pull-request client, exposed as a chia service-pattern node.

Companion to chia.github.github_issues_node.GithubIssuesNode, sharing the same repo-bound, head-node-only conventions and the chia.github.github_client.GithubClient HTTP plumbing. Use this for pull-request metadata and — its main purpose — reading the REVIEW FEEDBACK on a PR (review summaries + inline line comments + conversation comments) so an agent can act on it like a PR author.

Errors raise the typed exceptions from chia.github.github_client.

class chia.github.github_pulls_node.GithubPullsNode(repo: str, token: str | None = None, timeout_seconds: int = 30, logging_level: int = 10)

Bases: GithubClient

Read-only client for one GitHub repo’s pull requests.

Bind to one repo at construction, then:

• recent() — list the newest PRs (open/closed/all, per call).

• get_pull() — PR metadata (branches, head sha, draft/merged, body).

• pull_diff() — the PR’s current unified diff as raw text.

• check_runs() — CI check results (+ annotations for failures).

• reviews() — submitted review summaries.

• review_comments() — inline, line-anchored review comments.

• conversation_comments() — general (non-inline) conversation comments.

• review_feedback() — all of the above bundled into a GithubPullFeedback (with to_markdown() for LLM input).

recent(n: int = 1, after: int | None = None, state: str = 'open') → list[GithubPull]

Return up to n most-recent pull requests (sorted by created desc).

With after=None, the n newest PRs; with after=K, the n newest PRs whose number is strictly less than K. state is "open" / "closed" / "all" (per-call — this node binds no state at construction).

Note: the /pulls LIST payload omits the computed merged flag; merged on results from this method is derived from merged_at (equivalent for merged-vs-not).

get_pull(number: int) → GithubPull

Fetch one PULL REQUEST’s metadata by number.

Unlike the shared issues endpoint, /pulls/{number} serves ONLY pull requests — a plain issue number 404s even though it exists in the shared number space. That 404 is re-raised with a clearer message, since “not found” usually means “exists, but as an issue”. For issues use chia.github.github_issues_node.GithubIssuesNode.get_issue().

get(number: int) → GithubPull

Deprecated alias for get_pull().

pull_diff(number: int) → str

The PR’s CURRENT unified diff (head vs base), as raw text.

Uses the application/vnd.github.diff media type on the single-PR endpoint — this is the diff of the PR as it exists NOW (rebases and force-pushes included), which makes it the authoritative base for reconstructing the PR’s state. GitHub refuses very large diffs (~20k+ lines) with a 406, surfaced as GithubRequestError.

reviews(number: int) → list[GithubReview]

Submitted review summaries on PR number (oldest first).

review_comments(number: int) → list[GithubReviewComment]

Inline, line-anchored review comments on PR number (oldest first).

conversation_comments(number: int) → list[GithubComment]

General (non-inline) conversation comments on PR number.

PRs share the issue number space, so these come from the issues comments endpoint — the back-and-forth that isn’t anchored to a line.

check_runs(number: int, head_sha: str | None = None, annotations_for_failures: bool = True) → list[GithubCheckRun]

CI check results on PR number’s head commit (latest run per check).

Uses the Checks API with filter=latest so a re-run replaces its earlier attempt. For FAILED runs (conclusion failure/timed_out), also fetches the run’s file/line annotations — typically the compiler/test errors — capped at 50 per run. head_sha avoids a refetch of the PR when the caller already has it.

review_feedback(number: int, include_conversation: bool = True, include_checks: bool = True) → GithubPullFeedback

Bundle the PR + its reviews, inline comments, (optionally) the conversation comments, and (optionally) the CI check results into one GithubPullFeedback. A PR with no human feedback but FAILING CI is NOT is_empty() — red CI counts as feedback to act on.

State Def

class chia.github.state_def.GithubComment(author: str, created_at: str, body: str)

Bases: object

class chia.github.state_def.GithubIssue(number: int, title: str, state: str, author: str, created_at: str, updated_at: str, closed_at: str | None, body: str, labels: list[str], url: str, is_pull_request: bool, comments: list[chia.github.state_def.GithubComment] = <factory>)

Bases: object

to_markdown() → str

Render the issue + comments as one LLM-ready text blob.

class chia.github.state_def.GithubReview(author: str, state: str, body: str, submitted_at: str)

Bases: object

A submitted review on a PR (the summary, not the inline comments).

class chia.github.state_def.GithubReviewComment(author: str, path: str, line: int | None, body: str, diff_hunk: str, in_reply_to: int | None, created_at: str, id: int)

Bases: object

An inline (line-anchored) review comment on a PR’s diff.

class chia.github.state_def.GithubPull(number: int, title: str, state: str, author: str, body: str, base_ref: str, head_ref: str, head_sha: str, draft: bool, merged: bool, url: str)

Bases: object

A pull request’s metadata (separate from issue/PR-as-issue).

class chia.github.state_def.GithubCheckAnnotation(path: str, start_line: int, end_line: int, level: str, message: str, title: str = '')

Bases: object

A file/line-anchored message a CI check attached to its run.

class chia.github.state_def.GithubCheckRun(name: str, status: str, conclusion: str, summary: str, url: str, annotations: list[GithubCheckAnnotation] = <factory>)

Bases: object

One CI check’s latest result on a PR’s head commit.

class chia.github.state_def.GithubPullFeedback(pull: GithubPull, reviews: list[GithubReview] = <factory>, review_comments: list[GithubReviewComment] = <factory>, conversation_comments: list[GithubComment] = <factory>, check_runs: list[GithubCheckRun] = <factory>)

Bases: object

Everything a PR author needs to act on a review round: the PR plus its reviews, inline review comments, general conversation comments, and the CI check results on its head commit.

is_empty() → bool

True if there is nothing to act on: no reviews/comments AND no failing CI checks (green/neutral CI alone is not feedback).

to_markdown() → str

Render the review feedback as one LLM-ready, reviewer-style blob.

Inline comments are numbered [C1], [C2], … so an author can reference them when replying. Each shows its file, line, the diff hunk it anchors to, and the reviewer’s text.