gh-aw: Markdown-Defined AI Agents That Compile to GitHub Actions

What gh-aw Actually Compiles

gh-aw is a GitHub CLI extension that turns a Markdown file with YAML frontmatter into a standard GitHub Actions workflow. The frontmatter holds triggers, permissions, tools, and the AI engine selection. The Markdown body is the instruction set for the agent. The command `gh aw compile` validates the source and emits a `.lock.yml` file that Actions runs. This is a compile step, not a runtime interpreter. The generated workflow is what executes, so the source Markdown is a declarative spec, and the lock file is the artifact. The design separates authoring from execution, which is useful for review and auditing.

Where Agentic Workflows Fit in CI/CD

The README is explicit about the boundary: use conventional Actions for deterministic tasks like builds, tests, and deployments. Reach for an agentic workflow when the task needs reasoning or interpretation. Examples listed include issue triage, pull-request review, CI failure investigation, documentation maintenance, dependency analysis, and repository reporting. This is a complement, not a replacement. If you already have a mature CI pipeline, gh-aw slots in as an additional trigger-based job. The reasoning tasks are the ones where a deterministic script would be brittle, because the input is messy natural language or a noisy build log. The tool does not try to make every job intelligent; it targets the subset where an LLM's judgment adds value.

The Two-Part Source Format and the Compile Flow

Each agentic workflow has two parts. The YAML frontmatter configures triggers, permissions, tools, and the AI engine. The Markdown body tells the agent what to accomplish. The `gh aw compile` command validates the source and generates the `.lock.yml` workflow that GitHub Actions executes. That flow is the core mechanism. The compile step is where validation happens, so a malformed frontmatter or an unknown engine should fail before anything runs. The lock file is what you commit and review. This is a deliberate separation: the source is human-readable and editable, the lock file is the executable truth. It resembles a lockfile pattern from package managers, applied to workflow generation.

Security Model: Read-Only Defaults and Safe Outputs

Security is a stated core design concern. The supported agent-job path defaults to read-only GitHub access and sandboxed execution. That means the agent can read the repository and run in an isolated environment, but it cannot write to GitHub by default. Configured writes are handled through `safe-outputs` jobs. These jobs buffer writes, validate them, and apply them in separate jobs with scoped permissions. The key word is scoped: the write job gets only the permissions it needs, not a blanket token. This is a genuine attempt to contain the blast radius of an AI agent's actions. The controls are configurable, so the README warns that workflow authors must review permissions, tools, network access, and generated files before deployment. The warning is direct: using agentic workflows requires careful attention and human supervision, and even then things can go wrong.

Engines and Authentication: Bring Your Own AI Account

gh-aw supports multiple AI engines: GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, and Pi. The description says you can pick whichever AI account you already have. That is a practical advantage. You are not locked into one vendor's model. The documentation has a dedicated path for choosing and authenticating an engine, which suggests the setup varies per provider. The README does not detail the exact authentication flow for each engine, so expect to consult the referenced engine documentation. The multi-engine support is a differentiator compared to tools that are tied to a single model provider. It also means the cost model depends on your chosen engine, not on gh-aw itself.

Getting Started: Install, Configure, Run

Installation is a single command: `gh extension install github/gh-aw`. After that, you follow the quickstart to select an AI engine, add a sample workflow, and run it through GitHub Actions. The README points to the hosted quickstart at https://github.github.com/gh-aw/setup/quick-start/. The actual configuration keys live in the YAML frontmatter, but the README does not list them. You need the reference documentation for the full schema. The compile command is `gh aw compile`. For developers contributing to the project itself, there are custom Go linters. You can test them with `go test ./pkg/linters/<linter-name>/...`, build with `go build ./cmd/linters`, and run the full set with `make golint-custom`. That last command builds `cmd/linters` and runs the custom analyzers against `./cmd/...` and `./pkg/...`. This tells you the project takes its own code quality seriously, with custom static analysis on top of the standard toolchain.

Limits and Wrong-Tool Cases

The biggest limitation is that the README does not show a single concrete frontmatter example or a full workflow file. The quickstart lives on a separate site, so the repository itself is thin on immediate, copy-pasteable detail. You must visit the documentation to see real keys. Another constraint is the safety model's reliance on configuration. The defaults are read-only, which is good, but the moment you enable writes, the burden shifts to you to define the safe-outputs job correctly. If you misconfigure a permission or a tool, the agent could act beyond what you intended. The README's own risk warning is the strongest evidence. For deterministic tasks like a build or a test, gh-aw is the wrong tool. It adds an LLM where a shell script would be faster and more predictable. If your team is not already on GitHub Actions, the extension is useless, because it compiles to Actions workflows. It is also not a general-purpose agent runner; it is tied to the GitHub ecosystem.

Alternatives and How They Differ

The closest alternative is writing GitHub Actions workflows directly with a step that calls an AI CLI, such as `claude` or `codex`, inside a job. That approach gives you full control over the YAML, but you lose the compile-time validation and the safe-outputs pattern. You would need to hand-roll the scoped permissions and the write-buffer logic yourself. Another alternative is a standalone agent framework like LangChain or a custom script that runs outside Actions. Those give you portability across CI systems, but they do not integrate with GitHub's native triggers, permissions, or the Actions execution model. gh-aw's difference is that it makes the agentic workflow a first-class citizen of Actions, with a defined compilation step and a security wrapper. If you want to avoid vendor lock-in to GitHub, the standalone route is the one to consider.

Maintenance, License, and Upgrade Path

The project is written in Go and released under the MIT license, which means you can modify and redistribute it freely, subject to the license terms. The repository is active, with recent releases in August 2026 and a last push on 2026-08-28. The version numbers, v0.87.9 and v0.87.8, indicate a fast-moving project with frequent patches. That implies a maintenance cost: you will want to track releases for security fixes and engine compatibility updates. The README mentions a contributing guide and custom linters, so the project has a defined development process. For upgrades, the standard `gh extension upgrade` command should work, though the README does not state it. The lock file pattern means you can review the diff in generated workflows when you upgrade, which is a concrete way to see what changed.

Editorial conclusion

Adopt gh-aw if your team already lives in GitHub Actions and needs AI agents for tasks like issue triage or PR review without leaving the CI platform. Skip it if your workflows need complex conditional logic or if you cannot accept the risk of AI-generated writes, even with the safe-outputs buffer. Before deploying, verify the exact permissions and tools declared in each workflow's frontmatter, test the .lock.yml output in a fork or a private repo, and confirm your chosen AI engine's billing and authentication path. The project's own README warns that careful human supervision is still required and things can go wrong.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes