Struct InstallationClient

Source

pub struct InstallationClient { /* private fields */ }

Expand description

Installation-scoped GitHub API client.

Holds a reference to the parent GitHubClient for shared HTTP client, auth provider, and rate limiter. All operations use installation tokens.

Implementations§

Source §

impl InstallationClient

Source

pub async fn get_commit( &self, owner: &str, repo: &str, ref_name: &str, ) -> Result<FullCommit, ApiError>

Get a single commit by SHA, branch name, or tag name.

Retrieves complete commit details including the author, committer, commit message, parent references, and GPG verification status.

§Arguments

owner - Repository owner login
repo - Repository name
ref_name - Commit SHA (full or abbreviated), branch name, or tag name

§Returns

Returns a FullCommit with complete metadata.

§Errors

ApiError::NotFound - Commit or ref doesn’t exist, or repository not found
ApiError::InvalidRequest - Invalid ref syntax or empty repository (GitHub returns 422)
ApiError::AuthorizationFailed - Missing contents:read permission
ApiError::AuthenticationFailed - Token expired or invalid
ApiError::HttpError - Unexpected API response

§Examples

// Get by SHA
let commit = client.get_commit("owner", "repo", "abc123def456").await?;
println!("Message: {}", commit.commit.message);

// Get by branch name
let head = client.get_commit("owner", "repo", "main").await?;
println!("HEAD: {}", head.sha);

// Get by tag
let release = client.get_commit("owner", "repo", "v1.0.0").await?;
println!("Release commit: {}", release.sha);

§GitHub API

GET /repos/{owner}/{repo}/commits/{ref}

See https://docs.github.com/en/rest/commits/commits#get-a-commit

Source

pub async fn list_commits( &self, owner: &str, repo: &str, sha: Option<&str>, path: Option<&str>, author: Option<&str>, since: Option<DateTime<Utc>>, until: Option<DateTime<Utc>>, per_page: Option<u32>, page: Option<u32>, ) -> Result<Vec<FullCommit>, ApiError>

List commits in a repository with optional filtering.

Returns commits in reverse chronological order (newest first). All filter arguments are combined with AND logic.

§Arguments

owner - Repository owner login
repo - Repository name
sha - SHA or branch name to start listing from (default: repository default branch)
path - Only return commits that modified this file path or directory
author - Filter by GitHub username or commit author email address
since - Only include commits after this timestamp (inclusive)
until - Only include commits before this timestamp (inclusive)
per_page - Number of results per page; clamped to the range 1..=100
page - Page number for pagination (1-based, default: 1)

§Returns

Returns a Vec<FullCommit> in reverse chronological order.

§Errors

ApiError::NotFound - Repository not found
ApiError::InvalidRequest - Repository is empty (GitHub returns 422)
ApiError::AuthorizationFailed - Missing contents:read permission
ApiError::AuthenticationFailed - Token expired or invalid
ApiError::HttpError - Unexpected API response

§Examples

// List recent commits on the default branch
let commits = client.list_commits(
    "owner", "repo",
    None, None, None, None, None, None, None
).await?;

// List commits on a feature branch
let feature_commits = client.list_commits(
    "owner", "repo",
    Some("feature-branch"), None, None, None, None, None, None
).await?;

// List commits affecting a specific file
let readme_commits = client.list_commits(
    "owner", "repo",
    None, Some("README.md"), None, None, None, Some(50), None
).await?;

// List commits by author in a date range
let since = "2026-01-01T00:00:00Z".parse::<DateTime<Utc>>()?;
let until = "2026-01-31T23:59:59Z".parse::<DateTime<Utc>>()?;
let author_commits = client.list_commits(
    "owner", "repo",
    None, None, Some("alice"), Some(since), Some(until), None, None
).await?;

§Notes

per_page is silently clamped to the range 1..=100 (GitHub API maximum is 100; 0 is raised to 1).
Empty repositories cause GitHub to return 422, mapped to ApiError::InvalidRequest.

§GitHub API

GET /repos/{owner}/{repo}/commits

