GitHub Agentic Workflows

Loading slides...

With GitHub Agentic Workflows (gh-aw), developers define AI-powered repository automation in Markdown with YAML frontmatter and run AI agents through GitHub Actions. The gh-aw GitHub CLI extension compiles each source file into the .lock.yml workflow that GitHub Actions executes.

Use standard GitHub Actions for deterministic builds, tests, linting, deployments, and reproducible scripts. Add an agentic workflow for work that benefits from reasoning or interpretation, such as issue triage, CI investigation, documentation updates, code review, and repository reporting. The two approaches complement each other.

Supported built-in AI engines include GitHub Copilot, Claude Code, OpenAI Codex, and Google Gemini, plus Pi. Choose the engine and authentication method that fit the workflow, then keep the same Markdown-and-frontmatter authoring model.

By default, supported agent jobs use read-only GitHub access and sandboxed execution. Configured writes can be routed through validated safe outputs that run separately with scoped permissions. These controls remain configurable and require careful review.

Core capabilities

AI-Powered Decision Making

Workflows that understand context and adapt to situations

Multiple AI Engines

Built-in support for Copilot, Claude Code, Codex, Gemini, and Pi

Self-Hosted & ARC Runners

Deploy on Linux self-hosted runners, including ARC with Docker-in-Docker

MicroVM Isolation

Run agents in KVM-isolated Docker sbx microVMs on compatible runners

Engine Credential Isolation

The API proxy isolates supported AI engine credentials from the agent sandbox

Safe Outputs

Configured write requests are validated before separate jobs apply them

Integrity Filtering

Reduce prompt-injection risk by filtering untrusted GitHub content

GitHub Integration

Deep integration with Actions, Issues, PRs, Discussions, and repository management

Cost Controls

Per-run AI credit budgets, spend visibility, and OpenTelemetry cost analysis

Guardrails Built-In

AI agents can be manipulated by prompt injection, malicious repository content, or compromised tools. GitHub Agentic Workflows defaults to layered controls for the supported agent-job path: sandboxing limits where code can execute, scoped permissions limit what it can request, and gated outputs constrain configured writes to GitHub. Workflow authors can change some controls and must evaluate the resulting risk.

flowchart LR
    INPUT["Repository + Prompt Input"] --> TOKENS["Read-only Token"]
    TOKENS --> SECRETS["No Secrets in Agent"]
    SECRETS --> SANDBOX["Sandbox + Network Controls"]
    SANDBOX --> SAFE["Safe Outputs Gate"]
    SAFE --> DETECT["Threat Detection Scan (when enabled)"]
    DETECT --> APPLY["Scoped Write Job"]

Sandbox + network firewall

By default, the agent runs in a container behind the Agent Workflow Firewall; explicit opt-outs broaden its access.

Threat detection

When enabled, a dedicated job scans proposed outputs and blocks suspicious changes before configured writes.

Compile-time validation

Schema validation, expression allowlisting, action pinning, and security scanners reject misconfigurations before deployment.

See the Security Architecture for a full breakdown of the layered defense-in-depth model.

Manage Cost and Capacity

Cost control starts with visibility. Use gh aw logs and gh aw audit to find runs consuming the most time, tokens, and AI Credits (AIC), then tighten prompts, triggers, and model choices before spend drifts upward.

max-ai-credits gives each run a hard budget, while OpenTelemetry exports traces and token data to OTLP backends for dashboards, alerting, and cost analysis. For optimization over time, compare cost with outcomes so lower spend still produces useful accepted results.

Cost Management

Track Actions minutes, inference spend, and the heaviest runs before deciding what to optimize

OpenTelemetry

Export workflow traces to OTLP backends for dashboards, alerts, and spend analysis

AI Credits Budgets

Cap runaway runs with max-ai-credits and optimize around AI Credits usage

Example: Daily Issues Report

Here’s a simple workflow that runs daily to create an upbeat status report:

---
on:
  schedule: daily

permissions:
  contents: read
  issues: read
  pull-requests: read

safe-outputs:
  create-issue:
    title-prefix: "[team-status] "
    labels: [report, daily-status]
    close-older-issues: true
---

## Daily Issues Report

Create an upbeat daily status report for the team as a GitHub issue.

## What to include

- Recent repository activity (issues, PRs, discussions, releases, code changes)
- Progress tracking, goal reminders and highlights
- Project status and recommendations
- Actionable next steps for maintainers

The gh aw compile command turns this source into a hardened .lock.yml GitHub Actions workflow. GitHub Actions then runs the selected AI engine in the configured agent environment on the declared trigger. The AI agent reads allowed repository context and requests only the tools and outputs configured in frontmatter.

GitHub Agentic Workflows examples

Browse examples by repository task to find a starting point and learn when to use each workflow.

Repository Maintenance

Use Repo Assist to triage backlogs and make focused project improvements

Continuous Documentation

Continuous documentation maintenance and consistency

Continuous Improvement

Daily code simplification, refactoring, and style improvements

Metrics & Analytics

Daily reports, trend analysis, and workflow health monitoring

Quality & Testing

CI failure diagnosis, test improvements, and quality checks

Multi-Repository

Feature sync and cross-repo tracking workflows

AI Engines

GitHub Agentic Workflows (gh-aw) provides five stable built-in AI engines, including Pi. Engine changes may also require a different authentication method or tool configuration; use the linked guide for each engine.

GitHub Copilot

Default engine. Authenticate with the copilot-requests permission or a fine-grained personal access token.

Claude Code

Anthropic’s Claude Code. Select claude and use ANTHROPIC_API_KEY or Anthropic WIF.

OpenAI Codex

OpenAI Codex. Select codex and use CODEX_API_KEY or OPENAI_API_KEY.

Google Gemini

Google Gemini CLI. Select gemini and use GEMINI_API_KEY or Google WIF.

Pi

Multi-provider engine. Set engine: pi and configure its required proxies and provider authentication.

Imported engine samples

The engine import model can integrate other coding-agent CLIs through Markdown definitions. The following in-repository definitions are unsupported samples, not built-in or officially supported gh-aw engines.

Copilot SDK

A mode of the Copilot engine rather than a separate AI engine. Enable with copilot-sdk: true.

OpenCode

Provider-agnostic BYOK agent supporting 75+ models from Anthropic, OpenAI, Google, and more.

Cursor

Cursor’s AI coding agent, importable as a shared engine definition.

Kiro

Amazon’s Kiro agentic IDE, importable as a shared engine definition.

Aider

Open-source pair programming agent. Import the publisher-maintained definition.

Crush

Charmbracelet’s terminal-first coding agent, importable as a shared engine definition.

See Configuring a third-party agent and the Engines reference for how to import and pin an engine definition.

Common Use Cases

The task-oriented examples catalog also covers CI failure investigation, dependency analysis, scheduled maintenance, code improvement, and security review.

AI Issue Triage

Label, deduplicate, and ask clarifying questions when new issues arrive

Automated PR Review

Review diffs and post feedback comments when pull requests are opened

AI Release Notes

Generate release summaries and changelog drafts automatically

Docs Automation

Keep documentation in sync with code changes via automated PRs

Getting Started

Install the extension, add a sample workflow, and trigger your first run - all from the command line in minutes.

Creating Workflows

Create custom agentic workflows directly from the GitHub web interface using natural language.

Workshop

Interactive workshop

New

Choose a terminal, browser, or Copilot path and work through the workshop directly in the docs with saved progress.