GitHub Agentic Workflows

File Format

Agentic workflows are markdown files with YAML frontmatter.

---
emoji: 🧠
name: My Workflow
description: Short description
on:
  issues:
    types: [opened]
permissions:
  contents: read
  actions: read
strict: true
network:
  allowed: [defaults, github]
tools:
  github:
    mode: gh-proxy
    toolsets: [default]
safe-outputs:
  add-comment:
---

# Workflow Title

Natural language instructions for the AI agent.

Recompilation Rule

• Edit the frontmatter → run gh aw compile <workflow-id>.
• Edit the markdown body only → no recompilation required.

See also: workflow-editing.md

Core Rules

• Keep the main agent job read-only.
• Use safe-outputs: for GitHub writes.
• Prefer tools.github.mode: gh-proxy and use gh for GitHub reads.
• For non-GitHub MCP servers, prefer tools.cli-proxy: true and use mounted mcp-clis commands.
• Use ${{ steps.sanitized.outputs.text }} for untrusted user content.
• Set strict: true for production workflows.
• Limit network and bash access to what the workflow actually needs.

See also: workflow-constraints.md

Reference Files

Topic	File
Editing and recompilation rules	workflow-editing.md
Architectural and security constraints	workflow-constraints.md
Common design patterns	workflow-patterns.md
Frontmatter schema index	syntax.md
Safe outputs index	safe-outputs.md
Trigger patterns	triggers.md
Context expressions and {{#if}} templates	context.md
CLI commands and MCP equivalents	cli-commands.md
Network configuration	network.md
Memory and persistence	memory.md
Imports and shared components	reuse.md
Sub-agents	subagents.md
Skills	skills.md
Token cost optimization	token-optimization.md
GitHub MCP server configuration	github-mcp-server.md
Campaign and KPI patterns	campaign.md
Experiments and A/B testing	experiments.md
Charts and Python data visualization	charts.md
LLM API endpoint discovery	llms.md

Compile Commands

gh aw compile
gh aw compile <workflow-id>
gh aw compile --purge
gh aw compile --strict