github/gh-aw

GitHub Agentic Workflows (`gh‑aw`)

What it is – gh‑aw is a GitHub CLI extension that lets you write agentic workflows: Markdown files (with a YAML front‑matter header) that describe a task for an AI agent and the surrounding GitHub Actions configuration needed to run it. When you run gh aw compile, the tool validates the file and emits a normal .github/workflows/*.yml file that GitHub Actions can execute.

Why it matters – Traditional CI/CD steps are deterministic scripts. Some repository tasks (triaging new issues, reviewing PRs, investigating flaky CI, updating docs, analysing dependencies, generating reports) benefit from reasoning, natural‑language understanding, or code generation. gh‑aw gives you a way to plug in large‑language‑model engines (Copilot, Claude, OpenAI Codex, Gemini, Pi) into your existing CI pipeline while keeping the security model of GitHub Actions.

Core concepts

Concept	What it does
Agentic workflow file	A Markdown file whose front‑matter defines triggers, permissions, tools, and which AI engine to use; the body contains the prompt that tells the agent what to accomplish.
`gh aw compile`	Validates the workflow file and generates a locked GitHub Actions workflow (`.lock.yml`).
Read‑only agent jobs	By default the AI runs in a sandbox with only read‑only GitHub access.
Safe‑outputs jobs	Separate jobs that receive the agent’s suggested writes, validate them, and apply them with scoped permissions.
Built‑in AI engines	Supports GitHub Copilot, Anthropic Claude, OpenAI Codex, Google Gemini, and Pi out of the box.

Key features (as described in the README)

Markdown‑based authoring – write prompts in plain text, version‑controlled alongside code.
YAML front‑matter configuration – specify triggers (e.g., on: issue_comment), required permissions, and which LLM to call.
Secure execution model – default read‑only sandbox; optional writes go through a validation step (safe‑outputs).
Seamless CI/CD integration – the compiled workflow is a standard GitHub Actions file, so it works with existing runners, self‑hosted or GitHub‑hosted.
Multiple LLM providers – pick the engine that fits your cost, latency, or policy requirements.
Extensible tooling – you can add custom tools or linters (the repo includes a cmd/linters package and a make golint‑custom target).
Comprehensive docs – quick‑start guide, engine authentication docs, example library, security architecture overview, and an FAQ.

Typical use cases

Issue triage – an agent reads new issues, classifies them, and adds appropriate labels.
Pull‑request review – the LLM suggests code‑review comments or highlights potential bugs.
CI failure investigation – the agent parses logs, searches for known patterns, and posts a summary.
Documentation upkeep – automatically generate or update README sections based on code changes.
Dependency analysis – scan package.json/go.mod and propose upgrades or security patches.
Repository reporting – produce weekly stats (contributors, churn, test coverage) as a markdown report.

Getting started (from the README)

# Install the CLI extension
gh extension install github/gh-aw

# Follow the quick‑start guide (opens in the docs site)
# https://github.github.com/gh-aw/setup/quick-start/

The quick‑start walks you through selecting an AI engine, adding a sample workflow file, and running it via GitHub Actions.

Security model (high‑level)

Agent jobs run with read‑only GitHub permissions and inside a sandboxed environment.
Writes (e.g., creating a label, pushing a commit) are not performed directly. The agent outputs a safe‑output artifact that a separate, scoped job validates and then applies.
Configurable permissions – you can tighten or relax network access, tool usage, and file generation, but you must review them before enabling the workflow.
Human supervision recommended – the README warns that even with safeguards, agents can make mistakes; treat the system as an assistant, not an autonomous operator.

Documentation & resources

Main docs site – https://github.github.com/gh-aw/
Creating a workflow – https://github.github.com/gh-aw/setup/creating‑workflows/
Engine authentication – https://github.github.com/gh-aw/reference/engines/
Examples library – https://github.github.com/gh-aw/examples/
Security architecture – https://github.github.com/gh-aw/introduction/architecture/
Prompt index & corpus – llms.txt and llms‑full.txt in the repo, plus a JSON project summary for AI consumption.

Contributing

The repo follows a typical open‑source flow: see CONTRIBUTING.md for setup. It also ships custom Go linters (cmd/linters) that can be built and tested with go test ./... and make golint‑custom.

Bottom line – gh‑aw provides a structured, secure way to embed LLM‑powered automation into the familiar GitHub Actions CI pipeline, letting developers keep deterministic builds while delegating reasoning‑heavy tasks to AI agents.