gh-aw: agentic workflows compiled into GitHub Actions

What gh-aw solves, and for whom

Most repository automation is a shell script with a trigger. That works until the input stops being predictable. An issue body, a failing CI log, or a pull request diff does not map cleanly onto an if statement, so teams either write brittle heuristics or leave the task to a human. GitHub Agentic Workflows, or gh-aw, targets that gap. The README is explicit about the split: use conventional GitHub Actions for deterministic builds, tests, linting, deployments, and reproducible scripts, and add an agentic workflow when a task needs reasoning or interpretation. The examples it gives are issue triage, pull-request review, CI failure investigation, documentation maintenance, dependency analysis, and repository reporting. The stated position is that gh-aw complements existing CI/CD rather than replacing it. The audience is therefore repository maintainers and platform engineers who already live in GitHub Actions and want an AI step inside that system rather than a separate bot service. Because the engine list includes GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, and Pi, the pitch is that you can pick whichever AI account you already have instead of opening a new vendor relationship.

How a Markdown file becomes an Actions workflow

The unit of authoring is a single file with two parts. YAML frontmatter configures triggers, permissions, tools, and the AI engine. The Markdown body tells the agent what to accomplish. That file is source; it is not what GitHub runs. The gh aw compile command validates the source and generates a .lock.yml workflow that GitHub Actions executes. This is the same shape as a lockfile in a package manager: you edit the readable input, and a generated artifact is what actually ships. The security model is the second half of the mechanism. According to the README, agent jobs are read-only and sandboxed by default, and configured GitHub writes are normally applied through validated safe-outputs jobs with scoped permissions. Safe outputs buffer the writes the agent wants to make, validate them, and apply them in separate jobs that hold scoped permissions. The agent therefore does not hold a write token while it reasons. The README also states that these controls are configurable, which is the honest caveat: the default is safe, and the configuration is where a maintainer can weaken it. Workflow authors are told to review permissions, tools, network access, and generated files before deployment.

Installing gh-aw and compiling a first workflow

gh-aw ships as a GitHub CLI extension, so the prerequisite is a working gh installation. The README gives one command for the extension itself:

gh extension install github/gh-aw

After that, the README points to the quickstart page for selecting an AI engine, adding a sample workflow, and running it through GitHub Actions. The repository also carries install.md, install-gh-aw.sh, and install-gh-aw.ps1 at the top level, which is where a scripted or offline install path lives. Once a workflow file exists in the repository, the compile step is the command that turns authoring into something runnable:

gh aw compile

The README describes this command as validating the source and generating the .lock.yml workflow that GitHub Actions executes. The practical expectation is that a successful run leaves a generated lock file next to your source, and that the lock file is what you commit and what reviewers read. There is also a container path. The Dockerfile builds an Alpine image with git, jq, bash, curl, ca-certificates, and github-cli, copies in a gh-aw binary, and sets the entrypoint to gh-aw. Its default command is not the compiler. The Dockerfile states that the default command runs the MCP server with actor validation enabled, and that the GITHUB_ACTOR environment variable must be set for logs and audit tools to be available. The image name ghcr.io/github/gh-aw appears in the Makefile as DOCKER_IMAGE, with linux/amd64 and linux/arm64 as the declared platforms.

Where gh-aw is the wrong tool

The README draws the boundary itself, and it is worth taking literally. Deterministic work belongs in ordinary Actions: builds, tests, linting, deployments, reproducible scripts. Putting an agent in front of a build step adds cost, latency, and a class of failure that a shell script does not have. The second limitation is that the project does not claim to make agentic automation safe by default in an absolute sense. The README says that using agentic workflows requires careful attention to security considerations and careful human supervision, and that even then things can still go wrong, closing with a use-it-with-caution statement. That is unusually direct for a README, and it should shape expectations. The third constraint is operational: because compilation produces a generated .lock.yml, there are two artifacts to keep in sync, and a workflow that is edited but not recompiled will not behave the way its source reads. The README does not document rollback behaviour for a deployed workflow, so a team that needs a defined reversal procedure has to design one from the generated files. Finally, the architecture assumes GitHub. If your repositories live elsewhere, the read-only agent job, the safe-outputs write path, and the Actions runner are all unavailable, and the tool has nothing to attach to.

How it differs from running an agent bot directly

The obvious alternative is a standalone agent service: a bot process with its own credentials that listens for webhooks and comments on issues and pull requests. That approach gives you one long-lived process, your own scheduling, and no dependency on the Actions runner. It also means you own a server, a token with broad repository scope, and the audit trail for everything the bot does. gh-aw inverts all three. Execution happens on GitHub Actions, so there is no process to host. The agent job is read-only and sandboxed by default, and writes are routed through validated safe-outputs jobs with scoped permissions rather than through a token the agent holds. The audit trail is the Actions run itself, which is the same place your other CI evidence already lives. The trade-off is that you inherit Actions constraints: runner minutes, workflow triggers, and the compile step. A second alternative is to keep the agent entirely outside CI and have a human paste context into a chat interface. That is cheaper and has no permission surface at all, but it does not scale to every issue or pull request, and it leaves no record attached to the repository. gh-aw is the choice when you want the reasoning step to be a first-class, reviewable artifact in the repository rather than an external service or a manual habit.

Maintenance, upgrades, and the MIT licence

The repository is not archived, and the most recent push recorded is 2026-08-28. The release cadence visible in the release list is fast: v0.87.5 on 2026-08-25, v0.87.8 on 2026-08-28, and v0.87.9 on 2026-08-28. The version numbers sit below 1.0, which is worth weighing against the cadence: frequent patch releases on a pre-1.0 project mean the generated .lock.yml format and the frontmatter schema are the things most likely to move under you. The mitigation is already in the design, since the lock file is generated from source and can be regenerated, but that only holds if your source files are committed and your compile step is part of the change, not a manual afterthought. On the build side, go.mod declares go 1.26.8 and the Makefile builds with go build ./cmd/gh-aw, so teams that vendor or build from source are pinned to a recent Go toolchain. The project also maintains custom Go linters, with make golint-custom building cmd/linters and running the analyzers against ./cmd/... and ./pkg/..., which is relevant only if you intend to contribute. The licence is MIT, which is permissive and imposes no copyleft obligation on your workflows. Note that the licence covers the gh-aw code, not the AI engine you connect to it; the terms and billing of Copilot, Claude, Codex, Gemini, or Pi come from those providers, and the README does not describe them.

Editorial conclusion

Adopt gh-aw if your repository already runs GitHub Actions and you have a recurring task that needs interpretation rather than a fixed script, such as triage, review, or CI failure investigation. Do not adopt it for deterministic builds, tests, linting, or deployments, and do not adopt it if you cannot supervise an agent that runs against repository content. Before writing your first workflow, verify three things: which AI engine credentials the runner will use, what the frontmatter permissions and tools sections grant, and how the generated .lock.yml file is reviewed and committed.

Frequently asked questions

Official sources

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