Struct GhHttp 

pub struct GhHttp { /* private fields */ }

Native HTTP client for the GitHub API with connection pooling and proactive rate-limit avoidance.

Implementations

impl GhHttp

pub fn new() -> Result<Self>

Create a new client backed by the process-wide shared [TokenResolver].

Token is resolved lazily on first request: GH_TOKEN → GITHUB_TOKEN → gh.auth.token config → gh auth token CLI The result is cached in the shared resolver for the life of the process, so gh auth token is only called once regardless of how many instances are created.

pub fn is_rate_limited() -> Option<Duration>

Check if the REST GitHub API is currently rate-limited (backoff or approaching limit). Used by the engine to decide whether to skip a tick.

pub async fn graphql_with_vars( &self, query: &str, variables: Value, ) -> Result<Value>

pub async fn graphql_with_headers( &self, query: &str, headers: &[&str], ) -> Result<Value>

pub async fn graphql_with_headers_and_vars( &self, query: &str, headers: &[&str], variables: Value, ) -> Result<Value>

pub async fn auth_status(&self) -> Result<()>

Verify authentication by fetching the current user.

Returns detailed error messages for common auth failures to help users diagnose configuration issues at startup.

pub async fn create_issue( &self, repo: &str, title: &str, body: &str, labels: &[String], ) -> Result<GitHubIssue>

Create a GitHub issue.

pub async fn update_issue( &self, repo: &str, number: u64, title: &str, body: &str, labels: &[String], ) -> Result<GitHubIssue>

Replace an issue’s title, body and labels.

Labels replace the full set. Callers pass labels they want to keep

pub async fn list_blocked_by( &self, repo: &str, issue_number: u64, ) -> Result<BlockedByFetch>

List issues that block issue_number.

GET /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by. GA since 2025-08-21, no preview media type. This call sends X-GitHub-Api-Version: 2026-03-10 and Accept: application/vnd.github+json. 404 and 403 (except rate limit) are Unavailable. Transport errors and 5xx are Failed, so the caller does not drop stored links

pub async fn add_blocked_by( &self, repo: &str, issue_number: u64, blocking_issue_id: i64, ) -> Result<()>

POST /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by with {"issue_id": blocking_issue_id}. Same API version as list_blocked_by. 201 is success. A body that says the link already exists is also success

pub async fn remove_blocked_by( &self, repo: &str, number: u64, blocking_issue_id: u64, ) -> Result<()>

Remove a blocked-by link. issue_id in the path is the blocking issue’s database id

pub async fn get_issue(&self, repo: &str, number: &str) -> Result<GitHubIssue>

Get a single issue.

pub async fn is_pull_request(&self, repo: &str, number: &str) -> bool

Check whether an issue number refers to a pull request.

pub async fn list_issues( &self, repo: &str, label: &str, ) -> Result<Vec<GitHubIssue>>

List issues filtered by a label (paginated).

pub async fn list_issues_with_state( &self, repo: &str, label: &str, state: &str, ) -> Result<Vec<GitHubIssue>>

List issues filtered by a label and issue state (paginated).

state is passed directly to the GitHub API: "open", "closed", or "all".

pub async fn list_issues_closed_since( &self, repo: &str, label: &str, since: &str, ) -> Result<Vec<GitHubIssue>>

List closed issues updated since since (ISO 8601), filtered by label.

Used for dedup checks — prevents re-creating issues that were recently closed.

pub async fn list_closed_issues_since( &self, repo: &str, since: &str, ) -> Result<Vec<GitHubIssue>>

List closed issues updated since since (ISO 8601), no label filter.

pub async fn list_all_open_issues( &self, repo: &str, since: Option<&str>, ) -> Result<Vec<GitHubIssue>>

List all open issues (no label filter, paginated).

When since is Some(ts), only returns issues updated after that ISO 8601 timestamp. This is more efficient for periodic syncs — GitHub filters server-side.

pub async fn list_open_pulls(&self, repo: &str) -> Result<Vec<Value>>

List open pull requests (paginated) using the REST pulls endpoint. Returns raw JSON values for flexibility in callers.

pub async fn list_all_issues(&self, repo: &str) -> Result<Vec<GitHubIssue>>

List all issues (open and closed, no label filter, paginated).

This is more efficient than making separate calls for open and closed.

pub async fn add_labels( &self, repo: &str, number: &str, labels: &[String], ) -> Result<()>

Add labels to an issue.

pub async fn ensure_label( &self, repo: &str, name: &str, color: &str, description: &str, ) -> Result<()>

Ensure a label exists on the repo, creating it if needed.

