gh-aw Prompt Surface

This repository builds gh-aw (GitHub Agentic Workflows), a GitHub CLI extension for writing workflows in markdown and compiling them to GitHub Actions.

What this surface does

• Converts markdown workflow specs (.md) into compiled lock files (.lock.yml)
• Supports multiple AI engines (copilot, claude, codex, custom)
• Integrates tools, including GitHub MCP servers and safe-output tooling
• Provides CLI commands to compile, run, inspect, and audit workflows

Key concepts

1. Workflow compilation: edit workflow markdown, then recompile lock files
2. Engine selection: set engine in frontmatter to control runtime agent behavior
3. MCP tools: configure GitHub/MCP toolsets in frontmatter for repository operations
4. Safe outputs: workflow-safe issue/comment output paths and constraints

Representative usage examples

# Compile markdown workflows to lock files
gh aw compile

# Run a workflow manually
gh aw run .github/workflows/daily-skill-optimizer.md

# Inspect MCP server usage in workflows
gh aw mcp list
gh aw mcp inspect daily-skill-optimizer

# Audit a workflow run
gh aw audit 24814681146

Where to learn more in this repo

• /AGENTS.md for development/agent workflow conventions
• /skills/*/SKILL.md for focused domain guidance (GitHub MCP, docs, errors, etc.)

GitHub Agentic Workflows

Write agentic workflows in natural language markdown, and run them in GitHub Actions.

[!NOTE] Releases 0.68.4 through 0.71.3 are being retired due to a bug that impacts billing. If you are running one of these versions, please upgrade to the latest release as soon as possible.

Contents

• Quick Start
• Overview
• Guardrails
• Documentation
• FAQ
• Contributing
• Community Contributions
• Share Feedback
• Peli's Agent Factory
• Related Projects

Quick Start

Ready to get your first agentic workflow running? Follow our step-by-step Quick Start Guide to install the extension, add a sample workflow, and see it in action.

Overview

Learn about the concepts behind agentic workflows, explore available workflow types, and understand how AI can automate your repository tasks. See How It Works. Supports GitHub Copilot, Claude (Anthropic), Codex (OpenAI), and Gemini (Google) — pick whichever AI account you already have.

Guardrails

Guardrails, safety and security are foundational to GitHub Agentic Workflows. Workflows run with read-only permissions by default, with write operations only allowed through sanitized safe-outputs. The system implements multiple layers of protection including sandboxed execution, input sanitization, network isolation, supply chain security (SHA-pinned dependencies), tool allow-listing, and compile-time validation. Access can be gated to team members only, with human approval gates for critical operations, ensuring AI agents operate safely within controlled boundaries. See the Security Architecture for comprehensive details on threat modeling, implementation guidelines, and best practices.

Using agentic workflows in your repository requires careful attention to security considerations and careful human supervision, and even then things can still go wrong. Use it with caution, and at your own risk.

Documentation

For complete documentation, examples, and guides, see the Documentation. If you are an agent, download llms.txt or the full corpus llms-full.txt.

If you are running a version between 0.68.4 and 0.71.3, upgrading is strongly recommended due to a bug that impacts billing.

Contributing

For development setup and contribution guidelines, see CONTRIBUTING.md.

Custom Go linters

To build and test repository custom linters:

• go test ./pkg/linters/<linter-name>/...
• go build ./cmd/linters
• make golint-custom

make golint-custom builds cmd/linters and runs the custom analyzers against ./cmd/... and ./pkg/....

🌍 Community Contributions

• @abillingsley: #23736 (direct issue)
• @adamhenson: #25345 (direct issue), #24282 (direct issue)
• @ahmadabdalla: #27473 (direct issue)
• @ajfeldman6: #23924 (direct issue)
• @AkshatRaj00: #34302 (direct issue)
• @AlexDeMichieli: #26645 (direct issue)
• @alexsiilvaa: #20781 (direct issue), #20664 (direct issue)
• @alondahari: #21207 (direct issue)
• @anthonymastreanvae: #32481 (direct issue), #32479 (direct issue), #30897 (direct issue), #30841 (direct issue)
• @apenab: #25626 (direct issue)
• @app/github-actions: #31288 (direct issue), #30740 (direct issue), #29561 (direct issue), #29343 (direct issue), #26257 (direct issue), #26256 (direct issue), #26255 (direct issue), #26254 (direct issue), #26253 (direct issue)
• @arezero: #20515 (direct issue), #20514 (direct issue), #20513 (direct issue), #20512 (direct issue), #20511 (direct issue), #20510 (direct issue)
• @arthurfvives: #30356 (direct issue), #30088 (direct issue), #26223 (direct issue), #25993 (direct issue), #25294 (direct issue)
• @askpaisa: #29240 (direct issue)
• @b2pacific: #28720 (direct issue)
• @bartul: #29499 (direct issue)
• @bbonafed: #29174 (direct issue), #29173 (direct issue), #29172 (direct issue), #29171 (direct issue), #27670 (direct issue), #27472 (direct issue), #26719 (direct issue), #26045 (direct issue), #26043 (direct issue), #25646 (direct issue), #25224 (direct issue), #24949 (direct issue), #24918 (direct issue), #24896 (direct issue), #24323 (direct issue), #23900 (direct issue), #23724 (direct issue), #23566 (direct issue), #22564 (direct issue), #21990 (direct issue), #20801 (direct issue)
• @benvillalobos: #25717 (direct issue), #20885 (direct issue)
• @bmerkle: #31689 (direct issue), #26621 (direct issue), #20646 (direct issue)
• @bryanchen-d: #34109 (direct issue), #34108 (direct issue), #30866 (direct issue), #30704 (direct issue), #30695 (direct issue), #30472 (direct issue), #28774 (direct issue), #26696 (direct issue), #26487 (direct issue), #25719 (direct issue), #23265 (direct issue)
• @bryanknox: #25351 (direct issue)
• @Calidus: #33188 (direct issue), #26923 (direct issue)
• @camposbrunocampos: #23726 (direct issue), #22897 (direct issue)
• @carlincherry: #22017 (direct issue)
• @chrisfregly: #25349 (direct issue), #23963 (direct issue)
• @chrizbo: #34980 (direct issue), #32446 (direct issue), #31399 (direct issue), #28158 (direct issue), #22510 (direct issue), #21863 (direct issue)
• @clementbolin: #28888 (direct issue)
• @cogni-ai-ee: #32803 (direct issue), #32741 (direct issue)
• @Corb3nik: #21306 (direct issue)
• @corygehr: #33622 (direct issue), #33436 (direct issue), #33367 (direct issue), #31577 (direct issue), #27638 (direct issue), #26539 (direct issue), #26270 (direct issue), #26268 (direct issue), #25680 (direct issue), #24355 (direct issue), #23944 (direct issue), #23753 (direct issue)
• @dagecko: #24743 (direct issue)
• @Daidanny008: #27402 (direct issue)
• @Dan-Co: #22707 (direct issue)
• @danielmeppiel: #29076 (direct issue), #28678 (direct issue), #20663 (direct issue)
• @danquirk: #30403 (direct issue)
• @dbudym-cs: #22913 (direct issue)
• @devantler: #25768 (direct issue), #25767 (direct issue)
• @deyaaeldeen: #28966 (direct issue), #26486 (direct issue), #25573 (direct issue), #25359 (direct issue), #23198 (direct issue), #23024 (direct issue), #23020 (direct issue), #22957 (direct issue)
• @dfrysinger: #34886 (direct issue), #34885 (direct issue)
• @dholmes: #29228 (direct issue), #23578 (direct issue)
• @DimaBir: #20483 (direct issue)
• @dkurepa: #25511 (direct issue)
• @DogeAmazed: #22703 (direct issue)
• @doughgle: #23655 (direct issue)
• @drehelis: #25304 (direct issue)
• @dsyme: #23936 (direct issue), #22340 (direct issue), #20953 (direct issue), #20952 (direct issue), #20950 (direct issue), #20787 (direct issue), #20578 (direct issue), #20420 (direct issue)
• @duncankmckinnon: #25944 (direct issue)
• @eaftan: #23257 (direct issue), #20457 (direct issue)
• @edburns: #26920 (direct issue)
• @edgeq: #28315 (direct issue), #28308 (direct issue)
• @ericstj: #30260 (direct issue), #23766 (direct issue)
• @ferryhinardi: #24128 (direct issue)
• @flatiron32: #22469 (direct issue)
• @fr4nc1sc0-r4m0n: #20657 (direct issue)
• @GandrotulaRajesh: #33981 (direct issue)
• @glitch-ux: #24403 (direct issue)
• @grahame-white: #23643 (direct issue), #23093 (direct issue), #23092 (direct issue), #23088 (direct issue), #23083 (direct issue), #20868 (direct issue), #20719 (direct issue), #20629 (direct issue)
• @h3y6e: #27794 (direct issue)
• @haavamoa: #30191 (direct issue)
• @hermanho: #32197 (direct issue)
• @holwerda: #21243 (direct issue)
• @IEvangelist: #34998 (direct issue), #33285 (direct issue), #33069 (direct issue), #33068 (direct issue), #33060 (direct issue), #33043 (direct issue), #32536 (direct issue), #32354 (direct issue), #30848 (direct issue), #26908 (direct issue), #25467 (direct issue)
• @Infinnerty: #21957 (direct issue)
• @insop: #21686 (direct issue)
• @j-srodka: #25199 (direct issue), #23485 (direct issue), #23484 (direct issue), #23483 (direct issue), #23482 (direct issue), #23461 (direct issue)
• @jamesadevine: #28957 (direct issue), #26407 (direct issue), #26406 (direct issue)
• @JamesNK: #29310 (direct issue), #28867 (direct issue), #28704 (direct issue)
• @JanKrivanek: #25656 (direct issue), #25439 (direct issue)
• @jaroslawgajewski: #34917 (direct issue), #33644 (direct issue), #33640 (direct issue), #31678 (direct issue), #31658 (direct issue), #25593 (direct issue), #24373 (direct issue), #24372 (direct issue), #24371 (direct issue), #24259 (direct issue), #24036 (direct issue), #23779 (direct issue), #23558 (direct issue), #22647 (direct issue), #21816 (direct issue), #20813 (direct issue), #20811 (direct issue)
• @JasonYeMSFT: