GitHub Agentic Workflows

Loading slides...

Wake up to ready-to-review repository improvements — automated triage, CI insights, docs updates, and test enhancements. Use event-triggered and scheduled jobs to augment your existing, deterministic CI/CD with AI-powered intelligence.

GitHub Agentic Workflows deliver repository automation: simple markdown workflows running the coding agents you know and love, in GitHub Actions, with strong guardrails and security-first design principles. Supported AI engines include GitHub Copilot, Claude Code, Google Gemini and OpenAI Codex.

Developed by GitHub, GitHub Agentic Workflows run with strong guardrails, using safe outputs and sandboxed execution to help keep your repository safe.

Core capabilities

AI-Powered Decision Making

Workflows that understand context and adapt to situations

Coding Agents You Trust

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

Cost Controls

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

Guardrails Built-In

Sandboxing, scoped permissions, and safe outputs reduce risk of compromise

GitHub Integration

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

Use at Scale in Organizations

Use at scale in you organization or enterprise across multiple repositories

Guardrails Built-In

AI agents can be manipulated by prompt injection or malicious content. GitHub Agentic Workflows uses layered controls: sandboxing, scoped permissions, gated outputs and threat detection. See the Security Architecture for a full breakdown of the layered defense-in-depth model.

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

Compile-time validation

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

Credential Isolation

The API proxy isolates the agent from credentials

Sandbox & Firewall

The agent runs in a container with firewall; explicit opt-outs broaden its access.

Integrity Filtering

Reduce prompt-injection risk by filtering untrusted GitHub content

Safe Outputs

Configured write requests are validated before separate jobs apply them

Threat detection

A dedicated job scans proposed outputs, blocking suspicious changes.

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.

Gallery

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

Issue Triage

Automatically classify new issues, identify duplicates, apply bounded labels, and ask for missing information.

Pull Request Review

Automatically inspect diffs for concrete defects and post review feedback through controlled safe outputs.

Documentation Maintenance

Automatically detect drift between code and documentation and propose reviewable updates.

CI Failure Investigation

Automatically analyze failed GitHub Actions runs, correlate logs, and open diagnostic issues with likely causes.

Code Improvement

Automatically find unnecessary complexity or duplicated logic and propose focused changes for human review.

Dependency Analysis

Automatically research dependency usage and upstream changes before creating prioritized follow-up work.

Metrics and Analytics

Automatically collect workflow activity and store structured snapshots for health and performance analysis.

Repository Reporting

Automatically summarize repository or release activity on an event or schedule.

Repository Maintenance

Automatically review a backlog, perform bounded maintenance tasks, and propose controlled changes on a schedule.

Security Review

Automatically combine repository evidence with AI interpretation to report suspicious changes through code scanning.

Triage from Side Repo

Automatically triage a main repository from an isolated side repository through a slash-command bridge.

Code Quality Monitoring

Automatically analyze code quality across repositories and create focused, actionable issues.

Feature Synchronization

Automatically synchronize code and configuration across repositories through reviewable pull requests.

Cross-Repository Issue Tracking

Automatically aggregate and synchronize issue status in a central repository.

Dependabot Rollout

Automatically roll out tailored Dependabot configuration across multiple repositories.

AI Engines

GitHub Agentic Workflows provides five stable built-in AI engines. 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 organization billing or a personal access token.

Claude Code

Claude by Anthropic, automated with strong guardrails on GitHub Actions.

OpenAI Codex

Codex CLI by OpenAI, automated with strong guardrails on GitHub Actions.

Google Gemini

Google Gemini CLI, automated with strong guardrails on GitHub Actions.

Pi

Multi-provider engine, automated with strong guardrails on GitHub Actions, using provider-scoped models and endpoints.

Custom

Import a third-party agent definition or define your own engine in the repository.

Custom engines

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 custom AI engine and the Engines reference for how to import and pin an engine definition.

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.