gh-aw

module

v0.86.3 Latest Latest Go to latest Published: Aug 15, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/github/gh-aw

Links

Open Source Insights

README ¶

Configure this project with agentic workflows

Hey agent! If this repository hasn't been configured with agentic workflows yet, here is how to set it up.

Install the gh aw CLI extension using the install script (no GitHub token required):

curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash

Choose an engine, then run the init command to configure the repository. Replace <engine> with copilot, claude, codex, gemini, or pi:
```
gh aw init --engine <engine>
```
Add a daily repo status agentic workflow using the add command:
```
gh aw add --engine <engine> --create-pull-request
```
The workflow should:
- Run on a daily schedule
- Summarize the repository status (open issues, recent PRs, CI health)
- Use the Quick Start engine selector to choose your runtime:
  - For copilot, grant copilot-requests: write
  - For claude, set ANTHROPIC_API_KEY or configure Anthropic WIF. CLAUDE_CODE_OAUTH_TOKEN from claude login is not supported.
  - For codex, set CODEX_API_KEY or OPENAI_API_KEY
  - For gemini, set GEMINI_API_KEY or configure Google WIF
  - For pi, configure provider authentication and the required proxies

GitHub Agentic Workflows

GitHub Agentic Workflows (gh-aw) lets developers define AI-powered repository automation in Markdown with YAML frontmatter and run AI agents securely through GitHub Actions. The gh-aw GitHub CLI extension compiles each agentic workflow into a standard GitHub Actions workflow.

Use conventional GitHub Actions for deterministic builds, tests, linting, deployments, and reproducible scripts. Add an agentic workflow when a task needs reasoning or interpretation, such as issue triage, pull-request review, CI failure investigation, documentation maintenance, dependency analysis, or repository reporting. GitHub Agentic Workflows complements existing CI/CD; it does not replace it.

Built-in AI engines include GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, and Pi. Agent jobs are read-only and sandboxed by default, and configured GitHub writes are normally applied through validated safe-outputs jobs with scoped permissions.

[!NOTE] Releases 0.68.4 through 0.71.3 are being retired due to a bug that impacts billing. If you are running one of these versions, please upgrade to the latest release as soon as possible.

Quick Start

Install the GitHub CLI extension:

gh extension install github/gh-aw

Then follow the GitHub Agentic Workflows quickstart to select an AI engine, add a sample workflow, and run it through GitHub Actions.

How GitHub Agentic Workflows works

An agentic workflow has two parts: YAML frontmatter configures triggers, permissions, tools, and the AI engine; the Markdown body tells the AI agent what to accomplish. The gh aw compile command validates this source and generates the .lock.yml workflow that GitHub Actions executes. Learn how GitHub Agentic Workflows works.

Security and permissions

Security, permissions, and controlled writes are core design concerns. The supported agent-job path defaults to read-only GitHub access and sandboxed execution. Safe outputs buffer configured writes, validate them, and apply them in separate jobs with scoped permissions. These controls are configurable, so workflow authors must review permissions, tools, network access, and generated files before deployment. Learn how GitHub Agentic Workflows handles security and permissions.

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.

Documentation

Use the GitHub Agentic Workflows documentation for these paths:

For AI agents and retrieval tools, use the published agent prompt index, full prompt corpus, and AI-readable project summary.

Contributing

For development setup and contribution guidelines, see CONTRIBUTING.md.

Custom Go linters

To build and test repository custom linters:

go test ./pkg/linters/<linter-name>/...
go build ./cmd/linters
make golint-custom

make golint-custom builds cmd/linters and runs the custom analyzers against ./cmd/... and ./pkg/....

🌍 Community Contributions

^{Community members whose issues were resolved — updated automatically.}

@a-sjogren-accenture (1) @aaronspindler (1) @abillingsley (2) @adam-cobb (1) @adamhenson (2) @adamtasteslikegood (1) @adhikjoshi (1) @ahmadabdalla (1) @ajfeldman6 (1) @AkshatRaj00 (1) @alanpeabody (1) @alcastaneda (1) @AlexanderWert (1) @AlexDeMichieli (1) @alexsiilvaa (2) @alondahari (17) @alvistar (2) @AmoebaChant (1) @anthonymastreanvae (10) @aoxiangtianyu-go (1) @apenab (1) @arabkin (1) @arezero (6) @arthurfvives (8) @Artur- (1) @askpaisa (1) @askpt (1) @astefan (1) @awoisoak (1) @b2pacific (1) @babaakihiro (2) @bartul (1) @bbonafed (23) @beardofedu (1) @benissimo (7) @benvillalobos (12) @blozano-tt (7) @bmerkle (3) @boydj (2) @Bra1nFartz (1) @BrandonLewis (1) @bryanchen-d (23) @bryanknox (1) @bshore-bf (1) @Calidus (7) @camposbrunocampos (2) @carlincherry (1) @carlosflorencio (1) @CatsMiaow (1) @chepa92 (1) @chrisfregly (2) @chrizbo (7) @CiscoRob (2) @cknight (2) @clementbolin (1) @cogni-ai-ee (2) @consulthys (3) @Corb3nik (3) @corygehr (20) @corymhall (1) @crmitchelmore (1) @dagecko (1) @Daidanny008 (1) @Dan-Albrecht (1) @Dan-Co (2) @danielmeppiel (6) @danquirk (1) @darwin-gonzales (1) @davidahmann (3) @davidslater (3) @dbudym-cs (1) @DeagleGross (2) @devantler (2) @deyaaeldeen (10) @dfrysinger (2) @dgolombek (1) @dholmes (3) @dhrapson (2) @DimaBir (1) @dkurepa (1) @DogeAmazed (1) @doughgle (1) @drehelis (4) @DrPye (1) @dsfaccini (2) @dsibilio (3) @dsolteszopyn (2) @dsyme (35) @duncankmckinnon (1) @eaftan (3) @edburns (1) @edgeq (2) @elika56 (1) @emexelem (1) @enbw-mmattes (1) @eran-medan (1) @ericchansen (1) @ericstj (2) @Esomoire-consultancy-Company (1) @Etienne-M (1) @Evangelink (5) @fbecar22 (2) @FDevTakima (1) @ferryhinardi (1) @flatiron32 (2) @florianbader (1) @fr4nc1sc0-r4m0n (1) @funkymonkeyjam (1) @G1Vh (1) @GandrotulaRajesh (1) @github-actions (11) @github-antoine-brechon (4) @GKersten (1) @glitch-ux (1) @grahame-white (9) @graphaelli (1) @GregoireW (1) @h-no (1) @h3y6e (2) @haavamoa (1) @haolpku (1) @harrisoncramer (2) @heaversm (1) @heiskr (7) @hermanho (1) @holwerda (3) @hpsin (1) @hrishikeshathalye (1) @ianreay (1) @IEvangelist (14) @Infinnerty (1) @insop (1) @ivancea (9) @j-srodka (6) @jamesadevine (4) @JamesNK (4) @JanKrivanek (4) @jaroslawgajewski (26) @JasonYeMSFT (1) @jbaruch (1) @jcooklin (1) @jeffhandley (12) @jeremiah-snee-openx (1) @jfomhover (1) @jhamon (2) @jitran (4) @joesturge (1) @johnpreed (5) @johnwilliams-12 (11) @jonathanpeppers (4) @joperezr (1) @JoshGreenslade (2) @jsalmassy (1) @jsoref (2) @jsquire (1) @jtracey93 (1) @kaovilai (4) @karl-petter-sj (1) @katriendg (1) @kbreit-insight (5) @KGoovaer (1) @kkruel8100 (1) @Krzysztof-Cieslak (1) @kthompson (1) @labudis (2) @ladamski (1) @lecoursen (1) @lilseyi (2) @lindeberg (1) @loganrosen (4) @look (1) @lpcox (7) @ludoviclafole (1) @lukeed (1) @lupinthe14th (3) @m-titov (1) @maikelvdh (2) @mark-hingston (1) @mason-tim (8) @matiloti (4) @mattcosta7 (1) @MatthewBunker (2) @MatthewLabasan-NBCU (2) @MattSkala (3) @MauroDruwel (4) @maxbeizer (1) @maxknv (1) @mcantrell (1) @mdashrraf (1) @MH0386 (1) @mhavelock (1) @michen00 (2) @microsasa (9) @mlinksva (1) @mnkiefer (5) @molson504x (2) @Mossaka (3) @mrfelton (5) @mrjf (7) @MrSanchez (1) @mstrathman (1) @mvdbos (2) @nestele (2) @neta-vega (3) @NicoAvanzDev (3) @NicolasRannou (1) @nihal467 (1) @Nikhil-Anand-DSG (1) @NikolajBjorner (2) @norrietaylor (8) @not-mksv (2) @octatone (1) @oscarvalenzuelab (1) @PaulAylward2 (1) @petercort (1) @pethers (1) @pgaskin (1) @pholleran (4) @Phonesis (1) @Pierrci (1) @plengauer (1) @pmalarme (1) @polmichel (2) @ppusateri (1) @praveenkuttappan (1) @PureWeen (10) @qwert666 (1) @r-garcia-de-oliveira (2) @rabo-unumed (4) @racedale (1) @radiantspace (2) @rafael-unloan (1) @rbstp (3) @reggie-k (3) @remypanicker (1) @rhardouin (2) @rmarinho (1) @romainh-betclic (3) @rspurgeon (4) @Rubyj (3) @ruokun-niu (1) @ryckmansm (2) @salekseev (3) @salmanmkc (1) @samuelkahessay (30) @samus-aran (1) @SanthoshNandha (1) @sbodapati-gfm (1) @seangibeault (2) @seesharprun (4) @sg650 (15) @shawnHartsell (1) @shiran-gutsy (1) @shubhamtanwar23 (3) @siyo-rms (1) @srgibbs99 (6) @ssulei7 (1) @stacktick (1) @stefankrzyz (1) @steliosfran (3) @straub (6) @strawgate (48) @susmahad (3) @swimmesberger (1) @syarihu (1) @szabta89 (3) @tadelesh (1) @Tarekchehahde (2) @theletterf (19) @thi-feonir (1) @timdittler (3) @tinytelly (1) @tobio (1) @tomasmed (1) @tore-unumed (16) @trask (4) @tsm-harmoney (5) @tspascoal (2) @tvu4-wowcorp (1) @tylersmalley (1) @UncleBats (2) @v1v (4) @verkyyi (2) @veverkap (3) @ViktorHofer (3) @virenpepper (1) @vishalagrawal-jisr (2) @whoschek (1) @wizardofosmium (1) @wtgodbe (4) @xirzec (1) @yaananth (1) @Yoyokrazy (2) @yskopets (53) @zarenner (5) @zkoppert (2)

