Log Grouping & Annotations

Relevant source files

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

• src/gha.rs
• src/sync.rs
• src/main.rs
• AGENTS.md
• src/github/mod.rs

The Log Grouping & Annotations system provides integrated feedback within the GitHub Actions (GHA) environment. It enhances the visibility of the synchronization process by organizing console output into collapsible sections and surfacing errors or warnings directly in the GitHub UI as annotations.

The system specifically targets the GHA environment by checking for the GITHUB_ACTIONS environment variable. If present, the tool emits workflow commands using a specific ::command:: syntax.

Sources: src/gha.rs:1-32, AGENTS.md:23

Architecture and Components

The system relies on the gha module to interface with GitHub Actions runner commands.

Environment Detection

The is_github_actions function verifies if the software is running within a GHA runner. It returns true if the GITHUB_ACTIONS environment variable exists. Other logging functions in the module only print to standard output if this condition is met.

Sources: src/gha.rs:1-3

Workflow Commands

The module implements several standard GitHub Actions workflow commands:

Function	GHA Command	Description
group(title)	::group::{title}	Starts a collapsible log group in the Actions console.
endgroup()	::endgroup::	Closes the most recently opened log group.
warning(msg)	::warning::{msg}	Creates a warning annotation in the GitHub UI.
error(msg)	::error::{msg}	Creates an error annotation in the GitHub UI.
write_summary(content)	N/A	Appends Markdown content to the file path in GITHUB_STEP_SUMMARY.

Sources: src/gha.rs:5-32

Log Grouping Logic

The synchronization engine uses groups to isolate logs for each processed repository. This prevents the logs of large organizations from becoming unreadable.

1. The sync::run function initiates the process for a list of repositories.
2. For each repository, sync_repo calls gha::group with the repository name.
3. The system processes workflows, renders templates, and detects drift.
4. After processing, sync_repo calls gha::endgroup to close the section.

The diagram shows how the synchronization loop wraps repository-specific actions within grouping commands.
Sources: src/sync.rs:215-323

UI Annotations

The system creates annotations when critical failures occur during the synchronization of managed workflows. This allows maintainers to identify issues without searching through raw logs.

Warning Annotations

The system generates warnings if:

• It fails to retrieve the content of a workflow file from GitHub.
• The template rendering engine fails due to invalid parameters or template syntax errors.
• Action version preservation fails due to unsupported YAML layouts.

Sources: src/sync.rs:232, src/sync.rs:262, src/sync.rs:281

Error Annotations

The system generates an error annotation if the synchronization of an entire repository fails, usually due to network issues or API authorization problems.

Sources: src/sync.rs:141

Job Summaries

At the end of a synchronization run, the tool generates a comprehensive report. If running in GHA, the system writes this report to the GITHUB_STEP_SUMMARY.

1. The SyncReport struct generates a Markdown-formatted summary.
2. The main entry point calls gha::write_summary with this Markdown content.
3. The write_summary function opens the file specified by the GITHUB_STEP_SUMMARY environment variable in append mode and writes the data.

The sequence diagram illustrates the flow of the final report from the sync engine to the GitHub Actions Job Summary.
Sources: src/main.rs:76-77, src/sync.rs:88-151, src/gha.rs:24-32

Summary of Usage in Synchronization

The system tracks several metrics that are ultimately displayed in the annotations and summaries:

• Checked: Total workflows found in .github/workflows.
• Managed: Workflows containing @orcastrate frontmatter.
• Drifted: Managed workflows that differ from the rendered template.
• Errors: Count of failures encountered during the run.

Sources: src/sync.rs:11-21, src/sync.rs:35-51