# GitHub Agentic Workflows

> A GitHub CLI extension that compiles Markdown-defined AI agent workflows into secure, sandboxed GitHub Actions workflows.

GitHub Agentic Workflows (gh-aw) is a GitHub CLI extension from GitHub, made by GitHub Next and Microsoft Research, that lets developers define AI-powered repository automation in Markdown with YAML frontmatter. It compiles each workflow into a standard GitHub Actions workflow that runs the chosen coding agent. The project is open source under the MIT license, and the latest release listed is v1.2.2.

## What It Is

An agentic workflow has two parts: YAML frontmatter configures triggers, permissions, tools and the AI engine, and the Markdown body tells the agent what to accomplish. The `gh aw compile` command validates this source and generates a pinned `.lock.yml` workflow for GitHub Actions. It is meant to complement conventional CI/CD, which stays the right fit for deterministic builds, tests and deployments, by handling tasks that need reasoning, such as issue triage, pull-request review, CI failure investigation, documentation maintenance and repository reporting.

## Engines and Example Workflows

Built-in engines include GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini and Pi. The project site also lists Antigravity and sample integrations for other agents, and supports importing custom engine definitions. Ready-made workflows include Repo Assist, CI Doctor, Repo Status and Test Improver, plus others for issue triage, link checking, documentation updates and code simplification. Workflows can be created by prompting a coding agent, from the terminal, or through a wizard.

## Security and Cost Controls

Agent jobs are read-only and sandboxed by default. Configured writes are buffered as safe outputs, checked by threat detection, and applied by a separate job with scoped permissions. The site describes six layers: compile-time validation, a sandboxed agent, credential isolation through an API proxy, integrity filtering of untrusted GitHub content, threat detection, and safe outputs. A staged mode previews outputs without writing. Per-run and daily AI credit caps, `gh aw logs` and `gh aw audit` help monitor cost, and OpenTelemetry traces can go to an OTLP backend.

## Enterprise Deployment

Workflows can run on GitHub-hosted or self-hosted Linux runners, including ARC with Docker-in-Docker, with optional preview microVM runtimes. The docs describe central rollout across organizations. The README advises careful human supervision and review of permissions, tools and network access before deployment.

## Features
- Markdown workflows with YAML frontmatter
- Compiles to pinned GitHub Actions lock files via gh aw compile
- Multiple AI engines: Copilot, Claude Code, Codex, Gemini, Pi
- Read-only sandboxed agent execution
- Safe outputs applied by separate scoped jobs
- Threat detection and integrity filtering
- Agent workflow firewall and credential isolation
- Staged mode to preview outputs
- Per-run and daily AI credit budget caps
- OpenTelemetry tracing
- Self-hosted runners and ARC support
- Ready-made workflow library

## Integrations
GitHub Actions, GitHub CLI, GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, Antigravity, OpenTelemetry, Jira

## Platforms
WINDOWS, MACOS, LINUX, ANDROID, IOS, WEB, API, CLI

## Pricing
Open Source

## Version
v1.2.2

## Links
- Website: https://gh.io/gh-aw
- Documentation: https://github.github.com/gh-aw/introduction/overview/
- Repository: https://github.com/github/gh-aw
- EveryDev.ai: https://www.everydev.ai/tools/github-agentic-workflows
