Text of github.github.com › gh-aw › reference › frontmatter as Styx crawled it on Nov 18, 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 | GitHub Agentic Workflows

Skip to main content Frontmatter The frontmatter (YAML configuration section between --- markers) of GitHub Agentic Workflows includes the triggers, permissions, AI engines (which AI model/provider to use), and workflow settings. For example: --- on : issues : types : [ opened ] tools : edit : bash : [ " gh issue comment " ] --- ... markdown instructions... Frontmatter Elements Section titled “Frontmatter Elements” This page summarizes the available frontmatter fields for GitHub Agentic Workflows.

Description ( description: ) Section titled “Description (description:)” Provides a human-readable description of the workflow rendered as a comment in the generated lock file. description : " Workflow that analyzes pull requests and provides feedback " Intent ( intent: ) Section titled “Intent (intent:)” Describes the durable outcome the workflow exists to achieve, rendered as a comment in the generated lock file.

While description explains what the workflow does, intent explains why it exists and should stay implementation-independent, so it remains valid when the implementation changes. intent : " Reduce maintainer attention spent identifying recurring CI regressions. " description : " Analyzes failed CI runs and opens incidents for novel regressions. " Emoji ( emoji: ) Section titled “Emoji (emoji:)” An optional emoji to represent the workflow visually, for example in listings and UI surfaces. emoji : "" Invocation Skip Questions Section titled “Invocation Skip Questions” An optional top-level skip-if-decision list of up to 64 questions evaluated inside AWF before each otherwise eligible agent invocation, including initial execution, retries, resumes, and continuations.

The gate applies to all built-in engines and declarative engines, including command-based, custom-harness, and durable execution paths. Nonempty lists are incompatible with declarative protected-session-capture ; compilation rejects this combination to preserve recorder isolation and verified session ingestion. Questions and referenced files are screened for known credential patterns and configured secret values before transmission.

A match withholds that question as unknown with sensitive_content_blocked . Screening is heuristic; do not reference confidential files merely because they are inside an allowed path. Structured file evidence is still model-readable untrusted data, not an instruction-isolation boundary. skip-if-decision: - Is there no actionable work remaining in @context/task.md? - Has @reports/progress.md established that further execution is unnecessary?

Each question returns deny when its skip condition is established, allow when execution is recommended, or unknown when it abstains. Any deny skips the invocation; otherwise, any allow or all unknown preserves the execution path selected by the deterministic harness. An absent or empty list preserves existing behavior. Decisions cannot override retry limits, budgets, deadlines, or nonrecoverable failures. Questions share one Decisions request through the existing AWF API proxy, using gpt-6-luna-decisions on a configured Copilot provider, or gpt-6-luna when only OpenAI is configured.

No direct-provider fallback or additional credentials are used. Unavailable models or APIs, timeouts, malformed responses, and file-read failures abstain without decision retries. Decision requests remain subject to the proxy’s model and budget policies and its existing usage accounting. Runtime @file references resolve relative to engine.cwd , or the workspace when unset. They are read afresh before each invocation using the existing guarded regular-file reader: only workspace and /tmp/gh-aw/agent paths are eligible; symlinks, hardlinks, sensitive paths, and oversized context are rejected.

Each question’s imports have a 512 KiB ceiling including question text, evidence metadata, and JSON escaping; each read receives the remaining budget. The entire serialized Decisions request is capped at 400,000 UTF-8 bytes, approximately 100,000 tokens at four bytes per token. This is a byte-based estimate, not tokenizer-exact accounting, and includes request framing, questions, choices, and escaped evidence. Questions that would exceed the remaining budget become unknown ; smaller questions can still be evaluated.

Unreadable context also makes only its question unknown . Paths use letters, digits, _ , . , / , and - ; Actions expressions are not supported in questions. Decision metadata is retained in the existing harness retry artifact and as typed harness.decision events in the agent’s unified session. Events contain one-based question indices, outcomes, sanitized error codes, latency, the proposed attempt, and avoidedInvocation ; they never retain file contents or raw provider diagnostics. gh aw audit --json exposes this history under retries.decisions and counts avoided invocations separately from retries.

A denied invocation records a noop if no terminal safe-output exists. The gate does not apply to threat detection or evals. Labels ( labels: ) Section titled “Labels (labels:)” Optional array of strings for categorizing workflows by purpose, team, or functionality. Labels appear in gh aw status output as [automation ci diagnostics] (or a JSON array in --json mode) and can be filtered with gh aw status --label automation .

Each label name is limited to 50 characters. The compiler rejects longer names, including static labels configured for safe outputs. labels : [ " automation " , " ci " , " diagnostics " ] Metadata ( metadata: ) Section titled “Metadata (metadata:)” Optional key-value pairs for storing custom metadata compatible with the GitHub Copilot custom agent spec . metadata : author : John Doe version : 1.0.0 category : automation docs : https://docs.example.com/automation/repository-health Keys must be 1–64 characters; values are string-only, up to 1024 characters. metadata.docs , when present, must be an absolute HTTPS URL.

The compiler preserves it in generated lock-file metadata without fetching it or changing workflow execution. To explicitly reuse a metadata value in OTLP custom span or resource attributes, use a whole-value ${{ github.aw.metadata.<key> }} reference; it resolves against this root workflow’s metadata at compile time. Metadata is not exported automatically. Trigger Events ( on: ) Section titled “Trigger Events (on:)” The on: section uses standard GitHub Actions trigger syntax and adds controls for reactions, status comments, deadlines, approval, fork handling, actor filtering, search-based skipping, pre-activation steps, job dependencies, and trigger-specific authentication.

See Trigger Events for complete documentation. Conditional Execution ( if: ) Section titled “Conditional Execution (if:)” Standard GitHub Actions if: syntax: if : github.event_name == 'push' Token Broker ( token-broker: ) Section titled “Token Broker (token-broker:)” An optional object that independently enables OIDC-authenticated Copilot credential exchange. token-broker: copilot-task: true Select copilot-request , copilot-task , or both independently.

Brokered request authentication is supported in threat-detection and evals jobs; main agent inference remains blocked pending renewable AWF credential support. Request exchanges include the selected LLM inference provider ID. Jobs using brokered credentials run an unconditional post-step to invalidate credentials for that job. copilot-request cannot be combined with permissions.copilot-requests: write . The endpoint comes from the GH_AW_TOKEN_BROKER_URL Actions variable or secret at runtime, not from workflow source or the compiler environment.

Missing configuration or failed credential exchange blocks the affected operation instead of falling back to existing credentials. See enterprise token broker configuration . Imports ( imports: ) Section titled “Imports (imports:)” Share and reuse workflow components across multiple workflows. The imports: fi

The rest of this page is on the live site.