Frontmatter

The frontmatter section of GitHub Agentic Workflows includes the triggers, permissions, AI engines, and workflow settings. For example:

---
on:
  issues:
    types: [opened]

tools:
  edit:
  bash: ["gh issue comment"]
---
...markdown instructions...

Frontmatter Elements

The frontmatter combines standard GitHub Actions properties (on, permissions, run-name, runs-on, timeout_minutes, concurrency, env, environment, container, services, if, steps, cache) with GitHub Agentic Workflows-specific elements (description, source, github-token, imports, engine, strict, roles, features, safe-outputs, network, tools, cache-memory).

Trigger Events (on:)

The on: section uses standard GitHub Actions syntax to define workflow triggers, with additional fields for security and approval controls:

• Standard GitHub Actions triggers (push, pull_request, issues, schedule, etc.)
• reaction: - Add emoji reactions to triggering items
• stop-after: - Automatically disable triggers after a deadline
• manual-approval: - Require manual approval using environment protection rules
• forks: - Configure fork filtering for pull_request triggers

See Trigger Events for complete documentation.

Description (description:)

The description: field provides a human-readable description of the workflow that is rendered as a comment in the generated lock file. This helps document the purpose and functionality of the workflow.

description: "Workflow that analyzes pull requests and provides feedback"

The description appears in the lock file header as a comment:

# This file was automatically generated by gh-aw. DO NOT EDIT.
# To update this file, edit the corresponding .md file and run:
#   gh aw compile
# For more information: https://github.com/githubnext/gh-aw/blob/main/.github/instructions/github-agentic-workflows.instructions.md
#
# Workflow that analyzes pull requests and provides feedback

name: "PR Analyzer"
...

Source Tracking (source:)

The source: field tracks workflow origin (format: owner/repo/path@ref). This field is automatically populated when using gh aw add to install workflows from external repositories, enabling traceability, update tracking, and auditing.

source: "githubnext/agentics/workflows/ci-doctor.md@v1.0.0"

When you run gh aw add githubnext/agentics/ci-doctor@v1.0.0, the source field is automatically added to the workflow frontmatter. This field is optional for manually created workflows.

GitHub Token (github-token:)

The github-token: field configures the default GitHub token for the entire workflow. This token is used for engine authentication, checkout steps, and safe-output operations unless overridden at more specific levels.

github-token: ${{ secrets.CUSTOM_PAT }}

Secret Expression Required

The github-token field must use a GitHub Actions secret expression (e.g., ${{ secrets.CUSTOM_PAT }}). Plaintext tokens are rejected during compilation to prevent accidental secret leakage.

Valid formats:

• ${{ secrets.GITHUB_TOKEN }}
• ${{ secrets.CUSTOM_PAT }}
• ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

Invalid formats:

• ghp_1234567890... (plaintext token)
• ${{ env.MY_TOKEN }} (environment variable; not protected like secrets)
• my-secret-token (plaintext string)

The token precedence hierarchy allows fine-grained control:

1. Individual safe-output github-token (highest priority) - e.g., create-issue.github-token
2. Safe-outputs global github-token - e.g., safe-outputs.github-token
3. Top-level github-token - Workflow-level default
4. Default fallback - ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

This enables setting a workflow default while allowing specific operations to use different tokens. See the Security Guide for complete token configuration documentation.

Permissions (permissions:)

The permissions: section uses standard GitHub Actions permissions syntax to specify the permissions relevant to the agentic (natural language) part of the execution of the workflow. See GitHub Actions permissions documentation.

# Specific permissions
permissions:
  issues: write
  contents: read
  pull-requests: write

# All permissions
permissions: write-all
permissions: read-all

# No permissions
permissions: {}

If you specify any permission, unspecified ones are set to none.

Permission Validation

The compiler validates that workflows have sufficient permissions for their configured tools. When GitHub toolsets require permissions not declared in the frontmatter, the compiler behavior depends on the mode:

Non-strict mode (default):

gh aw compile

Emits actionable warnings with suggestions to either add missing permissions or reduce toolset requirements:

warning: Missing required permissions for github toolsets:
  - contents: write (required by repos)
  - issues: write (required by issues)

To fix this, you can either:

Option 1: Add missing permissions to your workflow frontmatter:
permissions:
  contents: write
  issues: write

Option 2: Reduce the required toolsets in your workflow:
Remove or adjust toolsets that require these permissions:
  - issues
  - repos

Strict mode:

gh aw compile --strict

Treats under-provisioned permissions as compilation errors, requiring workflows to declare all necessary permissions before deployment.

Use strict mode for production workflows that require enhanced security validation or compliance with security policies.

Repository Access Roles (roles:)

Controls who can trigger agentic workflows based on repository permission level. Defaults to [admin, maintainer, write] for security.

roles: [admin, maintainer, write]  # Default
roles: [admin, maintainer]         # Restrict to admin/maintainer only
roles: [write]                     # Allow write access only
roles: all                         # Allow any user (⚠️ use with caution)

