Data Flow

Relevant source files

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

• src/sync.rs
• src/main.rs
• src/github/mod.rs
• src/template/render.rs
• src/template/frontmatter.rs
• src/template/versions.rs
• src/config.rs
• src/diff.rs

Orcastrate automates the lifecycle of GitHub Actions workflows by centralizing template management and synchronizing changes across multiple repositories. The data flow begins with configuration loading and repository discovery, proceeds through template rendering and drift detection, and concludes with the application of changes via the GitHub API.

High-Level Orchestration Flow

The synchronization process moves through distinct phases: resolving the target repository list, scanning remote workflows for management markers, rendering local templates with specific parameters, and submitting changes through Pull Requests or Issues.

The high-level sequence diagram illustrates the communication between the local sync engine and the GitHub remote services.
Sources: src/sync.rs:136-168, src/main.rs:66-82

Repository Discovery and Filtering

Orcastrate identifies target repositories using two primary methods: explicit definition in orchestrator.toml and dynamic discovery via the GitHub Search API.

1. Static Configuration: The system reads [[repos]] entries from the local configuration file.
2. API Discovery: If a [discovery] block exists, the GitHubClient queries the organization for repositories matching specific topics.
3. Filtering: The resolve_repos function merges these lists and applies optional CLI filters provided via the --repo argument.

Component	Responsibility	Relevant Fields
Config	Loads static repo list	repos, discovery
GitHubClient	Executes searches	discover_repos()
sync::resolve_repos	Merges and filters	active_repos(), filter_repo

Sources: src/config.rs:10-24, src/github/mod.rs:434-472, src/sync.rs:170-205

Workflow Processing and Transformation

Once a repository is identified, Orcastrate iterates through all files in .github/workflows/. The data transformation pipeline follows a strict logical sequence to determine if a file requires updates.

Managed File Identification

The system retrieves file content and searches for a specific YAML comment block delimited by # @orcastrate and # @end-orcastrate. If these markers are absent, the file is ignored.
Sources: src/template/frontmatter.rs:17-64, src/sync.rs:242-261

Template Rendering Pipeline

The transformation of a managed workflow involves several steps:

1. Parsing: Extract the template name and parameter map from the frontmatter.
2. Rendering: The TemplateRenderer uses the Tera engine to inject parameters into the local template file.
3. Validation: The rendered output is validated as valid YAML using serde_norway.
4. Version Preservation: If ignore_action_versions is enabled, the system matches uses: lines in the rendered output against the current live file to preserve existing version tags or SHA hashes.

The flowchart depicts the internal transformation logic for a single workflow file before drift detection.
Sources: src/template/render.rs:26-53, src/template/versions.rs:77-128, src/sync.rs:263-294

Drift Detection and Change Application

Orcastrate compares the final rendered content with the current remote content. Drift is detected if the strings are not identical.

Change Submission

If drift is detected and the tool is not in --dry-run or Silent mode, it initiates a series of Git Data API calls:

• Branch Management: Creates a new branch (prefixed with orcastrate/sync/ by default) or updates an existing one using force: true.
• Tree/Commit Creation: Uses the Git Data API (/git/trees and /git/commits) to commit the modified workflow file. This approach avoids permission issues associated with the standard Contents API for workflow files.
• PR/Issue Creation: Depending on the SyncMode, it either opens a Pull Request (updating an existing one if available) or creates a GitHub Issue containing a unified diff of the changes.

Sources: src/diff.rs:5-7, src/sync.rs:313-395, src/github/mod.rs:163-264

Synchronization Reporting

The final stage of the data flow is the generation of a SyncReport. This report aggregates the results for all processed repositories, including:

• Count of workflows checked and managed.
• Number of drifted files detected.
• Actions taken (PRs or Issues created/updated).
• Any errors encountered during the process.

The report is output to stdout and, if running within GitHub Actions, written to the GITHUB_STEP_SUMMARY.
Sources: src/sync.rs:13-134, src/main.rs:79-81, src/gha.rs:26-33