Drift Check Command

Relevant source files

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

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

The Drift Check command identifies differences between active GitHub Actions workflow files and their canonical templates without performing any modifications. It allows users to verify compliance across multiple repositories by reporting which files have diverged (drifted) from the expected state.

This command serves as a read-only alias for the synchronization logic, specifically utilizing the Silent synchronization mode. It processes configured and discovered repositories, compares local content against rendered templates, and outputs a detailed summary report to the console and GitHub Action step summaries.

Sources: src/cli.rs:64-67, src/main.rs:63-65, README.md:105

Execution Logic

When you execute orcastrate drift, the application initializes a GitHubClient and a TemplateRenderer. The command follows the same core logic as the sync command but enforces SyncMode::Silent. This mode prevents the creation of Pull Requests or Issues regardless of the drift detected.

Sequence of Operations

The following diagram illustrates the data flow for the drift check process:

The logic iterates through every managed workflow file—those containing Orcastrate frontmatter markers—to determine if the remote content matches the locally rendered version.

Sources: src/main.rs:60-70, src/sync.rs:222-290, src/diff.rs:5-7

Drift Detection Mechanism

Drift detection relies on a direct comparison between the current content of a workflow file retrieved from GitHub and the content generated by the Tera-backed template engine.

Comparison Logic

1. Frontmatter Parsing: The system scans for # @orcastrate and # @end-orcastrate markers. If absent, the file is ignored.
2. Template Rendering: The renderer uses the template ID and parameters found in the frontmatter to generate the expected YAML.
3. Action Version Preservation: If ignore_action_versions is enabled in the configuration, the system preserves existing action tags (e.g., @v4) from the remote file within the rendered output to prevent false drift reports caused by version pinning.
4. Content Comparison: The has_drifted function performs a strict inequality check (current != rendered).

Sources: src/sync.rs:242-273, src/diff.rs:5-7, src/template/versions.rs:77-124

Diff Summaries

When drift is detected, the system calculates a DiffSummary containing the number of lines added and removed. This data is included in the final report.

Field	Type	Description
added	usize	Number of lines present in the rendered template but missing in the remote file.
removed	usize	Number of lines present in the remote file but missing in the rendered template.

Sources: src/diff.rs:18-32

Reporting and Output

The command generates a SyncReport containing results for every processed repository. This report is formatted into two primary views.

Console Summary

A plain-text summary displayed in the terminal. It includes:

• Total repositories processed.
• Total workflows checked vs. managed.
• Count of workflows that have drifted.
• List of specific errors encountered during the scan.

Markdown Summary

If running within a GitHub Action, the report is written to GITHUB_STEP_SUMMARY. In Silent mode (used by drift), it produces a table showing the status of each repository.

Repo	Checked	Managed	Drifted	Errors
owner/repo	Count of .yml files	Files with frontmatter	Files with drift	Count of failures

Sources: src/sync.rs:22-125, src/main.rs:71-72, src/gha.rs:32-40

Configuration and Filtering

The drift check behavior is influenced by the orchestrator.toml configuration and CLI arguments.

Argument	Description	Effect
--repo	Optional repository filter	Limits the drift check to a single specific repository.
--config	Path to config file	Defines template directories and discovery settings.
--dry-run	Global dry-run flag	Forces the GitHub client into read-only mode (redundant for drift).

Sources: src/cli.rs:17-30, src/cli.rs:77-80, src/config.rs:10-25

The command concludes with a process exit code of 1 if any errors were encountered during the execution (e.g., network failures, invalid YAML, or rendering errors), ensuring CI pipelines can fail on execution issues even if drift itself is not considered a failure.

Sources: src/main.rs:74-77