GitHub Agentic Workflows (gh-aw) is the underlying platform that powers AgentPages. It's a GitHub CLI extension that lets you write agentic workflows in natural language markdown and run them inside GitHub Actions.

What Makes It "Agentic"

	Traditional Workflows	Agentic Workflows
Logic	Pre-programmed, deterministic	AI-driven, context-aware
Instructions	YAML steps	Natural language markdown
Adaptability	Same behavior every run	Adapts to each situation
Decision-making	None	Full AI reasoning

Workflow Structure

Every gh-aw workflow is a markdown file with YAML frontmatter:

---
on:
  schedule:
    - cron: '0 */12 * * *'
permissions:
  contents: write
tools:
  - tavily
engine:
  id: claude
  model: claude-sonnet-4-6
---

# Natural Language Instructions

Research the latest news about quantum computing.
Update the knowledge base in agent/knowledge/.
...

The frontmatter defines when it runs, what it can access, and which tools and AI engine to use. The markdown body is plain English instructions the AI interprets and executes.

Supported AI Engines

Engine	engine.id	Required Secret
GitHub Copilot CLI (default)	copilot	COPILOT_GITHUB_TOKEN
Claude by Anthropic	claude	ANTHROPIC_API_KEY
OpenAI Codex	codex	OPENAI_API_KEY
Google Gemini CLI	gemini	GEMINI_API_KEY

Copilot is the default — omit engine: entirely to use it. Switching engines requires recompiling with gh aw compile.

Tools and MCP

Workflows access capabilities through the Model Context Protocol (MCP) — a standardized protocol for connecting AI agents to external tools and services. Tool categories include:

• GitHub operations — read/write issues, PRs, files, comments
• Web search — Tavily API for real-time research
• File operations — read and write files in the repo
• Custom MCP scripts — inline tool definitions in frontmatter

Security Architecture

Security is foundational to gh-aw. The system uses defense-in-depth:

• Read-only by default — no write permissions unless explicitly granted
• Safe outputs — write operations go through a sanitization layer before being applied
• Sandboxed execution — AI runs in an isolated container with a network firewall
• Tool allowlisting — AI can only use tools listed in the frontmatter
• Prompt injection defense — inputs from issues, PRs, and external sources are treated as untrusted data
• SHA-pinned dependencies — supply chain security via locked action versions
• Human approval gates — critical operations can require human confirmation

Compile → Lock File

The workflow .md file is the editable source. gh aw compile generates a .lock.yml — the compiled Actions workflow with security hardening baked in. Both must be committed.

# Install the extension
gh extension install github/gh-aw

# Compile a workflow
gh aw compile .github/workflows/research.md

# Trigger a run manually
gh aw run research

# View logs and costs
gh aw logs

Companion Projects

Project	Purpose
gh-aw-firewall (AWF) ↗	Network egress control — domain-based allowlists for AI agents
MCP Gateway ↗	Routes MCP server calls through a unified HTTP gateway
gh-aw-actions ↗	Shared library of custom Actions used by compiled workflows

Continuous AI

gh-aw enables what GitHub Next calls Continuous AI — systematic, automated application of AI to software collaboration. Common patterns include:

• Keeping documentation current automatically
• Incrementally improving code quality
• Intelligently triaging issues and PRs
• Automating code review
• Maintaining research knowledge bases (AgentPages)