GitHub Agentic Workflows

Agent quick links

Hello fellow agent! Welcome to GitHub Agentic Workflows = Actions + Agent + Safety. Here are some pointers to get you started in using this tool.

• Create a new workflow: https://raw.githubusercontent.com/github/gh-aw/main/create.md
• Install: https://raw.githubusercontent.com/github/gh-aw/main/install.md
• Package a workflow repository: https://raw.githubusercontent.com/github/gh-aw/main/package.md
• Reference: https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/github-agentic-workflows.md

GitHub Agentic Workflows (gh-aw) lets developers define AI-powered repository automation in Markdown with YAML frontmatter and run AI agents securely through GitHub Actions. The gh-aw GitHub CLI extension compiles each agentic workflow into a standard GitHub Actions workflow.

Use conventional GitHub Actions for deterministic builds, tests, linting, deployments, and reproducible scripts. Add an agentic workflow when a task needs reasoning or interpretation, such as issue triage, pull-request review, CI failure investigation, documentation maintenance, dependency analysis, or repository reporting. GitHub Agentic Workflows complements existing CI/CD; it does not replace it.

Built-in AI engines include GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, and Pi. Agent jobs are read-only and sandboxed by default, and configured GitHub writes are normally applied through validated safe-outputs jobs with scoped permissions.

Contents

• Quick Start
• How Agentic Workflows work
• Security and permissions
• Documentation
• Contributing
• Community Contributions
• Related Projects
• Workshop

[!NOTE] A security vulnerability was discovered in versions >= 0.83.3, < 0.85.4 and, as a result, those releases were retired as a pre-emptive measure.

Quick Start

Install the GitHub CLI extension:

gh extension install github/gh-aw

Then follow the GitHub Agentic Workflows quickstart to select an AI engine, add a sample workflow, and run it through GitHub Actions.

How Agentic Workflows work

An agentic workflow has two parts: YAML frontmatter configures triggers, permissions, tools, and the AI engine; the Markdown body tells the AI agent what to accomplish. The gh aw compile command validates this source and generates the .lock.yml workflow that GitHub Actions executes. Learn how GitHub Agentic Workflows works.

Security and permissions

Security, permissions, and controlled writes are core design concerns. The supported agent-job path defaults to read-only GitHub access and sandboxed execution. Safe outputs buffer configured writes, validate them, and apply them in separate jobs with scoped permissions. These controls are configurable, so workflow authors must review permissions, tools, network access, and generated files before deployment. Learn how GitHub Agentic Workflows handles security and permissions.