Text of github.github.com › gh-aw › introduction › how-they-work as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout.

Open the live page

How Agentic Workflows Work | GitHub Agentic Workflows

Skip to main content 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 Instructions Analyze 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, selected by the provider prefix in model: (see Quick Start ) 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 .