Home

Relevant source files

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

• README.md
• AGENTS.md
• src/main.rs
• src/sync.rs
• src/config.rs
• src/github/mod.rs
• src/template/frontmatter.rs
• src/template/render.rs

Orcastrate is a Rust-based CLI tool designed to manage GitHub Actions workflows across multiple repositories from a central orchestrator repository. It automates the rendering of canonical workflow templates, detects drift between local files and templates, and opens pull requests or issues to reconcile differences.

Sources: README.md:10-15, AGENTS.md:5-9

Core Architecture

Orcastrate operates as a scheduled GitHub Action or a standalone CLI. It uses a central orchestrator.toml file to define managed repositories and a templates/ directory for Jinja2-style Tera templates.

Execution Flow

The system follows a linear execution path to identify and resolve workflow drift:

1. Configuration Loading: Reads repository lists and global settings.
2. Discovery: Resolves target repositories via static config or GitHub Org API.
3. Scanning: Searches for .github/workflows/ files containing specific Orcastrate markers.
4. Rendering: Generates updated workflow content using the Tera engine.
5. Drift Detection: Compares current content with rendered output.
6. Resolution: Creates Pull Requests, Issues, or reports based on the configured sync mode.

Sources: README.md:17-30, src/sync.rs:163-180, AGENTS.md:13-25

The diagram shows the sequence of operations from configuration loading to final resolution.
Sources: src/sync.rs:182-350, src/main.rs:65-75

Module Map

Module	Responsibility
src/main.rs	CLI entrypoint, logging setup, and command dispatch.
src/config.rs	Parsing and validation of orchestrator.toml.
src/sync.rs	Orchestration of discovery, scanning, and drift resolution.
src/github/mod.rs	Wrapper for GitHub API (Octocrab) for git data and PR operations.
src/template/render.rs	Tera-backed template rendering and YAML validation.
src/template/frontmatter.rs	Parsing of @orcastrate comment blocks in YAML files.
src/diff.rs	Generation of unified diffs and drift status.

Sources: AGENTS.md:13-25, src/main.rs:1-15

Managed Workflows and Frontmatter

Workflows opt-in to management via a specific YAML comment block. This block defines the source template and any parameters passed to the renderer.

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

The parser extracts content between # @orcastrate and # @end-orcastrate, converting it to internal Frontmatter structures.

Sources: README.md:46-55, src/template/frontmatter.rs:7-15

Data Structure: Frontmatter

Field	Type	Description
template	String	ID of the template file in the templates directory.
params	HashMap<String, Value>	Key-value pairs injected into the Tera template.

Sources: src/template/frontmatter.rs:9-14

Template Rendering and Version Preservation

Templates use Tera syntax. Orcastrate includes a unique feature to preserve GitHub Action versions (e.g., @v4 or SHA pins) even when other parts of the workflow change.

• Preservation Logic: If ignore_action_versions is true (default), the system matches uses: lines between the current and rendered files to maintain existing version strings.
• Validation: Rendered output is validated as valid YAML before being applied.

Sources: README.md:120-135, src/template/render.rs:77-84, src/template/versions.rs:81-110

This sequence illustrates how version preservation occurs after the initial template rendering.
Sources: src/sync.rs:245-265, src/template/versions.rs:81-85

Authentication and Security

Orcastrate supports three authentication methods, often requiring a "dual-token" pattern for Personal Access Tokens (PATs) to handle restricted workflow scopes.

Mode	Token 1	Token 2	Function
GitHub App	App Token	-	Single token for all operations.
PAT + GITHUB_TOKEN	ORCASTRATE_TOKEN	GITHUB_TOKEN	PAT handles Git writes; GITHUB_TOKEN handles PRs.
Default	GITHUB_TOKEN	-	Standard GITHUB_TOKEN for internal operations.

Sources: README.md:150-170, AGENTS.md:46-52, src/main.rs:125-180

CLI Commands

The tool provides several subcommands for managing the orchestration process:

• sync: Processes all repositories and creates PRs/Issues for drift.
• drift: Checks for drift without modifying any remote resources.
• validate: Verifies the syntax of orchestrator.toml and all templates.
• render: Renders a local workflow file to stdout for debugging.
• list-repos: Displays all configured and discovered repositories.

Sources: README.md:75-85, src/main.rs:43-55

Summary

Orcastrate centralizes GitHub Actions management by treating workflows as rendered artifacts of canonical templates. By combining drift detection with automated Pull Request generation and sophisticated version preservation, it allows organizations to maintain consistent CI/CD standards across hundreds of repositories without manual intervention.

Sources: README.md:10-15, src/sync.rs:33-70