Write agentic workflows in natural language markdown and run them in GitHub Actions. Developed by GitHub Next and Microsoft Research.
gh-aw is an open-source framework developed by GitHub Next and Microsoft Research that enables writing AI agent workflows in natural language markdown and running them in GitHub Actions.
- Markdown Workflow Definition: Use
.md files + YAML frontmatter to define triggers, permissions, tools, etc.
- Natural Language Instructions: Describe AI tasks in natural language within Markdown body—no traditional programming required
- Modular Imports: Support for workflow snippet reuse and composition
- Compile-time Validation: Schema validation, expression safety checks, Action SHA pinning
| Engine | Configuration |
|---|
| GitHub Copilot | Default engine, authenticated via COPILOT_GITHUB_TOKEN |
| Anthropic Claude | Connected via ANTHROPIC_API_KEY |
| OpenAI Codex | Connected via OPENAI_API_KEY |
- Connect external tools and services via Model Context Protocol (MCP)
- MCP Gateway serves as unified HTTP gateway, isolating MCP servers from Agent runtime
| Layer | Mechanism | Protection Goal |
|---|
| Substrate | GitHub Actions VM, Docker containers, iptables | Memory, process, and network isolation |
| Configuration | Schema validation, Action SHA pinning, security scanning | Configuration validity, supply chain security |
| Plan | Lockdown Mode, Safe Outputs, threat detection | Operation scope limiting, output sanitization |
Specific Security Features:
- Safe Outputs: AI Agent has read-only permissions by default; write operations execute through pre-approved independent Jobs
- Agent Workflow Firewall (AWF): Network egress control with domain-based access control
- MCP Gateway: Unified HTTP gateway routing MCP calls, isolating MCP servers
- Content Sanitization: @mention neutralization, Bot trigger protection, XML/HTML tag conversion
- Secret Redaction: Automatic scanning and masking of sensitive information
- Threat Detection Pipeline: AI-driven threat detection jobs, integrable with TruffleHog, Semgrep
| Scenario | Description |
|---|
| Automated Daily Reports | Generate daily repository status reports, analyze issues/PRs/discussions/releases |
| Intelligent Issue Triage | Automatic triage, labeling, and commenting |
| Code Review Assistance | Automated code review suggestion generation |
| Continuous Documentation | Keep README, API docs synchronized with code |
| Incremental Code Improvement | Batched, auditable code quality improvements |
| Command | Purpose |
|---|
gh aw compile | Generate .lock.yml GitHub Actions config from .md workflow |
gh aw compile --watch | Watch mode, auto-compile on file changes |
gh aw run <workflow> | Trigger specified workflow run |
gh aw logs | Download and analyze run logs |
gh aw audit <run-id> | Investigate specific run details |
gh aw status | Check workflow health status |
# 1. Install extension
gh extension install github/gh-aw
# 2. Add sample workflow
gh aw add-wizard githubnext/agentics/daily-repo-status
# 3. Wait for workflow completion (~2-3 minutes)
# 4. Customize workflow
gh aw compile
- Agent Workflow Firewall (AWF): AI Agent network egress control
- MCP Gateway: Unified gateway for MCP server calls