Text of github.github.com › gh-aw › specs › frontmatter-hash-specification as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Frontmatter Hash Specification | GitHub Agentic Workflows

Skip to main content Frontmatter Hash Specification Version : 1.0.0 Status : Draft Publication Date : 2026-05-07 Latest Version : frontmatter-hash-specification Editor : GitHub Agentic Workflows Team This document specifies the algorithm for computing a deterministic hash of agentic workflow frontmatter, including contributions from imported workflows. Purpose Section titled “Purpose” The frontmatter hash provides: Stale lock detection : Identify when the compiled lock file is out of sync with the source workflow (e.g. after editing the .md file without recompiling) Reproducibility : Ensure identical configurations produce identical hashes across languages (Go and JavaScript) Change detection : Verify that workflow configuration has not changed between compilation and execution Conformance Section titled “Conformance” Conformance Classes Section titled “Conformance Classes” Basic Conformance : An implementation MUST compute a deterministic SHA-256 hash from canonicalized frontmatter input and MUST produce the same output for identical input.

Full Conformance : An implementation MUST satisfy Basic Conformance and MUST implement cross-language consistency checks between Go and JavaScript implementations. Requirements Notation Section titled “Requirements Notation” The key words MUST , MUST NOT , REQUIRED , SHALL , SHALL NOT , SHOULD , SHOULD NOT , RECOMMENDED , MAY , and OPTIONAL in this document are to be interpreted as described in RFC 2119 . Terminology Section titled “Terminology” Frontmatter : The YAML metadata block at the top of a workflow file that defines execution behavior, tool configuration, and runtime options.

BFS traversal : Breadth-first traversal of the workflow import graph where imports are processed level-by-level and sibling order follows the imports: declaration order. Diamond dependency : An import-graph shape where multiple parent workflows reference the same downstream workflow; the shared workflow is included once using first-seen BFS order. Canonical JSON : A deterministic JSON representation with normalized key ordering and formatting rules so equivalent input produces identical byte output across runtimes.

Hash Algorithm Section titled “Hash Algorithm” 1. Input Collection Section titled “1. Input Collection” Collect all frontmatter from the main workflow and all imported workflows in breadth-first order (BFS traversal): Main workflow frontmatter : The frontmatter from the root workflow file Imported workflow frontmatter : Frontmatter from each imported file in BFS processing order Includes transitively imported files (imports of imports) Agent files ( .github/agents/*.md ) only contribute markdown content, not frontmatter BFS Traversal and Tie-Breaking Rules Section titled “BFS Traversal and Tie-Breaking Rules” The BFS traversal processes imports level by level, starting from the root workflow.

When a workflow imports multiple files, they are enqueued left-to-right in the order they appear in the imports: list. This ordering is preserved at every level. Diamond-import handling : If a workflow file appears more than once in the import graph (a “diamond” dependency), the first occurrence in BFS order determines where that file’s frontmatter is merged; all subsequent occurrences of the same file MUST be silently skipped .

Implementations MUST detect duplicate import paths using canonical path comparison (case-sensitive, no trailing-slash normalization) and discard duplicates without error. Example (diamond graph) : root.md → imports: [a.md, b.md] a.md → imports: [shared.md] b.md → imports: [shared.md] BFS queue order: [root.md, a.md, b.md, shared.md] shared.md appears twice but is processed only once (after a.md in queue order). Canonical hash input order: root → a → b → shared.

If the root import list were reversed to [b.md, a.md] , the canonical order would be root → b → a → shared . The first sibling encountered in BFS order always claims the shared dependency. Later duplicates are skipped. This rule ensures that the hash is deterministic regardless of which traversal path first discovers a shared dependency. 2. Field Selection Section titled “2. Field Selection” Include the following frontmatter fields in the hash computation: Core Configuration: engine - AI engine specification on - Workflow triggers permissions - GitHub Actions permissions tracker-id - Workflow tracker identifier Tool and Integration: tools - Tool configurations (GitHub, Playwright, etc.) mcp-servers - MCP server configurations network - Network access permissions safe-outputs - Safe output configurations mcp-scripts - Safe input configurations Runtime Configuration: runtimes - Runtime version specifications (Node.js, Python, etc.) services - Container services cache - Caching configuration Workflow Structure: steps - Custom workflow steps post-steps - Post-execution steps jobs - GitHub Actions job definitions Metadata: description - Workflow description labels - Workflow labels bots - Authorized bot list timeout-minutes - Workflow timeout secret-masking - Secret masking configuration Import Metadata: imports - List of imported workflow paths (for traceability) inputs - Input parameter definitions Excluded Fields: Markdown body content (not part of frontmatter) Comments and whitespace variations Field ordering (normalized during processing) 2.1 Field Selection and Merge Strategy Table Section titled “2.1 Field Selection and Merge Strategy Table” Field Included in hash Merge strategy engine Yes Replace on Yes Replace permissions Yes Deep merge tools Yes Deep merge mcp-servers Yes Deep merge safe-outputs Yes Append mcp-scripts Yes Append steps Yes Append jobs Yes Append imports Yes Track (ordered list) inputs Yes Deep merge by input key 3.

Canonical JSON Serialization Section titled “3. Canonical JSON Serialization” Transform the collected frontmatter into a canonical JSON representation: 3.1 Merge Strategy Section titled “3.1 Merge Strategy” For each workflow in BFS order: Parse frontmatter into a structured object Merge with accumulated frontmatter using these rules: Replace : engine , on , tracker-id , description , timeout-minutes Deep merge : tools , mcp-servers , network , permissions , runtimes , cache , services Append : steps , post-steps , safe-outputs , mcp-scripts , jobs Union : labels , bots (deduplicated) Track : imports (list of all imported paths) 3.2 Normalization Rules Section titled “3.2 Normalization Rules” Apply these normalization rules to ensure deterministic output: Key Sorting : Sort all object keys alphabetically at every level Array Ordering : Preserve array order as-is (no sorting of array elements) Whitespace : Use minimal whitespace (no pretty-printing) Number Format : Represent numbers without exponents (e.g., 120 not 1.2e2 ) Boolean Values : Use lowercase true and false Null Handling : Include null values explicitly Empty Containers : Include empty objects {} and empty arrays [] String Escaping : Use JSON standard escaping (quotes, backslashes, control characters) 3.3 Serialization Format Section titled “3.3 Serialization Format” The canonical JSON includes all frontmatter fields plus version information: { "bots" : [ " copilot " ], "cache" : {}, "description" : " Daily audit of workflow runs " , "engine" : " claude " , "imports" : [ " shared/mcp/tavily.md " , " shared/jqschema.md " ], "jobs" : {}, "labels" : [ " audit " , " automation " ], "mcp-servers" : {}, "network" : { "allowed" : [ " api.github.com " ]}, "on" : { "schedule" : " daily " }, "permissions" : { "actions" : " read " , "contents" : " read " }, "post-steps" : [], "runtimes" : { "node" : { "version" : " 24 " }}, "mcp-scripts" : {}, "safe-outputs" : { "create-discussion" : { "category" : " audits " }}, "services" : {}, "steps" : [], "template-expressions" : [ " ${{ env.MY_VAR }} " ], "timeout-minutes" : 30 , "tools" : { "repo-memory" : { "branch-name" : " memory/audit " }}, "tracke

The rest of this page is on the live site.