github-rust 0.2.3

Rust library for GitHub API integration with GraphQL/REST support
Documentation

github-rust

An async Rust library for GitHub accounts, repositories, open issues and pull requests, search and stargazer access through REST and GraphQL.

Installation

Requires Rust 1.92 or later (edition 2024).

[dependencies]
github-rust = { git = "https://github.com/davlgd/github-rust" }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

Quick start

use github_rust::{GitHubService, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let service = GitHubService::new()?;
    let repo = service.get_repository_info("rust-lang", "rust").await?;
    println!("{}: {} stars", repo.name_with_owner, repo.stargazer_count);
    println!("Node ID: {}", repo.node_id);
    if let Some(id) = repo.database_id {
        println!("Database ID: {id}");
    }
    if let Some(count) = repo.open_issues() {
        println!("Open issues: {count}");
    }
    Ok(())
}

Without a token, repository lookups use REST directly. With a token, they use GraphQL and fall back to REST only on HTTP 502, 503 or 504. Authentication, authorization, quota and decoding errors are returned without fallback. A failed fallback retains both causes in GitHubError::FallbackError.

Configuration and authentication

GitHubService::new() reads GITHUB_TOKEN from the environment. An unset, empty or whitespace-only value selects anonymous access:

export GITHUB_TOKEN="your-token"

The library does not load .env files. Load them in your application if needed.

For explicit configuration, use the builder. It does not read the environment and is anonymous unless a token is supplied:

use github_rust::{FallbackPolicy, GitHubClient, GitHubService};

fn main() -> github_rust::Result<()> {
    let client = GitHubClient::builder().token("your-token".into()).build()?;
    let service = GitHubService::with_client(client).with_fallback_policy(FallbackPolicy::Never);
    Ok(())
}

The builder also accepts rest_url, graphql_url, and an injected reqwest::Client through http_client. This supports local mocks and GitHub Enterprise endpoints. Configure both URLs for a custom installation; API availability depends on the server version and permissions. Custom endpoints receive the token, so use trusted URLs. An injected transport controls its own timeout, proxy and redirect policy; the default transport has a 30-second request timeout.

The retained token uses secrecy::SecretString and is zeroized when dropped. HTTP requests also contain copies of its value in authorization headers; those copies are not covered by this zeroization guarantee. GitHubClient::client() exposes the raw transport without the library's authentication headers.

Repository data

Repository models use Rust field names in JSON. The shared License type retains spdxId for its spdx_id field; this also applies inside license_info.

  • node_id is an opaque string. database_id is an optional numeric ID. Do not decode node IDs.
  • watcher_count counts notification subscribers, independently of stargazer_count.
  • open_issue_count excludes pull requests. It is unavailable from the REST repository response.
  • pull_request_count includes all states, and release_count counts releases. Both are unavailable from the REST repository response.
  • An unavailable count is None; an observed zero is Some(0).
  • topics is a Vec<String>; default_branch is an Option<String>.
  • languages is an optional list of LanguageUsage { language, bytes }. A REST 404 for the language breakdown produces None. Other failures are returned. GraphQL retrieves up to 100 languages; check languages_complete before treating the list as exhaustive.

Helpers include language(), license(), license_spdx(), topics(), owner(), default_branch(), open_issues() and watcher_count().

Accounts, issues and pull requests

These methods require a token. Empty repository batches return an empty list without authentication or callbacks.

Method Returns
get_viewer() Authenticated account and its visible organizations
get_owned_repositories(login) Repositories owned by a user or organization
get_open_issues(owner, name) Open issues with authors, labels, assignees and comment counts
get_open_pull_requests(owner, name) Open PRs, including draft status and review decisions

Repository inventories include visible private repositories, forks and archives. For batch calls, select repositories in your application and convert them with RepositorySummary::coordinates().

Page streams

Process results incrementally with page streams:

Method Page type
get_owned_repository_pages(login) RepositoryPage
get_open_issue_pages(scopes) WorkItemPage<Issue>
get_open_pull_request_pages(scopes) WorkItemPage<PullRequest>
use futures_util::TryStreamExt;
use std::pin::pin;

async fn example(service: &github_rust::GitHubService) -> github_rust::Result<()> {
    let mut pages = pin!(service.get_owned_repository_pages("rust-lang"));
    while let Some(page) = pages.try_next().await? {
        println!("Received {} repositories", page.repositories.len());
    }
    Ok(())
}
  • Streams are Send + 'static and own their client and scope. Add futures-util = "0.3" to use TryStreamExt.
  • Each page transfers to the caller without cloning its contents or buffering the full result. Traversal retains IDs and cursors for consistency checks.
  • Requests advance when the stream is polled. Dropping it cancels traversal; the first error ends it.
  • Validation errors are stream items. Pages arrive in API/completion order and remain provisional until the entire stream finishes successfully.

See page_streams.rs for processing pages in a Tokio task.

Callbacks

Use get_owned_repositories_with_progress(), get_open_issues_with_progress() or get_open_pull_requests_with_progress() to receive borrowed pages and a final collected result:

