How Agentic Workflows Work
GitHub Agentic Workflows 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 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 |
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.
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.
Learn More
Section titled “Learn More”- Follow the GitHub Agentic Workflows quickstart.
- Learn how to create an agentic workflow.
- Compare supported AI engines and authentication.
- Browse the GitHub Agentic Workflows gallery.
- Read the security architecture and FAQ.
- Practice with the gh-aw workshop.