See https://docs.github.com/en/rest/commits/commits#list-commits

Source

pub async fn compare_commits( &self, owner: &str, repo: &str, base: &str, head: &str, ) -> Result<Comparison, ApiError>

Compare two commits, branches, or tags.

Returns a complete comparison including the list of commits between the two refs and every file that changed, with per-file statistics. Useful for changelog generation and release notes automation.

§Arguments

owner - Repository owner login
repo - Repository name
base - Base ref (SHA, branch, or tag) — the starting point
head - Head ref (SHA, branch, or tag) — the ending point

§Returns

Returns a Comparison with commits, file changes, and statistics.

§Errors

ApiError::NotFound - Base or head ref not found, or repository not found
ApiError::AuthorizationFailed - Missing contents:read permission
ApiError::AuthenticationFailed - Token expired or invalid
ApiError::HttpError - Unexpected API response

§Examples

// Compare two tags for release notes
let cmp = client.compare_commits("owner", "repo", "v1.0.0", "v1.1.0").await?;

println!("Status: {}", cmp.status);
println!("Commits: {}", cmp.total_commits);
println!("Files changed: {}", cmp.files.len());

for commit in &cmp.commits {
    let subject = commit.commit.message.lines().next().unwrap_or("");
    println!("- {}", subject);
}

// Compare a feature branch to main
let branch_diff = client.compare_commits("owner", "repo", "main", "feature-x").await?;
match branch_diff.status.as_str() {
    "ahead"    => println!("Feature is {} commits ahead", branch_diff.ahead_by),
    "behind"   => println!("Feature is {} commits behind", branch_diff.behind_by),
    "identical" => println!("Branches are identical"),
    "diverged" => println!("Branches have diverged"),
    _ => {}
}

§Comparison Status Values

Status	Meaning
`"ahead"`	Head has commits not in base
`"behind"`	Base has commits not in head
`"identical"`	Both refs point to the same commit
`"diverged"`	Refs have different histories

§Notes

Commits are returned in chronological order (oldest to newest).
GitHub limits comparisons to 250 commits.
File patches may be absent for binary files or very large diffs.

§GitHub API

GET /repos/{owner}/{repo}/compare/{base}...{head}

See https://docs.github.com/en/rest/commits/commits#compare-two-commits

Source §

impl InstallationClient

Source

pub fn new(client: Arc<GitHubClient>, installation_id: InstallationId) -> Self

Create a new installation client.

§Arguments

client - Parent GitHubClient
installation_id - Installation ID to bind to

Source

pub fn installation_id(&self) -> InstallationId

Get the installation ID this client is bound to.

Source

pub async fn get(&self, path: &str) -> Result<Response, ApiError>

Make an authenticated GET request to the GitHub API.

Uses installation token for authentication and includes automatic retry logic for transient errors (5xx, 429, network failures).

§Arguments

path - API path (e.g., “/repos/owner/repo” or “repos/owner/repo”)

§Returns

Returns the raw reqwest::Response for flexible handling.

§Errors

Returns ApiError for HTTP errors, authentication failures, or network issues.

Source

pub async fn post<T: Serialize>( &self, path: &str, body: &T, ) -> Result<Response, ApiError>

Make an authenticated POST request to the GitHub API.

Includes automatic retry logic for transient errors.

§Arguments

path - API path
body - Request body (will be serialized to JSON)

§Errors

Returns ApiError for HTTP errors, serialization failures, or network issues.

Source

pub async fn put<T: Serialize>( &self, path: &str, body: &T, ) -> Result<Response, ApiError>

Make an authenticated PUT request to the GitHub API.

Includes automatic retry logic for transient errors.

Source

pub async fn delete(&self, path: &str) -> Result<Response, ApiError>

Make an authenticated DELETE request to the GitHub API.

Includes automatic retry logic for transient errors.

Source

pub async fn post_graphql<V: Serialize>( &self, query: &str, variables: V, ) -> Result<Value, ApiError>

Make an authenticated POST request to the GitHub GraphQL API.

