Frontmatter Syntax

Relevant source files

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

• src/template/frontmatter.rs
• README.md
• AGENTS.md
• src/template/render.rs
• src/sync.rs

Frontmatter Syntax defines a metadata block embedded within GitHub Actions workflow files to enable management by Orcastrate. This block identifies a file as "managed," specifies the canonical template to use, and provides the parameters required for rendering that template.

Orcastrate scans workflow files in target repositories for these specific comment blocks. If a file contains valid frontmatter, Orcastrate renders the associated template and compares it against the existing file content to detect drift. Files without this syntax remain ignored by the orchestrator.

Sources: README.md:27-38, src/template/frontmatter.rs:3-5, AGENTS.md:23-28

Structure and Markers

The frontmatter block exists as a YAML comment block at the top of a workflow file. It uses mandatory starting and ending markers to delineate the metadata from the rest of the workflow content.

Block Markers

The parser searches for the following exact strings to identify the metadata section:

• Start Marker: # @orcastrate
• End Marker: # @end-orcastrate

Sources: src/template/frontmatter.rs:6-7, README.md:58-62

Content Format

The content between the markers must be valid YAML. Each line within the block must be prefixed with a hash symbol (#) followed by a space or the hash symbol alone. The parser strips these prefixes before deserializing the YAML content.

Sources: src/template/frontmatter.rs:27-39

The diagram shows the extraction process where raw text is converted into a structured Frontmatter object.
Sources: src/template/frontmatter.rs:21-52

Data Structures

The system represents parsed metadata using specific data structures defined in the frontmatter module.

Frontmatter Struct

This structure holds the deserialized configuration used for template rendering.

Field	Type	Description
template	String	The filename (without extension) of the canonical template in the central repository.
params	HashMap<String, serde_norway::Value>	A map of key-value pairs passed as context to the Tera template engine.

Sources: src/template/frontmatter.rs:10-14, src/template/render.rs:27-28

ParsedWorkflow Struct

When a file is processed, the system returns this structure to track both the metadata and the raw text for later reconstruction.

Field	Type	Description
frontmatter	Option<Frontmatter>	The parsed metadata, if markers were found.
raw_block	Option<String>	The exact raw text of the frontmatter block, including markers and comments.

Sources: src/template/frontmatter.rs:17-20

Parameters and Types

Parameters defined in the params section are injected into Tera templates. These can include strings, booleans, lists, or complex objects.

• String parameters: Used for toolchain versions or branch names.
• Sequence parameters: Used for feature lists or matrices (e.g., features: ["serde", "async"]).
• Default values: Templates often provide defaults for parameters not specified in frontmatter using Jinja2-style filters like {{ toolchain | default(value="stable") }}.

Sources: README.md:120-128, templates/rust-ci.yml:68-71, src/template/render.rs:77-83

Example Frontmatter

# @orcastrate
# template: rust-ci
# params:
#   toolchain: stable
#   features: ["serde", "async"]
# @end-orcastrate

Sources: src/template/frontmatter.rs:71-77, README.md:120-126

Parsing Logic and Validation

The parser enforces strict rules to ensure workflow integrity and prevent accidental data loss.

1. Marker Order: The start marker must appear before the end marker.
2. Completeness: If a start marker is found without an end marker (or vice-versa), the system returns a Frontmatter error and skips the file.
3. YAML Integrity: The content must be valid YAML; otherwise, an error is logged and reported in the sync report.
4. Preservation: During the sync process, Orcastrate preserves the raw_block to ensure the metadata remains at the top of the updated file.

Sources: src/template/frontmatter.rs:46-60, src/sync.rs:293-296, src/template/render.rs:59-62

The sequence diagram illustrates how the sync module coordinates parsing and rendering based on the presence and validity of frontmatter.
Sources: src/sync.rs:282-302, src/template/render.rs:55-63

Conclusion

Frontmatter Syntax serves as the primary integration point between local repository workflows and central orchestration. By encapsulating configuration within standard YAML comments, it allows repositories to opt-in to managed updates while maintaining valid GitHub Actions syntax.

Sources: README.md:27-38, AGENTS.md:23-28