Text of github.github.com › gh-aw › reference › frontmatter-full 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 Reference | GitHub Agentic Workflows

Skip to main content Frontmatter Reference This document provides a comprehensive reference for all available frontmatter configuration options in GitHub Agentic Workflows. The examples below are generated from the JSON Schema and include inline comments describing each field. Schema Description Section titled “Schema Description” JSON Schema for validating agentic workflow frontmatter configuration Complete Frontmatter Reference Section titled “Complete Frontmatter Reference” --- # Experimental.

Declare third-party endpoints, credential secret names, resource # grants and capability definitions directly in AW Markdown. Import normally and # select capabilities from the main workflow. # (optional) connectors : {} # Experimental. Up to 64 advisory skip questions evaluated inside AWF before each # eligible agent invocation. Nonempty lists emit a compile-time experimental # warning; configuration and behavior may change without deprecation.

Any deny # skips; allow or all unknown preserves deterministic harness eligibility. Runtime # @file references use sandbox filesystem restrictions. Nonempty lists cannot be # combined with declarative protected-session-capture. # (optional) skip-if-decision : [] # Array of strings # Experimental. Select independent Copilot capabilities to authenticate through # the OIDC token broker. Using this field emits a compile-time warning. # Configuration and behavior may change without deprecation. # (optional) token-broker : # Use brokered authentication for supported Copilot inference jobs. # (optional) copilot-request : true # Use brokered authentication for Copilot task creation and issue assignment. # (optional) copilot-task : true # Workflow name that appears in the GitHub Actions interface.

If not specified, # defaults to the filename without extension. # (optional) name : " My Workflow " # Optional workflow description that is rendered as a comment in the generated # GitHub Actions YAML file (.lock.yml) # (optional) description : " Description of the workflow " # Optional statement of the durable outcome the workflow exists to achieve. Unlike # 'description', which explains what the workflow does, 'intent' explains why the # workflow exists and should stay implementation-independent.

Rendered as a # comment in the generated GitHub Actions YAML file (.lock.yml). # (optional) intent : " example-value " # Policy for pre-start Docker images in agent and detection jobs. 'always' # (default) pulls images; 'never' validates exact local RepoDigests and does not # contact a registry. # (optional) docker-image-pull-policy : " always " # Optional emoji to represent the workflow visually in listings and UI surfaces. # (optional) emoji : " example-value " # Optional source reference indicating where this workflow was added from.

Format: # owner/repo/path@ref (e.g., githubnext/agentics/workflows/ci-doctor.md@v1.0.0). # Rendered as a comment in the generated lock file. # (optional) source : " example-value " # Installed source commit, managed by gh aw add and update. Used as the immutable # base for three-way merges while source retains the tracking ref. # (optional) source-sha : " example-value " # Optional workflow location redirect for updates.

Format: workflow spec or GitHub # URL (e.g., owner/repo/path@ref or # https://github.com/owner/repo/blob/main/path.md). When present, update follows # this location and rewrites source. # (optional) redirect : " example-value " # Optional tracker identifier to tag all created assets (issues, discussions, # comments, pull requests). Must be at least 8 characters and contain only # alphanumeric characters, hyphens, and underscores.

This identifier will be # inserted in the body/description of all created assets to enable searching and # retrieving assets associated with this workflow. # (optional) tracker-id : " example-value " # Auditable false-positive suppression annotations for compiler threat-detection # rules. # (optional) threat-detection-suppress : [] # Array items: rule : " example-value " reason : " example-value " # (optional) expires : " example-value " # Optional array of labels to categorize and organize workflows.

Labels can be # used to filter workflows in status/list commands. # (optional) labels : [] # Array of strings # Optional list of skill references to install during activation. Supports remote # repository-wide installs (`owner/repo@<sha>`), remote path-scoped installs # (`owner/repo/skill/path@<sha>`), and local path references (e.g. `skills/rig` or # `.github/skills/my-skill`). Remote static references may use a full 40-character # lowercase commit SHA, or a branch/tag name (resolved to a SHA at compile time). # Omitting the ref (`owner/repo@`) opts out of pinning and triggers a compile-time # warning.

Local paths are installed with --from-local at runtime and are # rewritten to a remote repospec by `gh aw add`. GitHub Actions expressions (`${{ # ... }}`) are also accepted and are evaluated at runtime. Entries may also be # objects to configure per-skill authentication via github-token or github-app. # (optional) skills : [] # Optional metadata field for storing custom key-value pairs compatible with the # custom agent spec.

Key names are limited to 64 characters, and values are # limited to 1024 characters. # (optional) metadata : # Optional absolute HTTPS URL for human-facing workflow documentation. Preserved # in generated lock-file metadata without being fetched during compilation. # (optional) docs : " https://docs.example.com/automation/repository-health " # Workflow specifications to import. Supports array form (list of paths) or object # form with 'aw' (agentic workflow paths) subfield.

Path resolution: (1) relative # paths (e.g., 'shared/file.md') are resolved relative to the workflow's # directory; (2) paths starting with '.github/' or '/' are resolved from the # repository root (repo-root-relative); (3) paths matching 'owner/repo/path@ref' # are fetched from GitHub at compile time (cross-repo). # (optional) # Accepted formats: # Format 1: Array of workflow specifications to import. Three path formats are # supported: relative paths ('shared/file.md'), repo-root-relative paths # ('.github/agents/my-agent.md'), and cross-repo paths ('owner/repo/path@ref'). # Any markdown files under .github/agents directory are treated as custom agent # files and only one agent file is allowed per workflow. imports : [] # Array items: undefined # Format 2: Object form of imports with 'aw' subfield for shared agentic workflow # paths. imports : # Array of shared agentic workflow specifications to import.

Format: # owner/repo/path@ref or relative paths. # (optional) aw : [] # Optional list of additional workflow or action files that should be fetched # alongside this workflow when running 'gh aw add'. Entries are relative paths # (from the same directory as this workflow in the source repository) to agentic # workflow .md files or GitHub Actions .yml/.yaml files. GitHub Actions expression # syntax (${{) is not allowed in resource paths. # (optional) resources : [] # Array of Relative path to a workflow .md file or action .yml/.yaml file.

Must be # a static path; GitHub Actions expression syntax (${{) is not allowed. # If true, inline all imports (including those without inputs) at compilation time # in the generated lock.yml instead of using runtime-import macros. When enabled, # the frontmatter hash covers the entire markdown body so any change to the # content will invalidate the hash. # (optional) inlined-imports : true # Workspace-relative folders to bundle in the activation artifact and restore # before the agent runs.

Useful for activation steps that generate reusable # prompt, skill, or agent context. # (optional) ambient-folders : [] # Array of strings # Workflow triggers that define when the agentic workflow should run. Supports # standard GitHub Actions trigger events plus special command triggers for # /commands (required) # (optional) # Accepted formats:

The rest of this page is on the live site.