gh-aw (GitHub Agentic Workflows) is GitHub's own MIT-licensed CLI extension for writing repository automation in plain Markdown that compiles to real GitHub Actions YAML, running Copilot, Claude, Codex, or Gemini as the agent with read-only defaults, sandboxing, and safe-outputs for writes.
- ⭐ 4852
- Go
- MIT
- Updated 2026-08-03
CI/CD Tools Compared: GitHub Actions vs GitLab CI vs Jenkins • Agent Governance Toolkit: Microsoft’s Answer to “Which Agent Did This?”
What Is GitHub Agentic Workflows? # #
GitHub Agentic Workflows (gh-aw) is GitHub’s own answer to “what if a CI workflow’s steps were an AI agent’s judgment instead of a fixed shell script?” The README’s own framing: “Actions + Agent + Safety.” You write repository automation in plain Markdown — a description of what should happen, plus a YAML frontmatter block for trigger and engine config — and gh-aw runs GitHub Copilot, Claude, OpenAI Codex, or Google Gemini as the agent that carries it out inside GitHub Actions.
🔗 GitHub: https://github.com/github/gh-aw
MIT licensed, built and maintained by GitHub itself, at 4,800+ stars, with a commit from August 2, 2026 — the day before this article. Being a first-party GitHub project (not a third-party wrapper around Actions) gives it a credibility baseline most agentic-CI tools don’t start with.
Worth flagging upfront: the README currently warns that releases 0.68.4 through 0.71.3 are being retired due to a bug that impacts billing — if you’re already running gh-aw, check your version and upgrade (gh extension upgrade aw
) before relying on it further.
Installation & Quick Start # #
curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash
No GitHub token is required for the install script itself. Then, inside a repository:
gh aw init
init
configures the repository for agentic workflows — this is a one-time setup step per repo, separate from creating an individual workflow.
gh aw new <workflow-name>
gh aw compile [workflow-name]
gh aw logs [workflow-name]
gh aw audit <run-id>
gh aw fix --write
gh aw compile --validate
How It Actually Runs: Markdown In, .lock.yml #
Out #
This is the architectural detail that matters most: a gh-aw workflow is not directly executable. You author .github/workflows/<name>.md
(Markdown body + YAML frontmatter), and gh aw compile
generates a companion .github/workflows/<name>.lock.yml
— a real, standard GitHub Actions workflow file — which is what GitHub Actions actually runs. The docs recommend marking the generated file in .gitattributes
:
.github/workflows/*.lock.yml linguist-generated=true merge=ours
So the Markdown file is the human-editable source of truth, and the .lock.yml
is a build artifact you commit alongside it — conceptually similar to committing a lockfile next to a manifest.
Choosing an Engine # #
Pick whichever AI account you already have — each engine needs its own credential wired in as a repo secret or permission:
| Engine | What you configure |
|---|---|
| GitHub Copilot | copilot-requests: write permission |
| Claude (Anthropic) | ANTHROPIC_API_KEY repository secret |
| OpenAI Codex | OPENAI_API_KEY repository secret |
| Google Gemini | GEMINI_API_KEY repository secret |
| Custom engine | Documented separately for non-built-in engines |
Guardrails: Read-Only by Default # #
The project’s Guardrails section is unusually direct for a first-party tool, and worth quoting rather than paraphrasing:
Read-only permissions by default— write operations are only allowed through sanitized**“safe outputs”, not raw agent write access Sandboxed executionand network isolationInput sanitizationSupply-chain security**— SHA-pinned dependencies** Tool allow-listingand compile-time validation****Access gating** to team members only, withhuman approval gates for critical operations
And the project’s own bottom line: “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.” That’s not boilerplate — it’s the same maintainer team telling you not to fully trust the guardrails either.
Key Features, at a Glance # #
Natural Language Workflows— Markdown + YAML frontmatter instead of hand-written Actions YAML** Multi-engine support**— Copilot, Claude, Codex, Gemini, or a custom engine** MCP server integration**— connect Model Context Protocol servers for additional tools inside a workflow** Safe Outputs**— structured, sanitized communication channel between the AI and the GitHub API** Strict Mode**— security-first validation and sandboxing** Shared Components**— reusable workflow building blocks across repos** Repo Memory**— persistent, git-backed storage so an agent can retain context across separate runs
gh-aw vs. Hand-Written GitHub Actions # #
| Aspect | gh-aw | Hand-written Actions YAML |
|---|---|---|
| Authoring format | Markdown + YAML frontmatter | Raw YAML |
| What executes the logic | An AI agent (Copilot/Claude/Codex/Gemini) | Fixed shell commands / actions |
| Adapts to unexpected repo state | Yes — agent reasons about context | No — script does exactly what’s written |
| Write permissions | Read-only by default, writes via safe-outputs | Whatever the workflow’s permissions: block grants |
| Compiled artifact | .md source → .lock.yml generated |
YAML is already the final artifact |
| Best fit | Judgment-requiring, variable tasks (triage, summarization, review) | Deterministic, well-defined build/test/deploy steps |
Use Cases # #
1. Daily Repository Status Summaries #
The README’s own quick-start example: a scheduled workflow that summarizes open issues, recent PRs, and CI health — the kind of task that benefits from an agent synthesizing varied signals rather than a fixed report template.
2. Issue Triage and Labeling #
An agent reading a new issue’s content and context to apply labels or route it, rather than keyword-matching rules that miss nuance.
3. PR Review Assistance Inside CI #
Running an agent against a PR diff for a first-pass review comment, gated behind read-only permissions and safe-outputs so it can comment but not merge or push unreviewed changes.
4. Repository Maintenance Tasks That Need Judgment #
Tasks like “check if this dependency bump is safe to auto-merge” benefit from an agent that can read changelogs and test output, versus a purely rule-based bot.
Related Repositories # #
| Repository | Purpose |
|---|---|
Related Articles # #
CI/CD Tools Compared: GitHub Actions vs GitLab CI vs Jenkins— for the underlying CI platform gh-aw builds on top ofAgent Governance Toolkit: Microsoft’s Answer to “Which Agent Did This?”— a complementary governance layer for agents operating outside the CI-specific guardrails gh-aw already ships
Conclusion # #
GitHub Agentic Workflows is GitHub’s own bet that a meaningful slice of CI automation is better expressed as “an agent that understands the task” than as “a script that handles the cases we thought of.” The Markdown-to-.lock.yml
compilation model keeps workflows readable and diffable, the multi-engine support avoids vendor lock-in to one AI provider, and the Guardrails section is refreshingly candid that read-only defaults and safe-outputs reduce risk without eliminating it. The active billing-bug warning for a specific version range is also worth taking as a sign of a fast-moving, not-yet-fully-settled project — check your version before depending on it in production CI.
Best for: Teams already on GitHub Actions who want judgment-requiring automation (triage, summarization, first-pass review) handled by an AI agent, with GitHub’s own guardrails rather than a third-party wrapper.
GitHub: https://github.com/github/gh-aw
Last updated: 2026-08-03