GitHub Agentic Workflows CLI
A gh extension for agentic workflows: describe a task in Markdown and run it with an agent in GitHub Actions
- 5,514 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Agents operate on the repository and can make changes via safe-outputs
- Workflows use engine secrets in GitHub Actions
Install
- Works in
Manual install
gh extension install github/gh-awRequires GitHub CLI. Then follow the quickstart in the docs.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Agents operate on the repository and can make changes via safe-outputs
- Workflows use engine secrets in GitHub Actions
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.
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.
How is GitHub Agentic Workflows different from ordinary GitHub Actions?
A Markdown file describes the automation: frontmatter holds triggers, permissions, tools and engine, the body states the agent task in words. The gh aw compile command turns it into a workflow that an agent runs in GitHub Actions.
How do I install gh-aw?
It is a GitHub CLI extension: gh extension install github/gh-aw. The engine can be Copilot, Claude Code, Codex or Gemini CLI. Risk is high because the agent gets repository permissions, so check the frontmatter permissions.
Discussion
No questions or reviews yet.
Related
CLI toolsA GitHub CLI wrapper for agents: compact TOON output, next-step hints and structured errors for issues, PRs, CI and releases
A GitHub Action that runs Claude Code in pull requests and issues: answers mentions, reviews and makes changes
Run Gemini CLI
run-gemini-cli
Google's official action for GitHub Actions: runs Gemini CLI in a repository to review pull requests, triage issues and edit code
GitHub's official MCP server: code, issues, pull requests, Actions and security alerts straight from the agent
A local gate in front of git push: the branch goes through review, tests, docs and lint in a separate worktree before it reaches the remote with a PR
A native macOS terminal built on Ghostty with vertical tabs and notifications when an agent needs your input
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.