Sync Engine Internal Logic

Relevant source files

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

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

The Sync Engine automates the maintenance of GitHub Actions workflow files across multiple repositories. It identifies managed files via specialized frontmatter, renders updates from templates, and reconciles differences by creating Pull Requests or Issues.

Sources: src/sync.rs:1-20, README.md

Core Orchestration Flow

The engine operates through a central run function that coordinates repository resolution and individual repository synchronization.

The sync process iterates through all configured and discovered repositories to detect state divergence.

Sources: src/sync.rs:125-155, src/sync.rs:188-210

Repository Discovery and Resolution

The engine determines which repositories to process based on static configuration and dynamic discovery.

Component	Logic
Active Repos	Reads [[repos]] from orchestrator.toml where enabled = true.
Discovery	Calls the GitHub Search API for a specific organization and optional topic.
Filtering	Filters the final list if a specific repo is requested via CLI.

Sources: src/config.rs:66-88, src/sync.rs:157-186, src/github/mod.rs:341-375

Workflow Processing Logic

For every workflow file found in a repository, the engine performs the following steps:

1. Frontmatter Parsing

The engine looks for a specific comment block delimited by # @orcastrate and # @end-orcastrate. If this block is missing, the file is ignored.

Sources: src/template/frontmatter.rs:10-25

2. Template Rendering

The engine extracts the template ID and parameters from the frontmatter. It uses the TemplateRenderer to generate the new YAML content using the Tera engine.

Sources: src/template/render.rs:25-50, src/sync.rs:242-251

3. Action Version Preservation

If ignore_action_versions is enabled in the configuration, the engine extracts action versions (tags/SHAs) from the existing file and injects them into the newly rendered content. This prevents the sync engine from overwriting versions managed by other tools like Renovate.

4. Drift Detection

The engine compares the final rendered string with the current file content. If they are not identical, it marks the workflow as "drifted".

Sources: src/diff.rs:3-5, src/sync.rs:271-282

Reconciliaton Modes

Once drift is detected, the engine executes actions based on the selected SyncMode.

Mode	Action
PR	Creates a unique branch for the workflow, commits the change, and opens/updates a Pull Request.
Issue	Creates or updates a GitHub Issue containing the diff.
Silent	Only records the drift in the final report summary.

Sources: src/sync.rs:307-375, src/cli.rs:23-29

Data Structures

SyncResult

Tracks the outcome of a single repository's synchronization.

• workflows_checked: Total YAML files in .github/workflows.
• workflows_managed: Files containing @orcastrate frontmatter.
• drifted: Number of managed files that differ from the template.
• errors: A list of strings capturing failures (e.g., render errors, API timeouts).

Sources: src/sync.rs:11-22

WorkflowUpdate

Internal structure used to carry state between detection and PR creation.

• path: File system path in the target repo.
• current: Existing file content.
• rendered: New content to be applied.
• template: Name of the template used.

Sources: src/sync.rs:392-397

Conclusion

The Sync Engine Internal Logic focuses on a stateless, idempotent approach to workflow management. By combining GitHub API interactions with a local templating engine and version preservation logic, it ensures organization-wide CI/CD consistency without disrupting local versioning strategies.

Sources: src/sync.rs, AGENTS.md