Security & Permissions
Relevant source files
The following files were used as context for generating this wiki page:
Orcastrate manages GitHub Actions workflows across multiple repositories using secure authentication and granular permissions. The system authenticates with the GitHub API via Personal Access Tokens (PATs) or GitHub Apps to perform git operations, manage pull requests, and create issues.
The security model relies on a dual-token pattern or single-token App installation to isolate high-privilege workflow writes from lower-privilege metadata operations.
Sources: README.md:167-175, AGENTS.md:35-37
Authentication Methods
Orcastrate supports three primary authentication strategies. Each strategy defines how the CLI or GitHub Action interacts with the GitHub API.
| Auth Strategy | Primary Token | Secondary Token | Description |
|---|---|---|---|
| GitHub App | App Token | None | Uses one installation token for all operations. Recommended for organizations. |
| Dual-Token (PAT) | ORCASTRATE_TOKEN | GITHUB_TOKEN | Uses a high-privilege PAT for git writes and a standard token for PRs/Issues. |
| Single-Token | GITHUB_TOKEN | None | Uses the default Action token. Limited by the token's repository scope. |
Sources: AGENTS.md:54-58, src/main.rs:94-150
GitHub App Authentication
GitHub Apps provide the most scalable security model for organizations. When you use an App, Orcastrate generates a short-lived installation token.
You must provide three environment variables for App authentication:
ORCASTRATE_APP_ID: The unique identifier of your GitHub App.ORCASTRATE_PRIVATE_KEY: The RSA private key for signing JWTs.ORCASTRATE_INSTALLATION_ID: The specific installation ID for your organization or repository.
Sources: README.md:188-192, src/main.rs:105-132, action.yml:32-37
Personal Access Token (PAT) Security
If you do not use a GitHub App, Orcastrate requires a fine-grained PAT. This token needs Workflows (Read & Write) permissions because standard GITHUB_TOKEN instances often lack the scope to modify files in .github/workflows/.
The following diagram illustrates the token selection logic during client construction:
The logic ensures that git writes and PR operations use the most appropriate credentials available.
Sources: src/main.rs:105-150, AGENTS.md:35-37
Required Permissions and Scopes
Orcastrate requires specific permissions to perform its core functions. These must be granted to either the PAT or the GitHub App.
Core Permission Scopes
- Repository Contents (Read & Write): Used for discovering files and writing git trees.
- Pull Requests (Read & Write): Used for opening and updating PRs when drift is detected.
- Workflows (Read & Write): Required to modify files within the
.github/workflows/directory. - Issues (Read & Write): Only required if running in
issuesync mode.
Sources: README.md:179-186, src/github/mod.rs:56-61, src/sync.rs:325-339
Git Data API Isolation
Orcastrate uses the Git Data API (trees, commits, refs) instead of the standard Contents API for writes. This design decision bypasses common workflow scope limitations associated with updating .github/workflows/* files via standard content updates.
Sources: AGENTS.md:33-34, src/github/mod.rs:155-240
Operational Security
Dry Run Mode
Orcastrate includes a global dry_run setting and a --dry-run CLI flag. When enabled, the system validates templates and detects drift but prevents all write operations to GitHub.
- Branch Creation: Skipped; logs intended branch name.
- Commits: Skipped; logs intended file updates.
- PRs/Issues: Skipped; logs intended titles and bodies.
Sources: src/config.rs:24-25, src/github/mod.rs:136-139, src/sync.rs:258-261
Bot Identities
Orcastrate manages the commit author and committer information based on the authentication method to maintain clear audit trails.
| Auth Method | Commit Author | PR Author |
|---|---|---|
| App | App Bot (Implicit) | App Bot |
| PAT/Token | github-actions[bot] | github-actions[bot] |
When using a PAT, the system explicitly sets the author to 41898282+github-actions[bot]@users.noreply.github.com.
Sources: AGENTS.md:54-58, src/github/mod.rs:8-9, src/github/mod.rs:200-205
Security Configuration in GitHub Actions
When running inside a GitHub Action, permissions must be explicitly defined in the workflow YAML to allow the default GITHUB_TOKEN to manage pull requests and contents.
permissions:
contents: write
pull-requests: write
This configuration ensures the environment has the baseline permissions required before the ORCASTRATE_TOKEN or App auth expands the scope to include workflow files.
Sources: README.md:96-98, action.yml:28-30
Conclusion
Security in Orcastrate is centralized in the GitHubClient. By utilizing a dual-token approach or a GitHub App, the system ensures that high-privilege workflow modifications are authorized through specific tokens while standard metadata operations remain restricted to standard environment tokens. The use of the Git Data API further hardens the system against common GitHub Action permission restrictions.