pub async fn remove_label( &self, repo: &str, number: &str, label: &str, ) -> Result<()>

Remove a label from an issue.

pub async fn add_comment( &self, repo: &str, number: &str, body: &str, ) -> Result<()>

Add a comment to an issue.

pub async fn post_commit_status( &self, repo: &str, sha: &str, state: &str, context: &str, description: &str, ) -> Result<()>

Post a commit status. state is one of pending, success, failure, error.

pub async fn add_reaction( &self, repo: &str, number: &str, content: &str, ) -> Result<()>

Add a reaction to an issue.

Supported content values: “+1”, “-1”, “laugh”, “confused”, “heart”, “hooray”, “rocket”, “eyes”

pub async fn add_comment_reaction( &self, repo: &str, comment_id: &str, content: &str, ) -> Result<()>

Add a reaction to an issue comment.

Supported content values: “+1”, “-1”, “laugh”, “confused”, “heart”, “hooray”, “rocket”, “eyes”

pub async fn list_comments( &self, repo: &str, number: &str, ) -> Result<Vec<GitHubComment>>

List comments on an issue.

pub async fn is_pr_merged(&self, repo: &str, branch: &str) -> Result<bool>

Check if a PR with the given branch was merged.

pub async fn get_closed_pr_state( &self, repo: &str, branch: &str, ) -> Result<Option<(u64, bool, String)>>

Get the state of a closed PR for the given branch.

Returns Some((merged, state)) if a closed PR exists for the branch, where merged indicates if it was merged and state is the PR state (“closed” or “merged”). Returns None if no closed PR exists for the branch. Get the state of a closed PR for a given branch.

Returns Some((pr_number, merged, state)) if a closed PR is found that matches the expected branch. Returns None if no matching closed PR is found.

Validates that the returned PR’s head ref matches the expected branch to prevent incorrect merge decisions when multiple PRs exist for the same branch.

pub async fn batch_is_pr_merged_by_branch( &self, repo: &str, branches: &[String], ) -> Result<HashMap<String, bool>>

Batch-check whether the PR for each branch was merged via a single GraphQL query.

Returns a map of branch → merged. Branches with no matching PR are omitted (callers should treat missing entries as not merged).

pub async fn get_mentions( &self, repo: &str, since: &str, ) -> Result<Vec<GitHubComment>>

Get issue/PR comments since a given timestamp (paginated).

pub async fn get_issue_comments( &self, repo: &str, issue_number: u64, ) -> Result<Vec<GitHubComment>>

Get all comments for a specific issue number.

pub async fn get_whoami(&self) -> Result<String>

Get the current authenticated username (cached after first call).

pub async fn get_pr_number( &self, repo: &str, branch: &str, ) -> Result<Option<u64>>

Get PR number by branch name.

pub async fn create_pr( &self, repo: &str, title: &str, body: &str, head: &str, base: &str, ) -> Result<String>

Create a new pull request.

Arguments

• repo - Repository in “owner/repo” format
• title - PR title
• body - PR body/description
• head - Branch name to create PR from
• base - Base branch to merge into (e.g., “main”)

Returns the created PR’s URL on success.

pub async fn get_default_branch(&self, repo: &str) -> Result<String>

Get the repository’s default branch from the GitHub API.

Used as a fallback when local git detection yields an invalid base branch for PR creation.

pub async fn get_pr( &self, repo: &str, pr_number: u64, ) -> Result<GitHubPullRequest>

Get PR details by PR number. Returns the full PR object including the mergeable field.

pub async fn batch_get_pr_states( &self, repo: &str, pr_numbers: &[u64], ) -> Result<HashMap<u64, (bool, String)>>

Fetch the merged/state for multiple PRs in a single GraphQL query.

Returns a map of pr_number → (merged, state). PRs that fail to fetch are silently omitted from the result.

pub async fn batch_get_issue_states( &self, repo: &str, issue_numbers: &[u64], caller_context: &str, ) -> Result<HashMap<String, (String, Vec<String>)>>

Batch-fetch state and labels for multiple GitHub issues in a single GraphQL request.

Returns a map of issue number (as string) → (state, labels) where state is lowercase (“open” / “closed”) to match the REST API convention used elsewhere.

pub async fn get_required_status_check_contexts( &self, repo: &str, branch: &str, ) -> Result<Vec<String>>

Get the required status check contexts for a branch.

pub async fn get_commit_status_contexts( &self, repo: &str, sha: &str, ) -> Result<Vec<(String, String)>>

Get commit status contexts for a SHA.

pub async fn has_workflows(&self, repo: &str) -> Result<bool>

Return true when the repository has at least one GitHub Actions workflow.

