gh-aw

module

v0.68.2 Latest Latest Go to latest Published: Apr 13, 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 ¶

GitHub Agentic Workflows

Write agentic workflows in natural language markdown, and run them in GitHub Actions.

[!NOTE] The Team and the Agents are in Spring Break. Expect delays.

Quick Start

Ready to get your first agentic workflow running? Follow our step-by-step Quick Start Guide to install the extension, add a sample workflow, and see it in action.

Overview

Learn about the concepts behind agentic workflows, explore available workflow types, and understand how AI can automate your repository tasks. See How It Works.

Guardrails

Guardrails, safety and security are foundational to GitHub Agentic Workflows. Workflows run with read-only permissions by default, with write operations only allowed through sanitized safe-outputs. The system implements multiple layers of protection including sandboxed execution, input sanitization, network isolation, supply chain security (SHA-pinned dependencies), tool allow-listing, and compile-time validation. Access can be gated to team members only, with human approval gates for critical operations, ensuring AI agents operate safely within controlled boundaries. See the Security Architecture for comprehensive details on threat modeling, implementation guidelines, and best practices.

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

For complete documentation, examples, and guides, see the Documentation. If you are an agent, download the llms.txt.

Contributing

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

🌍 Community Contributions

Thank you to the community members whose issue reports were resolved in this project! This list is updated automatically and reflects all attributed contributions.

@aaronspindler

#18714 (direct issue)

@abillingsley

#23736 (direct issue)

@adam-cobb

#18295 (direct issue)

@adamhenson

#25345 (direct issue)
#24282 (direct issue)

@adhikjoshi

#18781 (direct issue)

@ajfeldman6

#23924 (direct issue)

@AlexanderWert

#18703 (direct issue)

@alexsiilvaa

#20781 (direct issue)
#20664 (direct issue)

@alondahari

#21207 (direct issue)

@AmoebaChant

#17975 (direct issue)

@apenab

#25626 (direct issue)

@arezero

#20515 (direct issue)
#20513 (direct issue)
#20512 (direct issue)
#20511 (direct issue)
#20510 (direct issue)

@askpt

#17763 (direct issue)

@bbonafed

#25646 (direct issue)
#24949 (direct issue)
#25224 (direct issue)
#24918 (direct issue)
#24896 (direct issue)
#24323 (direct issue)
#23900 (direct issue)
#23724 (direct issue)
#23566 (direct issue)
#22564 (direct issue)
#21990 (direct issue)
#20801 (direct issue)
#20378 (direct issue)
#18542 (direct issue)

@beardofedu

#18723 (direct issue)

@benvillalobos

#25717 (direct issue)
#20885 (direct issue)
network: { allowed: [] } still allows infrastructure domains — same behavior as network: {} (direct issue)
#18115 (direct issue)
#18109 (direct issue)
#18103 (direct issue)
#18101 (direct issue)
#17995 (direct issue)
#17943 (direct issue)
#16625 (direct issue)

@bmerkle

#20646 (direct issue)

@bryanchen-d

#25719 (direct issue)
#23265 (direct issue)

@BrandonLewis

#18263 (direct issue)

@bryanknox

#25351 (direct issue)

@camposbrunocampos

#23726 (direct issue)

@carlincherry

#22017 (direct issue)

@chepa92

#20322 (direct issue)

@chrisfregly

#25349 (direct issue)
#23963 (direct issue)

@chrizbo

#22510 (direct issue)
#21863 (direct issue)
#19347 (direct issue)

@CiscoRob

#20416 (direct issue)

@Corb3nik

#18825 (direct issue)

@corygehr

#25680 (direct issue)
#24355 (direct issue)
#23944 (direct issue)
#23753 (direct issue)

@corymhall

#19839 (direct issue)

@dagecko

#24743 (direct issue)

@Dan-Co

#22707 (direct issue)
#17978 (direct issue)

@danielmeppiel

#20663 (direct issue)
#20380 (direct issue)
#19810 (direct issue)

@davidahmann

#18121 (direct issue)
#17151 (direct issue)
#16360 (direct issue)

@dbudym-cs

#22913 (direct issue)

@devantler

#25768 (direct issue)
#25767 (direct issue)

@deyaaeldeen

#25573 (direct issue)
#25359 (direct issue)
#23198 (direct issue)
#23024 (direct issue)
#23020 (direct issue)
#22957 (direct issue)
#19773 (direct issue)
#19770 (direct issue)

