What are GitHub Agentic Workflows?

GitHub Agentic Workflows (gh-aw) lets developers define AI-powered repository automation in Markdown with YAML frontmatter and run AI agents through GitHub Actions. The gh-aw CLI compiles the source into a standard GitHub Actions workflow while adding controls for permissions, tools, sandboxing, and writes.

What is an agentic workflow?

Agentic workflows are AI-powered automation 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 AI engines such as GitHub Copilot, Claude Code, OpenAI Codex, Google Gemini, or Pi to:

Understand context: Read your repository, issues, and pull requests to grasp the current situation
Make decisions: Choose appropriate actions based on the context, not just predefined conditions
Adapt behavior: Respond flexibly to different scenarios without requiring explicit programming for each case

Coding agents, running with tools, in GitHub Actions

With AI agents, you describe your automation needs in plain language. GitHub Agentic Workflows makes this possible by running Markdown instructions through an AI engine in GitHub Actions.

Instead of writing intricate scripts to handle issue triage, code reviews, or release management, you describe what you want to happen. The AI agent uses the repository context, tools, and permissions that the workflow allows to interpret the situation and request appropriate actions.

Here’s a simple example:

---
on:                        # Trigger: when to run
  issues:
    types: [opened]

permissions: read-all      # Security: read-only by default

safe-outputs:              # Allowed write operations
  add-comment:
---
# Issue Clarifier

Analyze the current issue and ask for additional details if the issue is unclear.

The YAML section at the top is called frontmatter; it configures when the workflow runs and what it can do. The Markdown body contains natural-language instructions. See Workflow Structure for details.

The gh aw compile command turns this Markdown file into a hardened GitHub Actions workflow .lock.yml file. The lock file embeds the compiled frontmatter configuration and loads the Markdown body at runtime. GitHub Actions then runs the selected AI engine whenever a new issue is opened.

Compilation validates the configuration, applies security hardening, and generates the workflow file that GitHub Actions can execute. Think of it like compiling code: you write human-readable Markdown, and the compiler produces machine-ready YAML.

The AI agent reads your repository context, understands the issue content, and takes appropriate actions - all defined in natural language rather than complex code.

The generated agent job uses read-only permissions by default. The recommended write path is sanitized safe-outputs, which can create issues, comments, and pull requests without granting the AI agent direct write access. Direct write permissions and custom jobs are also configurable and form separate trust boundaries. Review the GitHub Agentic Workflows security architecture for these boundaries and exceptions.

Browse GitHub Agentic Workflows examples by task or explore the larger Agentics collection.