Authentication Methods
Relevant source files
The following files were used as context for generating this wiki page:
Orcastrate interacts with the GitHub API to perform repository discovery, file reads, and automated updates through Pull Requests or Issues. To support these operations, the system implements several authentication strategies, including Personal Access Tokens (PAT) and GitHub Apps.
Each authentication method grants the necessary permissions to manage workflows across repositories. The application distinguishes between read/write operations for git data and administrative operations like PR creation.
Sources: AGENTS.md:5-10, README.md:15-25
Authentication Strategies
Orcastrate supports three primary authentication configurations. The choice of method determines how the GitHubClient is constructed and which tokens authorize specific API calls.
Dual-Token PAT Authentication
This method uses two distinct tokens to separate concerns and scopes. The ORCASTRATE_TOKEN (a fine-grained PAT) authorizes Git data writes to protected workflow paths, while the standard GITHUB_TOKEN handles PR and issue management.
- ORCASTRATE_TOKEN: Requires
contents: write,pull-requests: write, andworkflows: writepermissions. - GITHUB_TOKEN: Handled automatically by GitHub Actions to manage PR metadata and labels.
Sources: README.md:143-155, src/main.rs:135-150
GitHub App Authentication
GitHub App authentication is the recommended method for organization-wide management. It utilizes a single installation token derived from an App ID and Private Key. This token authorizes all operations, including git writes and PR management.
Sources: README.md:157-165, AGENTS.md:55-58
Single Token Authentication
If only GITHUB_TOKEN or ORCASTRATE_TOKEN is provided without a secondary token, Orcastrate uses that single token for all operations. This is common for simpler setups or single-repository management.
Sources: src/main.rs:118-125, AGENTS.md:63
Authentication Matrix
The following table describes the behavior and identity associated with each authentication method:
| Auth Method | Git Writes Token | PR/Issue Token | Commit Author | PR Author |
|---|---|---|---|---|
| GitHub App | App Installation Token | App Installation Token | App (Implicit) | App Bot |
| PAT + GITHUB_TOKEN | ORCASTRATE_TOKEN | GITHUB_TOKEN | github-actions[bot] | github-actions[bot] |
| GITHUB_TOKEN only | GITHUB_TOKEN | GITHUB_TOKEN | github-actions[bot] | github-actions[bot] |
Sources: AGENTS.md:60-65
Implementation Logic
The build_client function in src/main.rs initializes the GitHubClient by checking environment variables in a specific order of precedence.
This diagram shows the priority logic used to select an authentication provider based on available environment variables.
Sources: src/main.rs:100-140
Client Components
The GitHubClient structure manages the Octocrab instances required for communication.
crab: The primary client used for most operations, including repository content and git data.pr_crab: An optional secondary client used specifically for Pull Request and Issue operations when using the Dual-Token PAT strategy.is_app_auth: A boolean flag indicating if the client is operating as a GitHub App, which affects how commit author metadata is set.
Sources: src/github/mod.rs:9-15, src/main.rs:152-154
Identity Management
When committing files via PAT, Orcastrate manually sets the author and committer to the GitHub Actions bot to ensure consistent history.
- Name:
github-actions[bot] - Email:
41898282+github-actions[bot]@users.noreply.github.com
GitHub App authentication handles this identity automatically via the installation token.
Sources: src/github/mod.rs:153-162, src/github/mod.rs:5-6
Configuration Reference
Authentication is configured via environment variables or GitHub Action inputs.
| Environment Variable | GitHub Action Input | Description |
|---|---|---|
ORCASTRATE_TOKEN | orcastrate-token | PAT for workflow and git operations. |
GITHUB_TOKEN | github-token | Token for PRs (default: ${{ github.token }}). |
ORCASTRATE_APP_ID | app-id | ID of the GitHub App. |
ORCASTRATE_PRIVATE_KEY | private-key | PEM private key for the App. |
ORCASTRATE_INSTALLATION_ID | installation-id | Specific installation ID for the App. |
Sources: action.yml:25-50, src/main.rs:101-115
Summary
Orcastrate provides flexible authentication options to suit different organizational needs. While Personal Access Tokens offer a straightforward setup with dual-token separation, GitHub Apps provide a more scalable and manageable solution for organization-wide workflow orchestration. The GitHubClient abstracts these details, ensuring that drift detection and synchronization logic remain consistent regardless of the underlying authentication method.
Sources: README.md:143-165, AGENTS.md:50-58