Getting Started

Relevant source files

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

• README.md
• orchestrator.toml
• action.yml
• src/sync.rs
• src/template/frontmatter.rs
• src/config.rs
• AGENTS.md
• src/main.rs

Orcastrate manages GitHub Actions workflows across multiple repositories from a single central orchestrator repository. It eliminates the need to copy-paste workflow files by defining canonical templates once and syncing them to all managed repositories. The system scans target repositories, renders templates using declared parameters, and opens Pull Requests (PRs) when it detects drift between the local file and the template.

Sources: README.md:5-23, AGENTS.md:5-10

The Sync Lifecycle

Orcastrate follows a structured process to ensure repositories remain in sync with their templates. This lifecycle includes discovery, rendering, comparison, and update phases.

The diagram shows the logical flow from configuration loading to repository synchronization.
Sources: README.md:14-23, src/sync.rs:189-328

Initial Setup

You must configure a central repository to host your templates and synchronization logic. Follow these steps to begin management:

1. Create an Orchestrator Repository: Create a new repository in your GitHub organization (e.g., myorg/workflow-orchestrator).
2. Define Configuration: Create an orchestrator.toml file in the root directory to list target repositories and template locations.
3. Add Templates: Create a templates/ directory and populate it with Tera-powered YAML templates.
4. Set Up the Action: Create a scheduled GitHub Action in .github/workflows/sync.yml to execute the orcastrate binary.
5. Tag Target Workflows: Add the @orcastrate frontmatter block to the top of existing workflow files in your organization's repositories.

Sources: README.md:43-98, src/config.rs:56-66

Configuration and Template Opt-in

Orcastrate relies on two primary mechanisms to identify managed content: the central configuration file and embedded frontmatter in target workflows.

Central Configuration (orchestrator.toml)

The orchestrator.toml file defines the scope of management and global settings.

Field	Type	Description
templates_dir	String	The local directory containing .yml templates.
branch_prefix	String	Prefix for PR branches (default: orcastrate/sync).
pr_label	String	Label applied to generated PRs (default: orcastrate).
ignore_action_versions	Boolean	If true, preserves existing action tags/SHAs (default: true).
repos	Array	List of owner/repo strings to manage.
discovery	Object	Optional auto-discovery of repos by organization and topic.

Sources: README.md:107-123, src/config.rs:10-37

Managed Workflow Frontmatter

Target repositories opt in to management by including a YAML comment block at the top of their workflow files. Orcastrate only modifies files containing these specific markers.

# @orcastrate
# template: rust-ci
# params:
#   toolchain: stable
# @end-orcastrate

Sources: README.md:27-38, src/template/frontmatter.rs:7-13

Authentication

Orcastrate supports both Personal Access Tokens (PAT) and GitHub Apps for authentication.

Requirement	Token Type	Permissions Needed
Git Writes	ORCASTRATE_TOKEN (PAT) or App Token	Workflows (R/W), Contents (R/W)
PR/Issue Creation	GITHUB_TOKEN or App Token	Pull Requests (R/W), Issues (R/W)

If using a GitHub App, you must provide ORCASTRATE_APP_ID, ORCASTRATE_PRIVATE_KEY, and ORCASTRATE_INSTALLATION_ID as environment variables.

Sources: README.md:144-162, action.yml:25-36, src/main.rs:125-165

Execution Commands

The CLI tool provides several commands to manage the synchronization process manually or via automation.

Command	Usage
sync	Synchronizes all repositories and creates PRs for detected drift.
drift	Checks for differences without creating PRs or modifying files.
validate	Checks the syntax of orchestrator.toml and all Tera templates.
render <file>	Renders a specific local workflow file to stdout for debugging.
list-repos	Displays all explicitly configured and auto-discovered repositories.

Sources: README.md:83-93, src/cli.rs:32-60

By centralizing workflow definitions and automating the update process through PRs, Orcastrate ensures consistency across an organization's CI/CD pipeline while allowing individual repository maintainers to review changes before they are applied.

Sources: README.md:14-23, src/sync.rs:330-365