GitHub Agentic Workflows
The Complete Guide to AI-Powered Repository Automation
Describe your automation goals in plain Markdown. Compile to a hardened GitHub Actions workflow. Let coding agents — Copilot, Claude, or Codex — handle triage, documentation, testing, and reporting while humans stay in the loop. Welcome to Continuous AI.
What is GitHub Agentic Workflows?
GitHub Agentic Workflows (gh-aw) are AI-powered automations that can understand context, make decisions, and take meaningful actions — all from natural language instructions written in Markdown.
Unlike traditional automation with fixed if-then rules, agentic workflows use coding agents to interpret your instructions and carry out tasks that normally require human judgment — triaging issues, investigating CI failures, updating documentation, and improving tests.
Created by Don Syme and Peli de Halleux at GitHub Next, the project is fully open source under the MIT license, with 313+ releases and a vibrant community.
”A useful mental model: if repetitive work in a repository can be described in words, it might be a good fit for an agentic workflow.”
— GitHub BlogHow It Works
Write
Describe automation intent in Markdown with YAML frontmatter
Compile
Transform to a hardened Actions workflow via gh aw compile
Push
Commit both .md source and .lock.yml to your repo
Run
Triggers automatically via GitHub Actions on events or schedules
Review
Agent produces issues, PRs, and comments for human review
Why Agentic DevOps?
GitHub Agentic Workflows isn’t just a tool — it’s the first production implementation of Continuous AI, a new branch of DevOps where autonomous loops monitor, reason, and act on your repository at machine speed. Built on a kernel-level sandbox (Layer 0) that makes governance structural, not aspirational.
The Loop Collapsed
What took months became days, then minutes. The DevOps feedback loop compressed into a tight agentic core.
Layer 0 — The Sandbox
Kernel-level isolation makes governance structural. Agents can’t escape constraints — they’re walled, not warned.
Continuous AI
Two coupled loops — one autonomous, one agentic — running continuously to monitor, reason, and ship.
Project at a Glance
An actively developed open source project from GitHub Next, with rapid iteration and a growing community.
Dive Deeper
This guide covers everything from foundational concepts to advanced security, ecosystem integrations, and real-world use cases. Pick a topic to get started.
Your First Agentic Workflow
A complete workflow in plain Markdown — a daily repository status report that runs every morning and files an issue with insights.
--- name: Daily Repo Status Report description: Creates a daily summary of repository activity on: schedule: - cron: "0 9 * * 1-5" # Weekdays at 9am UTC workflow_dispatch: tools: github: # Access to repo data safe-outputs: create-issue: title-prefix: "[daily] " labels: [daily-report, automated] max: 1 --- # Daily Repository Status Report Analyze this repository and create a concise daily status report covering: - **New Issues**: Summarize issues opened in the last 24 hours with priority assessment - **PR Activity**: List merged, opened, and stalled pull requests - **CI Health**: Report on recent workflow runs, flag any failures or flaky tests - **Key Metrics**: Lines changed, active contributors, review turnaround time Format the report as a well-structured GitHub issue with clear sections and actionable items. Keep it concise — highlight what matters.
What's happening here
This single Markdown file becomes a fully automated workflow. The YAML frontmatter configures when it runs, what tools it can access, and what actions it can take. The body is the natural language instruction the AI agent follows.
- Schedule trigger — runs every weekday at 9 AM UTC
- GitHub tools — gives the agent read access to issues, PRs, commits, and CI data
- Safe outputs — can only create one issue with a title prefix and specific labels; no other write access
- Natural language body — the agent interprets these instructions with contextual reasoning
- Read-only by default — writes only happen through the declared safe outputs
- Human review — the created issue is visible for the team to inspect and act on
Run gh aw compile daily-status-report.md
to generate the hardened .lock.yml file, then push both to your repo.