orchestrator.toml Reference
Relevant source files
The following files were used as context for generating this wiki page:
The orchestrator.toml file serves as the central configuration hub for the Orcastrate CLI. It defines the global behavior of the orchestration engine, specifies the location of workflow templates, and identifies which repositories are subject to management.
Orcastrate uses this file to determine its operational scope during a sync run. The configuration allows for both explicit repository listing and dynamic repository discovery through GitHub organization topics.
Sources: src/config.rs:7-13, README.md:10-15, AGENTS.md:14-17
Configuration Structure
The configuration follows a TOML structure divided into three main components: global orchestrator settings, manual repository entries, and discovery rules.
Orchestrator Settings
The [orchestrator] block contains global parameters that control the synchronization logic and PR generation behavior.
| Field | Type | Default | Description |
|---|---|---|---|
templates_dir | String | (Required) | Path to the directory containing Tera-powered workflow templates. |
branch_prefix | String | orcastrate/sync | Prefix used for git branches created during synchronization. |
pr_label | String | orcastrate | Label applied to generated GitHub Pull Requests. |
dry_run | Boolean | false | When true, simulates actions without modifying remote repositories. |
ignore_action_versions | Boolean | true | When true, preserves existing action versions in target files rather than overwriting with template versions. |
Sources: src/config.rs:16-24, src/config.rs:38-48, README.md:95-104
Repository Management
Repositories are managed either through explicit entries in the [[repos]] list or via the [discovery] block.
Manual Repository Entry ([[repos]])
You define individual repositories using the [[repos]] array. Each entry must follow the owner/name format.
| Field | Type | Default | Description |
|---|---|---|---|
name | String | (Required) | The full GitHub repository name (e.g., "org/repo"). |
enabled | Boolean | true | Set to false to temporarily skip synchronization for this repository. |
Sources: src/config.rs:27-31, src/config.rs:61-68, orchestrator.toml:6-7
Repository Discovery ([discovery])
The [discovery] block enables Orcastrate to find repositories dynamically within a GitHub organization.
| Field | Type | Default | Description |
|---|---|---|---|
org | String | (Required) | The name of the GitHub organization to scan. |
topic | String | None | Optional topic filter. If set, only repositories with this topic are synced. |
Sources: src/config.rs:34-38, README.md:109-113
Data Flow and Resolution
When the CLI runs, it resolves the final list of target repositories by merging enabled manual entries with discovered repositories.
The application validates that at least one repository or one discovery block is present before proceeding. It also ensures all repository names match the expected owner/name pattern.
Sources: src/config.rs:56-71, src/sync.rs:175-195
Logic and Implementation Details
Version Preservation
The ignore_action_versions toggle determines how the engine handles @version tags in GitHub Actions uses: fields. If enabled, Orcastrate uses a span-aware logic to keep the existing tags or SHA pins in the target workflow while updating the rest of the file content based on the template.
Sources: src/config.rs:23, src/sync.rs:248-259
Config Example
[orchestrator]
templates_dir = "templates"
branch_prefix = "ci/sync"
pr_label = "automated-workflow"
ignore_action_versions = true
[[repos]]
name = "myorg/service-api"
[[repos]]
name = "myorg/legacy-app"
enabled = false
[discovery]
org = "myorg"
topic = "managed-workflows"
Sources: README.md:95-113, orchestrator.toml:1-7
Summary
The orchestrator.toml file is the primary configuration interface for Orcastrate. It provides a flexible mechanism to scale workflow management across an organization by combining static repository lists with dynamic discovery. Its settings directly influence how Pull Requests are titled, labeled, and branched, as well as how action versions are maintained during template application.