Action Version Management

Action Version Management in Orcastrate controls how GitHub Action references (tags, SHA pins, and versions) are updated during the synchronization process. The system defaults to preserving existing version metadata in target repositories to allow external tools like Renovate to manage dependencies without interference from canonical templates.

When the preservation logic is active, Orcastrate renders the template but replaces the uses: strings in the output with the specific versions found in the existing workflow file. This ensures that a template update for logic or environment settings does not accidentally roll back a security patch or a version bump applied by a bot.
Sources: README.md:143-150, src/template/versions.rs:81-140

Configuration

You control version management behavior via the orchestrator.toml configuration file. The ignore_action_versions setting determines if Orcastrate overwrites or preserves existing action tags.

Sources: src/config.rs:21-25, README.md:152-156

External Manager Integration

The project is configured to work alongside Renovate. The renovate.json file demonstrates a preference for pinning GitHub Action digests, which Action Version Management protects during template synchronization.
Sources: renovate.json:5-9

Technical Architecture

The version management logic operates during the synchronization loop after a template is rendered but before drift is calculated.

The diagram below illustrates the flow of data when version preservation is enabled:

This diagram shows the conditional execution of the version preservation logic within the sync module.
Sources: src/sync.rs:326-343, src/template/versions.rs:81-90

Data Structures and Extraction

The system represents action references using the ActionRef struct. This structure stores metadata necessary to uniquely identify an action use-case across different workflow versions.

struct ActionRef {
    job: String,
    step: Option<usize>,
    id: Option<String>,
    identity: String,
    occurrence: usize,
    value: String,
}

Sources: src/template/versions.rs:7-14

Extraction Logic

The action_refs function scans a YAML document to build a list of all action usages. It extracts the identity by splitting the string at the @ symbol. It tracks occurrence counts for actions used multiple times within the same job to ensure precise matching when unique IDs are absent.
Sources: src/template/versions.rs:16-51

Matching and Preservation Process

The core logic resides in preserve_action_versions. It follows a specific hierarchy to map rendered actions back to their source versions.

1. Filter Local Actions: The system ignores local paths (./) and Docker images (docker://) as these are considered managed by the template or environment.
2. Match by ID: If a step has an explicit id, the system matches the rendered action to the current action with the same ID.
3. Match by Occurrence: If no ID exists, the system matches based on the job name, action identity, and the order of appearance (occurrence) within the job.
4. String Replacement: The system performs a targeted string replacement on the rendered lines to preserve comments (e.g., # v1.2.3) and specific quoting styles found in the original file.

This sequence shows the interaction between the synchronization loop and the version preservation utility.
Sources: src/template/versions.rs:81-140, src/sync.rs:326-339

Implementation Constraints

To maintain safety and prevent accidental corruption of the workflow YAML, the system enforces several constraints.

• Block Style Required: The logic requires single-line, block-style uses: fields. It cannot safely parse or preserve versions in complex multi-line or inline YAML structures.
• Validation Check: After replacement, the system parses the result as YAML. If the structure (excluding the version string) differs from the rendered template, it returns a YamlValidation error and skips the workflow.
• Script Protection: The system refuses to rewrite ambiguous script text or text within run: blocks that happens to contain the string uses:.

Sources: src/template/versions.rs:54-79, src/template/versions.rs:142-150, README.md:158-164