Available roles: admin (full access), maintainer (manage repository), write (push and manage issues/PRs), read (read/clone only), all (no permission checking).

Workflows with potentially unsafe triggers (push, issues, pull_request) automatically enforce permission checks. Safe triggers (schedule, workflow_run) skip checks by default. Failed permission checks cancel the workflow with a warning.

Strict Mode (strict:)

Enables enhanced validation for production workflows, enforcing security constraints. When enabled, the compiler rejects workflows that don’t meet strict mode requirements.

strict: true  # Enable (default: false)

Strict mode enforces: (1) no write permissions for contents, issues, or pull-requests (use safe-outputs instead), (2) explicit network configuration required, (3) no wildcard * in network.allowed, (4) network configuration for custom MCP servers with containers.

Enable with strict: true in frontmatter or gh aw compile --strict (CLI flag applies to all workflows and takes precedence). Use for production workflows requiring enhanced security validation or security policy compliance.

Feature Flags (features:)

Enable experimental or optional features for your workflow using feature flags. Each feature is a boolean key-value pair.

features:
  my-experimental-feature: true

Firewall Feature Removed

The features.firewall flag has been removed. Use network.firewall instead. See Network Permissions for details.

Correct format:

network:
  firewall: true

AI Engine (engine:)

The engine: section specifies which AI engine to use to interpret the markdown section of the workflow, and controls options about how this execution proceeds. See AI Engines for details.

engine: copilot

Network Permissions (network:)

Control network access for AI engines using ecosystem identifiers and domain allowlists. See Network Permissions for detailed configuration options, security model, and examples.

Quick example:

engine:
  id: claude

network:
  allowed:
    - defaults              # Basic infrastructure
    - python               # Python/PyPI ecosystem
    - "api.example.com"    # Custom domain

Safe Outputs (safe-outputs:)

See Safe Outputs Processing for automatic issue creation, comment posting and other safe outputs.

Run Configuration (run-name:, runs-on:, timeout_minutes:)

Standard GitHub Actions properties:

run-name: "Custom workflow run name"  # Defaults to workflow name
runs-on: ubuntu-latest               # Defaults to ubuntu-latest (main job only)
timeout_minutes: 30                  # Defaults to 20 minutes

Workflow Concurrency Control (concurrency:)

GitHub Agentic Workflows automatically generates concurrency policies for the agent job to control concurrent execution.

See Concurrency Control for complete documentation on agent concurrency configuration.

Environment Variables (env:)

GitHub Actions standard env: syntax:

env:
  CUSTOM_VAR: "value"
  SECRET_VAR: ${{ secrets.MY_SECRET }}

Environment Protection (environment:)

The environment: section specifies the environment that the job references, enabling deployment protection rules and environment-specific secrets and variables. This follows standard GitHub Actions syntax for job-level environment configuration.

Simple environment name:

environment: production

For more information about environments, see GitHub Action’s environment documentation.

Container Configuration (container:)

The container: section specifies a container to run the job steps in, useful for standardized execution environments or specific runtime requirements.

Simple container image:

container: node:18

For more information about environments, see GitHub Action’s container documentation.

Service Containers (services:)

The services: section defines service containers that run alongside your job, commonly used for databases, caches, or other dependencies during testing and deployment.

Simple service:

services:
  postgres:
    image: postgres:13
    env:
      POSTGRES_PASSWORD: postgres
    ports:
      - 5432:5432

For more information about containers and services, see GitHub Action’s container documentation.

Conditional Execution (if:)

Standard GitHub Actions if: syntax:

if: github.event_name == 'push'

Custom Steps (steps:)

Add custom steps before the agentic execution step using GitHub Actions standard steps: syntax:

steps:
  - name: Install dependencies
    run: npm ci

If no custom steps are specified, a default step to checkout the repository is added automatically.

Post-Execution Steps (post-steps:)

Add custom steps after the agentic execution step using GitHub Actions standard steps: syntax. These steps run after the AI engine completes, regardless of whether the AI execution succeeds or fails (unless you add conditional expressions).

post-steps:
  - name: Upload Results
    if: always()
    uses: actions/upload-artifact@v4
    with:
      name: workflow-results
      path: /tmp/gh-aw/
      retention-days: 7

  - name: Generate Summary
    run: |
      echo "## Workflow Complete" >> $GITHUB_STEP_SUMMARY
      echo "AI execution finished" >> $GITHUB_STEP_SUMMARY

Post-steps are useful for:

• Uploading artifacts generated during AI execution
• Creating workflow summaries or reports
• Cleanup operations
• Triggering downstream workflows

Cache Configuration (cache:)

Cache configuration using standard GitHub Actions actions/cache syntax:

Single cache:

cache:
  key: node-modules-${{ hashFiles('package-lock.json') }}
  path: node_modules
  restore-keys: |
    node-modules-

Related Documentation

See also: Trigger Events, AI Engines, CLI Commands, Workflow Structure, Network Permissions, Command Triggers, MCPs, Tools, Imports