@dholmes

#23578 (direct issue)

@dhrapson

#18385 (direct issue)
#17962 (direct issue)

@DimaBir

#20483 (direct issue)

@DogeAmazed

#22703 (direct issue)

@drehelis

#25304 (direct issue)

@DrPye

#18711 (direct issue)

@dsolteszopyn

#18421 (direct issue)
#17058 (direct issue)

@dsyme

#23936 (direct issue)
#22340 (direct issue)
#20953 (direct issue)
#20952 (direct issue)
#20950 (direct issue)
#20787 (direct issue)
#20578 (direct issue)
#20420 (direct issue)
#20243 (direct issue)
#20241 (direct issue)
#20108 (direct issue)
#20103 (direct issue)
#19976 (direct issue)
#19708 (direct issue)
#19468 (direct issue)
#19465 (direct issue)
#19219 (direct issue)
#19120 (direct issue)
#19104 (direct issue)
#19067 (direct issue)
#18854 (direct issue)
#18831 (direct issue)
#18574 (direct issue)
#18535 (direct issue)
#18485 (direct issue)
#18483 (direct issue)
#18482 (direct issue)
#18481 (direct issue)
#18211 (direct issue)
#18018 (direct issue)
#16145 (direct issue)

@eaftan

#23257 (direct issue)
#20457 (direct issue)
#18412 (direct issue)

@elika56

#16163 (direct issue)

@eran-medan

#16457 (direct issue)

@ericchansen

#20222 (direct issue)

@ericstj

#23766 (direct issue)

@Esomoire-consultancy-Company

#20207 (direct issue)

@ferryhinardi

#24128 (direct issue)

@flatiron32

#22469 (direct issue)

@fr4nc1sc0-r4m0n

#20657 (direct issue)

@G1Vh

#20308 (direct issue)

@glitch-ux

#24403 (direct issue)

@grahame-white

#23643 (direct issue)
#23093 (direct issue)
#23092 (direct issue)
#23088 (direct issue)
#23083 (direct issue)
#20868 (direct issue)
#20719 (direct issue)
#20629 (direct issue)
#20299 (direct issue)

@harrisoncramer

#19441 (direct issue)
#18763 (direct issue)

@heaversm

#18747 (direct issue)

@heiskr

#20394 (direct issue)

@Henry-Shan

#23461 (direct issue)

@holwerda

#21243 (direct issue)

@hrishikeshathalye

[Question] Can I not use a PAT for Copilot? (direct issue)

@IEvangelist

#25467 (direct issue)

@Infinnerty

#21957 (direct issue)

@insop

#21686 (direct issue)

@j-srodka

#25199 (direct issue)
#23485 (direct issue)
#23484 (direct issue)
#23483 (direct issue)
#23482 (direct issue)

@JanKrivanek

#25656 (direct issue)
#25439 (direct issue)
#20187 (direct issue)

@jaroslawgajewski

#24373 (direct issue)
#24372 (direct issue)
#24371 (direct issue)
#24259 (direct issue)
#24036 (direct issue)
#23779 (direct issue)
#23558 (direct issue)
#22647 (direct issue)
#21816 (direct issue)
#20813 (direct issue)
#20811 (direct issue)
#19732 (direct issue)
#18356 (direct issue)
#16467 (direct issue)
#16314 (direct issue)
#16150 (direct issue)

@jeffhandley

#24384 (direct issue)

@jeremiah-snee-openx

#18196 (direct issue)

@johnpreed

#25687 (direct issue)
#23777 (direct issue)
#23212 (direct issue)
#21334 (direct issue)

@johnwilliams-12

#21205 (direct issue)
#21074 (direct issue)
#21071 (direct issue)
#21062 (direct issue)
#20821 (direct issue)
#20779 (direct issue)
#20697 (direct issue)
#20694 (direct issue)
#20658 (direct issue)
#20567 (direct issue)
#20508 (direct issue)

@joperezr

#17243 (direct issue)

@JoshGreenslade

#18480 (direct issue)
#16312 (direct issue)

@kbreit-insight

#24930 (direct issue)
#23940 (direct issue)
#23725 (direct issue)
#22430 (direct issue)
#21978 (direct issue)

@KGoovaer

#18556 (direct issue)

@Krzysztof-Cieslak

