1. Project Overview & Quickstart (github/gh-aw)
File: README.md
GitHub Agentic Workflows
Agent quick links
Hello fellow agent! Welcome to GitHub Agentic Workflows = Actions + Agent + Safety.
Here are some pointers to get you started in using this tool.
- Create a new workflow: https://raw.githubusercontent.com/github/gh-aw/main/create.md
- Install: https://raw.githubusercontent.com/github/gh-aw/main/install.md
- Package a workflow repository: https://raw.githubusercontent.com/github/gh-aw/main/package.md
- Reference: https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md
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.
Contents
- Quick Start
- How GitHub Agentic Workflows works
- Security and permissions
- Documentation
- Contributing
- Community Contributions
- Related Projects
- Workshop
Quick Start
Install the GitHub CLI extension:
gh extension install github/gh-awThen 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:
- Create an agentic workflow
- Choose and authenticate an AI engine
- Browse GitHub Agentic Workflows examples by task
- Review the security architecture
- Read the GitHub Agentic Workflows FAQ
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/lintersmake 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)
@b-dantas (1)
@b2pacific (1)
@babaakihiro (2)
@bartul (1)
@bbonafed (23)
@beardofedu (1)
@benissimo (8)
@benvillalobos (12)
@blavity-machine-user (1)
@blozano-tt (7)
@bmerkle (3)
@boydj (2)
@Bra1nFartz (1)
@BrandonLewis (1)
@bryanchen-d (23)
@bryanknox (1)
@bshore-bf (1)
@Calidus (8)
@camposbrunocampos (2)
@carlincherry (1)
@carlosflorencio (1)
@CatsMiaow (1)
@chepa92 (1)
@chrisfregly (2)
@chrizbo (7)
@CiscoRob (2)
@ckittel (1)
@cknight (2)
@clementbolin (1)
@cogni-ai-ee (2)
@consulthys (3)
@Corb3nik (3)
@corygehr (20)
@corymhall (1)
@crmitchelmore (3)
@dagecko (1)
@Daidanny008 (1)
@Dan-Albrecht (1)
@Dan-Co (2)
@danielmeppiel (6)
@danquirk (2)
@darwin-gonzales (1)
@davidahmann (3)
@davidslater (3)
@dbudym-cs (1)
@DeagleGross (3)
@devantler (2)
@deyaaeldeen (10)
@dfrysinger (2)
@dgolombek (1)
@dholmes (3)
@dhrapson (2)
@DimaBir (1)
@dkurepa (1)
@DogeAmazed (1)
@Dongbumlee (2)
@doughgle (1)
@drehelis (4)
@DrPye (1)
@dsfaccini (1)
@dsibilio (4)
@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 (4)
@Evangelink (5)
@fbecar22 (2)
@fchareyr (1)
@FDevTakima (1)
@ferryhinardi (1)
@flatiron32 (2)
@florianbader (1)
@fr4nc1sc0-r4m0n (1)
@funkymonkeyjam (2)
@G1Vh (1)
@GandrotulaRajesh (1)
@github-actions (11)
@github-antoine-brechon (4)
@GKersten (1)
@glitch-ux (1)
@grahame-white (9)
@graphaelli (1)
@GregoireW (1)
@gregsmi (2)
@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 (27)
@JasonYeMSFT (1)
@Jasper13006 (1)
@jbaruch (1)
@jcooklin (1)
@jeffhandley (12)
@jeremiah-snee-openx (1)
@jfomhover (1)
@jhamon (2)
@jitran (5)
@joesturge (1)
@johnpreed (5)
@johnwilliams-12 (11)
@jonathanpeppers (5)
@joperezr (1)
@JoshGreenslade (2)
@joshjohanning (1)
@jsalmassy (1)
@jsoref (2)
@jsquire (1)
@jtracey93 (1)
@kaovilai (4)
@karl-petter-sj (1)
@katriendg (1)
@kbreit-insight (5)
@KGoovaer (1)
@kkruel8100 (2)
@Knufle (1)
@kriptoburak (1)
@Krzysztof-Cieslak (1)
@kthompson (1)
@kubaflo (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 (4)
@MauroDruwel (4)
@maxbeizer (1)
@maxknv (1)
@mcantrell (1)
@mdashrraf (1)
@MH0386 (1)
@mhavelock (1)
@michen00 (2)
@microsasa (10)
@misrarim (1)
@mlinksva (1)
@mnkiefer (11)
@molson504x (2)
@Mossaka (3)
@mrfelton (5)
@mrjf (7)
@MrSanchez (1)
@mstrathman (1)
@mur6 (1)
@mvdbos (2)
@nestele (2)
@neta-vega (3)
@NicoAvanzDev (3)
@NicolasRannou (1)
@nihal467 (1)
@Nikhil-Anand-DSG (1)
@NikolajBjorner (2)
@norrietaylor (8)
@not-mksv (3)
@octatone (1)
@oscarvalenzuelab (1)
@PaulAylward2 (1)
@peter-hendy (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 (5)
@reggie-k (3)
@remypanicker (1)
@rhardouin (2)
@ricohomewood (1)
@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)
@Shazwazza (2)
@shiran-gutsy (1)
@shubhamtanwar23 (3)
@siyo-rms (1)
@srgibbs99 (6)
@ssulei7 (1)
@stacktick (1)
@stefankrzyz (1)
@steliosfran (3)
@stephen2002119 (1)
@straub (6)
@strawgate (48)
@susmahad (3)
@swimmesberger (1)
@syarihu (1)
@szabta89 (3)
@tadelesh (1)
@Tarekchehahde (2)
@theletterf (25)
@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.
File: docs/README.md
Startlight Docs
Project Structure
Inside of your Astro + Starlight project, you'll see the following folders and files:
.
├── public/
├── src/
│ ├── assets/
│ ├── content/
│ │ └── docs/
│ └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.jsonStarlight looks for .md or .mdx files in the src/content/docs/ directory. Each file is exposed as a route based on its file name.
Images can be added to src/assets/ and embedded in Markdown with a relative link.
Static assets, like favicons, can be placed in the public/ directory.
🧞 Commands
All commands are run from the root of the project, from a terminal:
| Command | Action |
|---|---|
npm install |
Installs dependencies |
npm run dev |
Starts local dev server at localhost:4321 |
npm run build |
Build your production site to ./dist/ |
npm run preview |
Preview your build locally, before deploying |
npm run astro ... |
Run CLI commands like astro add, astro check |
npm run astro -- --help |
Get help using the Astro CLI |
⚠️ Known Dev-Mode Limitations
Sitemap behavior in dev and production
The robots file references /gh-aw/sitemap.xml, which is the stable sitemap entrypoint for the docs site.
During a production build (npm run build), Astro generates /gh-aw/sitemap-index.xml, and the static /gh-aw/sitemap.xml entrypoint points crawlers at that generated sitemap index. The generated sitemap index is not available when running the local development server (npm run dev).
If a CI pipeline or automated tool checks the generated sitemap index URL during a local preview, it will receive a 404 response. To verify the production sitemap flow, run npm run build followed by npm run preview.
Robots/AI discovery paths on GitHub Pages project sites
This docs site is deployed as a GitHub Pages project site under /gh-aw/ (see base: '/gh-aw/' in astro.config.mjs).
robots.txtis served at/gh-aw/robots.txt- AI discovery file is served at
/gh-aw/.well-known/ai.txt - AI metadata files are served under
/gh-aw/ai/
Root-level endpoints on https://github.github.com/ (for example /robots.txt) are controlled by the main github.github.com site, not this repository.
Want to learn more?
Check out Starlight’s docs, read the Astro documentation, or jump into the Astro Discord server.
2. Official Technical Reference & Guides (github/docs)
GitHub Docs
Welcome to GitHub Docs! GitHub’s documentation is open source, meaning anyone from inside or outside the company can contribute. For full contributing guidelines, visit our contributing guide.
Quick links by contributor type
Hubbers (GitHub employees): See CONTRIBUTING.md in the
docs-contentrepository for GitHub-specific processes.Open source contributors: See CONTRIBUTING.md in the
docsrepository for a quick-start summary.
How we sync changes across Docs repositories
There are two GitHub Docs repositories:
github/docs(public): Open to external contributionsgithub/docs-internal(private): For GitHub employee contributions.
The two repositories sync frequently. Content changes in one are reflected in the other. Hubbers might prefer to post in docs when working with a customer, but docs has limitations on the types of contributions it accepts to safeguard the site and our workflows. Internal contributions should usually go to docs-internal.
Important: The docs repository accepts contributions to content files (.md files in /content and select /data sections like reusables only). Infrastructure files, workflows, and site-building code are not open for external modification.
New to contributing
Here are some resources to help you get started with open source contributions:
- Finding ways to contribute to open source on GitHub
- Set up Git
- GitHub flow
- Collaborating with pull requests
License
This project is dual-licensed under:
- Creative Commons Attribution 4.0 - for documentation and content in the assets, content, and data folders (see LICENSE)
- MIT License - for code (see LICENSE-CODE)