async fn example(service: &github_rust::GitHubService) -> github_rust::Result<()> {
    let scopes = [github_rust::RepositoryCoordinates::new(
        "rust-lang",
        "rust",
    )?];
    let issues = service
        .get_open_issues_with_progress(&scopes, async |page| {
            println!("Received {} issues", page.items.len());
            Ok(())
        })
        .await?;
    println!("Complete: {} issues", issues.len());
    Ok(())
}
  • Callbacks borrow pages without copying them and run serially in arrival order.
  • Pages remain provisional until the call succeeds. Return an error or drop the future to cancel.
  • Final issue and PR lists sort by update time descending, then node ID.
  • Use get_open_*_for_repositories() when you only need the final list.

See account_overview.rs for account discovery, repository filtering and batch calls.

Limits

Configure collection limits with GitHubService::with_fetch_options():

FetchOptions field Default Valid values
page_size 100 nodes 1–100
max_pages 500 per connection At least 1
max_concurrent_repositories 4 per call At least 1
  • The product of max_pages and page_size must fit in usize. Invalid limits return an error naming the field.
  • Changing totals, duplicate IDs, invalid cursors and repository scope changes produce errors.
  • Reaching a page cap or receiving incomplete labels or assignees produces a pagination error. Embedded metadata is limited to 100 labels and 100 assignees per item.
  • GitHub does not provide a snapshot across pages; concurrent changes may remain undetected.

Search

Repository search requires a token and uses GraphQL:

async fn example(service: &github_rust::GitHubService) -> github_rust::Result<()> {
    let repos = service
        .search_repositories(30, 100, Some("Rust"), 50)
        .await?;
    for repo in repos {
        println!("{}: {} stars", repo.name_with_owner, repo.stargazer_count);
    }
    Ok(())
}

Search selects public repositories created after the date days_back days ago, with at least min_stars, ordered by stars descending. It caps results at 1,000 and requests only the number still needed. A zero limit returns an empty list without a request. Invalid dates or language syntax produce InvalidInput; missing, repeated or nonprogressing pagination cursors produce PaginationError.

Stargazers and starred repositories

async fn example(service: &github_rust::GitHubService) -> github_rust::Result<()> {
    let stargazers = service
        .get_repository_stargazers("owner", "repo", Some(100), Some(1))
        .await?;
    for star in stargazers {
        println!("{} starred at {}", star.user.login, star.starred_at);
    }
    Ok(())
}

GitHub announced restrictions on stargazer listings to administrators and collaborators. A public repository alone does not guarantee access: GitHub documents possible empty responses or HTTP 403. This method reflects the server's response and cannot distinguish an access-filtered empty list from a repository with no stars. It is not a general public star-history API.

per_page defaults to 30 and is capped at 100; page defaults to 1. Zero values are rejected. The first page is not guaranteed to contain the most recent stars.

get_user_profile() and get_user_starred_repositories() require an authorized token. The starred-repository helper returns repository names and stops after 100 pages. If another page is needed at that point, it returns PaginationError instead of returning a silently truncated list.

Quotas and errors

Use GitHubError::kind() for application-facing messages. Raw Display output preserves upstream details and should stay in trusted diagnostics.

async fn example(service: &github_rust::GitHubService) -> github_rust::Result<()> {
    let quotas = service.check_rate_limits().await?;
    for (resource, limit) in quotas.resources {
        println!("{resource}: {}/{} remaining", limit.remaining, limit.limit);
        println!("Reset: {:?}", limit.reset_datetime());
    }
    Ok(())
}

check_rate_limit() is a convenience method for the REST core quota. Search and GraphQL have separate quotas; token presence alone does not establish the available allowance. RateLimit provides used(), is_exceeded(), time_until_reset() and reset_datetime(); an unrepresentable timestamp returns None from the last helper.

RateLimitError contains RateLimitDetails: the HTTP status, resource, remaining allowance, reset timestamp, original Retry-After, request ID and GraphQL errors when present. The library does not automatically sleep or retry. Applications can use this metadata to implement a bounded retry policy.

Other errors distinguish authentication, permission denial, unavailable resources, legal restrictions, API status errors, typed GraphQL errors, pagination and response parsing. Transport and decoding errors preserve their original std::error::Error::source() chains. GraphQL errors are returned even if the response also includes partial data.

Development

cargo fmt --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --all-targets --locked
cargo test --doc --locked
cargo doc --no-deps --locked

Tests use local HTTP mocks and do not require a token or contact GitHub. The single live API test is ignored by default; run it explicitly with cargo test --test github_api_tests test_real_github_api_rate_limit -- --ignored.

CI checks Rust 1.92 and stable on Linux, plus stable on macOS. Dependabot checks Cargo dependencies and GitHub Actions monthly. Examples:

cargo run --example basic_usage
GITHUB_TOKEN=your-token cargo run --example search_repositories
cargo run --example stargazers -- owner/repo

License

Apache-2.0.