GitHub Agentic Workflows

Loading slides...

GitHub Agentic Workflows (gh-aw) lets you write repository automation in plain Markdown and run AI coding agents — GitHub Copilot, Claude Code, OpenAI Codex, or Google Gemini — inside GitHub Actions, with sandboxed execution, read-only defaults, and safe outputs for writes.

Wake up to ready-to-review repository improvements — automated triage, CI insights, docs updates, and test enhancements from simple markdown workflows.

GitHub Agentic Workflows deliver this: repository automation, running the coding agents you know and love, in GitHub Actions, with strong guardrails and security-first design principles.

Use GitHub Copilot, Claude by Anthropic, Gemini from Google or OpenAI Codex for event-triggered and scheduled jobs to improve your repository. GitHub Agentic Workflows augment your existing, deterministic CI/CD with Continuous AI capabilities.

Developed by GitHub and Microsoft, workflows run with added guardrails, using safe outputs and sandboxed execution to help keep your repository safe.

Key Features

AI-Powered Decision Making

Workflows that understand context and adapt to situations

Multiple AI Engines

Support for Copilot, Claude, Codex, and custom AI processors

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

Zero-Secret Agents

Sensitive credentials never shared with agent sandbox

Safe Outputs

All outputs are validated before applied

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 uses layered controls to keep each run contained: sandboxing limits where code can execute, scoped permissions limit what it can request, and gated outputs ensure only approved actions reach GitHub.

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

Sandbox + network firewall

The agent runs in a container behind the Agent Workflow Firewall and can only reach allowed destinations.

Threat detection

A dedicated threat detection job scans proposed outputs and blocks suspicious changes.

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 cli hardens this to a traditional GitHub Actions Workflow (.lock.yml) that runs an AI coding agent (Copilot CLI, Claude Code, Codex, …) in a containerized environment on a schedule or manually. The AI coding agent reads your repository context, analyzes issues, generates visualizations, and creates reports. All defined in natural language rather than complex code.

Gallery

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

gh-aw supports built-in AI engines. Switch between them by changing one line of frontmatter.

GitHub Copilot

Default engine. Works with your existing Copilot subscription — no extra account.

Claude Code

Anthropic’s Claude. Set engine: claude and add ANTHROPIC_API_KEY.

OpenAI Codex

OpenAI Codex. Set engine: codex and add OPENAI_API_KEY.

Google Gemini

Google Gemini CLI. Set engine: gemini and add GEMINI_API_KEY.

Other Engines

gh-aw’s open engine model lets you plug in any coding agent CLI by importing a Markdown engine definition file. The following agents are available as sample integrations — import the definition maintained by the agent’s publisher to use them in your workflows.

Pi

Experimental multi-provider agent. Set engine: pi and add COPILOT_GITHUB_TOKEN.

Copilot SDK

Run Copilot in SDK mode for advanced multi-provider routing. 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

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.