GitHub Actions Integration

Relevant source files

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

• action.yml
• src/gha.rs
• src/sync.rs
• src/main.rs
• README.md
• AGENTS.md

Orcastrate integrates with GitHub Actions to automate the management and synchronization of workflow files across multiple repositories. It functions as a Docker-based GitHub Action that runs within a central "orchestrator" repository, typically on a schedule or via manual dispatch. The integration enables the tool to communicate with the GitHub runner environment, emit specialized log commands, and generate post-run summaries for visibility.

Sources: README.md:14-25, action.yml:1-51, AGENTS.md:5-9

GitHub Action Configuration

The project provides a formal GitHub Action definition in action.yml. This file defines the interface for the orchestrator, including required inputs for authentication, configuration paths, and execution modes.

Action Inputs

The following table describes the configuration inputs available when using Orcastrate as a GitHub Action:

Input	Description	Default
command	The execution command (sync, validate, drift, etc.)	sync
config	Path to the orchestrator.toml file	orchestrator.toml
mode	Sync behavior: pr, issue, or silent	pr
dry-run	Prevents modifications to remote repositories	false
orcastrate-token	PAT with workflow scope for writing files	N/A
github-token	Token for PR/Issue creation	${{ github.token }}
app-id	GitHub App ID for App-based authentication	N/A
private-key	GitHub App private key PEM	N/A
installation-id	GitHub App installation ID	N/A

Sources: action.yml:6-42

Runtime Environment

Orcastrate runs inside a Docker container using the image ghcr.io/michidk/orcastrate:main. The entrypoint script action-entrypoint.sh maps the Action inputs to CLI arguments for the Rust binary.

Runner Communication

Orcastrate uses standard GitHub Actions workflow commands to interact with the runner. These commands are implemented in src/gha.rs and allow the application to structure logs and report errors directly in the GitHub UI.

Workflow Commands

The application detects if it is running within a GitHub Actions environment by checking the GITHUB_ACTIONS environment variable.

• Log Grouping: The group(title) and endgroup() functions wrap log output in collapsible UI elements.
• Annotations: The warning(msg) and error(msg) functions emit ::warning:: and ::error:: commands, which GitHub uses to create annotations on the workflow run.
• Step Summaries: The write_summary(content) function appends Markdown content to the file located at the path defined in GITHUB_STEP_SUMMARY.

Sources: src/gha.rs:1-32

Sync Reports and Summaries

During execution, Orcastrate generates a SyncReport containing the results for every processed repository. After the synchronization logic completes, the application converts this report into a Markdown summary and writes it to the GitHub Step Summary.

Data Flow for Reporting

1. sync::run processes repositories and collects SyncResult objects.
2. SyncReport::summary_markdown generates a Markdown table based on the SyncMode.
3. main::cmd_sync calls gha::write_summary to display the table in the GitHub Actions run summary page.

Authentication Integration

The integration supports three primary authentication patterns within GitHub Actions:

1. Dual Token (PAT + GITHUB_TOKEN): Uses ORCASTRATE_TOKEN (a Personal Access Token) for operations requiring the workflow scope and the default GITHUB_TOKEN for Pull Request management.
2. GitHub App: Uses an App ID, Private Key, and Installation ID to generate a single token for all operations.
3. Single Token: Uses only GITHUB_TOKEN, though this may limit the ability to write to .github/workflows/ depending on repository permissions.

Sources: README.md:144-165, AGENTS.md:46-52, src/main.rs:125-177

Conclusion

GitHub Actions integration allows Orcastrate to operate as a central management layer for CI/CD workflows. By leveraging workflow commands and step summaries, the tool provides native feedback within the GitHub platform while automating the propagation of workflow templates across an organization.

Sources: README.md:14-25, src/gha.rs:1-32