Architecture Overview

Relevant source files

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

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

Orcastrate is a Rust-based CLI tool that manages GitHub Actions workflows across multiple repositories from a single orchestrator repository. It automates the process of synchronizing workflow files with canonical templates, detecting drift, and applying updates via Pull Requests or GitHub Issues.

The system operates primarily within a scheduled GitHub Action. It parses a central configuration to identify target repositories, scans those repositories for managed workflows, renders updated content using the Tera template engine, and interacts with the GitHub API to maintain consistency.

Sources: AGENTS.md:3-8, README.md:16-25

System Components

The architecture consists of several specialized modules that handle configuration, template processing, and GitHub integration.

Module Responsibilities

Module	Primary Responsibility
src/main.rs	Handles CLI entrypoint, logging initialization, and command dispatching.
src/config.rs	Parses and validates the orchestrator.toml configuration file.
src/sync.rs	Orchestrates the sync logic: discovery, scanning, and update creation.
src/template	Manages frontmatter parsing (frontmatter.rs) and Tera-based rendering (render.rs).
src/github	Wraps the GitHub API for file operations, branch management, and PR/Issue creation.
src/diff.rs	Performs drift detection and generates unified diffs for reports.

Sources: AGENTS.md:12-23, src/main.rs:24-43

Component Relationship Diagram

This diagram shows how the core modules interact during a synchronization run.

The Sync Engine acts as the central coordinator, utilizing the Config Loader for settings and the GitHub Client for all external communication.

Sources: AGENTS.md:12-23, src/sync.rs:135-141

Core Logic and Data Flow

The synchronization process follows a structured pipeline to ensure remote repositories match the local templates defined in the orchestrator repository.

Synchronization Pipeline

1. Repository Discovery: The system resolves a list of repositories from the orchestrator.toml file and optional GitHub organization topic searches.
2. Workflow Scanning: For each repository, it lists files in .github/workflows/ and retrieves their content.
3. Metadata Parsing: It extracts configuration from YAML frontmatter embedded in comments between # @orcastrate and # @end-orcastrate.
4. Rendering: It renders the specified template using the provided parameters.
5. Drift Detection: It compares the rendered output against the existing file content.
6. Reconciliation: If drift exists, it creates a new branch, commits the changes using the Git Data API, and opens a Pull Request (or Issue).

Sources: README.md:18-25, src/sync.rs:211-331, src/template/frontmatter.rs:7-8

Workflow Synchronization Sequence

This sequence diagram illustrates the interaction between the Sync module, the Template module, and the GitHub API.

Key Implementation Details

Managed Workflow Frontmatter

Metadata is stored directly within the workflow files using a specific comment block. This allows the tool to identify which template to use and which parameters to apply without maintaining a separate database of workflow-to-template mappings.

const MARKER_START: &str = "# @orcastrate";
const MARKER_END: &str = "# @end-orcastrate";

Sources: src/template/frontmatter.rs:7-8, README.md:31-41

Authentication Matrix

Orcastrate supports multiple authentication methods, primarily designed for GitHub Actions environments. It uses a "dual-token" pattern when using Personal Access Tokens (PATs) to separate workflow write permissions from PR management.

Operation	GitHub App	PAT + GITHUB_TOKEN
Git Writes	App Token	ORCASTRATE_TOKEN
PR/Issue Ops	App Token	GITHUB_TOKEN
Commit Author	App (implicit)	github-actions[bot]

Sources: AGENTS.md:46-52, src/main.rs:114-171

Version Preservation

By default, the system preserves existing GitHub Action versions (tags/SHAs) in uses: fields to avoid conflicts with tools like Renovate. This behavior is controlled by the ignore_action_versions configuration setting.

Sources: src/template/versions.rs:88-140, src/config.rs:24

Data Models

Configuration Schema

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

Field	Type	Description
templates_dir	String	Directory containing Tera templates.
branch_prefix	String	Prefix for branches created for PRs.
pr_label	String	Label applied to generated Pull Requests.
ignore_action_versions	Boolean	Whether to preserve existing action versions.

Sources: src/config.rs:13-35, README.md:112-127

Sync Result Model

The system generates a report summarizing the actions taken across all processed repositories.

pub struct SyncResult {
    pub repo: String,
    pub workflows_checked: usize,
    pub workflows_managed: usize,
    pub drifted: usize,
    pub prs_created: usize,
    pub prs_updated: usize,
    pub errors: Vec<String>,
    // ...
}

Sources: src/sync.rs:10-21

The architecture of Orcastrate prioritizes reliability and transparency by using a dry-run first approach, detailed diff reporting in PR bodies, and safe Git Data API operations to manage sensitive workflow files across large GitHub organizations.

Sources: AGENTS.md:27-31, src/sync.rs:356-389