Error Handling

Relevant source files

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

• src/error.rs
• src/sync.rs
• src/github/mod.rs
• src/template/frontmatter.rs
• src/gha.rs
• src/main.rs

Orcastrate manages errors through a centralized Error enumeration and a specialized Result type. The system categorizes errors by their source, such as configuration issues, GitHub API failures, or template rendering problems. It propagates these errors through the call stack to ensure that failures during repository synchronization are logged and reported correctly.

Sources: src/error.rs:1-38, src/main.rs:1-85

Error Infrastructure

The project defines a custom Error enum using the thiserror crate to provide descriptive error messages and facilitate automatic conversion from external error types.

The Error Enum

The Error enum contains variants for every major subsystem:

Variant	Description
Config(String)	Errors related to reading or validating orchestrator.toml.
Template(String)	Failures when loading templates from the filesystem.
Frontmatter { file, message }	Errors parsing the # @orcastrate block in workflow files.
GitHub(String)	Failures communicated by the GitHub API via octocrab.
Render { template, message }	Errors occurring during Tera template rendering.
YamlValidation(String)	Triggered when rendered output or workflow content is not valid YAML.
Io(std::io::Error)	Standard input/output failures.
Tera(tera::Error)	Direct errors from the Tera engine.
SerdeYaml(serde_norway::Error)	YAML deserialization errors.
SerdeJson(serde_json::Error)	JSON conversion errors for API payloads.
TomlDeser(toml::de::Error)	Configuration parsing errors.

Sources: src/error.rs:5-35

Result Alias

The project uses a standard Result alias to simplify function signatures:
pub type Result<T> = std::result::Result<T, Error>;

Sources: src/error.rs:38

Sync Failure Propagation

During the synchronization process, Orcastrate implements a "fail-soft" approach for individual repositories. If a repository fails to sync, the error is captured, logged to GitHub Actions annotations, and stored in a SyncResult structure.

The diagram shows how errors are isolated per repository to prevent one failure from stopping the entire sync process.

Sources: src/sync.rs:142-166, src/main.rs:53-57

GitHub Actions Integration

When running within GitHub Actions, the gha module converts internal errors into platform-specific commands.

• Annotations: The gha::error function prints ::error::{msg} to create a red error banner in the GitHub UI.
• Warnings: Non-fatal issues (like failing to get a single file) use gha::warning for ::warning::{msg} banners.
• Groups: Sync operations are wrapped in ::group and ::endgroup to collapse logs, making errors easier to locate.

Sources: src/gha.rs:1-25, src/sync.rs:205-212

API and Parsing Error Handling

Specific logic handles common external failures, particularly with GitHub and YAML parsing.

GitHub API Error Filtering

The GitHubClient differentiates between terminal API errors and expected missing resources.

• Not Found (404): Functions like list_workflows catch 404 errors to return an empty list rather than an error, as a repository may validly have no workflows.
• Unprocessable Entity (422): When creating a branch, a 422 error indicates the branch already exists. The client catches this and attempts a force-update (patch) instead of failing.

Sources: src/github/mod.rs:88-100, src/github/mod.rs:145-163, src/github/mod.rs:335-341

Frontmatter Validation

The parser for Orcastrate metadata enforces strict start and end markers. It returns specific Frontmatter errors if:

1. The start marker # @orcastrate is found without an end marker.
2. The end marker # @end-orcastrate is found without a start marker.
3. The YAML inside the markers is malformed.

Sources: src/template/frontmatter.rs:38-66

Summary of Error Recovery

Orcastrate prioritizes reporting over immediate termination. By collecting errors in SyncResult and SyncReport, the system provides a comprehensive summary of all failures at the end of the run. This allows administrators to see exactly which repositories or templates require attention without needing to re-run the tool for every individual fix.

Sources: src/sync.rs:13-24, src/main.rs:53-57