Compilation Process | GitHub Agentic Workflows
Skip to main content Compilation Process This guide documents the internal compilation process that transforms markdown workflow files into executable GitHub Actions YAML. Understanding this process helps when debugging workflows, optimizing performance, or contributing to the project. Overview Section titled “Overview” The gh aw compile command transforms a markdown workflow file into a complete GitHub Actions .lock.yml by embedding frontmatter and setting up runtime loading of the markdown body.
The process runs five compilation phases (parsing, validation, job construction, dependency resolution, and YAML generation) described below. When the workflow runs, the markdown body is loaded at runtime — you can edit instructions without recompilation. See Editing Workflows for details. Network access Section titled “Network access” Workflow schemas and built-in Actions/AW lint rules are bundled with the CLI; they do not download schemas or install linters during compilation.
Remote imports and action references not covered by cached or embedded pins can require GitHub requests. --validate additionally checks runtime packages, container images, and repository features. External scanners are opt-in and may download container images or contact upstream services. Interactive compilation performs a best-effort compiler update check at most once every 24 hours. It runs in the background with a three-second total budget, cancels outstanding requests when compilation finishes, and probes identical current/latest release tags only once. --no-check-update disables this check; CI and non-interactive invocations skip it.
Update-check timestamps persist in gh-aw-update-check under the operating system’s per-user cache directory, with owner-only permissions on Unix. Legacy shared temporary markers are ignored. Opt-in Syft scans save SBOMs in a unique, private gh-aw-syft-sboms-* temporary directory and print each file’s path. Successful outputs remain available for inspection and can be deleted when no longer needed; directories with no successful scans are removed. gh aw update refreshes upstream state on each invocation, but shares action release lists and tag resolutions across actions from the same repository within that invocation.
Release lists use 100 entries per page, and source content already fetched for comparison or merging is reused. By default, update also recompiles workflows, so a separate gh aw compile is unnecessary unless additional compilation options are required. When SDK authentication is available, update uses native GitHub API clients with pooled HTTP connections for source metadata, workflow downloads, release lists, and action tags, instead of starting a fresh gh api subprocess for each request.
Host selection follows the GitHub CLI helpers, including GH_HOST and repository detection. If native client setup fails, existing GitHub CLI requests remain available. Independent action release lookups, container digest lookups, and final action integrity checks run in bounded batches of up to eight concurrent operations. Concurrent requests for the same action metadata share one fetch, including failures. Action tags resolve through the commit endpoint with a SHA-only response, avoiding separate annotated-tag peeling requests and commit diff downloads.
Successful resolutions also prove commit existence; final validation reuses that evidence only within the same update invocation, checks the stored version/SHA pair against it, and fetches any unverified entries. Cache changes, workflow rewrites, and summaries are applied sequentially after each batch. Container digest resolution uses registry metadata only ( docker buildx imagetools inspect , then crane digest ); it never pulls full images to discover their digests.
If both methods fail, the command reports the failure and preserves any existing pin rather than downloading image layers. gh aw update --verbose prints network-operation start messages and completion messages with elapsed time and success/failure status. These cover GitHub CLI calls, native source/commit API requests, public API fallbacks, Git workflow downloads, and each metadata-only container-digest resolution strategy.
Native update requests also report connection reuse, DNS lookup, TCP connect, TLS handshake, and time to first response byte (measured from request start, including connection setup). GitHub CLI timings include subprocess startup and all pages requested by that invocation; they are not per-page HTTP timings. Request headers, credentials, and response bodies are not included. Repository Configuration ( aw.json ) Section titled “Repository Configuration (aw.json)” .github/workflows/aw.json stores repository-wide compilation settings.
Field Type Default Description lock_file_logo boolean true Include the ASCII logo in generated workflow headers, including companion workflows. Set to false to omit only the logo. issue_label string "agentic-workflows" Label used to create and find gh-aw’s own issues, including detection trackers, failure issues, and maintenance reports. .github/workflows/aw.json { "lock_file_logo" : false } gh aw compile --no-logo disables the logo for a single invocation, even when lock_file_logo is true .
Omitting the flag does not override lock_file_logo: false . Metadata, manifests, the “DO NOT EDIT” notice, and regeneration instructions are unchanged. For repositories with prefixed routing labels, set "issue_label": "area:agentic-workflows" . The value must be a nonblank label name of at most 50 characters, without control characters or GitHub Actions expressions. Recompile workflows after changing it. Existing issues must carry the configured label to be found by label-based lookups and cleanup; gh-aw does not relabel them automatically.
Per-output labels remain additive. Command labels such as agentic-workflows:disable are unchanged. Compilation Phases Section titled “Compilation Phases” Phase 1: Parsing and Validation Section titled “Phase 1: Parsing and Validation” The compiler extracts the YAML frontmatter, validates it against the workflow schema, validates expression safety (only allow-listed GitHub Actions expressions), and resolves imports.
With --validate , generated Actions YAML also passes through a native Go port of the Actions language-services parsers . The port uses the pinned upstream workflow schema and expression grammar, including field-specific context restrictions and implicit if expressions. Compiler validation adds the supported workflow/job cache-mode values ( read , write , write-only , none ) missing from that schema; the upstream conformance parser remains unchanged.
It supplements the existing JSON Schema, dependency, and security checks; it does not evaluate expressions, fetch reusable workflows, or replace the compiler’s Actions graph. Diagnostics identify positions in the generated YAML. Compiler expression extraction, condition optimization, import fallback folding, and context-reference checks share this parser and its quote-aware interpolation scanner. Reference detection and rewriting use AST access nodes, including single-quoted bracket notation, rather than matching reference-like text inside string literals.
Existing security allowlists still apply. Actions string literals require single quotes with doubled-quote escaping ( 'can''t' ); double-quoted and backtick literals, previously accepted by some compiler helpers, are rejected. The separate gh-aw experiment-comparison shorthand is normalized before Actions parsing. The parser runs offline, without Node.js or npm. Its conformance suite replays checked-in official-parser results during Go tests.
To compare directly against the pinned @actions/workflow-parser and @actions/expressions packages, run npm ci --prefix pkg/workflow/actionslanguageservice/conformance --ignore-scripts followed by make test-actions-parser-conformance . CI runs both the recorded corpus and additional bou
The rest of this page is on the live site.