GitHub’s GraphQL endpoint always returns HTTP 200 even for errors. Application-level errors are detected by checking the .errors array in the response body; the first error message is surfaced as ApiError::GraphQlError. On success, the .data value is returned.

Retry logic (backoff, 5xx, rate-limit handling) is identical to the REST helpers because the transport layer is the same.

§Arguments

query - GraphQL query or mutation string
variables - Variables object (serialised to JSON)

§Returns

Returns the data field from the GraphQL response as a serde_json::Value.

§Errors

ApiError::GraphQlError — GitHub returned .errors in the body
ApiError::GraphQlError — response body contains neither .errors nor a non-null .data field (malformed or unexpected response shape)
ApiError::AuthenticationFailed — HTTP 401
ApiError::JsonError — response body could not be parsed
Any other ApiError variant for HTTP-level failures

Source

pub async fn patch<T: Serialize>( &self, path: &str, body: &T, ) -> Result<Response, ApiError>

Make an authenticated PATCH request to the GitHub API.

Includes automatic retry logic for transient errors.

Source §

impl InstallationClient

Source

pub async fn list_issues( &self, owner: &str, repo: &str, state: Option<&str>, page: Option<u32>, ) -> Result<PagedResponse<Issue>, ApiError>

List issues in a repository.

Returns a paginated response with issues and pagination metadata. Use the pagination information to fetch subsequent pages if needed.

§Arguments

owner - Repository owner
repo - Repository name
state - Filter by state ("open", "closed", or "all")
page - Page number (1-indexed, omit for first page)

§Examples

// Get first page
let response = client.list_issues("owner", "repo", None, None).await?;
println!("Got {} issues", response.items.len());

// Check if more pages exist
if response.has_next() {
    if let Some(next_page) = response.next_page_number() {
        let next_response = client.list_issues("owner", "repo", None, Some(next_page)).await?;
        println!("Got {} more issues", next_response.items.len());
    }
}

Source

pub async fn get_issue( &self, owner: &str, repo: &str, issue_number: u64, ) -> Result<Issue, ApiError>

Get a specific issue by number.

Source

pub async fn create_issue( &self, owner: &str, repo: &str, request: CreateIssueRequest, ) -> Result<Issue, ApiError>

Create a new issue.

Source

pub async fn update_issue( &self, owner: &str, repo: &str, issue_number: u64, request: UpdateIssueRequest, ) -> Result<Issue, ApiError>

Update an existing issue.

Source

pub async fn set_issue_milestone( &self, owner: &str, repo: &str, issue_number: u64, milestone_number: Option<u64>, ) -> Result<Issue, ApiError>

Set the milestone on an issue.

Source

pub async fn list_labels( &self, owner: &str, repo: &str, ) -> Result<Vec<Label>, ApiError>

List all labels in a repository.

See docs/spec/interfaces/issue-operations.md

Source

pub async fn get_label( &self, owner: &str, repo: &str, name: &str, ) -> Result<Label, ApiError>

Get a specific label by name.

See docs/spec/interfaces/issue-operations.md

Source

pub async fn create_label( &self, owner: &str, repo: &str, request: CreateLabelRequest, ) -> Result<Label, ApiError>

Create a new label.

See docs/spec/interfaces/issue-operations.md

Source

pub async fn update_label( &self, owner: &str, repo: &str, name: &str, request: UpdateLabelRequest, ) -> Result<Label, ApiError>

Update an existing label.

See docs/spec/interfaces/issue-operations.md

Source

pub async fn delete_label( &self, owner: &str, repo: &str, name: &str, ) -> Result<(), ApiError>

Delete a label.

See docs/spec/interfaces/issue-operations.md

Source

pub async fn add_labels_to_issue( &self, owner: &str, repo: &str, issue_number: u64, labels: Vec<String>, ) -> Result<Vec<Label>, ApiError>

Add labels to an issue.

See docs/spec/interfaces/issue-operations.md

Source

pub async fn remove_label_from_issue( &self, owner: &str, repo: &str, issue_number: u64, name: &str, ) -> Result<Vec<Label>, ApiError>

