Render Command

Relevant source files

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

• src/cli.rs
• src/template/render.rs
• src/template/frontmatter.rs
• src/main.rs
• src/config.rs
• README.md

The render command processes a local GitHub Actions workflow file that contains Orcastrate frontmatter. It extracts template identifiers and parameters from the file, renders the associated Tera template, and outputs the final YAML to standard output.

This command provides a mechanism to validate parameters and preview rendered YAML without requiring GitHub credentials or making network calls. Users often pipe the output of this command to tools like actionlint to verify GitHub Actions syntax after template expansion.

Sources: src/main.rs:43-48, README.md:126-131, src/cli.rs:48-48

Execution Flow

The main.rs file handles the entry point for the render command. It initializes the TemplateRenderer using the directory specified in the orchestrator configuration and reads the target workflow file from the local filesystem.

The following diagram illustrates the data flow from the CLI input to the final output:

The flow shows how the application loads configuration, parses local file content, and applies templates before outputting the result.

Sources: src/main.rs:43-48, src/template/render.rs:56-62, src/template/render.rs:65-71

Template Rendering Logic

The TemplateRenderer class manages the interaction with the Tera engine. When rendering a workflow, it first parses the frontmatter to extract the template ID and the parameter map.

Frontmatter Parsing

Orcastrate searches for a specific comment block delimited by # @orcastrate and # @end-orcastrate. This block must contain valid YAML declaring the template name and optional params. The parser strips the # comment prefixes to create a raw YAML string for deserialization.

Sources: src/template/frontmatter.rs:7-13, src/template/frontmatter.rs:20-56

Tera Integration

The renderer converts the extracted parameters into serde_json::Value objects for compatibility with Tera's context. It appends a .yml extension to the template ID to locate the source file within the configured templates directory.

Sources: src/template/render.rs:28-41

Output Construction

The final output consists of the original frontmatter block followed by the rendered template content. The system ensures the output ends with exactly one newline character.

Sources: src/template/render.rs:49-51, src/template/render.rs:61-61

Validation and Error Handling

The render command performs two primary types of validation:

1. Frontmatter Validation: The parser ensures the start and end markers exist and are correctly ordered. It fails if the YAML within the markers is invalid.
2. YAML Validation: After rendering, the validate_yaml function attempts to parse the result into a generic serde_norway::Value. This ensures that the Tera template did not produce syntactically incorrect YAML.

Sources: src/template/frontmatter.rs:58-69, src/template/render.rs:65-71

Component	Responsibility	Relevant File
Cli	Defines the Render subcommand and workflow path argument.	src/cli.rs
TemplateRenderer	Orchestrates loading, rendering, and YAML validation.	src/template/render.rs
frontmatter::parse	Extracts metadata from the workflow comment block.	src/template/frontmatter.rs
Config	Provides the path to the templates_dir.	src/config.rs

Usage and Examples

The render command is executed via the CLI. It requires a path to a local workflow file.

orcastrate render .github/workflows/ci.yml

If the input file contains the following block:

# @orcastrate
# template: rust-ci
# params:
#   toolchain: nightly
# @end-orcastrate

The command retrieves rust-ci.yml from the templates directory, replaces {{ toolchain }} with nightly, and prints the resulting workflow.

Sources: README.md:126-131, src/template/render.rs:77-88

The render command is a diagnostic and development tool. Unlike the sync command, it does not communicate with the GitHub API, does not check for drift against remote repositories, and does not create Pull Requests. It serves as a local-first utility for template development.

Sources: src/main.rs:43-48, AGENTS.md:23-23