Drift Detection

Relevant source files

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

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

Drift detection identifies discrepancies between the current state of GitHub Actions workflow files in managed repositories and the expected state rendered from canonical templates. This process ensures that organizational standards remain consistent across multiple repositories.

Orcastrate scans remote repositories, parses embedded metadata in workflow files, renders the associated templates with provided parameters, and compares the resulting content against the existing file content. When differences exist, the system marks the workflow as "drifted."

Sources: src/sync.rs:215-260, README.md:16-23

Architecture and Data Flow

Drift detection occurs during the synchronization cycle. The orchestrator fetches files from the .github/workflows/ directory and filters for managed files containing Orcastrate frontmatter.

Detection Logic Flow

The following diagram illustrates the sequence of operations used to determine if a workflow has drifted from its template.

A brief summary of the flow: The system fetches content, parses metadata, renders the template, optionally reconciles GitHub Action versions, and performs a final string comparison.
Sources: src/sync.rs:215-268, src/template/frontmatter.rs:23-28

Core Components

Frontmatter Parsing

Managed workflows must include a specific comment block delimited by # @orcastrate and # @end-orcastrate. The parser extracts the template ID and a map of parameters used for rendering.

Sources: src/template/frontmatter.rs:7-10, README.md:27-38

Comparison Engine

The comparison engine determines the existence and scale of drift. It provides boolean checks and detailed summaries of changes.

Function	Description
has_drifted	Performs a direct string comparison between current and rendered content.
diff_summary	Calculates the number of lines added and removed.
generate_diff	Produces a unified diff string with a standard context radius.

Sources: src/diff.rs:3-22

Action Version Preservation

By default, Orcastrate ignores differences in GitHub Action versions (e.g., tags or SHA hashes) to allow external tools like Renovate to manage updates. The preserve_action_versions function identifies uses: lines in the current file and injects those specific versions into the newly rendered content before the final comparison.

Sources: src/template/versions.rs:77-123, src/config.rs:24-25

Drift Reporting

When drift is detected, the system generates a DiffSummary and prepares updates for the selected sync mode (PR, Issue, or Silent).

Diff Summary Structure

The DiffSummary struct tracks granular changes found during the drift check.

pub struct DiffSummary {
    pub added: usize,
    pub removed: usize,
}

Sources: src/diff.rs:28-31

Workflow Update Context

If drift exists, the system encapsulates the findings into a WorkflowUpdate structure to facilitate PR or issue creation.

Field	Source	Description
path	src/sync.rs:431	The file path in the target repository.
current	src/sync.rs:432	The existing content found in the repo.
rendered	src/sync.rs:433	The content generated from the template.
template	src/sync.rs:434	The ID of the template used for rendering.

Sources: src/sync.rs:429-435

Configuration Options

Drift detection behavior is controlled via the orchestrator section of orchestrator.toml.

Option	Type	Default	Description
ignore_action_versions	Boolean	true	When true, prevents action version changes from triggering drift.
dry_run	Boolean	false	If true, detects drift but performs no remote writes.

Sources: src/config.rs:18-26

Summary

Drift detection serves as the primary validation mechanism in Orcastrate. It ensures that manual changes to managed workflows or updates to central templates are identified, quantified via unified diffs, and reported through automated synchronization workflows.
Sources: AGENTS.md:16-20, src/sync.rs:44-55