#18488 (direct issue)

@look

#23258 (direct issue)

@lpcox

#22281 (direct issue)

@lupinthe14th

#18712 (direct issue)

@mark-hingston

#20335 (direct issue)

@mason-tim

#21562 (direct issue)
#19765 (direct issue)

@MatthewLabasan-NBCU

#19500 (direct issue)

@MattSkala

#24567 (direct issue)
#21203 (direct issue)

@maxbeizer

#18875 (direct issue)

@mcantrell

#20592 (direct issue)

@mhavelock

#22110 (direct issue)

@microsasa

#21098 (direct issue)
#20851 (direct issue)
#20833 (direct issue)
#20586 (direct issue)

@mnkiefer

#22409 (direct issue)
[research] Overview of docs improver agents (direct issue)

@molson504x

#21834 (direct issue)
#21615 (direct issue)

@Mossaka

#21644 (direct issue)
#21630 (direct issue)

@mstrathman

#16005 (direct issue)

@mvdbos

#20411 (direct issue)
#20249 (direct issue)

@neta-vega

#25895 (direct issue)

@NicoAvanzDev

#21542 (direct issue)
#20540 (direct issue)
#20528 (direct issue)

@Nikhil-Anand-DSG

#18200 (direct issue)

@pholleran

#25313 (direct issue)
#23572 (direct issue)
#21313 (direct issue)

@Phonesis

#16236 (direct issue)

@Pierrci

#18587 (direct issue)

@plengauer

#18297 (direct issue)

@pmalarme

#16642 (direct issue)

@ppusateri

#16587 (direct issue)

@praveenkuttappan

#18386 (direct issue)
#18379 (direct issue)

@PureWeen

#23567 (direct issue)

@qwert666

#18162 (direct issue)

@rabo-unumed

#20679 (direct issue)

@racedale

#17982 (direct issue)

@rafael-unloan

#11190 (direct issue)

@rmarinho

#16555 (direct issue)

@rspurgeon

#19451 (direct issue)
#18373 (direct issue)
#15595 (direct issue)

@Rubyj

#21432 (direct issue)
#20283 (direct issue)

@salekseev

#25137 (direct issue)
#25122 (direct issue)
#24135 (direct issue)

@samuelkahessay

#24756 (direct issue)
#24755 (direct issue)
#24754 (direct issue)
#22380 (direct issue)
#22364 (direct issue)
#22161 (direct issue)
#22138 (direct issue)
#21975 (direct issue)
#21955 (direct issue)
#21501 (direct issue)
#21304 (direct issue)
#20035 (direct issue)
#20031 (direct issue)
#20030 (direct issue)
#19605 (direct issue)
#19476 (direct issue)
#19475 (direct issue)
#19474 (direct issue)
#19473 (direct issue)
#19158 (direct issue)
#19024 (direct issue)
#19023 (direct issue)
#19020 (direct issue)
#19018 (direct issue)
#19017 (direct issue)

@samus-aran

#18468 (direct issue)

@seangibeault

#24905 (direct issue)

@srgibbs99

#22939 (direct issue)
#19640 (direct issue)
#19622 (direct issue)
#18751 (direct issue)
#18745 (direct issue)
#17298 (direct issue)

@stacktick

#21361 (direct issue)

@steliosfran

[bug] base-branch in assign-to-agent uses customInstructions text instead of GraphQL baseRef field (direct issue)
[enhancement] Add base-branch support to assign-to-agent safe output for cross-repo PR creation (direct issue)
#16280 (direct issue)

@straub

#24569 (direct issue)
#19631 (direct issue)

@strawgate

#24422 (direct issue)
#24199 (direct issue)
#23935 (direct issue)
#23768 (direct issue)
#21157 (direct issue)
#21144 (direct issue)
#19982 (direct issue)
#21135 (direct issue)
#21028 (direct issue)
#20910 (direct issue)
#20259 (direct issue)
#20168 (direct issue)
#20125 (direct issue)
#20033 (direct issue)
#19172 (direct issue)
#18945 (direct issue)
#18900 (direct issue)
#18744 (direct issue)
#18565 (direct issue)
#18563 (direct issue)
#18547 (direct issue)
#18545 (direct issue)
#18501 (direct issue)
#18362 (direct issue)
#18226 (direct issue)
#17839 (direct issue)
#17828 (direct issue)
#17522 (direct issue)
#17521 (direct issue)
#16896 (direct issue)
#16673 (direct issue)
#16664 (direct issue)
#16511 (direct issue)
#16370 (direct issue)
#16036 (direct issue)
#15982 (direct issue)
#15976 (direct issue)
#15836 (direct issue)
#15583 (direct issue)
#15576 (direct issue)