GitHub Agentic Workflows is supported by companion projects that provide additional security and integration capabilities:

Agent Workflow Firewall (AWF) - Network egress control for AI agents, providing domain-based access controls and activity logging for secure workflow execution
MCP Gateway - Routes Model Context Protocol (MCP) server calls through a unified HTTP gateway for centralized access management
gh-aw-actions - Shared library of custom GitHub Actions used by compiled workflows, providing functionality such as MCP server file management

Workshop

[!TIP] Ready to learn GitHub Agentic Workflows hands-on? The Factory Tour Workshop is a self-contained, step-by-step workshop repository designed to teach you how to build, run, and customize agentic workflows from scratch.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
gh-aw command
gh-aw-wasm command
linters command Command linters runs the gh-aw custom analysis linters.	Command linters runs the gh-aw custom analysis linters.
internal
tools/actions-build command
tools/generate-action-metadata command
pkg
actionpins Package actionpins provides action pin resolution for GitHub Actions, mapping repository references to their pinned commit SHAs.	Package actionpins provides action pin resolution for GitHub Actions, mapping repository references to their pinned commit SHAs.
agentdrain
cli Package cli provides the command-line interface for gh-aw (GitHub Agentic Workflows).	Package cli provides the command-line interface for gh-aw (GitHub Agentic Workflows).
colorwriter Package colorwriter is a low-level dependency of pkg/logger (which uses it to build its stderr writer).	Package colorwriter is a low-level dependency of pkg/logger (which uses it to build its stderr writer).
console Package console provides terminal UI components and formatting utilities for the gh-aw CLI.	Package console provides terminal UI components and formatting utilities for the gh-aw CLI.
constants
ctxutil Package ctxutil provides small helpers for consistent context.Context handling.	Package ctxutil provides small helpers for consistent context.Context handling.
envutil Package envutil provides utilities for reading and validating environment variables.	Package envutil provides utilities for reading and validating environment variables.
errorutil Package errorutil provides shared helpers for classifying and inspecting errors returned by the GitHub API and gh CLI.	Package errorutil provides shared helpers for classifying and inspecting errors returned by the GitHub API and gh CLI.
fileutil Package fileutil provides utility functions for working with file paths and file operations.	Package fileutil provides utility functions for working with file paths and file operations.
github
githubapi
gitutil
importinpututil
intent
jsonutil
linters Package linters is a namespace for gh-aw's custom Go analysis linters.	Package linters is a namespace for gh-aw's custom Go analysis linters.
linters/appendbytestring Package appendbytestring implements a Go analysis linter that flags append(b, []byte(s)...) calls where b is []byte and s is a string, which can be simplified to append(b, s...) without the redundant conversion.	Package appendbytestring implements a Go analysis linter that flags append(b, []byte(s)...) calls where b is []byte and s is a string, which can be simplified to append(b, s...) without the redundant conversion.
linters/appendoneelement Package appendoneelement implements a Go analysis linter that flags append(s, []T{x}...) calls where a single-element slice literal is spread, which can be simplified to append(s, x).	Package appendoneelement implements a Go analysis linter that flags append(s, []T{x}...) calls where a single-element slice literal is spread, which can be simplified to append(s, x).
linters/bytesbufferstring Package bytesbufferstring implements a Go analysis linter that flags string(buf.Bytes()) calls where buf is a bytes.Buffer value receiver, suggesting buf.String() instead.	Package bytesbufferstring implements a Go analysis linter that flags string(buf.Bytes()) calls where buf is a bytes.Buffer value receiver, suggesting buf.String() instead.
linters/bytescomparestring Package bytescomparestring implements a Go analysis linter that flags string(a) == string(b) and string(a) != string(b) comparisons where both a and b are []byte values, which should use bytes.Equal(a, b) instead for clearer intent.	Package bytescomparestring implements a Go analysis linter that flags string(a) == string(b) and string(a) != string(b) comparisons where both a and b are []byte values, which should use bytes.Equal(a, b) instead for clearer intent.
linters/contextcancelnotdeferred Package contextcancelnotdeferred implements a Go analysis linter that flags context cancel functions called manually instead of deferred.	Package contextcancelnotdeferred implements a Go analysis linter that flags context cancel functions called manually instead of deferred.
linters/ctxbackground Package ctxbackground implements a Go analysis linter that flags calls to context.Background() inside functions that already receive a context.Context parameter.	Package ctxbackground implements a Go analysis linter that flags calls to context.Background() inside functions that already receive a context.Context parameter.
linters/deferinloop Package deferinloop implements a Go analysis linter that flags defer statements placed directly inside for or range loop bodies.	Package deferinloop implements a Go analysis linter that flags defer statements placed directly inside for or range loop bodies.
linters/errorfwrapv Package errorfwrapv implements a Go analysis linter that flags calls to fmt.Errorf that either format error arguments with %v or otherwise pass error arguments without any %w, which breaks error-chain inspection via errors.Is and errors.As.	Package errorfwrapv implements a Go analysis linter that flags calls to fmt.Errorf that either format error arguments with %v or otherwise pass error arguments without any %w, which breaks error-chain inspection via errors.Is and errors.As.
linters/errormessage Package errormessage implements a Go analysis linter that enforces actionable error-message patterns in changed files.	Package errormessage implements a Go analysis linter that enforces actionable error-message patterns in changed files.
linters/errortypeassertion Package errortypeassertion implements a Go analysis linter that flags type assertions on values typed as the built-in error interface when asserting to concrete types, and recommends errors.As for wrapped error traversal.	Package errortypeassertion implements a Go analysis linter that flags type assertions on values typed as the built-in error interface when asserting to concrete types, and recommends errors.As for wrapped error traversal.
linters/errstringmatch Package errstringmatch implements a Go analysis linter that flags calls to strings.Contains/HasPrefix/HasSuffix/EqualFold/Index/LastIndex/Compare on err.Error() with a string literal — all perform brittle substring matching on error messages instead of using errors.Is or errors.As.	Package errstringmatch implements a Go analysis linter that flags calls to strings.Contains/HasPrefix/HasSuffix/EqualFold/Index/LastIndex/Compare on err.Error() with a string literal — all perform brittle substring matching on error messages instead of using errors.Is or errors.As.
linters/excessivefuncparams Package excessivefuncparams implements a Go analysis linter that flags functions with too many positional parameters.	Package excessivefuncparams implements a Go analysis linter that flags functions with too many positional parameters.
linters/execcommandwithoutcontext Package execcommandwithoutcontext implements a Go analysis linter that flags calls to exec.Command inside functions that already receive a context.Context parameter, where exec.CommandContext should be used instead to propagate cancellation.	Package execcommandwithoutcontext implements a Go analysis linter that flags calls to exec.Command inside functions that already receive a context.Context parameter, where exec.CommandContext should be used instead to propagate cancellation.
linters/fileclosenotdeferred Package fileclosenotdeferred implements a Go analysis linter that flags file operations where Close() is not immediately deferred.	Package fileclosenotdeferred implements a Go analysis linter that flags file operations where Close() is not immediately deferred.
linters/fmterrorfnoverbs Package fmterrorfnoverbs implements a Go analysis linter that flags calls to fmt.Errorf where the format string contains no format verbs, in which case errors.New is the idiomatic and cheaper alternative.	Package fmterrorfnoverbs implements a Go analysis linter that flags calls to fmt.Errorf where the format string contains no format verbs, in which case errors.New is the idiomatic and cheaper alternative.