Sync Modes & PR Creation

Relevant source files

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

• src/sync.rs
• src/cli.rs
• src/github/mod.rs
• src/config.rs
• src/main.rs
• src/diff.rs
• README.md

Orcastrate manages GitHub Action workflow files across multiple repositories by comparing them against canonical templates. When the system detects drift between a repository's local workflow and the rendered template, it performs automated actions based on the selected sync mode. This system ensures that organization-wide CI/CD standards remain consistent without manual intervention.

The synchronization process involves discovering target repositories, scanning for managed workflows containing specific frontmatter, and generating updates. Depending on configuration, Orcastrate can open Pull Requests, create GitHub Issues, or simply report drift status.

Sources: src/sync.rs:1-15, README.md:12-23

Sync Modes

Orcastrate supports three distinct operational modes defined in the SyncMode enum. These modes determine how the application reacts when it identifies a difference between a managed workflow and its template.

Mode	Behavior	Use Case
Pr	Creates or updates a branch and Pull Request for each drifted workflow.	Standard automated management.
Issue	Creates or updates a GitHub Issue with the diff details.	Manual review or notification without code changes.
Silent	Performs drift detection and reporting only.	Auditing and status checks (aliased as drift).

Sources: src/cli.rs:25-30, src/sync.rs:271-330

Mode Logic Flow

The following diagram illustrates how the sync_repo function handles drifted workflows based on the active mode:

This logic ensures that only one communication channel (PR or Issue) remains open per workflow file to prevent notification spam.

Sources: src/sync.rs:271-332

Pull Request Creation Architecture

When operating in Pr mode, Orcastrate uses a multi-step Git Data API flow to create changes. This approach avoids common workflow scope issues associated with the standard Contents API.

1. Branch Management

The system generates a branch name using the configured branch_prefix (default: orcastrate/sync) and the workflow filename. If the branch already exists, the system force-updates it to the current default branch SHA.

Sources: src/sync.rs:281-285, src/github/mod.rs:141-164, src/config.rs:40-42

2. Atomic Commits

Orcastrate bundles changes into a single commit using the following Git objects:

• Blobs: Created for the rendered workflow content.
• Trees: Built using the base_tree from the default branch and the new blobs.
• Commits: Created with the new tree and the default branch's latest commit as the parent.

Sources: src/github/mod.rs:172-225

3. PR Submission and Metadata

After updating the reference, the system checks for an existing PR from the generated branch.

• New PRs: Created with a specific title (e.g., chore(ci): sync [workflow] from template [template]) and the configured pr_label.
• Existing PRs: Updated with the latest rendering and diff summary.

Sources: src/sync.rs:301-325, src/github/mod.rs:256-291

PR Body Generation

The PR body provides developers with context regarding the automated change. It includes a unified diff of the changes and a link to the orchestrator repository.

fn build_pr_body(update: &WorkflowUpdate) -> String {
    let mut body = String::new();
    body.push_str("## 🐬 Orcastrate Workflow Sync\n\n");
    // ... context about templates and drift
    let diff_text = diff::generate_diff(&update.current, &update.rendered, &update.path);
    // ... logic to truncate diff if > 200 lines
    body.push_str(&format!("```diff\n{diff_text}```\n\n"));
    body
}

Sources: src/sync.rs:343-376

Configuration Options

Sync behavior is governed by settings in the orchestrator.toml file.

Parameter	Type	Default	Description
branch_prefix	String	orcastrate/sync	Prefix for branches created in Pr mode.
pr_label	String	orcastrate	Label applied to created PRs and Issues.
dry_run	Boolean	false	If true, logs actions without making API calls.
ignore_action_versions	Boolean	true	If true, preserves existing action tags/SHAs to allow Renovate management.

Sources: src/config.rs:16-24, README.md:129-140

Execution Summary

At the end of a sync run, Orcastrate generates a SyncReport. In GitHub Actions environments, this report is written to GITHUB_STEP_SUMMARY in Markdown format. The report tracks:

• Total repositories processed.
• Number of workflows checked vs. managed.
• Count of drifted workflows.
• Success/Failure count for PR or Issue creation.

Sources: src/sync.rs:21-45, src/main.rs:72-74, src/gha.rs:25-31

The synchronization system centralizes workflow logic while providing repository owners the opportunity to review changes via standard GitHub collaboration tools. This balances organization-wide consistency with local repository autonomy.