@susmahad

#25866 (direct issue)
#25710 (direct issue)

@swimmesberger

#19421 (direct issue)

@szabta89

#24037 (direct issue)

@theletterf

#25494 (direct issue)
#18465 (direct issue)

@timdittler

#16331 (direct issue)
#16117 (direct issue)
#16107 (direct issue)

@tomasmed

#20157 (direct issue)

@tore-unumed

#20780 (direct issue)
#19370 (direct issue)
#18329 (direct issue)
#18107 (direct issue)
#17289 (direct issue)

@tspascoal

#20597 (direct issue)
#18123 (direct issue)

@UncleBats

#20359 (direct issue)

@veverkap

#22362 (direct issue)
#21260 (direct issue)
#21257 (direct issue)

@ViktorHofer

#18340 (direct issue)
#18311 (direct issue)

@virenpepper

#23765 (direct issue)

@whoschek

#15510 (direct issue)

@wtgodbe

#25130 (direct issue)
#24921 (direct issue)

@yaananth

#24125 (direct issue)

@yskopets

#25959 (direct issue)
#25833 (direct issue)
#25363 (direct issue)
#25362 (direct issue)
#25125 (direct issue)
#24897 (direct issue)
#24573 (direct issue)
#23914 (direct issue)

⚠️ Attribution Candidates Need Review

The following community issues were closed during this period but could not be automatically linked to a specific merged PR. Please verify whether they should be credited:

@Henry-Shan for Add agentic workflow: Proactive Dependency Auto-Remediation (#23268) — closed 2026-03-28, NOT_PLANNED
@haritha-px for Model version generation issue (#21871) — closed 2026-03-25, NOT_PLANNED
@porada for Support .lock.yaml files (#21828) — closed 2026-03-25, NOT_PLANNED

We welcome your feedback on GitHub Agentic Workflows!

Peli's Agent Factory

See the Peli's Agent Factory for a guided tour through many uses of agentic workflows.

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

Directories ¶

Path	Synopsis
cmd
gh-aw command
gh-aw-wasm command
internal
tools/actions-build command
tools/generate-action-metadata command
pkg
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).
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
envutil Package envutil provides utilities for reading and validating environment variables.	Package envutil provides utilities for reading and validating environment variables.
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.
gitutil
logger Package logger provides namespace-based debug logging with zero overhead when disabled.	Package logger provides namespace-based debug logging with zero overhead when disabled.
parser Package parser provides markdown frontmatter parsing and content extraction for agentic workflow files.	Package parser provides markdown frontmatter parsing and content extraction for agentic workflow files.
repoutil Package repoutil provides utility functions for working with GitHub repository slugs and URLs.	Package repoutil provides utility functions for working with GitHub repository slugs and URLs.
semverutil Package semverutil provides shared semantic versioning primitives used across the pkg/workflow and pkg/cli packages.	Package semverutil provides shared semantic versioning primitives used across the pkg/workflow and pkg/cli packages.
sliceutil Package sliceutil provides utility functions for working with slices.	Package sliceutil provides utility functions for working with slices.
stringutil Package stringutil provides utility functions for working with strings.	Package stringutil provides utility functions for working with strings.
styles Package styles provides centralized style and color definitions for terminal output.	Package styles provides centralized style and color definitions for terminal output.
testutil
timeutil
tty Package tty provides utilities for TTY (terminal) detection.	Package tty provides utilities for TTY (terminal) detection.
types Package types provides shared type definitions used across gh-aw packages.	Package types provides shared type definitions used across gh-aw packages.
typeutil Package typeutil provides general-purpose type conversion utilities.	Package typeutil provides general-purpose type conversion utilities.
workflow Package workflow implements workflow compilation orchestration.	Package workflow implements workflow compilation orchestration.
scripts
tmp smoke_test_22524436360.go - smoke test file for run 22524436360 This file was automatically created during smoke testing and can be safely removed.	smoke_test_22524436360.go - smoke test file for run 22524436360 This file was automatically created during smoke testing and can be safely removed.

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