GitHub API Client Wrapper

Relevant source files

The following files were used as context for generating this wiki page:

• src/github/mod.rs
• src/main.rs
• src/sync.rs
• src/config.rs
• AGENTS.md

The GitHub API Client Wrapper, implemented via the GitHubClient struct, provides a high-level interface for interacting with GitHub services. It abstracts the complexities of authentication, repository discovery, and low-level Git operations. The wrapper uses the octocrab crate to perform HTTP requests and manage API interactions.

Sources: src/github/mod.rs:10-15, AGENTS.md:32, Cargo.toml:19

Authentication Architecture

The GitHubClient supports three primary authentication methods: GitHub App authentication, Personal Access Tokens (PAT), and the standard GITHUB_TOKEN. When you use a PAT for Git writes, the client implements a "dual-token" pattern. It uses the ORCASTRATE_TOKEN for repository modifications and the GITHUB_TOKEN for Pull Request operations.

Sources: src/main.rs:118-176, AGENTS.md:52-58

Authentication Methods

Auth Method	Required Environment Variables	Purpose
GitHub App	ORCASTRATE_APP_ID, ORCASTRATE_PRIVATE_KEY, ORCASTRATE_INSTALLATION_ID	Single token for all operations. Recommended for organization-scale management.
Mixed PAT	ORCASTRATE_TOKEN, GITHUB_TOKEN	Dual-token mode. PAT handles Git writes; GITHUB_TOKEN handles PRs/Issues.
PAT Only	ORCASTRATE_TOKEN or GITHUB_TOKEN	Single token for all operations.

Sources: src/main.rs:123-176, AGENTS.md:52-58

Client Construction Flow

The diagram shows the logic within src/main.rs that determines which authentication strategy to initialize based on available environment variables.

Sources: src/main.rs:118-176

Git Operations and Repository Management

The client manages files using the GitHub Git Data API rather than the Contents API. This design choice bypasses security restrictions that often prevent the Contents API from modifying files within the .github/workflows/ directory.

Sources: AGENTS.md:42-44

Data Flow for Committing Files

When updating workflows, the client follows a specific sequence of low-level Git operations to ensure atomicity and proper reference updates.

The sequence diagram illustrates the three-step process for committing changes using the Git Data API as implemented in commit_files.

Sources: src/github/mod.rs:136-224

Repository Discovery

The client discovers repositories through two mechanisms: explicit configuration and organization-wide topic search. The discover_repos function queries the GitHub Search API for repositories belonging to a specific organization, optionally filtered by a topic.

Sources: src/github/mod.rs:356-394, src/config.rs:29-33

Discovery Logic

1. The orchestrator loads the DiscoveryConfig from orchestrator.toml.
2. The client constructs a search query (e.g., org:myorg topic:managed-workflows).
3. The client paginates through search results until all matching repositories are retrieved.
4. The sync module merges discovered repositories with those explicitly listed in the repos configuration.

Sources: src/github/mod.rs:356-394, src/sync.rs:188-216

Core API Methods

Method	Description	API Endpoints / Logic
list_workflows	Retrieves workflow files from .github/workflows.	GET /repos/{owner}/{repo}/contents/.github/workflows
get_file_content	Downloads and decodes a file's content.	GET /repos/{owner}/{repo}/contents/{path}
create_branch	Creates or force-updates a Git reference.	POST /git/refs or PATCH /git/refs/heads/{branch}
commit_files	Creates a new Git tree and commit for multiple files.	POST /git/trees, POST /git/commits
create_pr	Opens a new Pull Request and adds optional labels.	POST /pulls, POST /issues/{number}/labels
discover_repos	Searches for repositories by organization and topic.	GET /search/repositories

Sources: src/github/mod.rs:56-394

Dry Run Mode

The GitHubClient includes a dry_run flag. When this flag is true, the client logs intended write operations (such as creating branches, commits, PRs, or issues) to the console instead of executing the API calls. This allows users to preview changes without modifying remote repositories.

Sources: src/github/mod.rs:107-111, src/github/mod.rs:137-145, src/github/mod.rs:244-252

Error Handling

The client maps octocrab errors to the project's internal Error::GitHub variant. It includes specialized logic to detect specific HTTP status codes:

• 404 Not Found: Handled via is_not_found to treat missing directories as empty lists.
• 422 Unprocessable Entity: Handled via is_unprocessable to identify when a branch already exists, triggering a force-update instead of a new creation.

Sources: src/github/mod.rs:72-76, src/github/mod.rs:120-134, src/github/mod.rs:397-403

The GitHub API Client Wrapper provides a robust, authenticated bridge between the orcastrate logic and the GitHub platform. By utilizing the Git Data API and supporting diverse authentication schemes, it ensures that workflow management remains secure and functional across large organizations.