GitHub Agentic Workflows
Describe AI repo automation in Markdown plus YAML, then compile it into standard, safely sandboxed GitHub Actions workflows.
- Source repo
- github/gh-aw
- Stars
- ★ 5.4k
- Last updated
- today
- License
- MIT
- Primary language
- Go
- FA score
- 57/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesClaude Code · OpenAI API · Claude APIChatGPT (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A maintainer wants new issues auto-triaged, labeled and given a first reply
- Not a fit if
- Teams that need automation outside GitHub Actions
- Teams that cannot send repo data to a cloud AI engine
- Teams unwilling to review permissions and generated files
- Source review
- 57/100 · Major gaps
What does this agent do, and when should you use it?
GitHub Agentic Workflows (gh-aw) is a GitHub CLI extension for defining AI-powered repository automation in Markdown files with YAML frontmatter. The frontmatter configures triggers, permissions, tools and the AI engine; the Markdown body tells the agent what to accomplish, and gh aw compile validates the source and emits a standard .lock.yml GitHub Actions workflow. Built-in engines include GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini and Pi. Agent jobs are read-only and sandboxed by default, while configured GitHub writes go through validated safe-outputs jobs with scoped permissions. It is positioned as a complement to existing CI/CD rather than a replacement, so deterministic builds, tests and deployments stay in conventional Actions.
You write a Markdown file whose YAML frontmatter declares triggers, permissions, available tools and the AI engine, and whose body states the task. gh aw compile validates that source and generates the .lock.yml workflow executed by GitHub Actions. At runtime the agent job runs sandboxed with read-only GitHub access and calls the selected engine (Copilot, Claude Code, Codex, Gemini, Pi) for reasoning; when repository writes are needed, safe-outputs jobs buffer them, validate them, and apply them in separate jobs with scoped permissions. The output is an ordinary Actions run plus the resulting repository changes, such as issue comments or PR reviews.
- A maintainer wants new issues auto-triaged, labeled and given a first reply
- A team wants automated pull-request review while keeping deterministic CI checks
- An engineer needs CI failures investigated from logs and summarized
- A docs team wants periodic detection of stale or missing documentation
- Security or ops staff want recurring dependency analysis and repository reports
How do you install or deploy this agent?
You need the GitHub CLI (gh) and GitHub Actions enabled in the target repository. Then install the extension:
gh extension install github/gh-awAfter installing, follow the official quickstart to pick an AI engine and add a sample workflow. Engine authentication is documented at https://github.github.com/gh-aw/reference/engines/ .
How do you use this agent?
Create an agentic workflow source file (Markdown plus YAML frontmatter), then compile it into an executable Actions workflow:
gh aw compileThe compile step produces a .lock.yml that GitHub Actions runs according to the triggers in the frontmatter. Review permissions, tools, network access and generated files before deploying. Quick-reference source documents:
https://raw.githubusercontent.com/github/gh-aw/main/create.md
https://raw.githubusercontent.com/github/gh-aw/main/install.md
https://raw.githubusercontent.com/github/gh-aw/main/package.md
https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.mdWhat are this agent's strengths and limitations?
- Single Markdown-plus-YAML source compiled into reviewable, versioned standard Actions workflows
- Read-only sandboxed agent jobs with writes isolated behind validated safe-outputs jobs
- Multiple built-in engines (Copilot, Claude Code, Codex, Gemini, Pi) let teams match existing tooling
- Explicitly additive to CI/CD, so deterministic pipelines stay untouched and migration risk is low
- Distributed as a gh CLI extension, matching native GitHub tooling
- Locked to GitHub Actions and the gh CLI; no path to run outside GitHub
- Requires your own AI engine account or API access, billed per model usage
- README states workflow authors must review permissions and accept risk of things going wrong
- README notes a security vulnerability affecting 0.83.3–0.85.4 whose releases were retired
- Authoring workflows and authenticating engines spans several external docs
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| GitHub Agentic Workflows This agent | 57 · Major gaps | CLIFree + model costs | ★ 5.4k | today | Go | Claude Code · OpenAI API · Claude API |
| n8n-as-code | 79 · Good | IDE extensionFree | ★ 1.6k | 1d ago | TypeScript | — |
| Auto Company | 70 · Some gaps | CLIFree + model costs | ★ 3.1k | 2d ago | Python | Codex · Claude Code |
| WebBrain | 65 · Some gaps | Browser extensionFree + model costs | ★ 1.5k | today | JavaScript | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
README states agent jobs are read-only and sandboxed by default, with writes routed through validated safe-outputs jobs under scoped permissions; ADR-29433 and ADR-43244 show compile-time validation of pull_request_target and permission boundaries, so least_privilege scores 2. User confirmation is only implied via 'review permissions before deployment' guidance with no interactive confirmation flow, so user_confirmation is 1. Data-flow and sensitive-data handling are backed by architecture docs and the P10 token-isolation predicate, scoring 2; dependency security has go.mod advisory comments, a depguard rule, SBOM generation and govulncheck, scoring 2. External effects are buffered and validated via safe-outputs, scoring 2; rollback is limited to retiring affected releases with no workflow-level undo, scoring 1. Source attribution is clear via MIT copyright and GitHub org, scoring 2.
README's two-part workflow model and .lock.yml compilation match the compiler pipeline described in the ADRs, so self_consistency is 2. Dependencies are pinned in go.mod with an explicit replace rationale, dependency_availability 2. ADR-29433 mandates specific error phrases and remediation hints, failure_messages 2; a full runtime error catalogue is not present in the reviewed files, so not 3.
README clearly separates deterministic CI from reasoning-heavy agentic tasks and lists multiple AI engines, audience_and_scenarios 2. capability_boundaries is explicit ('complements, does not replace CI/CD'), 2. trigger_precision is supported by the pull_request_target validator and frontmatter trigger config, 2. environment_fit is thin: only Windows build/integration workflows are shown, no broader environment guidance, 1.
README has a clear contents list, quick start and doc index, information_architecture 2. install_notes gives the gh extension install command, 2. naming_stability is weakened by numerous Draft ADRs with Unknown deciders and auto-generated docs, 1. examples_and_faq only link to an external site with no in-repo examples, 1. known_limitations includes security warnings and at-your-own-risk language, 2. license is full MIT text, 3. versioning_changelog only mentions a retired version range, no changelog file, 1. maintenance_responsibility is supported by SECURITY.md reporting channel and GitHub org ownership, 2.
output_usability is supported by compiling to standard Actions workflows with auditable artifacts, 2. marginal_value comes from controlled automation for reasoning tasks complementing existing CI, 2. cost_benefit lacks cost/quota guidance and the ADRs show many skipped or documentary-only formal tests, so evidence of return on effort is thin, 1.
claim_traceability is supported by ADR predicate-to-test mapping tables and spec references, 2. cross_source_corroboration is weak because ADR-56076 admits 11 of 12 predicates are skipped and the formal model is documentary only, 1. fact_inference_separation is handled by ADRs distinguishing implemented vs pending (t.Skip rationale), 2.
- README itself warns to use with caution and at your own risk, and several releases were retired after a security vulnerability; permissions, tools and network access must be reviewed before deployment.
- ADR-56076 shows 11 of 12 formal predicates are skipped and the formal model is documentary only, so security guarantees should not be assumed continuously verified.
- Several ADRs are Draft, have Unknown deciders, or were generated by AI agents, leaving spec stability and final decision ownership unclear.
- In-repo examples and a changelog are absent; examples and FAQ depend on an external site, limiting offline evidence.
- This is a static source review with no workflow or test execution; confidence is low.
FAQ
Does it replace my existing CI?
Can the agent write to my repository directly?
What does it cost?
Can I run it without GitHub Actions?
.lock.yml executed by GitHub Actions, and the execution and permission model depends on it.