This is used to distinguish repos that genuinely have no CI configured from repos where CI exists but GitHub has not surfaced any runs yet.

pub async fn get_check_runs( &self, repo: &str, sha: &str, ) -> Result<Vec<GitHubCheckRun>>

Get check runs for a PR head SHA.

pub async fn get_check_run_annotations( &self, repo: &str, check_run_id: u64, ) -> Result<Vec<GitHubAnnotation>>

Get annotations for a specific check run.

Returns the list of annotations attached to the check run, including billing failure messages (“The job was not started because recent account payments have failed …”) that GitHub surfaces as annotations rather than as a distinct CI conclusion value.

pub async fn get_pr_reviews( &self, repo: &str, pr_number: u64, ) -> Result<Vec<GitHubReview>>

Get reviews for a PR.

pub async fn get_commit_timestamp( &self, repo: &str, sha: &str, ) -> Result<String>

Get the committer timestamp for a specific commit SHA.

Returns an ISO-8601 string, e.g. "2024-01-15T12:00:00Z". Used to determine whether the branch has been updated since a review was submitted.

pub async fn update_pr_body( &self, repo: &str, pr_number: u64, body: &str, ) -> Result<()>

Update the body of a pull request.

pub async fn close_pr(&self, repo: &str, pr_number: u64) -> Result<()>

Close a pull request without merging it.

pub async fn compare_behind_by( &self, repo: &str, base: &str, head_sha: &str, ) -> Result<u64>

How many commits the head is missing from base (GitHub’s behind_by).

Zero means the head already contains the current base tip, so its checks ran against the code the merge would produce.

pub async fn close_issue(&self, repo: &str, number: &str) -> Result<()>

Close a GitHub issue.

pub async fn reopen_issue(&self, repo: &str, number: &str) -> Result<()>

Reopen a closed GitHub issue.

pub async fn is_collaborator(&self, repo: &str, username: &str) -> Result<bool>

Check if a user is a collaborator.

pub async fn add_sub_issue( &self, parent_node_id: &str, child_node_id: &str, ) -> Result<()>

Add a sub-issue relationship via GraphQL.

pub async fn link_issue_to_branch( &self, repo: &str, issue_number: u64, branch: &str, ) -> Result<String>

Link an issue to a branch using GraphQL.

Creates a “Development” sidebar link in GitHub that connects the issue to the branch, similar to gh issue develop.

Arguments

• repo - Repository in “owner/repo” format
• issue_number - The issue number to link
• branch - The branch name to link the issue to

Returns the linked branch ID on success.

pub async fn merge_pr( &self, repo: &str, pr_number: u64, delete_branch: bool, ) -> Result<()>

Merge a PR using the REST API (squash merge).

pub async fn update_pr_branch(&self, repo: &str, pr_number: u64) -> Result<()>

Update a PR’s branch by merging the latest base branch into it (equivalent of the “Update branch” button on GitHub, or gh pr update-branch). Produces a new merge commit on the head branch, which re-triggers CI — used to give a PR a chance to pick up a fix that landed on the base branch after the PR’s last CI run failed.

pub async fn enable_auto_merge(&self, repo: &str, pr_number: u64) -> Result<()>

Enable auto-merge on a PR via GraphQL.

GitHub will automatically merge the PR once all required checks pass.

pub async fn get_sub_issues(&self, repo: &str, number: &str) -> Result<Vec<u64>>

Get sub-issues via GraphQL (paginated).

pub async fn get_combined_status( &self, repo: &str, git_ref: &str, has_workflows: bool, mergeable_state: Option<&str>, ) -> Result<(String, u64, u64, u64, u64)>

Get combined CI check status for a git ref.

pub async fn rerun_failed_workflow( &self, repo: &str, workflow_name: &str, branch: &str, ) -> Result<()>

Rerun the latest failed workflow run for a given workflow name and branch.

Finds the most recent failed (or cancelled) run of workflow_name on branch triggered by a push event, then calls the GitHub Actions rerun endpoint so the same check run on the commit flips green.

pub async fn batch_fetch_pr_review_data( &self, repo: &str, pr_numbers: &[u64], ) -> Result<HashMap<u64, PrReviewBatchData>>

Fetch reviews, review comments, and issue comments for multiple PRs in a single GraphQL query instead of 4–5 REST calls per PR.

Returns a map of pr_number → PrReviewBatchData. PRs missing from the response are omitted from the result.

pub async fn get_automated_review_status( &self, repo: &str, pr_number: u64, ) -> Result<Option<String>>

Check the latest automated review comment on a PR.

Trait Implementations

impl Clone for GhHttp

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.