How GitHub Agentic Workflows Work
GitHub Agentic Workflows (gh-aw) compiles Markdown workflow files into GitHub Actions workflows that run AI agents for complex, multi-step repository tasks. GitHub Actions supplies the triggers, runners, logs, and job orchestration; gh-aw adds the AI engine, natural-language instructions, and security controls for agent execution.
Workflow Structure
Section titled “Workflow Structure”Each workflow contains frontmatter (the YAML configuration section between --- markers) and markdown instructions. The frontmatter defines triggers (when the workflow runs), permissions (what it can access), and tools (what capabilities the AI has), while the markdown contains natural language task descriptions. This declarative structure enables reliable, secure agentic programming by sandboxing AI capabilities and triggering at the right moments.
---on: ...permissions: ...tools: ...---# Natural Language InstructionsAnalyze this issue and provide helpful triage comments...AI Engines
Section titled “AI Engines”Built-in engines are GitHub Copilot (default), Claude Code, OpenAI Codex, Google Gemini, and Pi. Each AI engine runs the selected model and interprets the natural-language instructions using the configured tools and permissions.
Each engine authenticates with its own secret or permission:
| Engine | Frontmatter engine: | Secret or permission required |
|---|---|---|
| GitHub Copilot (default) | copilot | copilot-requests: write permission or COPILOT_GITHUB_TOKEN |
| Claude Code | claude | ANTHROPIC_API_KEY or Anthropic WIF |
| OpenAI Codex | codex | CODEX_API_KEY or OPENAI_API_KEY |
| Google Gemini | gemini | GEMINI_API_KEY or Google WIF |
| Pi | pi | Copilot, Anthropic, or OpenAI/Codex authentication, depending on model: |
See Authentication for the full setup instructions for each engine.
Tools and Model Context Protocol (MCP)
Section titled “Tools and Model Context Protocol (MCP)”Workflows expose only configured tools to the AI agent. Some integrations use the Model Context Protocol (MCP), a standardized protocol for connecting AI agents to external tools and services; other tools are provided by the selected AI engine or built-in gh-aw adapters.
GitHub Agentic Workflows and standard GitHub Actions
Section titled “GitHub Agentic Workflows and standard GitHub Actions”Standard GitHub Actions workflows are ideal for deterministic operations such as builds, tests, linting, deployments, and reproducible scripts. Keep these operations deterministic when identical inputs should produce predictable steps and outputs.
Agentic workflows add AI reasoning for tasks such as investigation, triage, review, research, and content or code generation. They run on GitHub Actions and can include deterministic steps, so GitHub Agentic Workflows complements existing CI/CD instead of replacing it.
Security Design
Section titled “Security Design”GitHub Agentic Workflows uses a defense-in-depth security architecture to reduce risk from prompt injection, rogue MCP servers, and compromised agents. The supported agent-job path defaults to compilation-time validation, runtime isolation, permission separation, network controls, and output sanitization. Some controls can be changed or disabled and must be evaluated during workflow review.
flowchart LR
INPUT[" Input"] --> COMPILE[" Compile"]
COMPILE --> RUNTIME[" Runtime"]
RUNTIME --> ISOLATION[" Isolation"]
ISOLATION --> OUTPUT[" Output"]
OUTPUT --> ACTIONS["✓ Actions"]
Supported agent jobs run with minimal permissions and no write access by default. Configured safe outputs are processed in separate jobs before changes are applied, and critical actions can require human approval. Custom jobs and explicitly relaxed controls form separate trust boundaries. For details and exceptions, see the GitHub Agentic Workflows security architecture.
MCP Scripts and Safe Outputs
Section titled “MCP Scripts and Safe Outputs”- MCP Scripts (custom inline tools) - Custom MCP tools defined inline in workflow frontmatter
- Safe outputs (validated GitHub operations) - Pre-approved actions the AI can request without write permissions
Regenerating the Lock File
Section titled “Regenerating the Lock File”Use gh aw compile to generate .lock.yml files from the frontmatter of the workflow .md files. The .md file is the editable source of truth, while .lock.yml is the compiled GitHub Actions workflow with security hardening. Commit both files.
Continuous AI Patterns
Section titled “Continuous AI Patterns”Enable Continuous AI patterns like keeping documentation current, improving code quality incrementally, intelligently triaging issues and PRs, and automating code review.
Best Practices
Section titled “Best Practices”Start simple and iterate with clear, specific instructions. Test workflows using gh aw compile --watch and gh aw run, monitor costs with gh aw logs, and review AI-generated content before merging. Use safe outputs (pre-approved GitHub operations) for controlled creation of issues, comments, and PRs.
Workshop
Section titled “Workshop”Next steps
Section titled “Next steps”- Follow the GitHub Agentic Workflows quickstart.
- Learn how to create an agentic workflow.
- Compare supported AI engines and authentication.
- Browse GitHub Agentic Workflows examples by task.
- Read the security architecture and FAQ.