GitHub Agentic Workflows (gh-aw)

Write agentic workflows in natural-language markdown, compile them to secure GitHub Actions YAML, and run them with AI engines (Copilot, Claude, Codex).

Docs: https://github.github.com/gh-aw/ Repo: https://github.com/github/gh-aw

Help — Topic Navigator

When the user asks for help with gh-aw or a specific topic, use this table to find the right reference file. Read the reference only when needed.

When responding to a help request, list these topics and ask which area the user needs guidance on. Then load only the relevant reference file.

Quick Start (10 minutes)

1. Install the CLI Extension

gh extension install github/gh-aw
# Or standalone (works in Codespaces / restricted networks):
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash

Verify: gh aw version

2. Add a Sample Workflow

gh aw add-wizard githubnext/agentics/daily-repo-status

The wizard checks prerequisites, selects an engine, sets up the required secret, adds the workflow + lock file, and optionally triggers a run.

3. Customize

1. Edit .github/workflows/daily-repo-status.md (markdown body — no recompile needed)
2. If you changed frontmatter, recompile: gh aw compile
3. Commit both .md and .lock.yml, push

Core Workflow

Creating a Workflow

Three methods, in order of ease:

Method A — Wizard (recommended for existing workflows):

gh aw add-wizard githubnext/agentics/<workflow-name>

Method B — AI-assisted (recommended for new workflows): Prompt a coding agent with:

Create a workflow for GitHub Agentic Workflows using
https://raw.githubusercontent.com/github/gh-aw/main/create.md

The purpose of the workflow is: <describe your goal>

Method C — Manual:

1. Create .github/workflows/<name>.md with frontmatter + markdown body
2. Compile: gh aw compile
3. Commit both .md and .lock.yml

Workflow File Structure

.github/workflows/
├── my-workflow.md          # Source (frontmatter + markdown)
└── my-workflow.lock.yml    # Compiled GitHub Actions YAML (generated)

Minimal example:

---
on:
  issues:
    types: [opened]
permissions:
  contents: read
safe-outputs:
  add-comment:
tools:
  github:
    toolsets: [issues]
---

# Issue Responder

Read issue #${{ github.event.issue.number }}.
Add a helpful comment with relevant resources.

What Requires Recompilation

Compiling

gh aw compile                    # All workflows
gh aw compile my-workflow        # Single workflow
gh aw compile --watch            # Watch mode
gh aw compile --verbose          # Debug output
gh aw compile --strict           # Enhanced security validation
gh aw compile --purge            # Remove orphaned .lock.yml files
gh aw compile --dependabot       # Generate dependency manifests

Running

gh aw run <workflow-name>        # Trigger via CLI
gh aw status                     # Check all workflow states
gh aw list                       # List all workflows

Also runnable from GitHub Actions UI (Actions tab > select workflow > Run).

Debugging

gh aw logs <workflow-name>       # View recent logs
gh aw audit <run-id>             # Detailed run analysis
gh aw mcp inspect <workflow>     # Check MCP server/tool config

Enable Actions debug: set repo secret ACTIONS_STEP_DEBUG = true.

Use Copilot Chat: /agent agentic-workflows debug <description>

Workflow Authoring Essentials

Frontmatter (YAML between ---)

Key fields (see references/frontmatter-reference.md for the complete spec):

---
on: daily on weekdays                    # Trigger (fuzzy schedule)
engine: copilot                          # AI engine (copilot|claude|codex)
permissions:
  contents: read                         # Minimal permissions
tools:
  github:
    toolsets: [default]                  # MCP tool groups
safe-outputs:
  create-issue:                          # Pre-approved write operations
    title-prefix: "[bot] "
    max: 3
    expires: 7
network:
  allowed: [defaults, python]            # Domain allowlist
imports:
  - shared/reporting.md                  # Reusable components
---

Markdown Body

Write clear, action-oriented natural language instructions:

• Structured headings for multi-step processes
• Specific criteria and examples for consistent AI decisions
• Use ${{ needs.activation.outputs.text }} for sanitized user input
• Use ${{ github.event.issue.number }}, ${{ github.actor }}, etc.
• Do NOT use ${{ secrets.* }} or ${{ env.* }} in the markdown body

Templating

Conditional sections:

{{#if github.event.issue.number}}
Analyze issue #${{ github.event.issue.number }}.
{{/if}}

Runtime imports (load files at execution time):

{{#runtime-import coding-standards.md}}
{{#runtime-import? optional-file.md}}
{{#runtime-import https://example.com/checklist.md}}

File paths restricted to .github/ folder. No recursion.

Engine Configuration

Switching Engines

engine: copilot    # Default — uses COPILOT_GITHUB_TOKEN
engine: claude     # Uses ANTHROPIC_API_KEY
engine: codex      # Uses OPENAI_API_KEY

Extended Engine Config

engine:
  id: copilot
  model: claude-sonnet-4          # Override model
  agent: my-custom-agent          # .github/agents/my-custom-agent.agent.md
  args: ["--add-dir", "/workspace"]
  env:
    DEBUG_MODE: "true"
  concurrency:
    group: "gh-aw-copilot-${{ github.workflow }}"

Setting Up Secrets

gh aw secrets set COPILOT_GITHUB_TOKEN    # For Copilot
gh aw secrets set ANTHROPIC_API_KEY       # For Claude
gh aw secrets set OPENAI_API_KEY          # For Codex
gh aw secrets bootstrap                   # Auto-detect and prompt

Validation & Quality

Compile-Time Validation

Strict mode (strict: true or --strict) enforces:

• No direct write permissions (use safe-outputs instead)
• Explicit network configuration required
• No wildcard * in allowed domains
• Ecosystem identifiers preferred over individual domains
• GitHub Actions pinned to commit SHAs

Validate Without Compiling

gh aw compile <workflow> --validate

Apply Automated Fixes

gh aw fix --write                # Apply all codemods
gh aw fix <workflow> --write     # Fix specific workflow

Codemods: sandbox-false-to-agent-false, network-firewall-migration, safe-inputs-mode-removal, schedule-at-to-around-migration, and more.

Upgrade Workflows

gh aw upgrade                    # Update agents, apply codemods, recompile
gh aw upgrade -v                 # Verbose
gh aw upgrade --no-fix           # Skip codemods

Repository Initialization

gh aw init                       # Interactive setup
gh aw init --no-mcp              # Skip MCP server integration
gh aw init --push                # Auto-commit and push
gh aw init --completions         # Install shell completions

Creates: .gitattributes, .github/aw/ prompt files, .github/agents/agentic-workflows.agent.md, Copilot instructions.

Common Patterns (Quick Reference)

See references/patterns-and-examples.md for full details on all 14 patterns.

Advanced Features (Quick Reference)

Memory

tools:
  cache-memory: true              # 7-day retention, /tmp/gh-aw/cache-memory/
  repo-memory:                    # Unlimited retention via Git branches
    branch-name: memory/my-data

Imports (Reusable Components)

imports:
  - shared/reporting.md                          # Local
  - githubnext/agentics/shared/tools.md@v1.0.0   # Remote (pinned)

Cross-Repository Operations

safe-outputs:
  github-token: ${{ secrets.CROSS_REPO_PAT }}
  create-issue:
    target-repo: "org/other-repo"
tools:
  github:
    mode: remote

Orchestrator / Worker Pattern

safe-outputs:
  dispatch-workflow:
    workflows: [worker-a, worker-b]
    max: 10

Ephemerals (Auto-Expiring Resources)

safe-outputs:
  create-issue:
    expires: 7                     # Auto-close after 7 days
    close-older-issues: true       # Replace previous reports
on:
  schedule: daily
  stop-after: "+30d"               # Auto-disable workflow after 30 days

CLI Quick Reference

# Setup
gh extension install github/gh-aw
gh aw init
gh aw secrets bootstrap

# Workflow management
gh aw add-wizard <source>         # Interactive add
gh aw add <source>                # Non-interactive add
gh aw compile [workflow]          # Compile to .lock.yml
gh aw run <workflow>              # Trigger run
gh aw list                        # List workflows
gh aw status                      # Check states

# Debugging
gh aw logs [workflow]             # View logs
gh aw audit <run-id>              # Detailed analysis
gh aw mcp inspect <workflow>      # Check MCP config

# Maintenance
gh aw upgrade                     # Update + recompile
gh aw fix --write                 # Apply codemods
gh aw compile --purge             # Clean orphaned locks
gh aw secrets set <name>          # Set secret
gh aw trial <workflow>            # Test in isolation