GitHub Agentic Workflows
A gh extension for agentic workflows: describe a task in Markdown and run it with an agent in GitHub Actions
Install
gh extension install github/gh-awRequires GitHub CLI. Then follow the quickstart in the docs.
This is third-party code. Review the repository files before installing.
What it does
gh-aw lets you describe repository automation as a Markdown file: the frontmatter sets triggers, permissions, tools and engine, and the body says in plain words what the agent should do. The gh aw compile command validates the file and generates a standard .lock.yml GitHub Actions workflow. Engines include GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini and Pi. Agent jobs are read-only and sandboxed by default, and GitHub writes go through separate validated safe-outputs jobs.
Who it is for. For GitHub teams that want agents to handle issue triage, reviews and repository reports.
Good fit when
- You need automated issue triage or CI failure investigation
- You want to describe automation in words rather than YAML
- You need to limit the agent's write access to the repository
Not a fit when
- The task is deterministic: builds, tests, deploys
- The repository is not on GitHub
Example request
Create an agentic workflow that triages new issues and labels themLimitations
It needs GitHub CLI and access to the chosen engine via a key or subscription. The authors warn that things can go wrong even with safeguards and human oversight is required. Some versions were retired due to a vulnerability, so keep the extension updated. Engine availability from Russia depends on the provider.
How to disable. Remove the extension with gh extension remove gh-aw and delete the agentic workflow files from .github/workflows.
Security check
- Agents operate on the repository and can make changes via safe-outputs
- Workflows use engine secrets in GitHub Actions
README in short
The README explains how agentic workflows differ from regular CI and gives the install command. It describes the frontmatter plus Markdown file format and the compile step. The security section covers the sandbox, read-only permissions and safe-outputs. For agents there are links to install and workflow creation instructions. MIT licensed.
FAQ
Does it replace regular CI?
No, the authors recommend keeping deterministic tasks in regular Actions and using agents where reasoning is needed.
What does GitHub actually run?
The compiled .lock.yml file that gh aw compile generates from Markdown.
Related
An MCP server built into the Netdata agent: metrics, logs, alerts and live process, service and container data for an AI assistant
GitHub's official MCP server: code, issues, pull requests, Actions and security alerts straight from the agent
A GitHub Action that runs Claude Code in pull requests and issues: answers mentions, reviews and makes changes
An AI assistant for Kubernetes that turns plain-language requests into kubectl operations and doubles as an MCP server