GitHub Agentic Workflows: AI-Powered Repo Automation

What are GitHub Agentic Workflows?

GitHub Agentic Workflows is GitHub's own CLI extension for defining AI-powered automation as Markdown files with YAML frontmatter, compiled by `gh aw compile` into a standard `.lock.yml` GitHub Actions workflow. Frontmatter fields configure the trigger, the required permissions, the available tools, and which AI engine runs the job; everything below that frontmatter, in plain Markdown, is the task description the agent actually carries out. Built-in engines: GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, and Pi.

The Need for AI in Repository Automation

Conventional GitHub Actions are deterministic: a YAML step either runs a command or it doesn't, which is exactly right for builds, tests, and deploys but breaks down for jobs that need judgment — deciding whether a CI failure is a flaky test or a real regression, or whether an issue report has enough detail to triage. GitHub Agentic Workflows targets that specific gap: issue triage, pull-request review, CI failure investigation, documentation maintenance, dependency analysis, and repository reporting, per its own README. It's explicit that this complements existing CI/CD rather than replacing it — deterministic steps stay in plain Actions, and reasoning-heavy steps move into an agentic workflow compiled the same way.

Core Features

• ✓Workflows are Markdown files with YAML frontmatter; `gh aw compile` validates them and generates a `.lock.yml` file that GitHub Actions actually executes — so the compiled workflow is inspectable like any other Actions file.
• ✓Five built-in AI engines to pick from: GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, and Pi, selected with `gh aw init --engine <engine>`.
• ✓Agent jobs run read-only and sandboxed by default; any GitHub write the agent wants to make goes through a separate 'safe-outputs' job with its own scoped permissions instead of running inline with agent-controlled write access.
• ✓`gh aw add --engine <engine> --create-pull-request` scaffolds a sample workflow — the README's example is a daily job that summarizes open issues, recent PRs, and CI health and opens the result as a PR.
• ✓Per-engine auth is explicit rather than assumed: Claude needs `ANTHROPIC_API_KEY` or Anthropic WIF (according to the README, `CLAUDE_CODE_OAUTH_TOKEN` generated by `claude login` is unsupported), Codex needs `CODEX_API_KEY` or `OPENAI_API_KEY`, Gemini needs `GEMINI_API_KEY` or Google WIF, Copilot needs `copilot-requests: write` granted, and Pi needs provider auth plus configured proxies.
• ✓Documentation ships as an llms.txt index, a full llms-full.txt prompt corpus, and an ai/summary.json file specifically for AI agents and retrieval tools to consume.

Practical Use Cases

• •Adding a scheduled repo-status workflow that reports open issues, recent PR activity, and CI health without writing that reporting logic by hand — the README's own quick-start example.
• •Triaging incoming issues or reviewing pull requests with an AI engine instead of a human doing the first pass, per the categories of tasks the README lists as good fits.
• •Investigating why a CI run failed when the failure needs interpretation rather than just re-running a deterministic step.
• •Keeping documentation current or running dependency analysis as a recurring agentic job rather than a manual chore.

Quick Start: Installation and Setup

Install the extension with `gh extension install github/gh-aw`, or with the standalone script: `curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash`, which the README notes needs no GitHub token. Next, run `gh aw init --engine <engine>` — swapping in `copilot`, `claude`, `codex`, `gemini`, or `pi` — to configure the repository for that engine. From there, `gh aw add --engine <engine> --create-pull-request` scaffolds the sample daily-status workflow as a pull request you review before merging. Engine authentication is separate per engine (API keys or workload identity federation) and isn't detailed further in these steps — the README defers the full walkthrough to its published quickstart guide.

Comparing with Other Automation Approaches

Common Questions

How to use

Day-to-day, a workflow is a Markdown file with YAML frontmatter: the frontmatter declares triggers, permissions, tools, and the AI engine, and the Markdown body is the plain-language task description the agent acts on. Run `gh aw compile` to validate that source and generate the `.lock.yml` file GitHub Actions actually runs — so you're reviewing a real Actions workflow, not trusting the agent's frontmatter blindly. Because agent jobs default to read-only and sandboxed execution, any GitHub write (commenting, opening a PR, labeling) goes through a separate safe-outputs job with permissions scoped to just that action, and the README still asks you to review permissions, tools, network access, and generated files before you deploy a workflow.

Who should try it — and who should skip

Try GitHub Agentic Workflows if your repo already runs GitHub Actions and you want recurring reasoning-heavy chores — issue triage, PR review, CI failure investigation — compiled into workflows you can read in version control rather than run through an opaque bot. Skip it if you're not ready to review generated permissions and safe-outputs configuration line by line, or if the `pi` engine's proxy setup and the other engines' per-engine auth requirements are more configuration than you want to take on right now.

Related repositories