Remove a label from an issue.

See docs/spec/interfaces/issue-operations.md

Source

pub async fn list_issue_comments( &self, owner: &str, repo: &str, issue_number: u64, ) -> Result<Vec<Comment>, ApiError>

List comments on an issue.

See docs/spec/interfaces/issue-operations.md

Source

pub async fn get_issue_comment( &self, owner: &str, repo: &str, comment_id: u64, ) -> Result<Comment, ApiError>

Get a specific comment by ID.

See docs/spec/interfaces/issue-operations.md

Source

pub async fn create_issue_comment( &self, owner: &str, repo: &str, issue_number: u64, request: CreateCommentRequest, ) -> Result<Comment, ApiError>

Create a comment on an issue.

See docs/spec/interfaces/issue-operations.md

Source

pub async fn update_issue_comment( &self, owner: &str, repo: &str, comment_id: u64, request: UpdateCommentRequest, ) -> Result<Comment, ApiError>

Update an existing comment.

See docs/spec/interfaces/issue-operations.md

Source

pub async fn delete_issue_comment( &self, owner: &str, repo: &str, comment_id: u64, ) -> Result<(), ApiError>

Delete a comment.

See docs/spec/interfaces/issue-operations.md

Source §

impl InstallationClient

Source

pub async fn list_organization_projects( &self, _org: &str, ) -> Result<Vec<ProjectV2>, ApiError>

List all Projects v2 for an organisation.

See docs/spec/interfaces/project-operations.md

Source

pub async fn list_user_projects( &self, _username: &str, ) -> Result<Vec<ProjectV2>, ApiError>

List all Projects v2 for a user.

See docs/spec/interfaces/project-operations.md

Source

pub async fn get_project( &self, _owner: &str, _project_number: u64, ) -> Result<ProjectV2, ApiError>

Get details about a specific project.

See docs/spec/interfaces/project-operations.md

Source

pub async fn add_item_to_project( &self, owner: &str, project_number: u64, content_node_id: &str, ) -> Result<ProjectV2Item, ApiError>

Add an issue or pull request to a project.

Resolves the project node ID from owner + project_number (trying organisation first, then falling back to user), then calls the addProjectV2ItemById GraphQL mutation to attach the content.

§Arguments

owner - Organisation or user login name
project_number - Project number (unique within owner)
content_node_id - Node ID of the issue or pull request to add

§Returns

Ok(ProjectV2Item) — the newly created project item
Err(ApiError::NotFound) — project not found for this owner
Err(ApiError::AuthorizationFailed) — no write access to the project
Err(ApiError) — other transport or GraphQL errors

Source

pub async fn get_issue_linked_projects( &self, owner: &str, repo: &str, issue_number: u64, ) -> Result<Vec<ProjectV2>, ApiError>

Get all Projects v2 linked to a specific issue.

Queries the GitHub GraphQL API for all Projects v2 that contain the given issue. Returns an empty Vec when the issue exists but is not linked to any projects. Results are fetched in pages of 20; all pages are retrieved automatically and returned as a single combined Vec.

§Arguments

owner - Repository owner (organisation or user login)
repo - Repository name
issue_number - Issue number

§Returns

Ok(Vec<ProjectV2>) — all projects linked to the issue (may be empty)
Err(ApiError::NotFound) — repository or issue does not exist
Err(ApiError::AuthenticationFailed) — token is invalid
Err(ApiError) — other transport or GraphQL errors

Source

pub async fn remove_item_from_project( &self, _owner: &str, _project_number: u64, _item_id: &str, ) -> Result<(), ApiError>

Remove an item from a project.

See docs/spec/interfaces/project-operations.md

Source §

impl InstallationClient

Source

pub async fn list_pull_requests( &self, owner: &str, repo: &str, state: Option<&str>, page: Option<u32>, ) -> Result<PagedResponse<PullRequest>, ApiError>

List pull requests in a repository.

Returns a paginated response with pull requests and pagination metadata. Use the pagination information to fetch subsequent pages if needed.