This is the full developer documentation for GitHub Agentic Workflows # GitHub Agentic Workflows > Repository automation, running the coding agents you know and love, with strong guardrails in GitHub Actions. Imagine a world where improvements to your repositories are automatically delivered each morning, ready for you to review. Issues are automatically triaged, CI failures analyzed, documentation maintained and tests improved. All defined via simple markdown files. GitHub Agentic Workflows deliver this: repository automation, running the coding agents you know and love, in GitHub Actions, with strong guardrails and security-first design principles. Use GitHub Copilot, Claude by Anthropic, Gemini from Google or OpenAI Codex for event-triggered and scheduled jobs to improve your repository. GitHub Agentic Workflows [augment](https://github.github.com/gh-aw/reference/faq/#determinism) your existing, deterministic CI/CD with [Continuous AI](https://githubnext.com/projects/continuous-ai) capabilities. Developed by GitHub and Microsoft, workflows run with added guardrails, using safe outputs and sandboxed execution to help keep your repository safe. > ⓘ Note: GitHub Agentic Workflows is in early development and may change significantly. Using agentic workflows requires careful attention to security considerations and careful human supervision, and even then things can still go wrong. Use it with caution, and at your own risk. ## Key Features [Section titled “Key Features”](#key-features) ### [Automated Markdown Workflows](/gh-aw/introduction/overview/#natural-language-to-github-actions) [Write automation in markdown instead of complex YAML](/gh-aw/introduction/overview/#natural-language-to-github-actions) ### [AI-Powered Decision Making](/gh-aw/introduction/how-they-work/) [Workflows that understand context and adapt to situations](/gh-aw/introduction/how-they-work/) ### [GitHub Integration](/gh-aw/reference/github-tools/) [Deep integration with Actions, Issues, PRs, Discussions, and repository management](/gh-aw/reference/github-tools/) ### [Safety First](/gh-aw/introduction/architecture/) [Sandboxed execution with minimal permissions and safe output processing](/gh-aw/introduction/architecture/) ### [Multiple AI Engines](/gh-aw/reference/engines/) [Support for Copilot, Claude, Codex, and custom AI processors](/gh-aw/reference/engines/) ### [Continuous AI](/gh-aw/introduction/how-they-work/) [Systematic, automated application of AI to software collaboration](/gh-aw/introduction/how-they-work/) ## Guardrails Built-In [Section titled “Guardrails Built-In”](#guardrails-built-in) AI agents can be manipulated into taking unintended actions—through malicious repository content, compromised tools, or prompt injection. GitHub Agentic Workflows addresses this with five security layers that work together to contain the impact of a confused or compromised agent. ### Read-only tokens [Section titled “Read-only tokens”](#read-only-tokens) The AI agent receives a GitHub token scoped to read-only permissions. Even if the agent attempts to create a pull request, push code, or delete a file, the underlying token simply doesn’t allow it. The agent can observe your repository; it cannot change it. ### Zero secrets in the agent [Section titled “Zero secrets in the agent”](#zero-secrets-in-the-agent) The agent process never receives write tokens, API keys, or other sensitive credentials. Those secrets exist only in separate, isolated jobs that run *after* the agent has finished and its output has passed review. A compromised agent has nothing to steal and no credentials to misuse. ### Containerized with a network firewall [Section titled “Containerized with a network firewall”](#containerized-with-a-network-firewall) The agent runs inside an isolated container. A built-in network firewall—the [Agent Workflow Firewall](/gh-aw/introduction/architecture/#agent-workflow-firewall-awf)—routes all outbound traffic through a Squid proxy enforcing an explicit domain allowlist. Traffic to any other destination is dropped at the kernel level, so a compromised agent cannot exfiltrate data or call out to unexpected servers. ### Safe outputs with strong guardrails [Section titled “Safe outputs with strong guardrails”](#safe-outputs-with-strong-guardrails) The agent cannot write to GitHub directly. Instead, it produces a structured artifact describing its intended actions—for example, “create an issue with this title and body.” A separate job with [scoped write permissions](/gh-aw/reference/safe-outputs/) reads that artifact and applies only what your workflow explicitly permits: hard limits per operation (such as a maximum of one issue per run), required title prefixes, and label constraints. The agent requests; a gated job decides. ### Agentic threat detection [Section titled “Agentic threat detection”](#agentic-threat-detection) Before any output is applied, a dedicated [threat detection job](/gh-aw/reference/threat-detection/) runs an AI-powered scan of the agent’s proposed changes. It checks for prompt injection attacks, leaked credentials, and malicious code patterns. If anything looks suspicious, the workflow fails immediately and nothing is written to your repository. See the [Security Architecture](/gh-aw/introduction/architecture/) for a full breakdown of the layered defense-in-depth model. ## Example: Daily Issues Report [Section titled “Example: Daily Issues Report”](#example-daily-issues-report) Here’s a simple workflow that runs daily to create an upbeat status report: ```markdown --- on: schedule: daily permissions: contents: read issues: read pull-requests: read safe-outputs: create-issue: title-prefix: "[team-status] " labels: [report, daily-status] close-older-issues: true --- ## Daily Issues Report Create an upbeat daily status report for the team as a GitHub issue. ## What to include - Recent repository activity (issues, PRs, discussions, releases, code changes) - Progress tracking, goal reminders and highlights - Project status and recommendations - Actionable next steps for maintainers ``` The `gh aw` cli hardens this to a traditional GitHub Actions Workflow (.lock.yml) that runs an AI coding agent (Copilot CLI, Claude Code, Codex, …) in a containerized environment on a schedule or manually. The AI coding agent reads your repository context, analyzes issues, generates visualizations, and creates reports. All defined in natural language rather than complex code. ## Gallery [Section titled “Gallery”](#gallery) ### [Issue & PR Management](/gh-aw/blog/2026-01-13-meet-the-workflows-issue-management/) [Automated triage, labeling, and project coordination](/gh-aw/blog/2026-01-13-meet-the-workflows-issue-management/) ### [Continuous Documentation](/gh-aw/blog/2026-01-13-meet-the-workflows-documentation/) [Continuous documentation maintenance and consistency](/gh-aw/blog/2026-01-13-meet-the-workflows-documentation/) ### [Continuous Improvement](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-simplicity/) [Daily code simplification, refactoring, and style improvements](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-simplicity/) ### [Metrics & Analytics](/gh-aw/blog/2026-01-13-meet-the-workflows-metrics-analytics/) [Daily reports, trend analysis, and workflow health monitoring](/gh-aw/blog/2026-01-13-meet-the-workflows-metrics-analytics/) ### [Quality & Testing](/gh-aw/blog/2026-01-13-meet-the-workflows-quality-hygiene/) [CI failure diagnosis, test improvements, and quality checks](/gh-aw/blog/2026-01-13-meet-the-workflows-quality-hygiene/) ### [Multi-Repository](/gh-aw/examples/multi-repo/) [Feature sync and cross-repo tracking workflows](/gh-aw/examples/multi-repo/) ## Getting Started [Section titled “Getting Started”](#getting-started) Install the extension, add a sample workflow, and trigger your first run - all from the command line in minutes. Your browser doesn't support HTML5 video. [Download Install and add workflow in CLI demo video](/gh-aw/videos/install-and-add-workflow-in-cli.mp4). ## Creating Workflows [Section titled “Creating Workflows”](#creating-workflows) Create custom agentic workflows directly from the GitHub web interface using natural language. Your browser doesn't support HTML5 video. [Download Create workflow on GitHub demo video](/gh-aw/videos/create-workflow-on-github.mp4). # Agent Factory > Experimental agentic workflows used by the team to learn and build. These are experimental agentic workflows used by the GitHub Next team to learn, build, and use agentic workflows. [Browse source files](https://github.com/github/gh-aw/tree/main/.github/workflows). | Workflow | Agent | Status | Schedule | Command | | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------: | :-------: | | [\[aw\] Failure Investigator (6h)](https://github.com/github/gh-aw/blob/main/.github/workflows/aw-failure-investigator.md) | claude | [![\[aw\] Failure Investigator (6h)](https://github.com/github/gh-aw/actions/workflows/aw-failure-investigator.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/aw-failure-investigator.lock.yml) | `every 6h` | - | | [/cloclo](https://github.com/github/gh-aw/blob/main/.github/workflows/cloclo.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/cloclo.lock.yml) | - | `/cloclo` | | [ACE Editor Session](https://github.com/github/gh-aw/blob/main/.github/workflows/ace-editor.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/ace-editor.lock.yml) | - | - | | [Agent Container Smoke Test](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-test-tools.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-test-tools.lock.yml) | - | - | | [Agent Performance Analyzer - Meta-Orchestrator](https://github.com/github/gh-aw/blob/main/.github/workflows/agent-performance-analyzer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/agent-performance-analyzer.lock.yml) | - | - | | [Agent Persona Explorer](https://github.com/github/gh-aw/blob/main/.github/workflows/agent-persona-explorer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/agent-persona-explorer.lock.yml) | - | - | | [Agentic Workflow Audit Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/audit-workflows.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/audit-workflows.lock.yml) | - | - | | [Agentic Workflow Portfolio Yield](https://github.com/github/gh-aw/blob/main/.github/workflows/aw-portfolio-yield.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/aw-portfolio-yield.lock.yml) | - | - | | [AI Moderator](https://github.com/github/gh-aw/blob/main/.github/workflows/ai-moderator.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/ai-moderator.lock.yml) | - | - | | [Approach Validator](https://github.com/github/gh-aw/blob/main/.github/workflows/approach-validator.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/approach-validator.lock.yml) | - | - | | [Archie](https://github.com/github/gh-aw/blob/main/.github/workflows/archie.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/archie.lock.yml) | - | `/archie` | | [Architecture Diagram Generator](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-architecture-diagram.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-architecture-diagram.lock.yml) | - | - | | [Architecture Guardian](https://github.com/github/gh-aw/blob/main/.github/workflows/architecture-guardian.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/architecture-guardian.lock.yml) | - | - | | [Artifacts Summary](https://github.com/github/gh-aw/blob/main/.github/workflows/artifacts-summary.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/artifacts-summary.lock.yml) | - | - | | [Auto-Assign Issue](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-assign-issue-to-user.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-assign-issue-to-user.lock.yml) | - | - | | [Auto-Triage Issues](https://github.com/github/gh-aw/blob/main/.github/workflows/auto-triage-issues.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/auto-triage-issues.lock.yml) | - | - | | [Basic Research Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/research.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/research.lock.yml) | - | - | | [Blog Auditor](https://github.com/github/gh-aw/blob/main/.github/workflows/blog-auditor.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/blog-auditor.lock.yml) | - | - | | [Bot Detection](https://github.com/github/gh-aw/blob/main/.github/workflows/bot-detection.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/bot-detection.lock.yml) | `every 6h` | - | | [Brave Web Search Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/brave.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/brave.lock.yml) | - | - | | [Breaking Change Checker](https://github.com/github/gh-aw/blob/main/.github/workflows/breaking-change-checker.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/breaking-change-checker.lock.yml) | - | - | | [Changeset Generator](https://github.com/github/gh-aw/blob/main/.github/workflows/changeset.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/changeset.lock.yml) | - | - | | [Chaos PR Bundle Fuzzer](https://github.com/github/gh-aw/blob/main/.github/workflows/chaos-pr-bundle-fuzzer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/chaos-pr-bundle-fuzzer.lock.yml) | - | - | | [CI Cleaner](https://github.com/github/gh-aw/blob/main/.github/workflows/hourly-ci-cleaner.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/hourly-ci-cleaner.lock.yml) | - | - | | [CI Failure Doctor](https://github.com/github/gh-aw/blob/main/.github/workflows/ci-doctor.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/ci-doctor.lock.yml) | - | - | | [CI Optimization Coach](https://github.com/github/gh-aw/blob/main/.github/workflows/ci-coach.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/ci-coach.lock.yml) | `daily around 13:00 on weekdays` | - | | [Claude Code User Documentation Review](https://github.com/github/gh-aw/blob/main/.github/workflows/claude-code-user-docs-review.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/claude-code-user-docs-review.lock.yml) | - | - | | [CLI Consistency Checker](https://github.com/github/gh-aw/blob/main/.github/workflows/cli-consistency-checker.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/cli-consistency-checker.lock.yml) | `daily around 13:00 on weekdays` | - | | [CLI Version Checker](https://github.com/github/gh-aw/blob/main/.github/workflows/cli-version-checker.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/cli-version-checker.lock.yml) | - | - | | [Code Refiner](https://github.com/github/gh-aw/blob/main/.github/workflows/refiner.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/refiner.lock.yml) | - | - | | [Code Scanning Fixer](https://github.com/github/gh-aw/blob/main/.github/workflows/code-scanning-fixer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/code-scanning-fixer.lock.yml) | - | - | | [Code Simplifier](https://github.com/github/gh-aw/blob/main/.github/workflows/code-simplifier.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/code-simplifier.lock.yml) | - | - | | [Codex GitHub Remote MCP Test](https://github.com/github/gh-aw/blob/main/.github/workflows/codex-github-remote-mcp-test.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/codex-github-remote-mcp-test.lock.yml) | - | - | | [Commit Changes Analyzer](https://github.com/github/gh-aw/blob/main/.github/workflows/commit-changes-analyzer.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/commit-changes-analyzer.lock.yml) | - | - | | [Constraint Solving — Problem of the Day](https://github.com/github/gh-aw/blob/main/.github/workflows/constraint-solving-potd.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/constraint-solving-potd.lock.yml) | - | - | | [Contribution Check](https://github.com/github/gh-aw/blob/main/.github/workflows/contribution-check.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/contribution-check.lock.yml) | - | - | | [Copilot Agent PR Analysis](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-agent-analysis.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/copilot-agent-analysis.lock.yml) | - | - | | [Copilot Agent Prompt Clustering Analysis](https://github.com/github/gh-aw/blob/main/.github/workflows/prompt-clustering-analysis.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/prompt-clustering-analysis.lock.yml) | - | - | | [Copilot CLI Deep Research Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-cli-deep-research.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/copilot-cli-deep-research.lock.yml) | - | - | | [Copilot Opt](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-opt.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/copilot-opt.lock.yml) | `weekly on monday` | - | | [Copilot PR Conversation NLP Analysis](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-pr-nlp-analysis.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/copilot-pr-nlp-analysis.lock.yml) | `daily around 10:00 on weekdays` | - | | [Copilot PR Prompt Pattern Analysis](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-pr-prompt-analysis.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/copilot-pr-prompt-analysis.lock.yml) | - | - | | [Copilot Session Insights](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-session-insights.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/copilot-session-insights.lock.yml) | - | - | | [Copilot Token Usage Optimizer](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-token-optimizer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/copilot-token-optimizer.lock.yml) | `daily around 14:00 on weekdays` | - | | [Daily A/B Testing Advisor](https://github.com/github/gh-aw/blob/main/.github/workflows/ab-testing-advisor.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/ab-testing-advisor.lock.yml) | - | - | | [Daily Agent of the Day Blog Writer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-agent-of-the-day-blog-writer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-agent-of-the-day-blog-writer.lock.yml) | - | - | | [Daily AgentRx Trace Optimizer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-agentrx-trace-optimizer.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-agentrx-trace-optimizer.lock.yml) | - | - | | [Daily AstroStyleLite Markdown Spellcheck](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-astrostylelite-markdown-spellcheck.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-astrostylelite-markdown-spellcheck.lock.yml) | - | - | | [Daily AW Cross-Repo Compile Check](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-aw-cross-repo-compile-check.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-aw-cross-repo-compile-check.lock.yml) | - | - | | [Daily Cache Strategy Analyzer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-cache-strategy-analyzer.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/daily-cache-strategy-analyzer.lock.yml) | - | - | | [Daily Caveman Optimizer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-caveman-optimizer.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-caveman-optimizer.lock.yml) | - | - | | [Daily Choice Type Test](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-choice-test.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-choice-test.lock.yml) | `daily around 12:00 on weekdays` | - | | [Daily CLI Performance Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-cli-performance.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-cli-performance.lock.yml) | - | - | | [Daily CLI Tools Exploratory Tester](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-cli-tools-tester.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-cli-tools-tester.lock.yml) | - | - | | [Daily Code Metrics and Trend Tracking Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-code-metrics.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-code-metrics.lock.yml) | - | - | | [Daily Community Attribution Updater](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-community-attribution.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-community-attribution.lock.yml) | - | - | | [Daily Compiler Quality Check](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-compiler-quality.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-compiler-quality.lock.yml) | - | - | | [Daily Compiler Threat Spec Optimizer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-compiler-threat-spec-optimizer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-compiler-threat-spec-optimizer.lock.yml) | - | - | | [Daily Copilot PR Merged Report](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-pr-merged-report.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/copilot-pr-merged-report.lock.yml) | `daily around 15:00 on weekdays` | - | | [Daily Copilot Token Usage Audit](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-token-audit.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/copilot-token-audit.lock.yml) | `daily around 12:00 on weekdays` | - | | [Daily Documentation Healer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-doc-healer.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-doc-healer.lock.yml) | - | - | | [Daily Documentation Updater](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-doc-updater.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-doc-updater.lock.yml) | - | - | | [Daily Fact About gh-aw](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-fact.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/daily-fact.lock.yml) | `daily around 14:00 on weekdays` | - | | [Daily File Diet](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-file-diet.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-file-diet.lock.yml) | - | - | | [Daily Firewall Logs Collector and Reporter](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-firewall-report.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-firewall-report.lock.yml) | - | - | | [Daily Go Function Namer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-function-namer.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-function-namer.lock.yml) | - | - | | [Daily Grafana OTel Instrumentation Advisor](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-grafana-otel-instrumentation-advisor.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-grafana-otel-instrumentation-advisor.lock.yml) | - | - | | [Daily Hippo Learn](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-hippo-learn.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-hippo-learn.lock.yml) | `daily around 7:00` | - | | [Daily Issues Report Generator](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-issues-report.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-issues-report.lock.yml) | - | - | | [Daily Malicious Code Scan Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-malicious-code-scan.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-malicious-code-scan.lock.yml) | - | - | | [Daily MCP Tool Concurrency Analysis](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-mcp-concurrency-analysis.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-mcp-concurrency-analysis.lock.yml) | - | - | | [Daily Model Inventory Checker](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-model-inventory.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-model-inventory.lock.yml) | - | - | | [Daily News](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-news.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-news.lock.yml) | `daily around 9:00 on weekdays` | - | | [Daily Observability Report for AWF Firewall and MCP Gateway](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-observability-report.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/daily-observability-report.lock.yml) | - | - | | [Daily OTel Instrumentation Advisor](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-otel-instrumentation-advisor.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-otel-instrumentation-advisor.lock.yml) | - | - | | [Daily Project Performance Summary Generator (Using MCP Scripts)](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-performance-summary.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-performance-summary.lock.yml) | - | - | | [Daily Regulatory Report Generator](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-regulatory.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-regulatory.lock.yml) | - | - | | [Daily Reliability Review](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-reliability-review.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-reliability-review.lock.yml) | - | - | | [Daily Rendering Scripts Verifier](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-rendering-scripts-verifier.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-rendering-scripts-verifier.lock.yml) | - | - | | [Daily Safe Output Integrator](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-safe-output-integrator.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-safe-output-integrator.lock.yml) | - | - | | [Daily Safe Output Tool Optimizer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-safe-output-optimizer.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-safe-output-optimizer.lock.yml) | - | - | | [Daily Safe Outputs Conformance Checker](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-safe-outputs-conformance.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-safe-outputs-conformance.lock.yml) | - | - | | [Daily Secrets Analysis Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-secrets-analysis.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-secrets-analysis.lock.yml) | - | - | | [Daily Security Observability Report](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-security-observability.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-security-observability.lock.yml) | - | - | | [Daily Security Red Team Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-security-red-team.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-security-red-team.lock.yml) | - | - | | [Daily Semgrep Scan](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-semgrep-scan.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-semgrep-scan.lock.yml) | - | - | | [Daily Sentrux Report](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-sentrux-report.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-sentrux-report.lock.yml) | - | - | | [Daily Skill Optimizer Improvements](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-skill-optimizer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-skill-optimizer.lock.yml) | - | - | | [Daily SPDD Spec Planner](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-spdd-spec-planner.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-spdd-spec-planner.lock.yml) | - | - | | [Daily Sub-Agent Optimizer](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-subagent-optimizer.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-subagent-optimizer.lock.yml) | - | - | | [Daily Syntax Error Quality Check](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-syntax-error-quality.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-syntax-error-quality.lock.yml) | - | - | | [Daily Team Evolution Insights](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-team-evolution-insights.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-team-evolution-insights.lock.yml) | - | - | | [Daily Team Status](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-team-status.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-team-status.lock.yml) | `daily around 9:00 on weekdays` | - | | [Daily Testify Uber Super Expert](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-testify-uber-super-expert.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-testify-uber-super-expert.lock.yml) | - | - | | [Daily Token Consumption Report (Sentry OTel)](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-token-consumption-report.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-token-consumption-report.lock.yml) | - | - | | [Daily Workflow Updater](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-workflow-updater.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-workflow-updater.lock.yml) | - | - | | [daily-experiment-report](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-experiment-report.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-experiment-report.lock.yml) | - | - | | [DataFlow PR & Discussion Dataset Builder](https://github.com/github/gh-aw/blob/main/.github/workflows/dataflow-pr-discussion-dataset.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/dataflow-pr-discussion-dataset.lock.yml) | - | - | | [Dead Code Removal Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/dead-code-remover.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/dead-code-remover.lock.yml) | - | - | | [DeepReport - Intelligence Gathering Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/deep-report.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/deep-report.lock.yml) | `daily around 15:00 on weekdays` | - | | [Delight](https://github.com/github/gh-aw/blob/main/.github/workflows/delight.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/delight.lock.yml) | - | - | | [Dependabot Burner](https://github.com/github/gh-aw/blob/main/.github/workflows/dependabot-burner.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/dependabot-burner.lock.yml) | - | - | | [Dependabot Campaign](https://github.com/github/gh-aw/blob/main/.github/workflows/dependabot-campaign.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/dependabot-campaign.lock.yml) | - | - | | [Dependabot Dependency Checker](https://github.com/github/gh-aw/blob/main/.github/workflows/dependabot-go-checker.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/dependabot-go-checker.lock.yml) | `20 9 * * 1,3,5` | - | | [Dependabot Local Repair](https://github.com/github/gh-aw/blob/main/.github/workflows/dependabot-repair.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/dependabot-repair.lock.yml) | - | - | | [Dependabot Worker](https://github.com/github/gh-aw/blob/main/.github/workflows/dependabot-worker.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/dependabot-worker.lock.yml) | - | - | | [Deployment Incident Monitor](https://github.com/github/gh-aw/blob/main/.github/workflows/deployment-incident-monitor.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/deployment-incident-monitor.lock.yml) | - | - | | [Design Decision Gate](https://github.com/github/gh-aw/blob/main/.github/workflows/design-decision-gate.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/design-decision-gate.lock.yml) | - | - | | [Dev](https://github.com/github/gh-aw/blob/main/.github/workflows/dev.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/dev.lock.yml) | `daily around 9:00` | - | | [Dev Hawk](https://github.com/github/gh-aw/blob/main/.github/workflows/dev-hawk.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/dev-hawk.lock.yml) | - | - | | [Developer Documentation Consolidator](https://github.com/github/gh-aw/blob/main/.github/workflows/developer-docs-consolidator.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/developer-docs-consolidator.lock.yml) | - | - | | [Dictation Prompt Generator](https://github.com/github/gh-aw/blob/main/.github/workflows/dictation-prompt.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/dictation-prompt.lock.yml) | `weekly on sunday around 6:00` | - | | [Discussion Task Miner - Code Quality Improvement Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/discussion-task-miner.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/discussion-task-miner.lock.yml) | - | - | | [Documentation Noob Tester](https://github.com/github/gh-aw/blob/main/.github/workflows/docs-noob-tester.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/docs-noob-tester.lock.yml) | - | - | | [Documentation Unbloat](https://github.com/github/gh-aw/blob/main/.github/workflows/unbloat-docs.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/unbloat-docs.lock.yml) | - | - | | [Draft PR Cleanup](https://github.com/github/gh-aw/blob/main/.github/workflows/draft-pr-cleanup.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/draft-pr-cleanup.lock.yml) | - | - | | [Duplicate Code Detector](https://github.com/github/gh-aw/blob/main/.github/workflows/duplicate-code-detector.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/duplicate-code-detector.lock.yml) | - | - | | [Example: Properly Provisioned Permissions](https://github.com/github/gh-aw/blob/main/.github/workflows/example-permissions-warning.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/example-permissions-warning.lock.yml) | - | - | | [Firewall Test Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/firewall.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/firewall.lock.yml) | - | - | | [Functional Pragmatist](https://github.com/github/gh-aw/blob/main/.github/workflows/functional-pragmatist.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/functional-pragmatist.lock.yml) | `25 9 * * 2,4` | - | | [GEO Optimizer Daily Audit](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-geo-optimizer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-geo-optimizer.lock.yml) | - | - | | [GitHub API Consumption Report Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/api-consumption-report.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/api-consumption-report.lock.yml) | - | - | | [GitHub MCP Remote Server Tools Report Generator](https://github.com/github/gh-aw/blob/main/.github/workflows/github-mcp-tools-report.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/github-mcp-tools-report.lock.yml) | - | - | | [GitHub MCP Structural Analysis](https://github.com/github/gh-aw/blob/main/.github/workflows/github-mcp-structural-analysis.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/github-mcp-structural-analysis.lock.yml) | `daily around 11:00 on weekdays` | - | | [GitHub Remote MCP Authentication Test](https://github.com/github/gh-aw/blob/main/.github/workflows/github-remote-mcp-auth-test.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/github-remote-mcp-auth-test.lock.yml) | - | - | | [Glossary Maintainer](https://github.com/github/gh-aw/blob/main/.github/workflows/glossary-maintainer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/glossary-maintainer.lock.yml) | `daily around 10:00 on weekdays` | - | | [Go Fan](https://github.com/github/gh-aw/blob/main/.github/workflows/go-fan.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/go-fan.lock.yml) | - | - | | [Go Logger Enhancement](https://github.com/github/gh-aw/blob/main/.github/workflows/go-logger.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/go-logger.lock.yml) | - | - | | [Go Pattern Detector](https://github.com/github/gh-aw/blob/main/.github/workflows/go-pattern-detector.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/go-pattern-detector.lock.yml) | `daily around 14:00 on weekdays` | - | | [GPL Dependency Cleaner (gpclean)](https://github.com/github/gh-aw/blob/main/.github/workflows/gpclean.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/gpclean.lock.yml) | - | - | | [Grumpy Code Reviewer](https://github.com/github/gh-aw/blob/main/.github/workflows/grumpy-reviewer.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/grumpy-reviewer.lock.yml) | - | - | | [Hippo Embed](https://github.com/github/gh-aw/blob/main/.github/workflows/hippo-embed.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/hippo-embed.lock.yml) | - | - | | [Instructions Janitor](https://github.com/github/gh-aw/blob/main/.github/workflows/instructions-janitor.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/instructions-janitor.lock.yml) | - | - | | [Issue Arborist](https://github.com/github/gh-aw/blob/main/.github/workflows/issue-arborist.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/issue-arborist.lock.yml) | - | - | | [Issue Monster](https://github.com/github/gh-aw/blob/main/.github/workflows/issue-monster.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/issue-monster.lock.yml) | - | - | | [Issue Summary to Notion](https://github.com/github/gh-aw/blob/main/.github/workflows/notion-issue-summary.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/notion-issue-summary.lock.yml) | - | - | | [Issue Triage Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/issue-triage-agent.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/issue-triage-agent.lock.yml) | - | - | | [jsweep - JavaScript Unbloater](https://github.com/github/gh-aw/blob/main/.github/workflows/jsweep.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/jsweep.lock.yml) | - | - | | [Layout Specification Maintainer](https://github.com/github/gh-aw/blob/main/.github/workflows/layout-spec-maintainer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/layout-spec-maintainer.lock.yml) | - | - | | [Linter Miner](https://github.com/github/gh-aw/blob/main/.github/workflows/linter-miner.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/linter-miner.lock.yml) | - | - | | [LintMonster](https://github.com/github/gh-aw/blob/main/.github/workflows/lint-monster.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/lint-monster.lock.yml) | - | - | | [Lockfile Statistics Analysis Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/lockfile-stats.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/lockfile-stats.lock.yml) | - | - | | [Matt Pocock Skills Reviewer](https://github.com/github/gh-aw/blob/main/.github/workflows/mattpocock-skills-reviewer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/mattpocock-skills-reviewer.lock.yml) | - | - | | [MCP Inspector Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/mcp-inspector.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/mcp-inspector.lock.yml) | - | - | | [Mergefest](https://github.com/github/gh-aw/blob/main/.github/workflows/mergefest.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/mergefest.lock.yml) | - | - | | [Metrics Collector - Infrastructure Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/metrics-collector.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/metrics-collector.lock.yml) | - | - | | [Multi-Device Docs Tester](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-multi-device-docs-tester.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/daily-multi-device-docs-tester.lock.yml) | - | - | | [Necromancer](https://github.com/github/gh-aw/blob/main/.github/workflows/necromancer.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/necromancer.lock.yml) | - | - | | [Organization Health Report](https://github.com/github/gh-aw/blob/main/.github/workflows/org-health-report.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/org-health-report.lock.yml) | - | - | | [OTLP Data Quality Validator](https://github.com/github/gh-aw/blob/main/.github/workflows/otlp-data-quality-validator.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/otlp-data-quality-validator.lock.yml) | - | - | | [Outcome Collector](https://github.com/github/gh-aw/blob/main/.github/workflows/outcome-collector.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/outcome-collector.lock.yml) | - | - | | [Package Specification Enforcer](https://github.com/github/gh-aw/blob/main/.github/workflows/spec-enforcer.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/spec-enforcer.lock.yml) | - | - | | [Package Specification Extractor](https://github.com/github/gh-aw/blob/main/.github/workflows/spec-extractor.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/spec-extractor.lock.yml) | - | - | | [Package Specification Librarian](https://github.com/github/gh-aw/blob/main/.github/workflows/spec-librarian.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/spec-librarian.lock.yml) | - | - | | [Plan Command](https://github.com/github/gh-aw/blob/main/.github/workflows/plan.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/plan.lock.yml) | - | - | | [Poem Bot - A Creative Agentic Workflow](https://github.com/github/gh-aw/blob/main/.github/workflows/poem-bot.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/poem-bot.lock.yml) | - | - | | [PR Code Quality Reviewer](https://github.com/github/gh-aw/blob/main/.github/workflows/pr-code-quality-reviewer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/pr-code-quality-reviewer.lock.yml) | - | - | | [PR Description Updater](https://github.com/github/gh-aw/blob/main/.github/workflows/pr-description-caveman.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/pr-description-caveman.lock.yml) | - | - | | [PR Nitpick Reviewer](https://github.com/github/gh-aw/blob/main/.github/workflows/pr-nitpick-reviewer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/pr-nitpick-reviewer.lock.yml) | - | - | | [PR Sous Chef](https://github.com/github/gh-aw/blob/main/.github/workflows/pr-sous-chef.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/pr-sous-chef.lock.yml) | - | - | | [PR Triage Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/pr-triage-agent.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/pr-triage-agent.lock.yml) | - | - | | [Python Data Visualization Generator](https://github.com/github/gh-aw/blob/main/.github/workflows/python-data-charts.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/python-data-charts.lock.yml) | - | - | | [Q](https://github.com/github/gh-aw/blob/main/.github/workflows/q.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/q.lock.yml) | - | `/q` | | [Rebuild the documentation after making changes](https://github.com/github/gh-aw/blob/main/.github/workflows/technical-doc-writer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/technical-doc-writer.lock.yml) | - | - | | [Refactoring Cadence](https://github.com/github/gh-aw/blob/main/.github/workflows/refactoring-cadence.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/refactoring-cadence.lock.yml) | - | - | | [Release](https://github.com/github/gh-aw/blob/main/.github/workflows/release.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/release.lock.yml) | - | - | | [Repository Audit & Agentic Workflow Opportunity Analyzer](https://github.com/github/gh-aw/blob/main/.github/workflows/repo-audit-analyzer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/repo-audit-analyzer.lock.yml) | - | - | | [Repository Quality Improvement Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/repository-quality-improver.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/repository-quality-improver.lock.yml) | `daily around 13:00 on weekdays` | - | | [Repository Tree Map Generator](https://github.com/github/gh-aw/blob/main/.github/workflows/repo-tree-map.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/repo-tree-map.lock.yml) | - | - | | [Resource Summarizer Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/pdf-summary.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/pdf-summary.lock.yml) | - | - | | [Safe Output Health Monitor](https://github.com/github/gh-aw/blob/main/.github/workflows/safe-output-health.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/safe-output-health.lock.yml) | - | - | | [Schema Consistency Checker](https://github.com/github/gh-aw/blob/main/.github/workflows/schema-consistency-checker.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/schema-consistency-checker.lock.yml) | - | - | | [Schema Feature Coverage Checker](https://github.com/github/gh-aw/blob/main/.github/workflows/schema-feature-coverage.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/schema-feature-coverage.lock.yml) | - | - | | [Scout](https://github.com/github/gh-aw/blob/main/.github/workflows/scout.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/scout.lock.yml) | - | `/scout` | | [Security Compliance Campaign](https://github.com/github/gh-aw/blob/main/.github/workflows/security-compliance.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/security-compliance.lock.yml) | - | - | | [Security Review Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/security-review.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/security-review.lock.yml) | - | - | | [Semantic Function Refactoring](https://github.com/github/gh-aw/blob/main/.github/workflows/semantic-function-refactor.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/semantic-function-refactor.lock.yml) | - | - | | [Sergo - Serena Go Expert](https://github.com/github/gh-aw/blob/main/.github/workflows/sergo.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/sergo.lock.yml) | - | - | | [Slide Deck Maintainer](https://github.com/github/gh-aw/blob/main/.github/workflows/slide-deck-maintainer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/slide-deck-maintainer.lock.yml) | `daily around 16:00 on weekdays` | - | | [Smoke Agent: all/merged](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-agent-all-merged.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/smoke-agent-all-merged.lock.yml) | - | - | | [Smoke Agent: all/none](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-agent-all-none.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/smoke-agent-all-none.lock.yml) | - | - | | [Smoke Agent: public/approved](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-agent-public-approved.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/smoke-agent-public-approved.lock.yml) | - | - | | [Smoke Agent: public/none](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-agent-public-none.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/smoke-agent-public-none.lock.yml) | - | - | | [Smoke Agent: scoped/approved](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-agent-scoped-approved.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/smoke-agent-scoped-approved.lock.yml) | - | - | | [Smoke Call Workflow](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-call-workflow.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/smoke-call-workflow.lock.yml) | - | - | | [Smoke CI](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-ci.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-ci.lock.yml) | - | - | | [Smoke Claude](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-claude.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/smoke-claude.lock.yml) | - | - | | [Smoke Codex](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-codex.md) | codex | [](https://github.com/github/gh-aw/actions/workflows/smoke-codex.lock.yml) | - | - | | [Smoke Copilot](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-copilot.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-copilot.lock.yml) | - | - | | [Smoke Copilot ARM64](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-copilot-arm.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-copilot-arm.lock.yml) | - | - | | [Smoke Create Cross-Repo PR](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-create-cross-repo-pr.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-create-cross-repo-pr.lock.yml) | - | - | | [Smoke Crush](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-crush.md) | crush | [](https://github.com/github/gh-aw/actions/workflows/smoke-crush.lock.yml) | - | - | | [Smoke Gemini](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-gemini.md) | gemini | [](https://github.com/github/gh-aw/actions/workflows/smoke-gemini.lock.yml) | - | - | | [Smoke Multi PR](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-multi-pr.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-multi-pr.lock.yml) | - | - | | [Smoke OpenCode](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-opencode.md) | opencode | [](https://github.com/github/gh-aw/actions/workflows/smoke-opencode.lock.yml) | - | - | | [Smoke OTEL](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-otel-backends.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-otel-backends.lock.yml) | - | - | | [Smoke Pi](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-pi.md) | pi | [](https://github.com/github/gh-aw/actions/workflows/smoke-pi.lock.yml) | - | - | | [Smoke Project](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-project.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-project.lock.yml) | - | - | | [Smoke Service Ports](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-service-ports.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-service-ports.lock.yml) | - | - | | [Smoke Temporary ID](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-temporary-id.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-temporary-id.lock.yml) | - | - | | [Smoke Update Cross-Repo PR](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-update-cross-repo-pr.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-update-cross-repo-pr.lock.yml) | - | - | | [Smoke Workflow Call](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-workflow-call.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-workflow-call.lock.yml) | - | - | | [Smoke Workflow Call with Inputs](https://github.com/github/gh-aw/blob/main/.github/workflows/smoke-workflow-call-with-inputs.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/smoke-workflow-call-with-inputs.lock.yml) | - | - | | [Stale PR Cleanup](https://github.com/github/gh-aw/blob/main/.github/workflows/stale-pr-cleanup.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/stale-pr-cleanup.lock.yml) | - | - | | [Stale Repository Identifier](https://github.com/github/gh-aw/blob/main/.github/workflows/stale-repo-identifier.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/stale-repo-identifier.lock.yml) | - | - | | [Static Analysis Report](https://github.com/github/gh-aw/blob/main/.github/workflows/static-analysis-report.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/static-analysis-report.lock.yml) | - | - | | [Step Name Alignment](https://github.com/github/gh-aw/blob/main/.github/workflows/step-name-alignment.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/step-name-alignment.lock.yml) | - | - | | [Sub-Issue Closer](https://github.com/github/gh-aw/blob/main/.github/workflows/sub-issue-closer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/sub-issue-closer.lock.yml) | - | - | | [Super Linter Report](https://github.com/github/gh-aw/blob/main/.github/workflows/super-linter.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/super-linter.lock.yml) | `daily around 14:00 on weekdays` | - | | [Terminal Stylist](https://github.com/github/gh-aw/blob/main/.github/workflows/terminal-stylist.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/terminal-stylist.lock.yml) | - | - | | [Test Create PR Error Handling](https://github.com/github/gh-aw/blob/main/.github/workflows/test-create-pr-error-handling.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/test-create-pr-error-handling.lock.yml) | - | - | | [Test Dispatcher Workflow](https://github.com/github/gh-aw/blob/main/.github/workflows/test-dispatcher.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/test-dispatcher.lock.yml) | - | - | | [Test Project URL Explicit Requirement](https://github.com/github/gh-aw/blob/main/.github/workflows/test-project-url-default.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/test-project-url-default.lock.yml) | - | - | | [Test Quality Sentinel](https://github.com/github/gh-aw/blob/main/.github/workflows/test-quality-sentinel.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/test-quality-sentinel.lock.yml) | - | - | | [Test Workflow](https://github.com/github/gh-aw/blob/main/.github/workflows/test-workflow.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/test-workflow.lock.yml) | - | - | | [The Daily Repository Chronicle](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-repo-chronicle.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/daily-repo-chronicle.lock.yml) | `daily around 16:00 on weekdays` | - | | [The Great Escapi](https://github.com/github/gh-aw/blob/main/.github/workflows/firewall-escape.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/firewall-escape.lock.yml) | - | - | | [Tidy](https://github.com/github/gh-aw/blob/main/.github/workflows/tidy.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/tidy.lock.yml) | `daily around 7:00` | - | | [Typist - Go Type Analysis](https://github.com/github/gh-aw/blob/main/.github/workflows/typist.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/typist.lock.yml) | - | - | | [Ubuntu Actions Image Analyzer](https://github.com/github/gh-aw/blob/main/.github/workflows/ubuntu-image-analyzer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/ubuntu-image-analyzer.lock.yml) | - | - | | [UK AI Operational Resilience](https://github.com/github/gh-aw/blob/main/.github/workflows/uk-ai-operational-resilience.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/uk-ai-operational-resilience.lock.yml) | - | - | | [Update Astro](https://github.com/github/gh-aw/blob/main/.github/workflows/update-astro.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/update-astro.lock.yml) | - | - | | [Video Analysis Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/video-analyzer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/video-analyzer.lock.yml) | - | - | | [Visual Regression Checker](https://github.com/github/gh-aw/blob/main/.github/workflows/visual-regression-checker.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/visual-regression-checker.lock.yml) | - | - | | [Weekly Blog Post Writer](https://github.com/github/gh-aw/blob/main/.github/workflows/weekly-blog-post-writer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/weekly-blog-post-writer.lock.yml) | - | - | | [Weekly Editors Health Check](https://github.com/github/gh-aw/blob/main/.github/workflows/weekly-editors-health-check.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/weekly-editors-health-check.lock.yml) | - | - | | [Weekly Issue Summary](https://github.com/github/gh-aw/blob/main/.github/workflows/weekly-issue-summary.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/weekly-issue-summary.lock.yml) | `weekly on monday around 15:00` | - | | [Weekly Safe Outputs Specification Review](https://github.com/github/gh-aw/blob/main/.github/workflows/weekly-safe-outputs-spec-review.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/weekly-safe-outputs-spec-review.lock.yml) | `weekly on monday` | - | | [Weekly Workflow Analysis](https://github.com/github/gh-aw/blob/main/.github/workflows/example-workflow-analyzer.md) | claude | [](https://github.com/github/gh-aw/actions/workflows/example-workflow-analyzer.lock.yml) | - | - | | [Workflow Craft Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/craft.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/craft.lock.yml) | - | `/my` | | [Workflow Generator](https://github.com/github/gh-aw/blob/main/.github/workflows/workflow-generator.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/workflow-generator.lock.yml) | - | - | | [Workflow Health Manager - Meta-Orchestrator](https://github.com/github/gh-aw/blob/main/.github/workflows/workflow-health-manager.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/workflow-health-manager.lock.yml) | - | - | | [Workflow Normalizer](https://github.com/github/gh-aw/blob/main/.github/workflows/workflow-normalizer.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/workflow-normalizer.lock.yml) | - | - | | [Workflow Skill Extractor](https://github.com/github/gh-aw/blob/main/.github/workflows/workflow-skill-extractor.md) | copilot | [](https://github.com/github/gh-aw/actions/workflows/workflow-skill-extractor.lock.yml) | - | - | Note Badges update automatically. Click badges for run details or workflow names for source files. # Welcome to Peli's Agent Factory > It's basically a candy shop chocolate factory of agentic workflows.  Welcome, welcome, WELCOME to Peli’s Agent Factory! Imagine a software repository where AI agents work alongside your team - not replacing developers, but handling the repetitive, time-consuming tasks that slow down collaboration and forward progress. Peli’s Agent Factory is our exploration of what happens when you take the design philosophy of **“let’s create a new automated agentic workflow for that”** as the answer to almost every opportunity that arises! What happens when you **max out on automated agentic workflows** - when you make and use dozens of specialized, automated AI agentic workflows and use them in practice. Software development is changing rapidly. This is our attempt to understand how automated agentic AI can make software teams more efficient, collaborative, and more enjoyable. It’s basically a candy shop chocolate factory of agentic workflows. And we’d like to share it with you. Let’s explore together! ## What Is Peli’s Agent Factory? [Section titled “What Is Peli’s Agent Factory?”](#what-is-pelis-agent-factory) Peli’s factory is a collection of [**automated agentic workflows**](https://gh.io/gh-aw) we use in practice. We have built and operated **over 100 automated agentic workflows** within the [`github/gh-aw`](https://github.com/github/gh-aw) repository. These were used mostly in the context of the [`github/gh-aw`](https://github.com/github/gh-aw) project itself, but some have also been applied at scale in GitHub internal repositories. These weren’t hypothetical demos - they were working agents that: * [Triage incoming issues](/gh-aw/blog/2026-01-13-meet-the-workflows/) * [Diagnose CI failures](/gh-aw/blog/2026-01-13-meet-the-workflows-quality-hygiene/) * [Maintain documentation](/gh-aw/blog/2026-01-13-meet-the-workflows-documentation/) * [Improve test coverage](/gh-aw/blog/2026-01-13-meet-the-workflows-testing-validation/) * [Monitor security compliance](/gh-aw/blog/2026-01-13-meet-the-workflows-security-compliance/) * [Optimize workflow efficiency](/gh-aw/blog/2026-01-13-meet-the-workflows-metrics-analytics/) * [Execute multi-day projects](/gh-aw/blog/2026-01-13-meet-the-workflows-multi-phase/) * Even [write poetry to boost team morale](/gh-aw/blog/2026-01-13-meet-the-workflows-creative-culture/) Some workflows are [“read-only analysts”](/gh-aw/blog/2026-01-13-meet-the-workflows-metrics-analytics/). Others [proactively propose changes through pull requests](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-simplicity/). Some are [meta-agents that monitor and improve the health of other workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-metrics-analytics/). We know we’re taking things to an extreme here. Most repositories won’t need dozens of agentic workflows. No one can read all these outputs (except, of course, another workflow). But by pushing the boundaries, we learned valuable lessons about what works, what doesn’t, and how to design safe, effective agentic workflows that teams can trust and use. ## Why Build a Factory? [Section titled “Why Build a Factory?”](#why-build-a-factory) When we started exploring agentic workflows, we faced a fundamental question: **What should repository-level automated agentic workflows actually do?** Rather than trying to build one “perfect” agent, we took a broad, heterogeneous approach: 1. **Embrace diversity** - Create many specialized workflows as we identified opportunities 2. **Use them continuously** - Run them in real development workflows 3. **Observe what works** - Find which patterns work and which fail 4. **Share the knowledge** - Catalog the structures that make agents safe and effective The factory becomes both an experiment and a reference collection - a living library of patterns that others can study, adapt, and remix. Each workflow is written in natural language using Markdown, then converted into secure [GitHub Actions](https://github.com/features/actions) that run with carefully scoped permissions with guardrails. Everything is observable, auditable, and remixable. ## Meet the Workflows [Section titled “Meet the Workflows”](#meet-the-workflows) In our first series, [Meet the Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows/), we’ll take you on a tour of the most interesting agents in the factory. Each article is bite-sized. If you’d like to skip ahead, here’s the full list of articles in the series: 1. [Meet a Simple Triage Workflow](/gh-aw/blog/2026-01-13-meet-the-workflows/) 2. [Introducing Continuous Simplicity](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-simplicity/) 3. [Introducing Continuous Refactoring](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-refactoring/) 4. [Introducing Continuous Style](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-style/) 5. [Introducing Continuous Improvement](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-improvement/) 6. [Introducing Continuous Documentation](/gh-aw/blog/2026-01-13-meet-the-workflows-documentation/) After that we have a cornucopia of specialized workflow categories for you to dip into: * [Meet the Issue & PR Management Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-issue-management/) * [Meet the Fault Investigation Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-quality-hygiene/) * [Meet the Metrics & Analytics Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-metrics-analytics/) * [Meet the Operations & Release Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-operations-release/) * [Meet the Security-related Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-security-compliance/) * [Meet the Teamwork & Culture Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-creative-culture/) * [Meet the Interactive & ChatOps Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-interactive-chatops/) * [Meet the Testing & Validation Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-testing-validation/) * [Meet the Tool & Infrastructure Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-tool-infrastructure/) * [Introducing Multi-Phase Improver Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-multi-phase/) * [Meet the Organization & Cross-Repo Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-organization/) * [Go Deep with Advanced Analytics & ML Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-advanced-analytics/) * [Go Deep with Project Coordination Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows-campaigns/) Every post comes with instructions about how to add the workflow to your own repository, or customize and remix it to create your own variant. ## What We’re Learning [Section titled “What We’re Learning”](#what-were-learning) Running this many agents in production is a learning experience! We’ve watched agents succeed spectacularly and fail in instructive ways. Over the next few weeks, we’ll also be sharing what we’ve learned through a series of detailed articles. We’ll be looking at the design and operational patterns we’ve discovered, security lessons, and practical guides for building your own workflows. To give a taste, some key lessons are emerging: * **Repository-level automation is powerful** - Agents embedded in the development workflow can have outsized impact * **Specialization reveals possibilities** - Focused agents allowed us to find more useful applications of automation than a single monolithic coding agent * **Guardrails enable innovation** - Strict constraints actually make it easier to experiment safely * **Meta-agents are valuable** - Agents that watch other agents become incredibly valuable * **Cost-quality tradeoffs are real** - Longer analyses aren’t always better We’ll dive deeper into these lessons in upcoming articles. ## Try It Yourself [Section titled “Try It Yourself”](#try-it-yourself) Want to start with automated agentic workflows on GitHub? See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/). ## Learn More [Section titled “Learn More”](#learn-more) * **[Meet the Workflows](/gh-aw/blog/2026-01-13-meet-the-workflows/)** - The 19-part tour of the workflows * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Credits [Section titled “Credits”](#credits) **Peli’s Agent Factory** is by GitHub Next, Microsoft Research and collaborators, including Peli de Halleux, Don Syme, Mara Kiefer, Edward Aftandilian, Russell Horton, Jiaxiao Zhou. This is part of GitHub Next’s exploration of [Continuous AI](https://githubnext.com/projects/continuous-ai) - making AI-enriched automation as routine as CI/CD. ## Factory Status [Section titled “Factory Status”](#factory-status) [Current Factory Status](/gh-aw/agent-factory-status/) # Meet the Workflows: Issue Triage > A curated tour of triage and summarization workflows in the factory  Welcome back to [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! We’re the GitHub Next team. Over the past months, we’ve built and operated a collection of automated agentic workflows. These aren’t just demos - these are real agents doing actual work in our [`github/gh-aw`](https://github.com/github/gh-aw) repository and others. Think of this as your guided tour through our agent factory. We’re showcasing the workflows that caught our attention. Every workflow links to its source markdown file, so you can peek under the hood and see exactly how it works. ## Starting Simple: Automated Issue Triage [Section titled “Starting Simple: Automated Issue Triage”](#starting-simple-automated-issue-triage) To start the tour, let’s begin with one of the simpler workflows that **handles incoming activity** - issue triage. Issue triage represents a “hello world” of automated agentic workflows: practical, immediately useful, relatively simple, and impactful. It’s used as the starter example in other agentic automation technologies like [Claude Code in GitHub Actions](https://code.claude.com/docs/en/github-actions). When a new issue is opened, the triage agent analyzes its content, does research in the codebase and other issues, responds with a comment, and applies appropriate labels based on predefined categories. This helps maintainers quickly understand the nature of incoming issues without manual review. Let’s take a look at the full **[Issue Triage Agent](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/issue-triage-agent.md?plain=1)**: ```markdown --- timeout-minutes: 5 on: issue: types: [opened, reopened] permissions: issues: read tools: github: toolsets: [issues, labels] safe-outputs: add-labels: allowed: [bug, feature, enhancement, documentation, question, help-wanted, good-first-issue] add-comment: {} --- # Issue Triage Agent List open issues in ${{ github.repository }} that have no labels. For each unlabeled issue, analyze the title and body, then add one of the allowed labels: `bug`, `feature`, `enhancement`, `documentation`, `question`, `help-wanted`, or `good-first-issue`. Skip issues that: - Already have any of these labels - Have been assigned to any user (especially non-bot users) Do research on the issue in the context of the codebase and, after adding the label to an issue, mention the issue author in a comment, explain why the label was added and give a brief summary of how the issue may be addressed. ``` Note how concise this is - it’s like reading a to-do list for the agent. The workflow runs whenever a new issue is opened or reopened. It checks for unlabeled issues, analyzes their content, and applies appropriate labels based on content analysis. It even leaves a friendly comment explaining the label choice. In the frontmatter, we define [permissions](/gh-aw/reference/frontmatter/#permissions-permissions), [tools](/gh-aw/reference/tools/), and [safe outputs](/gh-aw/reference/safe-outputs/). This ensures the agent only has access to what it needs and can’t perform any unsafe actions. The natural language instructions in the body guide the agent’s behavior in a clear, human-readable way. Issue triage workflows in public repositories may need to process issues from all contributors. By default, `min-integrity: approved` restricts agent visibility to owners, members, and collaborators. If you are a maintainer in a public repository and need your triage agent to see and label issues from users without push access, set `min-integrity: none` in your GitHub tools configuration. See [Integrity Filtering](/gh-aw/reference/integrity/) for security considerations and best practices. We’ve deliberately kept this workflow ultra-simple. In practice, in your own repo, **customization** is key. Triage differs in every repository. Tailoring workflows to your specific context will make them more effective. Generic agents are okay, but customized ones are often a better fit. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add this workflow to your own repository and remix it as follows: **Issue Triage Agent:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/issue-triage-agent.md ``` Then edit and remix the workflow specification to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Next Up: Code Quality & Refactoring Workflows [Section titled “Next Up: Code Quality & Refactoring Workflows”](#next-up-code-quality--refactoring-workflows) Now that we’ve explored how triage workflows help us stay on top of incoming activity, let’s turn to something far more radical and powerful: agents that continuously improve code. Continue reading: [Continuous Simplicity →](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-simplicity/) ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows *** *This is part 1 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Advanced Analytics & ML > A curated tour of workflows that use ML to extract insights from agent behavior  *Ooh!* Time to plunge into the *data wonderland* at [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! Where numbers dance and patterns sing! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-organization/), we explored organization and cross-repo workflows that operate at enterprise scale - analyzing dozens of repositories together to find patterns and outliers that single-repo analysis would miss. We learned that perspective matters: what looks normal in isolation might signal drift at scale. Beyond tracking basic metrics (run time, cost, success rate), we wanted deeper insights into *how* our agents actually behave and *how* developers interact with them. What patterns emerge from thousands of agent prompts? What makes some PR conversations more effective than others? How do usage patterns reveal improvement opportunities? This is where we brought out the big guns: machine learning, natural language processing, sentiment analysis, and clustering algorithms. Advanced analytics workflows don’t just count things - they understand them, finding patterns and insights that direct observation would never reveal. ## Advanced Analytics & ML Workflows [Section titled “Advanced Analytics & ML Workflows”](#advanced-analytics--ml-workflows) These agents use sophisticated analysis techniques to extract insights: * **[Copilot Session Insights](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/copilot-session-insights.md?plain=1)** - Analyzes Copilot coding agent usage patterns and metrics - **32 analysis discussions** * **[Copilot PR NLP Analysis](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/copilot-pr-nlp-analysis.md?plain=1)** - Natural language processing on PR conversations * **[Prompt Clustering Analysis](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/prompt-clustering-analysis.md?plain=1)** - Clusters and categorizes agent prompts using ML - **27 analysis discussions** * **[Copilot Agent Analysis](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/copilot-agent-analysis.md?plain=1)** - Deep analysis of agent behavior patterns - **48 daily analysis discussions** Prompt Clustering Analysis has created **27 analysis discussions** using ML to categorize thousands of agent prompts - for example, [#6918](https://github.com/github/gh-aw/discussions/6918) clustering agent prompts to identify patterns and optimization opportunities. It revealed patterns we never noticed (“oh, 40% of our prompts are about error handling”). Copilot PR NLP Analysis applies natural language processing to PR conversations, performing sentiment analysis and identifying linguistic patterns across agent interactions. It found that PRs with questions in the title get faster review. Copilot Session Insights has created **32 analysis discussions** examining Copilot coding agent usage patterns and metrics across the workflow ecosystem. It identifies common patterns and failure modes. Copilot Coding Agent Analysis has created **48 daily analysis discussions** providing deep analysis of agent behavior patterns - for example, [#6913](https://github.com/github/gh-aw/discussions/6913) with the daily Copilot coding agent analysis. What we learned: **meta-analysis is powerful** - using AI to analyze AI systems reveals insights that direct observation misses. These workflows helped us understand not just what our agents do, but *how* they behave and how users interact with them. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix it as follows: **Copilot Session Insights:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/copilot-agent-analysis.md ``` **Copilot PR NLP Analysis:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/copilot-pr-nlp-analysis ``` **Prompt Clustering Analysis:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/prompt-clustering-analysis.md ``` **Copilot Agent Analysis:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/copilot-agent-analysis.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Project Coordination Workflows [Section titled “Next Up: Project Coordination Workflows”](#next-up-project-coordination-workflows) We’ve reached the final stop: coordinating multiple agents toward shared, complex goals across extended timelines. Continue reading: [Project Coordination Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-campaigns/) *** *This is part 18 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Project Coordination > A curated tour of workflows that coordinate multi-agent projects  My dear friends, we’ve arrived at the *grand finale* - the most spectacular room of all in [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! We’ve journeyed through 18 categories of workflows - from triage bots to code quality improvers, from security guards to creative poets, culminating in [advanced analytics](/gh-aw/blog/2026-01-13-meet-the-workflows-advanced-analytics/) that use machine learning to understand agent behavior patterns. Each workflow handles its individual task admirably. But here’s the ultimate challenge: how do you coordinate *multiple* agents working toward a shared goal? How do you break down a large initiative like “migrate all workflows to a new engine” into trackable sub-tasks that different agents can tackle? How do you monitor progress, alert on delays, and ensure the whole is greater than the sum of its parts? This final post explores planning, task-decomposition and project coordination workflows - the orchestration layer that proves AI agents can handle not just individual tasks, but entire structured projects requiring careful coordination and progress tracking. ## Planning & Project Coordination Workflows [Section titled “Planning & Project Coordination Workflows”](#planning--project-coordination-workflows) These agents coordinate multi-agent plans and projects: * **[Plan Command](https://github.com/github/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/plan.md?plain=1)** - Breaks down issues into actionable sub-tasks via `/plan` command - **514 merged PRs out of 761 proposed (67% merge rate)** * **[Discussion Task Miner](https://github.com/github/gh-aw/tree/2c1f68a721ae7b3b67d0c2d93decf1fa5bcf7ee3/.github/workflows/discussion-task-miner.md?plain=1)** - Extracts actionable tasks from discussion threads - **60 merged PRs out of 105 proposed (57% merge rate)** Plan Command has contributed **514 merged PRs out of 761 proposed (67% merge rate)**, providing on-demand task decomposition that breaks complex issues into actionable sub-tasks. This is the **highest-volume workflow by attribution** in the entire factory. Developers can comment `/plan` on any issue to get an AI-generated breakdown into actionable sub-issues that agents can work on. A verified example causal chain: [Discussion #7631](https://github.com/github/gh-aw/discussions/7631) → [Issue #8058](https://github.com/github/gh-aw/issues/8058) → [PR #8110](https://github.com/github/gh-aw/pull/8110). Discussion Task Miner has contributed **60 merged PRs out of 105 proposed (57% merge rate)**, continuously scanning discussions to extract actionable tasks that might otherwise be lost. The workflow demonstrates perfect causal chain attribution: when it creates an issue from a discussion, and Copilot Coding Assistant later fixes that issue, the resulting PR is correctly attributed to Discussion Task Miner. A verified example: [Discussion #13934](https://github.com/github/gh-aw/discussions/13934) → [Issue #14084](https://github.com/github/gh-aw/issues/14084) → [PR #14129](https://github.com/github/gh-aw/pull/14129). Recent merged examples include [fixing firewall SSL-bump field extraction](https://github.com/github/gh-aw/pull/13920) and [adding security rationale to permissions documentation](https://github.com/github/gh-aw/pull/13918). We learned that individual agents are great at focused tasks, but orchestrating multiple agents toward a shared goal requires careful architecture. Project coordination isn’t just about breaking down work - it’s about discovering work (Task Miner), planning work (Plan Command), and tracking work (Workflow Health Manager). These workflows implement patterns like epic issues, progress tracking, and deadline management. They prove that AI agents can handle not just individual tasks, but entire projects when given proper coordination infrastructure. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Plan Command:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/plan.md ``` **Discussion Task Miner:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/discussion-task-miner.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows *** ## What We’ve Learned [Section titled “What We’ve Learned”](#what-weve-learned) Throughout this 19-part journey, we’ve explored workflows spanning from simple triage bots to sophisticated multi-phase improvers, from security guards to creative poets, from individual task automation to organization-wide orchestration. The key insight? **AI agents are most powerful when they’re specialized, well-coordinated, and designed for their specific context.** No single agent does everything - instead, we have an ecosystem where each agent excels at its particular job, and they work together through careful orchestration. We’ve learned that observability is essential, that incremental progress beats heroic efforts, that security needs careful boundaries, and that even “fun” workflows can drive meaningful engagement. We’ve discovered that AI agents can maintain documentation, manage campaigns, analyze their own behavior, and continuously improve codebases - when given the right architecture and guardrails. As you build your own agentic workflows, remember: start small, measure everything, iterate based on real usage, and don’t be afraid to experiment. The workflows we’ve shown you evolved through experimentation and real-world use. Yours will too. *This is part 19 (final) of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Continuous Improvement > Agents that take a holistic view of repository health  Welcome back to [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! In our [previous posts](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-simplicity/), we’ve explored autonomous cleanup agents. Now we complete the picture with agents that analyze dependencies, type safety, and overall repository quality. ## Continuous Improvement Workflows [Section titled “Continuous Improvement Workflows”](#continuous-improvement-workflows) * **[Go Module Usage Expert (aka Go Fan)](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/go-fan.md?plain=1)** - Daily Go module usage reviewer * **[Typist](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/typist.md?plain=1)** - Analyzes type usage patterns for improved safety * **[Functional Pragmatist](https://github.com/github/gh-aw/blob/main/.github/workflows/functional-programming-enhancer.md?plain=1)** - Applies functional techniques pragmatically * **[Repository Quality Improver](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/repository-quality-improver.md?plain=1)** - Holistic code quality analysis ### Go Module Usage Expert: The Dependency Enthusiast [Section titled “Go Module Usage Expert: The Dependency Enthusiast ”](#go-module-usage-expert-the-dependency-enthusiast-) The **Go Module Usage Expert** is perhaps the most uniquely characterized workflow in the factory - an “enthusiastic Go module expert” who performs daily deep-dive reviews of the project’s Go dependencies. This isn’t just dependency scanning - it’s thoughtful analysis of **how well we’re using the tools we’ve chosen**. Most dependency tools focus on vulnerabilities or outdated versions. Go Module Usage Expert asks deeper and more positive questions: Are we using this module’s best features? Have recent updates introduced better patterns we should adopt? Could we use a more appropriate module for this use case? Are we following the module’s recommended practices? Go Module Usage Expert uses an intelligent selection algorithm. It extracts direct dependencies from `go.mod`, fetches GitHub metadata for each dependency including last update time, sorts by recency to prioritize recently updated modules, uses round-robin selection to cycle through modules ensuring comprehensive coverage, and maintains persistent memory through cache-memory to track which modules were recently reviewed. This ensures recently updated modules get reviewed first since new features might be relevant, all modules eventually get reviewed so nothing is forgotten, and reviews don’t repeat unnecessarily thanks to cache tracking. For each module, Go Module Usage Expert researches the repository (releases, docs, best practices), analyzes actual usage patterns using Serena, and generates actionable recommendations. It saves summaries under `scratchpad/mods/` and opens GitHub Discussions. The output of Go Module Usage Expert is a discussion, which is then often “task mined” for actionable tasks using the [ResearchPlanAssignOps](https://github.github.com/gh-aw/patterns/research-plan-assign-ops/) design pattern. Let’s take a look at an example of how this works: 1. Go Module Usage Expert created the [Go Module Review: actionlint](https://github.com/github/gh-aw/discussions/7472) discussion after noticing the `actionlint` module was updated. 2. Peli [requested the Plan agent](https://github.com/github/gh-aw/discussions/7472#discussioncomment-15342254) mine for actionable tasks. 3. This created [a parent issue](https://github.com/github/gh-aw/issues/7648) and 5 sub-tasks. 4. The subtasks were then solved by further workflow runs. An example PR is [Implement parallel multi-file actionlint execution](https://github.com/github/gh-aw/issues/7649). Through this multi-agent causal chain pattern, Go Module Usage Expert has generated **58 merged PRs out of 74 proposed (78% merge rate)** across 67 module reviews. Notable chains include: spinner improvements (4 PRs from [briandowns/spinner review](https://github.com/github/gh-aw/discussions/5094)), MCP SDK v1.2.0 upgrade (5 PRs from [go-sdk review](https://github.com/github/gh-aw/discussions/7710)), and terminal styling overhaul (3 PRs from [lipgloss review](https://github.com/github/gh-aw/discussions/5158)). ### Typist: The Type Safety Advocate [Section titled “Typist: The Type Safety Advocate”](#typist-the-type-safety-advocate) The **Typist** analyzes Go type usage patterns with a singular focus: improving type safety. It hunts for untyped code that should be strongly typed, and identifies duplicated type definitions that create confusion. Typist looks for untyped usages: `interface{}` or `any` where specific types would be better, untyped constants that should have explicit types, and type assertions that could be eliminated with better design. It also hunts for duplicated type definitions - the same types defined in multiple packages, similar types with different names, and type aliases that could be unified. Using grep patterns and Serena’s semantic analysis, it discovers type definitions, identifies semantic duplicates, analyzes untyped usage patterns, and generates refactoring recommendations. Typist also uses the [ResearchPlanAssignOps](https://github.github.com/gh-aw/patterns/research-plan-assign-ops/) pattern. This means the job of Typist is not to fix code, but to analyze code and recommend possible improvements. Let’s take a look at an example of this in practice: * Typist created the [Typist - Go Type Consistency Analysis Report](https://github.com/github/gh-aw/discussions/4082). This used grep and other tools to perform a comprehensive analysis examining 208 non-test Go files. * The report found 477 instances of `map[string]any` usage, 36 untyped constants and 30+ uses `any` in function signatures. * [Peli requested `/plan` on that issue](https://github.com/github/gh-aw/discussions/4082#discussioncomment-14983559), causing the Plan agent to do further research and create 5 issues for work to be done such as [Create unified ToolsConfig struct in tools\_types.go](https://github.com/github/gh-aw/issues/4155). * 4/5 of these issues were then solved by Copilot. For example [Add unified ToolsConfig struct to replace map\[string\]any pattern](https://github.com/github/gh-aw/pull/4158). Through this multi-agent causal chain, Typist has produced **19 merged PRs out of 25 proposed (76% merge rate)** from 57 discussions → 22 issues → 25 PRs. The blog example (Discussion #4082 → Issue #4155 → PR #4158) is a verified causal chain. The static v. dynamic typing debate has raged for decades. Today’s hybrid languages like Go, C#, TypeScript and F# support both strong and dynamic typing. Continuous typing improvement offers **a new and refreshing perspective on this old debate**: rather than enforcing strict typing upfront, we can develop quickly with flexibility, then let autonomous agents like Typist trail behind, strengthening type safety over time. This allows us to get the best of both worlds: rapid development without getting bogged down in type design, while still achieving strong typing and safety as the codebase matures. ### Functional Pragmatist: The Pragmatic Purist [Section titled “Functional Pragmatist: The Pragmatic Purist ”](#functional-pragmatist-the-pragmatic-purist-) **Functional Pragmatist** applies moderate functional programming techniques to improve code clarity and safety, balancing pragmatism with functional principles. The workflow focuses on seven patterns: immutability, functional initialization, transformative operations (map/filter/reduce), functional options pattern, avoiding shared mutable state, pure functions, and reusable logic wrappers. It searches for opportunities (mutable variables, imperative loops, initialization anti-patterns, global state), scores by safety/clarity/testability improvements, uses Serena for deep analysis, and implements changes like converting to composite literals, using functional options, eliminating globals, extracting pure functions, and creating reusable wrappers (Retry, WithTiming, Memoize). The workflow is pragmatic: Go’s simple style is respected, for-loops stay when clearer, and abstraction is added only where it genuinely improves code. It runs Tuesday and Thursday mornings, systematically improving patterns over time. An example PR from our own use of this workflow is [Apply functional programming and immutability improvements](https://github.com/github/gh-aw/pull/12921). Functional Pragmatist (originally named “Functional Enhancer”) is a recent addition - so far it has created **2 PRs (both merged, 100% merge rate)**, demonstrating that its pragmatic approach to functional patterns is well-received. ### Repository Quality Improver: The Holistic Analyst [Section titled “Repository Quality Improver: The Holistic Analyst”](#repository-quality-improver-the-holistic-analyst) **Repository Quality Improver** takes the widest view, selecting a different *focus area* each day to analyze the repository from that perspective. It uses cache memory to ensure diverse coverage: 60% custom areas (repository-specific concerns), 30% standard categories (code quality, documentation, testing, security, performance), and 10% revisits for consistency. Standard categories cover fundamentals. Custom areas are repository-specific: error message consistency, CLI flag naming conventions, workflow YAML generation patterns, console output formatting, configuration validation. The workflow loads recent history, selects the next area, spends 20 minutes on deep analysis, generates discussions with recommendations, and saves state. It looks for cross-cutting concerns that don’t fit neatly into other categories but impact overall quality. Example reports from our own use of this workflow are: * [Repository Quality Improvement - CI/CD Optimization](https://github.com/github/gh-aw/discussions/6863) * [Repository Quality Improvement Report - Performance](https://github.com/github/gh-aw/discussions/13280). Through its multi-agent causal chain (59 discussions → 30 issues → 40 PRs), Repository Quality Improver has produced **25 merged PRs out of 40 proposed (62% merge rate)**, taking a holistic view of quality from multiple angles. ## The Power of Continuous Improvement [Section titled “The Power of Continuous Improvement”](#the-power-of-continuous-improvement) These workflows complete the autonomous improvement picture: Go Module Usage Expert keeps dependencies fresh, Typist strengthens type safety, Functional Pragmatist applies functional techniques, and Repository Quality Improver maintains coherence. Combined with earlier workflows, we have agents improving code at every level: line-level output (Terminal Stylist), function-level complexity (Code Simplifier), file-level organization (Semantic Function Refactor), pattern-level consistency (Go Pattern Detector), functional clarity (Functional Pragmatist), type safety (Typist), module dependencies (Go Module Usage Expert), and repository coherence (Repository Quality Improver). This is the future of code quality: not periodic cleanup sprints, but continuous autonomous improvement across every dimension simultaneously. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Go Module Usage Expert:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/go-fan.md ``` **Typist:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/typist.md ``` **Functional Pragmatist:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/main/.github/workflows/functional-programming-enhancer.md ``` **Repository Quality Improver:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/repository-quality-improver.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Next Up: Continuous Documentation [Section titled “Next Up: Continuous Documentation”](#next-up-continuous-documentation) Beyond code quality, we need to keep documentation accurate and up-to-date as code evolves. How do we maintain docs that stay current? Continue reading: [Continuous Documentation Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-documentation/) ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows *** *This is part 5 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Continuous Refactoring > Agents that identify structural improvements and systematically refactor code  Welcome back to [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-simplicity/), we met automated agents that detect complexity and propose simpler solutions. These work tirelessly in the background, cleaning things up. Now let’s explore similar agents that take a deeper structural view, extending the automation to *structural refactoring*. ## Continuous Refactoring [Section titled “Continuous Refactoring”](#continuous-refactoring) Our next two agents continuously analyze code structure, suggesting systematic improvements: * **[Semantic Function Refactor](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/semantic-function-refactor.md?plain=1)** - Spots refactoring opportunities we might have missed * **[Large File Simplifier](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-file-diet.md?plain=1)** - Monitors file sizes and proposes splitting oversized files The **Semantic Function Refactor** workflow combines agentic AI with code analysis tools to analyze and address the structure of the entire codebase. It analyzes all Go source files in the `pkg/` directory to identify functions that might be in the wrong place. As codebases evolve, functions sometimes end up in files where they don’t quite belong. Humans struggle to notice these organizational issues because we work on one file at a time and focus on making code work rather than on where it lives. The workflow performs comprehensive discovery by 1. algorithmically collecting all function names from non-test Go files, then 2. agentically grouping functions semantically by name and purpose. It then identifies functions that don’t fit their current file’s theme as outliers, uses Serena-powered semantic code analysis to detect potential duplicates, and creates issues recommending consolidated refactoring. These issues can then be reviewed and addressed by coding agents. The workflow follows a “one file per feature” principle: files should be named after their primary purpose, and functions within each file should align with that purpose. It closes existing open issues with the `[refactor]` prefix before creating new ones. This prevents issue accumulation and ensures recommendations stay current. In our extended use of Semantic Function Refactoring, the workflow has driven **112 merged PRs out of 142 proposed (79% merge rate)** through causal chains - creating 99 refactoring issues that downstream agents turn into code changes. For example, [issue #12291](https://github.com/github/gh-aw/issues/12291) analyzing code organization opportunities led to [PR #12363 splitting permissions.go into focused modules](https://github.com/github/gh-aw/pull/12363) (928→133 lines). An example PR from our own use of this workflow is [Move misplaced extraction functions to frontmatter\_extraction.go](https://github.com/github/gh-aw/pull/7043). ### Large File Simplifier: The Size Monitor [Section titled “Large File Simplifier: The Size Monitor”](#large-file-simplifier-the-size-monitor) Large files are a common code smell - they often indicate unclear boundaries, mixed responsibilities, or accumulated complexity. The **Large File Simplifier** workflow monitors file sizes daily and creates actionable issues when files grow too large. The workflow runs on weekdays, analyzing all Go source files in the `pkg/` directory. It identifies the largest file, checks if it exceeds healthy size thresholds, and creates a detailed issue proposing how to split it into smaller, more focused files. What makes this workflow effective is its focus and prioritization. Instead of overwhelming developers with issues about every large file, it creates at most one issue, targeting the largest offender. The workflow also skips if an open `[file-diet]` issue already exists, preventing duplicate work. In our extended use, Large File Simplifier (also known as “Daily File Diet”) has driven **26 merged PRs out of 33 proposed (79% merge rate)** through causal chains - creating 37 file-diet issues targeting the largest files, which downstream agents turn into modular code changes. For example, [issue #12535](https://github.com/github/gh-aw/issues/12535) targeting add\_interactive.go led to [PR #12545 refactoring it into 6 domain-focused modules](https://github.com/github/gh-aw/pull/12545). The workflow uses Serena for semantic code analysis to understand function relationships and propose logical boundaries for splitting. It both counts lines and analyzes the code structure to suggest meaningful module boundaries that make sense. ## The Power of Continuous Refactoring [Section titled “The Power of Continuous Refactoring”](#the-power-of-continuous-refactoring) These workflows demonstrate how AI agents can continuously maintain institutional knowledge about code organization. The benefits compound over time: better organization makes code easier to find, consistent patterns reduce cognitive load, reduced duplication improves maintainability, and clean structure attracts further cleanliness. They’re particularly valuable in AI-assisted development, where code gets written quickly and organizational concerns can take a backseat to functionality. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Semantic Function Refactor:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/semantic-function-refactor.md ``` **Large File Simplifier:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-file-diet.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Next Up: Continuous Style [Section titled “Next Up: Continuous Style”](#next-up-continuous-style) Beyond structure and organization, there’s another dimension of code quality: presentation and style. How do we maintain beautiful, consistent console output and formatting? Continue reading: [Meet the Workflows: Continuous Style →](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-style/) ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows *** *This is part 3 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Continuous Simplicity > Agents that detect complexity and propose simpler solutions  Ah, what marvelous timing! Come, come, let me show you the *next wonders* in [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows/), we explored how a simple triage workflow helps us stay on top of incoming activity - automatically labeling issues and reducing cognitive load. Now let’s meet the agents that work quietly in the background to keep code simple and clean. These workflows embody a powerful principle: **code quality is not a destination, it’s a continuous practice**. While developers race ahead implementing features and fixing bugs, autonomous cleanup agents trail behind, constantly sweeping, polishing, and simplifying. Let’s meet the agents that hunt for complexity. ## Continuous Simplicity [Section titled “Continuous Simplicity”](#continuous-simplicity) The next two agents represent different aspects of code simplicity: detecting *overcomplicated code* and *duplicated logic*: * **[Automatic Code Simplifier](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/code-simplifier.md?plain=1)** - Analyzes recently modified code and creates PRs with simplifications * **[Duplicate Code Detector](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/duplicate-code-detector.md?plain=1)** - Uses Serena’s semantic analysis to identify duplicate code patterns The **Automatic Code Simplifier** runs daily, analyzing recently modified code for opportunities to simplify without changing functionality. It looks at what changed in the last few commits and asks: “Could this be clearer? Could it be shorter? Could it be more idiomatic?” This workflow is particularly valuable after rapid development sessions. When you’re racing to implement a feature or fix a bug, code often becomes more complex than necessary. Variables get temporary names, logic becomes nested, error handling gets verbose. The workflow tirelessly cleans up after these development sessions, creating PRs that preserve functionality while improving clarity, consistency, and maintainability. The kinds of simplifications it proposes range from extracting repeated logic into helper functions to converting nested if-statements to early returns. It spots opportunities to simplify boolean expressions, use standard library functions instead of custom implementations, and consolidate similar error handling patterns. Code Simplifier is a recent addition - so far it has created **6 PRs (5 merged, 83% merge rate)**, such as [extracting an action mode helper to reduce code duplication](https://github.com/github/gh-aw/pull/13982) and [simplifying validation config code for clarity](https://github.com/github/gh-aw/pull/13118). The **Duplicate Code Detector** uses traditional, road-tested semantic code analysis in conjunction with agentic reasoning to find duplicate patterns. It understands code *meaning* rather than just textual similarity, catching patterns where: * The same logic appears with different variable names * Similar functions exist across different files * Repeated patterns could be extracted into utilities * Structure is duplicated even if implementation differs What makes this workflow special is its use of semantic analysis through [Serena](https://oraios.github.io/serena/) - a powerful coding agent toolkit capable of turning an LLM into a fully-featured agent that works directly on your codebase. When we use Serena, we understand code at the compiler-resolved level, not just syntax. The workflow focuses on recent changes in the latest commits, intelligently filtering out test files, workflows, and non-code files. It creates issues only for significant duplication: patterns spanning more than 10 lines or appearing in 3 or more locations. It performs a multi-phase analysis. It starts by setting up Serena’s semantic environment for the repository, then finds changed `.go` and `.cjs` files while excluding tests and workflows. Using `get_symbols_overview` and `find_symbol`, it understands structure, identifies similar function signatures and logic blocks, and compares symbol overviews across files for deeper similarities. It creates issues with the `[duplicate-code]` prefix and limits itself to 3 issues per run, preventing overwhelm. Issues include specific file references, code snippets, and refactoring suggestions. In our extended use of Duplicate Code Detector, the agent has raised **76 merged PRs out of 96 proposed (79% merge rate)**, demonstrating sustained practical value of semantic code analysis. Recent examples include [refactoring expired-entity cleanup scripts to share expiration processing](https://github.com/github/gh-aw/pull/13420) and [refactoring safe-output update handlers to eliminate duplicate control flow](https://github.com/github/gh-aw/pull/8791). ## Continuous AI for Simplicity - A New Paradigm [Section titled “Continuous AI for Simplicity - A New Paradigm”](#continuous-ai-for-simplicity---a-new-paradigm) Together, these workflows point towards **an emerging shift in how we maintain code quality**. Instead of periodic “cleanup sprints” or waiting for code reviews to catch complexity, we have agents that clean up after us and continuously monitor and propose improvements. This is especially valuable in AI-assisted development. When developers use AI to write code faster, these cleanup agents ensure speed doesn’t sacrifice simplicity. They understand the same patterns that humans recognize but apply them consistently across the entire codebase, every day. The workflows never take a day off, never get tired, and never let technical debt accumulate. They embody the principle that *good enough* can always become *better*, and that incremental improvements compound over time. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Automatic Code Simplifier:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/code-simplifier.md ``` **Duplicate Code Detector:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/duplicate-code-detector.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Next Up: Continuous Refactoring [Section titled “Next Up: Continuous Refactoring”](#next-up-continuous-refactoring) Simplification is just the beginning. Beyond removing complexity, we can use agents to continuously improve code in many more ways. Our next posts explore this topic. Continue reading: [Continuous Refactoring →](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-refactoring/) ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows *** *This is part 2 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Continuous Style > The agent that makes console output beautiful and consistent  Welcome back to [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! In our [previous posts](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-simplicity/), we’ve explored how autonomous cleanup agents work continuously in the background, simplifying code and improving structure. Today’s post is dedicated to one agent, and the larger admirable concept it represents: continuously making things *beautiful*. ## A Continuous Style Workflow [Section titled “A Continuous Style Workflow”](#a-continuous-style-workflow) Today’s post is dedicated to one agent, and the larger concept it represents: the **[Terminal Stylist](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/terminal-stylist.md?plain=1)** workflow. This agent’s purpose is to **make things look better**, by reviewing and enhancing the style of command-line interface (CLI) output. Command-line interfaces are a primary interaction point for developer tools. When output is inconsistent or noisy, it still “works,” but it adds friction. When it’s well-styled, information becomes scannable, color highlights what matters, layouts remain readable across light and dark themes, and the overall experience feels professional. Under the hood, the workflow looks for non-test Go files with console-related code and patterns such as `fmt.Print*`, `console.*`, and Lipgloss usage. It then checks for consistency in formatting helpers (especially for errors), sensible TTY-aware rendering, and accessible color choices. When it finds rough edges, it proposes concrete improvements, such as replacing plain output like `fmt.Println("Error: compilation failed")` with `fmt.Fprintln(os.Stderr, console.FormatErrorMessage("Compilation failed"))`, or swapping ad-hoc ANSI coloring for adaptive Lipgloss styles. Rather than opening issues or PRs, the Terminal Stylist posts GitHub Discussions in the “General” category. Styling changes are often subjective, and discussions make it easier to converge on the right balance between simplicity and polish. Terminal Stylist demonstrates multi-agent collaboration at its best. The workflow created **31 daily analysis reports** as discussions, which were then mined by Discussion Task Miner and Plan Command into **25 actionable issues**. Those issues spawned **16 merged PRs (80% merge rate)** improving console output across the codebase - from [Charmbracelet best practices adoption](https://github.com/github/gh-aw/pull/9928) to [progress bars](https://github.com/github/gh-aw/pull/8731) to [stderr routing fixes](https://github.com/github/gh-aw/pull/12302). Terminal Stylist never creates PRs directly; instead, it identifies opportunities that other agents implement, showing how workflows can collaborate through GitHub’s discussion → issue → PR pipeline. The Terminal Stylist is proof that autonomous cleanup agents can have surprisingly specific taste. It focuses on terminal UI craft, using the Charmbracelet ecosystem (especially Lipgloss and Huh) to keep the CLI not just correct, but pleasant to use. ## The Art of Continuous Style [Section titled “The Art of Continuous Style”](#the-art-of-continuous-style) The Terminal Stylist shows that autonomous improvement isn’t limited to structure and correctness; it also covers user experience. By continuously reviewing output patterns, it helps new features match the project’s visual language, keeps styling aligned with evolving libraries, and nudges the CLI toward accessibility and clarity. This is especially useful in AI-assisted development, where quick suggestions tend to default to `fmt.Println`. The Terminal Stylist cleans up after the AI, bringing that output back in line with the project’s conventions. Continuous Style is a new frontier in code quality. It recognizes that how code *looks* matters just as much as how it *works*. By automating style reviews, we ensure that every interaction with our tools feels polished and professional. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add this workflow to your own repository and remix it as follows: **Terminal Stylist:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/terminal-stylist.md ``` Then edit and remix the workflow specification to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Next Up: Continuous Improvement [Section titled “Next Up: Continuous Improvement”](#next-up-continuous-improvement) Beyond simplicity, structure, and style, there’s a final dimension: holistic quality improvement. How do we analyze dependencies, type safety, and overall repository health? Continue reading: [Continuous Improvement Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-improvement/) ## Learn More [Section titled “Learn More”](#learn-more) Learn more about **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)**, try the **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** guide, and explore **[Charmbracelet](https://charm.sh/)**, the terminal UI ecosystem referenced by the Terminal Stylist. *** *This is part 4 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Teamwork & Culture > A curated tour of creative and culture workflows that bring joy to work  *Oh, my dear friends!* Let’s explore the *playful workshop* - the most fun corner of [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-security-compliance/), we explored security and compliance workflows - the essential guardrails that manage vulnerability campaigns, validate network security, and prevent credential exposure. These workflows let us sleep soundly knowing our agents operate within safe boundaries. But here’s the thing: work doesn’t have to be all business. While we’ve built serious, production-critical workflows for quality, releases, and security, we also discovered something unexpected - AI agents can bring joy, build team culture, and create moments of delight. Not every workflow needs to solve a critical problem; some can simply make your day better. Let’s explore the playful side of our agent factory, where we learned that personality and fun drive engagement just as powerfully as utility. ## Teamwork & Culture Workflows [Section titled “Teamwork & Culture Workflows”](#teamwork--culture-workflows) These agents facilitate team communication and remind us that work can be fun: * **[Daily Team Status](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-team-status.md?plain=1)** - Shares team mood and status updates - **22 issues**, **17 discussions** (plus 2 causal chain PRs!) * **[Daily News](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-news.md?plain=1)** - Curates relevant news for the team - **45 news digest discussions** * **[Poem Bot](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/poem-bot.md?plain=1)** - Responds to `/poem-bot` commands with creative verses (yes, really) * **[Weekly Issue Summary](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/weekly-issue-summary.md?plain=1)** - Creates digestible summaries complete with charts and trends - **5 weekly analysis discussions** * **[Daily Repo Chronicle](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-repo-chronicle.md?plain=1)** - Narrates the day’s activity like a storyteller - **6 chronicle discussions** The Poem Bot started as a whimsy in our Copilot for PRs project in 2022. Someone said “wouldn’t it be funny if we had an agent that writes poems about our code?” and then we built it. Poem Bot responds to `/poem-bot` commands with creative verses about code, adding a touch of whimsy to the development workflow. We learned that AI agents don’t have to be all business - they can build culture and create moments of joy. Daily News has created **45 news digest discussions** curating relevant developments for the team - for example, [#6932](https://github.com/github/gh-aw/discussions/6932) with the daily status roundup. It shares links, adds commentary and connects them to our work. Daily Team Status has created **22 issues** and **17 discussions** sharing daily team status updates - for example, [#6930](https://github.com/github/gh-aw/discussions/6930) with the daily team status report. Two of its issues even led to merged PRs by downstream agents, showing that even “soft” workflows can drive concrete improvements. Weekly Issue Summary has created **5 weekly analysis discussions** with digestible summaries, charts, and trends - for example, [#5844](https://github.com/github/gh-aw/discussions/5844) analyzing the week of December 1-8, 2025. Daily Repo Chronicle has created **6 chronicle discussions** narrating the repository’s activity like a storyteller - for example, [#6750](https://github.com/github/gh-aw/discussions/6750) chronicling a development surge with 42 active PRs. A theme here is the **reduction of cognitive load**. Having agents summarize and narrate daily activity means we don’t have to mentally parse long lists of issues or PRs. Instead, we get digestible stories that highlight what’s important. This frees up mental bandwidth for actual work. Another theme is that **tone** can help make things more enjoyable. The Daily Repo Chronicle started writing summaries in a narrative, almost journalistic style. The outputs from AI agents don’t have to be robotic - they can have personality while still being informative. These communication workflows help build team cohesion and remind us that work can be delightful. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Daily Team Status:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-team-status.md ``` **Daily News:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-news.md ``` **Poem Bot:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/poem-bot.md ``` **Weekly Issue Summary:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/weekly-issue-summary.md ``` **Daily Repo Chronicle:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-repo-chronicle.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Summon an Agent on Demand [Section titled “Next Up: Summon an Agent on Demand”](#next-up-summon-an-agent-on-demand) Scheduled workflows are great, but sometimes you need help *right now*. Enter ChatOps and interactive workflows. Continue reading: [Interactive & ChatOps Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-interactive-chatops/) *** *This is part 12 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Continuous Documentation > A curated tour of workflows that maintain high-quality documentation  Step right up, step right up, and enter the *documentation chamber* of [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! Pure imagination meets technical accuracy in this most delightful corner of our establishment! In our [previous posts](/gh-aw/blog/2026-01-13-meet-the-workflows-continuous-simplicity/), we explored autonomous cleanup agents - workflows that continuously improve code quality by simplifying complexity, refactoring structure, polishing style, and maintaining overall repository health. These agents never take a day off, quietly working to make our codebase better. Now let’s address one of software development’s eternal challenges: keeping documentation accurate and up-to-date. Code evolves rapidly; docs… not so much. Terminology drifts, API examples become outdated, slide decks grow stale, and blog posts reference deprecated features. The question isn’t “can AI agents write good documentation?” but rather “can they maintain it as code changes?” Documentation and content workflows challenge conventional wisdom about AI-generated technical content. Spoiler: the answer involves human review, but it’s way better than the alternative (no docs at all). ## Continuous Documentation Workflows [Section titled “Continuous Documentation Workflows”](#continuous-documentation-workflows) These agents maintain high-quality documentation and content: * **[Daily Documentation Updater](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-doc-updater.md?plain=1)** - Reviews and updates documentation to ensure accuracy and completeness - **57 merged PRs out of 59 proposed (96% merge rate)** * **[Glossary Maintainer](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/glossary-maintainer.md?plain=1)** - Keeps glossary synchronized with codebase - **10 merged PRs out of 10 proposed (100% merge rate)** * **[Documentation Unbloat](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/unbloat-docs.md?plain=1)** - Reviews and simplifies documentation by reducing verbosity - **88 merged PRs out of 103 proposed (85% merge rate)** * **[Documentation Noob Tester](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/docs-noob-tester.md?plain=1)** - Tests documentation as a new user would, identifying confusing steps - **9 merged PRs (43% merge rate)** via causal chain * **[Slide Deck Maintainer](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/slide-deck-maintainer.md?plain=1)** - Maintains presentation slide decks - **2 merged PRs out of 5 proposed (40% merge rate)** * **[Multi-device Docs Tester](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-multi-device-docs-tester.md?plain=1)** - Tests documentation site across mobile, tablet, and desktop devices - **2 merged PRs out of 2 proposed (100% merge rate)** * **[Blog Auditor](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/blog-auditor.md?plain=1)** - Verifies blog posts are accessible and contain expected content - **6 audits completed** (5 passed, 1 flagged issues) Documentation is where we challenged conventional wisdom. Can AI agents write *good* documentation? The **Technical Doc Writer** generates API docs from code, but more importantly, it *maintains* them - updating docs when code changes. The Glossary Maintainer caught terminology drift (“we’re using three different terms for the same concept”). The **Slide Deck Maintainer** keeps our presentation materials current without manual updates. The **Multi-device Docs Tester** uses Playwright to verify our documentation site works across phones, tablets, and desktops - testing responsive layouts, accessibility, and interactive elements. It catches visual regressions and layout issues that only appear on specific screen sizes. The **Blog Auditor** ensures our blog posts stay accurate as the codebase evolves - it flags outdated code examples and broken links. Blog Auditor is a **validation-only workflow** that creates audit reports rather than code changes. It has run **6 audits** (5 passed, [1 flagged out-of-date content](https://github.com/github/gh-aw/issues/2162)), confirming blog accuracy. Documentation Noob Tester deserves special mention for its exploratory nature. It has produced **9 merged PRs out of 21 proposed (43% merge rate)** through a causal chain: 62 discussions analyzed → 21 issues created → 21 PRs. The lower merge rate reflects this workflow’s exploratory nature - it identifies many potential improvements, some of which are too ambitious for immediate implementation. For example, [Discussion #8477](https://github.com/github/gh-aw/discussions/8477) led to [Issue #8486](https://github.com/github/gh-aw/issues/8486) which spawned PRs [#8716](https://github.com/github/gh-aw/pull/8716) and [#8717](https://github.com/github/gh-aw/pull/8717), both merged. AI-generated docs need human/agent review, but they’re dramatically better than *no* docs (which is often the alternative). Validation can be automated to a large extent, freeing writers to focus on content shaping, topic, clarity, tone, and accuracy. In this collection of agents, we took a heterogeneous approach - some workflows generate content, others maintain it, and still others validate it. Other approaches are possible - all tasks can be rolled into a single agent. We found that it’s easier to explore the space by using multiple agents, to separate concerns, and that encouraged us to use agents for other communication outputs such as blogs and slides. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Daily Documentation Updater:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-doc-updater.md ``` **Glossary Maintainer:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/glossary-maintainer.md ``` **Documentation Unbloat:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/unbloat-docs.md ``` **Documentation Noob Tester:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/docs-noob-tester.md ``` **Slide Deck Maintainer:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/slide-deck-maintainer.md ``` **Multi-device Docs Tester:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-multi-device-docs-tester.md ``` **Blog Auditor:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/blog-auditor.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Issue & PR Management Workflows [Section titled “Next Up: Issue & PR Management Workflows”](#next-up-issue--pr-management-workflows) Beyond writing code and docs, we need to manage the flow of issues and pull requests. How do we keep collaboration smooth and efficient? Continue reading: [Issue & PR Management Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-issue-management/) *** *This is part 6 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Interactive & ChatOps > A curated tour of interactive workflows that respond to commands  *Onwards, onwards!* Let’s keep exploring the wonders of [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! To the *command center* where instant magic happens! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-creative-culture/), we explored creative and culture workflows - agents that bring joy, build team culture, and create moments of delight. We discovered that AI agents don’t have to be all business; they can have personality while making work more enjoyable. But sometimes you need help *right now*, at the exact moment you’re stuck on a problem. You don’t want to wait for a scheduled run - you want to summon an expert agent with a command. That’s where interactive workflows and ChatOps come in. These agents respond to slash commands and GitHub reactions, providing on-demand assistance with full context of the current situation. We learned that the right agent at the right moment with the right information is a valuable addition to an agent portfolio. ## Interactive & ChatOps Workflows [Section titled “Interactive & ChatOps Workflows”](#interactive--chatops-workflows) These agents respond to commands, providing on-demand assistance whenever you need it: * **[Q](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/q.md?plain=1)** - Workflow optimizer that investigates performance and creates PRs - **69 merged PRs out of 88 proposed (78% merge rate)** * **[Grumpy Reviewer](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/grumpy-reviewer.md?plain=1)** - Performs critical code reviews with personality - creates issues for downstream agents * **[Workflow Generator](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/workflow-generator.md?plain=1)** - Creates new workflows from issue requests - scaffolds workflow files Interactive workflows changed how we think about agent invocation. Instead of everything running on a schedule, these respond to slash commands and reactions - `/q` summons the workflow optimizer, a reaction triggers analysis. Q (yes, named after the James Bond quartermaster) became our go-to troubleshooter - it has contributed **69 merged PRs out of 88 proposed (78% merge rate)**, responding to commands and investigating workflow issues on demand. Recent examples include [fixing the daily-fact workflow action-tag](https://github.com/github/gh-aw/pull/14127) and [configuring PR triage reports with 1-day expiration](https://github.com/github/gh-aw/pull/13903). The Grumpy Reviewer performs opinionated code reviews, creating issues that flag security risks and code quality concerns (e.g., [#13990](https://github.com/github/gh-aw/issues/13990) about risky event triggers) for downstream agents to fix. It gave us surprisingly valuable feedback with a side of sass (“This function is so nested it has its own ZIP code”). Workflow Generator creates new agentic workflows from issue requests, scaffolding the markdown workflow files that other agents then refine (e.g., [#13379](https://github.com/github/gh-aw/issues/13379) requesting AWF mode changes). We learned that **context is king** - these agents work because they’re invoked at the right moment with the right context, not because they run on a schedule. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Q:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/q.md ``` **Grumpy Reviewer:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/grumpy-reviewer.md ``` **Workflow Generator:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/workflow-generator.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Testing & Validation Workflows [Section titled “Next Up: Testing & Validation Workflows”](#next-up-testing--validation-workflows) While ChatOps agents respond to commands, we also need workflows that continuously verify our systems still function as expected. Continue reading: [Testing & Validation Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-testing-validation/) *** *This is part 13 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Issue & PR Management > A curated tour of workflows that enhance GitHub collaboration  *Ah!* Let’s discuss the art of managing issues and pull requests at [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! A most delicious topic indeed! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-documentation/), we explored documentation and content workflows - agents that maintain glossaries, technical docs, slide decks, and blog content. We learned how we took a heterogeneous approach to documentation agents - some workflows generate content, others maintain it, and still others validate it. Now let’s talk about the daily rituals of software development: managing issues and pull requests. GitHub provides excellent primitives for collaboration, but there’s ceremony involved - linking related issues, merging main into PR branches, assigning work, closing completed sub-issues, optimizing templates. These are small papercuts individually, but they can add up to significant friction. ## Issue & PR Management Workflows [Section titled “Issue & PR Management Workflows”](#issue--pr-management-workflows) These agents enhance issue and pull request workflows: * **[Issue Arborist](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/issue-arborist.md?plain=1)** - Links related issues as sub-issues - **77 discussion reports** and **18 parent issues** created * **[Issue Monster](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/issue-monster.md?plain=1)** - Assigns issues to the asynchronous [GitHub Copilot coding agent](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) one at a time - **task dispatcher** for the whole system * **[Mergefest](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/mergefest.md?plain=1)** - Automatically merges main branch into PR branches - **orchestrator workflow** * **[Sub Issue Closer](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/sub-issue-closer.md?plain=1)** - Closes completed sub-issues automatically - **orchestrator workflow** The Issue Arborist is an **organizational workflow** that has created **77 discussion reports** (titled “\[Issue Arborist] Issue Arborist Report”) and **18 parent issues** to group related sub-issues. It keeps the issue tracker organized by automatically linking related issues, building a dependency tree we’d never maintain manually. For example, [#12037](https://github.com/github/gh-aw/issues/12037) grouped engine documentation updates. The Issue Monster is the **task dispatcher** - it assigns issues to the GitHub platform’s asynchronous [Copilot coding agent](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) one at a time. It doesn’t create PRs itself, but enables every other agent’s work by feeding them tasks. This prevents the chaos of parallel work on the same codebase. Mergefest is an **orchestrator workflow** that automatically merges main into PR branches, keeping long-lived PRs up to date without manual intervention. It eliminates the “please merge main” dance. Sub Issue Closer automatically closes completed sub-issues when their parent issue is resolved, keeping the issue tracker clean. Issue and PR management workflows don’t replace GitHub’s features; they enhance them, removing ceremony and making collaboration feel smoother. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Issue Arborist:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/issue-arborist.md ``` **Issue Monster:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/issue-monster.md ``` **Mergefest:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/mergefest.md ``` **Sub Issue Closer:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/sub-issue-closer.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Fault Investigation Workflows [Section titled “Next Up: Fault Investigation Workflows”](#next-up-fault-investigation-workflows) Next up we look at agents that maintain codebase health - spotting problems before they escalate. Continue reading: [Fault Investigation Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-quality-hygiene/) *** *This is part 7 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Metrics & Analytics > A curated tour of metrics and analytics workflows that turn data into insights  Excellent journey! Now it’s time to plunge into the *observatory* - the nerve center of [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-quality-hygiene/), we explored quality and hygiene workflows - the vigilant caretakers that investigate failed CI runs, detect schema drift, and catch breaking changes before users do. These workflows maintain codebase health by spotting problems before they escalate. When you’re running dozens of AI agents, how do you know if they’re actually working well? How do you spot performance issues, cost problems, or quality degradation? That’s where metrics and analytics workflows come in - they’re the agents that monitor other agents. The aim is to turn raw activity data into actionable insights. ## Metrics & Analytics Workflows [Section titled “Metrics & Analytics Workflows”](#metrics--analytics-workflows) Let’s take a look at these three workflows: * **[Metrics Collector](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/metrics-collector.md?plain=1)** - Tracks daily performance across the entire agent ecosystem * **[Portfolio Analyst](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/portfolio-analyst.md?plain=1)** - Identifies cost reduction opportunities * **[Audit Workflows](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/audit-workflows.md?plain=1)** - A meta-agent that audits all the other agents’ runs The Metrics Collector has created **41 daily metrics discussions** tracking performance across the agent ecosystem - for example, [#6986](https://github.com/github/gh-aw/discussions/6986) with the daily code metrics report. It became our central nervous system, gathering performance data that feeds into higher-level orchestrators. Portfolio Analyst has created **7 portfolio analysis discussions** identifying cost reduction opportunities and token optimization patterns - for example, [#6499](https://github.com/github/gh-aw/discussions/6499) with a weekly portfolio analysis. The workflow has identified workflows that were costing us money unnecessarily (turns out some agents were way too chatty with their LLM calls). Audit Workflows is our most prolific discussion-creating agent with **93 audit report discussions** and **9 issues**, acting as a meta-agent that analyzes logs, costs, errors, and success patterns across all other workflow runs. Four of its issues led to PRs by downstream agents. Observability isn’t optional when you’re running dozens of AI agents - it’s the difference between a well-oiled machine and an expensive black box. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Metrics Collector:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/metrics-collector.md ``` **Portfolio Analyst:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/portfolio-analyst.md ``` **Audit Workflows:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/audit-workflows.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Operations & Release Workflows [Section titled “Next Up: Operations & Release Workflows”](#next-up-operations--release-workflows) Now that we can measure and optimize our agent ecosystem, let’s talk about the moment of truth: actually shipping software to users. Continue reading: [Operations & Release Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-operations-release/) *** *This is part 9 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Multi-Phase Improvers > A curated tour of multi-phase workflows that tackle long-running projects  Let’s continue our journey through [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-tool-infrastructure/), we explored infrastructure workflows - the meta-monitoring layer that validates MCP servers, checks tool configurations, and ensures the platform itself stays healthy. These workflows watch the watchers, providing visibility into the invisible plumbing. Most workflows we’ve seen so far run once and complete: analyze this PR, triage that issue, test this deployment. They’re ephemeral - they execute, produce results, and disappear. But what about projects that are too big to tackle in a single run? What about initiatives that require research, setup, and incremental implementation? Traditional CI/CD is built for stateless execution, but we discovered something powerful: workflows that maintain state across days, working a little bit each day like a persistent team member who never takes breaks. Welcome to our most ambitious experiment - multi-phase improvers that prove AI agents can handle complex, long-running projects. ## Multi-Phase Improver Workflows [Section titled “Multi-Phase Improver Workflows”](#multi-phase-improver-workflows) These are some of our most ambitious agents - they tackle big projects over multiple days: * **[Daily Backlog Burner](https://github.com/githubnext/agentics/blob/main/workflows/daily-backlog-burner.md?plain=1)** - Systematically works through issues and PRs, one day at a time * **[Daily Perf Improver](https://github.com/githubnext/agentics/blob/main/workflows/daily-perf-improver.md?plain=1)** - Three-phase performance optimization (research, setup, implement) * **[Daily QA](https://github.com/githubnext/agentics/blob/main/workflows/daily-qa.md?plain=1)** - Continuous quality assurance that never sleeps * **[Daily Accessibility Review](https://github.com/githubnext/agentics/blob/main/workflows/daily-accessibility-review.md?plain=1)** - WCAG compliance checking with Playwright * **[PR Fix](https://github.com/githubnext/agentics/blob/main/workflows/pr-fix.md?plain=1)** - On-demand slash command to fix failing CI checks (super handy!) This is where we got experimental with agent persistence and multi-day workflows. Traditional CI runs are ephemeral, but these workflows maintain state across days using repo-memory. The Daily Perf Improver runs in three phases - research (find bottlenecks), setup (create profiling infrastructure), implement (optimize). It’s like having a performance engineer who works a little bit each day. The Daily Backlog Burner systematically tackles our issue backlog - one issue per day, methodically working through technical debt. We learned that **incremental progress beats heroic sprints** - these agents never get tired, never get distracted, and never need coffee breaks. The PR Fix workflow is our emergency responder - when CI fails, invoke `/pr-fix` and it investigates and attempts repairs. These workflows prove that AI agents can handle complex, long-running projects when given the right architecture. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Daily Backlog Burner:** ```bash gh aw add-wizard githubnext/agentics/workflows/daily-backlog-burner.md ``` **Daily Perf Improver:** ```bash gh aw add-wizard githubnext/agentics/workflows/daily-perf-improver.md ``` **Daily QA:** ```bash gh aw add-wizard githubnext/agentics/workflows/daily-qa.md ``` **Daily Accessibility Review:** ```bash gh aw add-wizard githubnext/agentics/workflows/daily-accessibility-review.md ``` **PR Fix:** ```bash gh aw add-wizard githubnext/agentics/workflows/pr-fix.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Organization & Cross-Repo Workflows [Section titled “Next Up: Organization & Cross-Repo Workflows”](#next-up-organization--cross-repo-workflows) Single-repository workflows are powerful, but what happens when you scale to an entire organization with dozens of repositories? Continue reading: [Organization & Cross-Repo Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-organization/) *** *This is part 16 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Operations & Release > A curated tour of operations and release workflows that ship software  Ah! Right this way to our next chamber in [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! The chamber where our AI agents enhance the magical moment of *shipping software*. In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-metrics-analytics/), we explored metrics and analytics workflows - the agents that monitor other agents, turning raw activity data into actionable insights. ## Operations & Release Workflows [Section titled “Operations & Release Workflows”](#operations--release-workflows) The agents that help us actually ship software: * **[Changeset](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/changeset.md?plain=1)** - Manages version bumps and changelog entries for releases - **22 merged PRs out of 28 proposed (78% merge rate)** * **[Daily Workflow Updater](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-workflow-updater.md?plain=1)** - Keeps GitHub Actions and dependencies current Shipping software is stressful enough without worrying about whether you formatted your release notes correctly. Changeset Generator has contributed **22 merged PRs out of 28 proposed (78% merge rate)**, automating version bumps and changelog generation for every release. It analyzes commits since the last release, determines the appropriate version bump (major, minor, patch), and updates the changelog accordingly. Daily Workflow Updater keeps GitHub Actions and dependencies current, ensuring workflows don’t fall behind on security patches or new features. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Changeset:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/changeset.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Security-related Workflows [Section titled “Next Up: Security-related Workflows”](#next-up-security-related-workflows) After all this focus on shipping, we need to talk about the guardrails: how do we ensure these powerful agents operate safely? Continue reading: [Security-related Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-security-compliance/) *** *This is part 10 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Organization & Cross-Repo > A curated tour of workflows that operate at organization scale  Let’s zoom out at [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-multi-phase/), we explored multi-phase improver workflows - our most ambitious agents that tackle big projects over multiple days, maintaining state and making incremental progress. These workflows proved that AI agents can handle complex, long-running initiatives when given the right architecture. But all that sophisticated functionality has focused on a single repository. What happens when you zoom out to organization scale? What insights emerge when you analyze dozens or hundreds of repositories together? What looks perfectly normal in one repo might be a red flag across an organization. Organization and cross-repo workflows operate at enterprise scale, requiring careful permission management, thoughtful rate limiting, and different analytical lenses. Let’s explore workflows that see the forest, not just the trees. ## Organization & Cross-Repo Workflows [Section titled “Organization & Cross-Repo Workflows”](#organization--cross-repo-workflows) These agents work at organization scale, across multiple repositories: * **[Org Health Report](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/org-health-report.md?plain=1)** - Organization-wide repository health metrics - **4 organization health discussions** created * **[Stale Repo Identifier](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/stale-repo-identifier.md?plain=1)** - Identifies inactive repositories - **2 issues** flagging truly stale repos * **[Ubuntu Image Analyzer](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/ubuntu-image-analyzer.md?plain=1)** - Documents GitHub Actions runner environments - **4 merged PRs out of 8 proposed (50% merge rate)** Scaling agents across an entire organization changes the game. Org Health Report has created **4 organization health discussions** analyzing dozens of repositories at scale - for example, [#6777](https://github.com/github/gh-aw/discussions/6777) with the December 2025 organization health report. It identifies patterns and outliers (“these three repos have no tests, these five haven’t been updated in months”). Stale Repo Identifier has created **2 issues** flagging truly stale repositories for organizational hygiene - for example, [#5384](https://github.com/github/gh-aw/issues/5384) identifying Skills-Based-Volunteering-Public as truly stale. It helps find abandoned projects that should be archived or transferred. We learned that **cross-repo insights are different** - what looks fine in one repository might be an outlier across the organization. These workflows require careful permission management (reading across repos needs organization-level tokens) and thoughtful rate limiting (you can hit API limits fast when analyzing 50+ repos). Ubuntu Image Analyzer has contributed **4 merged PRs out of 8 proposed (50% merge rate)**, documenting GitHub Actions runner environments to keep the team informed about available tools and versions. It’s wonderfully meta - it documents the very environment that runs our agents. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Org Health Report:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/org-health-report.md ``` **Stale Repo Identifier:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/stale-repo-identifier.md ``` **Ubuntu Image Analyzer:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/ubuntu-image-analyzer.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Advanced Analytics & ML Workflows [Section titled “Next Up: Advanced Analytics & ML Workflows”](#next-up-advanced-analytics--ml-workflows) Cross-repo insights reveal patterns, but we wanted to go even deeper - using machine learning to understand agent behavior. Continue reading: [Advanced Analytics & ML Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-advanced-analytics/) *** *This is part 17 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Fault Investigation > A curated tour of proactive fault investigation workflows that maintain codebase health  *Ah, splendid!* Welcome back to [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! Come, let me show you the chamber where vigilant caretakers investigate faults before they escalate! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-issue-management/), we explored issue and PR management workflows. Now let’s shift from collaboration ceremony to fault investigation. While issue workflows help us handle what comes in, fault investigation workflows act as vigilant caretakers - spotting problems before they escalate and keeping our codebase healthy. These are the agents that investigate failed CI runs, detect schema drift, and catch breaking changes before users do. ## Fault Investigation Workflows [Section titled “Fault Investigation Workflows”](#fault-investigation-workflows) These are our diligent caretakers - the agents that spot problems before they become bigger problems: * **[CI Doctor](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/ci-doctor.md?plain=1)** - Investigates failed workflows and opens diagnostic issues - **9 merged PRs out of 13 proposed (69% merge rate)** * **[Schema Consistency Checker](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/schema-consistency-checker.md?plain=1)** - Detects when schemas, code, and docs drift apart - **55 analysis discussions** created * **[Breaking Change Checker](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/breaking-change-checker.md?plain=1)** - Watches for changes that might break things for users - creates alert issues The CI Doctor (also known as “CI Failure Doctor”) was one of our most important workflows. Instead of drowning in CI failure notifications, we now get *timely*, *investigated* failures with actual diagnostic insights. The agent doesn’t just tell us something broke - it analyzes logs, identifies patterns, searches for similar past issues, and even suggests fixes - even before the human has read the failure notification. CI Failure Doctor has contributed **9 merged PRs out of 13 proposed (69% merge rate)**, including fixes like [adding Go module download pre-flight checks](https://github.com/github/gh-aw/pull/13740) and [adding retry logic to prevent proxy 403 failures](https://github.com/github/gh-aw/pull/13155). We learned that agents excel at the tedious investigation work that humans find draining. The Schema Consistency Checker has created **55 analysis discussions** examining schema drift between JSON schemas, Go structs, and documentation - for example, [#7020](https://github.com/github/gh-aw/discussions/7020) analyzing conditional logic consistency across the codebase. It caught drift that would have taken us days to notice manually. Breaking Change Checker is a newer workflow that monitors for backward-incompatible changes and creates alert issues (e.g., [#14113](https://github.com/github/gh-aw/issues/14113) flagging CLI version updates) before they reach production. These “hygiene” workflows became our first line of defense, catching issues before they reached users. The CI Doctor has inspired a growing range of similar workflows inside GitHub, where agents proactively do depth investigations of site incidents and failures. This is the future of operational excellence: AI agents kicking in immediately to do depth investigation, for faster organizational response. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **CI Doctor:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/ci-doctor.md ``` **Schema Consistency Checker:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/schema-consistency-checker.md ``` **Breaking Change Checker:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/breaking-change-checker.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Metrics & Analytics Workflows [Section titled “Next Up: Metrics & Analytics Workflows”](#next-up-metrics--analytics-workflows) Next up, we look at workflows which help us understand if the agent collection as a whole is working well That’s where metrics and analytics workflows come in. Continue reading: [Metrics & Analytics Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-metrics-analytics/) *** *This is part 8 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Security-related > A curated tour of security and compliance workflows that enforce safe boundaries  *Splendid!* How great to have you back at [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! Now, let me show you the *guardian chamber* - where the watchful protectors stand vigil! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-operations-release/), we explored operations and release workflows that handle the critical process of shipping software - building, testing, generating release notes, and publishing. These workflows need to be rock-solid reliable because they represent the moment when our work reaches users. But reliability alone isn’t enough - we also need *security*. When AI agents can access APIs, modify code, and interact with external services, security becomes paramount. How do we ensure agents only access authorized resources? How do we track vulnerabilities and enforce compliance deadlines? How do we prevent credential exposure? That’s where security and compliance workflows become our essential guardrails - the watchful guardians that let us sleep soundly at night. ## Security-related Workflows [Section titled “Security-related Workflows”](#security-related-workflows) These agents are our security guards, keeping watch and enforcing the rules: * **[Security Compliance](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/security-compliance.md?plain=1)** - Runs vulnerability campaigns with deadline tracking * **[Firewall](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/firewall.md?plain=1)** - Tests network security and validates rules - **59 daily firewall report discussions**, **5 smoke test issues** * **[Daily Secrets Analysis](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-secrets-analysis.md?plain=1)** - Scans for exposed credentials (yes, it happens) * **[Daily Malicious Code Scan](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-malicious-code-scan.md?plain=1)** - Reviews recent code changes for suspicious patterns * **[Static Analysis Report](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/static-analysis-report.md?plain=1)** - Daily security scans using zizmor, poutine, and actionlint - **57 analysis discussions** plus **12 Zizmor security reports** Security Compliance manages vulnerability remediation campaigns with deadline tracking, ensuring security issues are addressed within defined SLAs - perfect for those “audit in 3 weeks” panic moments. The Firewall workflow has created **59 daily firewall report discussions** and **5 smoke test issues**, validating that our agents can’t access unauthorized resources - for example, [#6943](https://github.com/github/gh-aw/discussions/6943) with the daily firewall analysis. It’s the bouncer that enforces network rules. Daily Secrets Analysis scans for exposed credentials in commits and discussions, providing an automated security net against accidental secret exposure - catching those “oops, I committed my API key” moments before they become incidents. Daily Malicious Code Scan reviews recent code changes for suspicious patterns, adding an automated defense layer against supply chain attacks. Static Analysis Report has created **57 analysis discussions** plus **12 Zizmor security reports**, running comprehensive daily security audits using industry-standard tools - for example, [#6973](https://github.com/github/gh-aw/discussions/6973) with the latest static analysis findings and [#3033](https://github.com/github/gh-aw/discussions/3033) with a Zizmor security analysis. This shows how traditional security tools can be integrated into an AI agent workflow. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Security Compliance:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/security-compliance.md ``` **Firewall:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/firewall.md ``` **Daily Secrets Analysis:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-secrets-analysis.md ``` **Daily Malicious Code Scan:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-malicious-code-scan.md ``` **Static Analysis Report:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/static-analysis-report.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Teamwork & Culture Workflows [Section titled “Next Up: Teamwork & Culture Workflows”](#next-up-teamwork--culture-workflows) After all this serious talk, let’s explore the fun side: agents that bring joy and build team culture. Continue reading: [Teamwork & Culture Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-creative-culture/) *** *This is part 11 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Testing & Validation > A curated tour of testing workflows that keep everything running smoothly  *Right this way!* Let’s continue our grand tour of [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! Into the *verification chamber* where nothing escapes scrutiny! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-interactive-chatops/), we explored ChatOps workflows - agents that respond to slash commands and GitHub reactions, providing on-demand assistance with full context. But making code *better* is only half the battle. We also need to ensure it keeps *working*. As we refactor, optimize, and evolve our codebase, how do we know we haven’t broken something? How do we catch regressions before users do? That’s where testing and validation workflows come in - the skeptical guardians that continuously verify our systems still function as expected. We learned that AI infrastructure needs constant health checks, because what worked yesterday might silently fail today. These workflows embody **trust but verify**. ## Testing & Validation Workflows [Section titled “Testing & Validation Workflows”](#testing--validation-workflows) These agents keep everything running smoothly through continuous testing: ### Code Quality & Test Validation [Section titled “Code Quality & Test Validation”](#code-quality--test-validation) * **[Daily Testify Uber Super Expert](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-testify-uber-super-expert.md?plain=1)** - Analyzes test files daily and suggests testify-based improvements - **19 issues created**, **13 led to merged PRs (100% causal chain merge rate)** * **[Daily Test Improver](https://github.com/githubnext/agentics/blob/main/workflows/daily-test-improver.md?plain=1)** - Identifies coverage gaps and implements new tests incrementally * **[Daily Compiler Quality Check](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-compiler-quality.md?plain=1)** - Analyzes compiler code to ensure it meets quality standards ### User Experience & Integration Testing [Section titled “User Experience & Integration Testing”](#user-experience--integration-testing) * **[Daily Multi-Device Docs Tester](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-multi-device-docs-tester.md?plain=1)** - Tests documentation across devices with Playwright - **2 merged PRs out of 2 proposed (100% merge rate)** * **[CLI Consistency Checker](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/cli-consistency-checker.md?plain=1)** - Inspects the CLI for inconsistencies, typos, and documentation gaps - **80 merged PRs out of 102 proposed (78% merge rate)** ### CI/CD Optimization [Section titled “CI/CD Optimization”](#cicd-optimization) * **[CI Coach](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/ci-coach.md?plain=1)** - Analyzes CI pipelines and suggests optimizations - **9 merged PRs out of 9 proposed (100% merge rate)** * **[Workflow Health Manager](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/workflow-health-manager.md?plain=1)** - Meta-orchestrator monitoring health of all agentic workflows - **40 issues created**, **5 direct PRs + 14 causal chain PRs merged** The Daily Testify Expert has created **19 issues** analyzing test quality, and **13 of those issues led to merged PRs** by downstream agents - a perfect 100% causal chain merge rate. For example, [issue #13701](https://github.com/github/gh-aw/issues/13701) led to [#13722](https://github.com/github/gh-aw/pull/13722) modernizing console render tests with testify assertions. The Daily Test Improver works alongside it to identify coverage gaps and implement new tests. The Multi-Device Docs Tester uses Playwright to test our documentation on different screen sizes - it has created **2 PRs (both merged)**, including [adding —network host to Playwright Docker containers](https://github.com/github/gh-aw/pull/7158). It found mobile rendering issues we never would have caught manually. The CLI Consistency Checker has contributed **80 merged PRs out of 102 proposed (78% merge rate)**, maintaining consistency in CLI interface and documentation. Recent examples include [removing undocumented CLI commands](https://github.com/github/gh-aw/pull/12762) and [fixing upgrade command documentation](https://github.com/github/gh-aw/pull/11559). CI Optimization Coach has contributed **9 merged PRs out of 9 proposed (100% merge rate)**, optimizing CI pipelines for speed and efficiency with perfect execution. Examples include [removing unnecessary test dependencies](https://github.com/github/gh-aw/pull/13925) and [fixing duplicate test execution](https://github.com/github/gh-aw/pull/8176). The Workflow Health Manager has created **40 issues** monitoring the health of all other workflows, with **25 of those issues leading to 34 PRs** (14 merged) by downstream agents - plus **5 direct PRs merged**. For example, [issue #14105](https://github.com/github/gh-aw/issues/14105) about a missing runtime file led to [#14127](https://github.com/github/gh-aw/pull/14127) fixing the workflow configuration. These workflows embody the principle: **trust but verify**. Just because it worked yesterday doesn’t mean it works today. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **Daily Testify Uber Super Expert:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-testify-uber-super-expert.md ``` **Daily Test Improver:** ```bash gh aw add-wizard githubnext/agentics/daily-test-improver ``` **Daily Compiler Quality Check:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-compiler-quality.md ``` **Daily Multi-Device Docs Tester:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/daily-multi-device-docs-tester.md ``` **CLI Consistency Checker:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/cli-consistency-checker.md ``` **CI Coach:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/ci-coach.md ``` **Workflow Health Manager:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/workflow-health-manager.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Monitoring the Monitors [Section titled “Next Up: Monitoring the Monitors”](#next-up-monitoring-the-monitors) But what about the infrastructure itself? Who watches the watchers? Time to go meta. Continue reading: [Tool & Infrastructure Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-tool-infrastructure/) *** *This is part 14 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Meet the Workflows: Tool & Infrastructure > A curated tour of infrastructure workflows that monitor the agentic systems  *Delighted to have you back* on our journey through [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/)! Now, prepare yourself for something *quite peculiar* - the room where we watch the watchers! In our [previous post](/gh-aw/blog/2026-01-13-meet-the-workflows-testing-validation/), we explored testing and validation workflows that continuously verify our systems function correctly - running smoke tests, checking documentation across devices, and catching regressions before users notice them. We learned that trust must be verified. But here’s a question that kept us up at night: what if the *infrastructure itself* fails? What if MCP servers are misconfigured, tools become unavailable, or agents can’t access the capabilities they need? Testing the *application* is one thing; monitoring the *platform* that runs AI agents is another beast entirely. Tool and infrastructure workflows provide meta-monitoring - they watch the watchers, validate configurations, and ensure the invisible plumbing stays functional. Welcome to the layer where we monitor agents monitoring agents monitoring code. Yes, it gets very meta. ## Tool & Infrastructure Workflows [Section titled “Tool & Infrastructure Workflows”](#tool--infrastructure-workflows) These agents monitor and analyze the agentic infrastructure itself: * **[MCP Inspector](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/mcp-inspector.md?plain=1)** - Validates Model Context Protocol configurations - ensures agents can access tools * **[GitHub MCP Tools Report](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/github-mcp-tools-report.md?plain=1)** - Analyzes available MCP tools - **5 merged PRs out of 6 proposed (83% merge rate)** * **[Agent Performance Analyzer](https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/agent-performance-analyzer.md?plain=1)** - Meta-orchestrator for agent quality - **29 issues created, 14 leading to PRs (8 merged)** Infrastructure for AI agents is different from traditional infrastructure - you need to validate that tools are available, properly configured, and actually working. The MCP Inspector continuously validates Model Context Protocol server configurations because a misconfigured MCP server means an agent can’t access the tools it needs. GitHub MCP Tools Report Generator has contributed **5 merged PRs out of 6 proposed (83% merge rate)**, analyzing MCP tool availability and keeping tool configurations up to date. For example, [PR #13169](https://github.com/github/gh-aw/pull/13169) updates MCP server tool configurations. Agent Performance Analyzer has created **29 issues** identifying performance problems across the agent ecosystem, and **14 of those issues led to PRs** (8 merged) by downstream agents - for example, it detected that draft PRs accounted for 9.6% of open PRs, created issue #12168, which led to [#12174](https://github.com/github/gh-aw/pull/12174) implementing automated draft cleanup. We learned that **layered observability** is crucial: you need monitoring at the infrastructure level (are servers up?), the tool level (can agents access what they need?), and the agent level (are they performing well?). These workflows provide visibility into the invisible. ## Using These Workflows [Section titled “Using These Workflows”](#using-these-workflows) You can add these workflows to your own repository and remix them. Get going with our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/), then run one of the following: **MCP Inspector:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/mcp-inspector.md ``` **GitHub MCP Tools Report:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/github-mcp-tools-report.md ``` **Agent Performance Analyzer:** ```bash gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/agent-performance-analyzer.md ``` Then edit and remix the workflow specifications to meet your needs, regenerate the lock file using `gh aw compile`, and push to your repository. See our [Quick Start](https://github.github.com/gh-aw/setup/quick-start/) for further installation and setup instructions. You can also [create your own workflows](/gh-aw/setup/creating-workflows/). ## Learn More [Section titled “Learn More”](#learn-more) * **[GitHub Agentic Workflows](https://github.github.com/gh-aw/)** - The technology behind the workflows * **[Quick Start](https://github.github.com/gh-aw/setup/quick-start/)** - How to write and compile workflows ## Next Up: Multi-Phase Improver Workflows [Section titled “Next Up: Multi-Phase Improver Workflows”](#next-up-multi-phase-improver-workflows) Most workflows we’ve seen are stateless - they run, complete, and disappear. But what if agents could maintain memory across days? Continue reading: [Multi-Phase Improver Workflows →](/gh-aw/blog/2026-01-13-meet-the-workflows-multi-phase/) *** *This is part 15 of a 19-part series exploring the workflows in Peli’s Agent Factory.* # Weekly Update – March 18, 2026 > Seven releases in seven days: guard policy overhaul, new triggers, GHE improvements, and a healthy dose of quality-of-life fixes. It’s been a busy week in [github/gh-aw](https://github.com/github/gh-aw) — seven releases shipped between March 13 and March 17, covering everything from a security model overhaul to a new label-based trigger and a long-overdue terminal resize fix. Let’s dig in. ## Releases This Week [Section titled “Releases This Week”](#releases-this-week) ### [v0.61.0](https://github.com/github/gh-aw/releases/tag/v0.61.0) — March 17 [Section titled “v0.61.0 — March 17”](#v0610--march-17) The freshest release focuses on reliability and developer experience: * **Automatic debug logging** ([#21406](https://github.com/github/gh-aw/pull/21406)): Set `ACTIONS_RUNNER_DEBUG=true` on your runner and full debug logging activates automatically — no more manually adding `DEBUG=*` to every troubleshooting run. * **Cross-repo project item updates** ([#21404](https://github.com/github/gh-aw/pull/21404)): `update_project` now accepts a `target_repo` parameter, so org-level project boards can update fields on items from any repository. * **GHE Cloud data residency support** ([#21408](https://github.com/github/gh-aw/pull/21408)): Compiled workflows now auto-inject a `GH_HOST` step, fixing `gh` CLI failures on `*.ghe.com` instances. * **CI build artifacts** ([#21440](https://github.com/github/gh-aw/pull/21440)): The `build` CI job now uploads the compiled `gh-aw` binary as a downloadable artifact — handy for testing PRs without a local build. ### [v0.60.0](https://github.com/github/gh-aw/releases/tag/v0.60.0) — March 17 [Section titled “v0.60.0 — March 17”](#v0600--march-17) This release rewires the security model. **Breaking change**: automatic `lockdown=true` is gone. Instead, the runtime now auto-configures guard policies on the GitHub MCP server — `min_integrity=approved` for public repos, `min_integrity=none` for private/internal. Remove any explicit `lockdown: false` from your frontmatter; it’s no longer needed. Other highlights: * **GHES domain auto-allowlisting** ([#21301](https://github.com/github/gh-aw/pull/21301)): When `engine.api-target` points to a GHES instance, the compiler automatically adds GHES API hostnames to the firewall. No more silent blocks after every recompile. * **`github-app:` auth in APM dependencies** ([#21286](https://github.com/github/gh-aw/pull/21286)): APM `dependencies:` can now use `github-app:` auth for cross-org private package access. ### [v0.59.0](https://github.com/github/gh-aw/releases/tag/v0.59.0) — March 16 [Section titled “v0.59.0 — March 16”](#v0590--march-16) A feature-packed release with two breaking changes (field renames in `safe-outputs.allowed-domains`) and several new capabilities: * **Label Command Trigger** ([#21118](https://github.com/github/gh-aw/pull/21118)): Activate a workflow by adding a label to an issue, PR, or discussion. The label is automatically removed so it can be reapplied to re-trigger. * **`gh aw domains` command** ([#21086](https://github.com/github/gh-aw/pull/21086)): Inspect the effective network domain configuration for all your workflows, with per-domain ecosystem annotations. * **Pre-activation step injection** — New `on.steps` and `on.permissions` frontmatter fields let you inject custom steps and permissions into the activation job for advanced scenarios. ### Earlier in the Week [Section titled “Earlier in the Week”](#earlier-in-the-week) * [v0.58.3](https://github.com/github/gh-aw/releases/tag/v0.58.3) (March 15): MCP write-sink guard policy for non-GitHub MCP servers, Copilot pre-flight diagnostic for GHES, and a richer run details step summary. * [v0.58.2](https://github.com/github/gh-aw/releases/tag/v0.58.2) (March 14): GHES auto-detection in `audit` and `add-wizard`, `excluded-files` support for `create-pull-request`, and clearer `run` command errors. * [v0.58.1](https://github.com/github/gh-aw/releases/tag/v0.58.1) / [v0.58.0](https://github.com/github/gh-aw/releases/tag/v0.58.0) (March 13): `call-workflow` safe output for chaining workflows, `checkout: false` for agent jobs, custom OpenAI/Anthropic API endpoints, and 92 merged PRs in v0.58.0 alone. ## Notable Pull Requests [Section titled “Notable Pull Requests”](#notable-pull-requests) * **[Top-level `github-app` fallback](https://github.com/github/gh-aw/pull/21510)** ([#21510](https://github.com/github/gh-aw/pull/21510)): Define your GitHub App config once at the top level and let it propagate to safe-outputs, checkout, MCP, APM, and activation — instead of repeating it in every section. * **[GitHub App-only permission scopes](https://github.com/github/gh-aw/pull/21511)** ([#21511](https://github.com/github/gh-aw/pull/21511)): 31 new `PermissionScope` constants cover repository, org, and user-level GitHub App permissions (e.g., `administration`, `members`, `environments`). * **[Custom Huh theme](https://github.com/github/gh-aw/pull/21557)** ([#21557](https://github.com/github/gh-aw/pull/21557)): All 11 interactive CLI forms now use a Dracula-inspired theme consistent with the rest of the CLI’s visual identity. * **[Weekly blog post writer workflow](https://github.com/github/gh-aw/pull/21575)** ([#21575](https://github.com/github/gh-aw/pull/21575)): Yes, the workflow that wrote this post was itself merged this week. Meta! * **[CI job timeout limits](https://github.com/github/gh-aw/pull/21601)** ([#21601](https://github.com/github/gh-aw/pull/21601)): All 25 CI jobs that relied on GitHub’s 6-hour default now have explicit timeouts, preventing a stuck test from silently burning runner compute. ## Agent of the Week: auto-triage-issues [Section titled “ Agent of the Week: auto-triage-issues”](#-agent-of-the-week-auto-triage-issues) The first-ever Agent of the Week goes to the workflow that handles the unglamorous but essential job of keeping the issue tracker from becoming a swamp. `auto-triage-issues` runs on a schedule and fires on every new issue, reading each one and deciding how to categorize it. This week it ran five times — three successful runs and two that were triggered by push events to a feature branch (which apparently fire the workflow but don’t give it much to work with). On its scheduled run this morning, it found zero open issues in the repository, so it created a tidy summary discussion to announce the clean state, as instructed. On an earlier issues-triggered run, it attempted to triage issue [#21572](https://github.com/github/gh-aw/pull/21572) but hit empty results from GitHub MCP tools on all three read attempts — so it gracefully called `missing_data` and moved on rather than hallucinating a label. Across its recent runs it made 131 `search_repositories` calls. We’re not sure why it finds repository searches so compelling, but clearly it’s very thorough about knowing its neighborhood before making any decisions. **Usage tip**: Pair `auto-triage-issues` with a notify workflow on specific labels (e.g., `security` or `needs-repro`) so the right people get pinged automatically without anyone having to watch the inbox. → [View the workflow on GitHub](https://github.com/github/gh-aw/blob/main/.github/workflows/auto-triage-issues.md) ## Try It Out [Section titled “Try It Out”](#try-it-out) Update to [v0.61.0](https://github.com/github/gh-aw/releases/tag/v0.61.0) to get all the improvements from this packed week. If you run workflows on GHES or in GHE Cloud, the new auto-detection and `GH_HOST` injection features are especially worth trying. As always, contributions and feedback are welcome in [github/gh-aw](https://github.com/github/gh-aw). # Weekly Update – March 23, 2026 > Eight releases this week: security hardening, custom Actions as safe-output tools, a 20-second speed boost, and timezone support for scheduled workflows. Another week, another flurry of releases in [github/gh-aw](https://github.com/github/gh-aw). Eight versions shipped between March 18 and March 21, pushing security hardening, extensibility, and performance improvements across the board. Here’s what you need to know. ## Releases This Week [Section titled “Releases This Week”](#releases-this-week) ### [v0.62.5](https://github.com/github/gh-aw/releases/tag/v0.62.5) — March 21 [Section titled “v0.62.5 — March 21”](#v0625--march-21) The latest release leads with two important security fixes: * **Supply chain protection**: The Trivy vulnerability scanner action was removed after a supply chain compromise was discovered ([#22007](https://github.com/github/gh-aw/pull/22007), [#22065](https://github.com/github/gh-aw/pull/22065)). Scanning has been replaced with a safer alternative. * **Public repo integrity hardening** ([#21969](https://github.com/github/gh-aw/pull/21969)): GitHub App authentication no longer exempts public repositories from the minimum-integrity guard policy, closing a gap where untrusted content could bypass integrity checks. On the feature side: * **Timezone support for `on.schedule`** ([#22018](https://github.com/github/gh-aw/pull/22018)): Cron entries now accept an optional `timezone` field — finally, no more mental UTC arithmetic when you want your workflow to run “at 9 AM Pacific”. * **Boolean expression optimizer** ([#22025](https://github.com/github/gh-aw/pull/22025)): Condition trees are optimized at compile time, generating cleaner `if:` expressions in compiled workflows. * **Wildcard `target-repo` in safe-output handlers** ([#21877](https://github.com/github/gh-aw/pull/21877)): Use `target-repo: "*"` to write a single handler definition that works across any repository. ### [v0.62.3](https://github.com/github/gh-aw/releases/tag/v0.62.3) — March 20 [Section titled “v0.62.3 — March 20”](#v0623--march-20) This one is a standout for extensibility and speed: * **Custom Actions as Safe Output Tools** ([#21752](https://github.com/github/gh-aw/pull/21752)): You can now expose any GitHub Action as an MCP tool via the new `safe-outputs.actions` block. The compiler resolves `action.yml` at compile time to derive the tool schema and inject it into the agent — no custom wiring needed. This opens the door to a whole ecosystem of reusable safe-output handlers built from standard Actions. * **\~20 seconds faster per workflow run** ([#21873](https://github.com/github/gh-aw/pull/21873)): A bump to `DefaultFirewallVersion` v0.24.5 eliminates a 10-second shutdown delay for both the agent container and the threat detection container. That’s 20 free seconds on every single run. * **`trustedBots` support in MCP Gateway** ([#21865](https://github.com/github/gh-aw/pull/21865)): Pass an allowlist of additional GitHub bot identities to the MCP Gateway, enabling safe cross-bot collaboration in guarded environments. * **`gh-aw-metadata` v3** ([#21899](https://github.com/github/gh-aw/pull/21899)): Lock files now embed the configured agent ID/model in the `gh-aw-metadata` comment, making audits much easier. ### [v0.62.2](https://github.com/github/gh-aw/releases/tag/v0.62.2) — March 19 [Section titled “v0.62.2 — March 19”](#v0622--march-19) ! **Breaking change alert**: `lockdown: true` is gone. It has been replaced by the more expressive `min-integrity` field. If you have `lockdown: false` in your frontmatter, remove it — it’s no longer recognized. The new integrity-level system gives you finer control over what content can trigger your workflows. This release also introduces **integrity filtering for log analysis** — the `gh aw logs` command can now filter to only runs where DIFC integrity events were triggered, making security investigations much faster. ### [v0.62.0](https://github.com/github/gh-aw/releases/tag/v0.62.0) — March 19 [Section titled “v0.62.0 — March 19”](#v0620--march-19) The GitHub MCP guard policy graduates to **general availability**. The policy automatically configures appropriate access controls on the GitHub MCP server at runtime — no manual `lockdown` configuration required. Also new: **inline custom safe-output scripts**, letting you define JavaScript handlers directly in your workflow frontmatter without a separate file. ### [v0.61.x](https://github.com/github/gh-aw/releases/tag/v0.61.2) — March 18 [Section titled “v0.61.x — March 18”](#v061x--march-18) Three patch releases covered: * Signed-commit support for protected branches ([v0.61.1](https://github.com/github/gh-aw/releases/tag/v0.61.1)) * Broader ecosystem domain coverage for language package registries ([v0.61.2](https://github.com/github/gh-aw/releases/tag/v0.61.2)) * Critical `workflow_dispatch` expression evaluation fix ([v0.61.2](https://github.com/github/gh-aw/releases/tag/v0.61.2)) ## Notable Pull Requests [Section titled “Notable Pull Requests”](#notable-pull-requests) Several important fixes landed today (March 23): * **[Propagate `assign_copilot` failures to agent failure comment](https://github.com/github/gh-aw/pull/22371)** ([#22371](https://github.com/github/gh-aw/pull/22371)): When `assign_copilot_to_created_issues` fails (e.g., bad credentials), the failure context is now surfaced in the agent failure issue so you can actually diagnose it. * **[Post failure comment when agent assignment fails](https://github.com/github/gh-aw/pull/22347)** ([#22347](https://github.com/github/gh-aw/pull/22347)): A follow-up to the above — the failure now also posts a comment directly on the target issue or PR for immediate visibility. * **[Hot-path regexp and YAML parse elimination](https://github.com/github/gh-aw/pull/22359)** ([#22359](https://github.com/github/gh-aw/pull/22359)): Redundant regexp compilations and YAML re-parses on the hot path have been eliminated, improving throughput for high-volume workflow execution. * **[`blocked-users` and `approval-labels` in guard policy](https://github.com/github/gh-aw/pull/22360)** ([#22360](https://github.com/github/gh-aw/pull/22360)): The `tools.github` guard policy now supports `blocked-users` and `approval-labels` fields, giving you more granular control over who can trigger guarded workflows. * **[Pull merged workflow files after GitHub confirms readiness](https://github.com/github/gh-aw/pull/22335)** ([#22335](https://github.com/github/gh-aw/pull/22335)): A race condition where merged workflow files were pulled before GitHub reported the workflow as ready has been fixed. ## Agent of the Week: contribution-check [Section titled “ Agent of the Week: contribution-check”](#-agent-of-the-week-contribution-check) Your tireless four-hourly guardian of PR quality — reads every open pull request and evaluates it against `CONTRIBUTING.md` for compliance and completeness. `contribution-check` ran five times this week (once every four hours, as scheduled) and processed a steady stream of incoming PRs, creating issues for contributors who needed guidance, adding labels, and leaving review comments. Four of five runs completed in under 5 minutes with 6–9 turns. The fifth run, however, apparently found the task of reviewing PRs during a particularly active Sunday evening so intellectually stimulating that it worked through 50 turns and consumed 1.55 million tokens — roughly 5× its usual appetite — before the safe\_outputs step politely called it a night. It still managed to file issues, label PRs, and post comments on the way out. Overachiever. One earlier run also hit a minor hiccup: the pre-agent filter step forgot to write its output file, leaving the agent with nothing to evaluate. Rather than fabricating a list of PRs to review, it dutifully reported “missing data” and moved on. Sometimes the bravest thing is knowing when there’s nothing to do. **Usage tip**: The `contribution-check` pattern works best when your `CONTRIBUTING.md` is explicit and opinionated — the more specific your guidelines, the more actionable its feedback will be for contributors. → [View the workflow on GitHub](https://github.com/github/gh-aw/blob/main/.github/workflows/contribution-check.md) ## Try It Out [Section titled “Try It Out”](#try-it-out) Update to [v0.62.5](https://github.com/github/gh-aw/releases/tag/v0.62.5) to pick up the security fixes and timezone support. If you’ve been holding off on migrating from `lockdown: true`, now’s the time — check the [v0.62.2 release notes](https://github.com/github/gh-aw/releases/tag/v0.62.2) for the migration path. As always, contributions and feedback are welcome in [github/gh-aw](https://github.com/github/gh-aw). # Weekly Update – March 30, 2026 > Six releases in seven days: audit superpowers, integrity-aware cache-memory, a serious security sweep, and runner flexibility for compile-stable jobs. Six releases shipped in [github/gh-aw](https://github.com/github/gh-aw) between March 24 and March 30 — that’s almost one a day. From expanded audit tooling to integrity-isolated cache storage and a wave of security fixes, this was a dense week. Here’s the rundown. ## Releases This Week [Section titled “Releases This Week”](#releases-this-week) ### [v0.64.4](https://github.com/github/gh-aw/releases/tag/v0.64.4) — March 30 [Section titled “v0.64.4 — March 30”](#v0644--march-30) The freshest release ships with quality-of-life wins for workflow authors: * **`runs-on-slim` for compile-stable jobs** ([#23490](https://github.com/github/gh-aw/pull/23490)): Override the runner for `compile-stable` framework jobs with a new `runs-on-slim` key, giving you fine-grained control over which machine handles compilation. * **Sibling nested imports fixed** ([#23475](https://github.com/github/gh-aw/pull/23475)): `./file.md` imports now resolve relative to the importing file’s directory, not the working directory. Modular workflows that import sibling files were silently broken before — now they’re not. * **Custom tools in `` prompt** ([#23487](https://github.com/github/gh-aw/pull/23487)): Custom jobs, scripts, and actions are now listed in the agent’s `` prompt block so the AI actually knows they exist. * **Compile-time validation of safe-output job ordering** ([#23486](https://github.com/github/gh-aw/pull/23486)): Misconfigured `needs:` ordering on custom safe-output jobs is now caught at compile time. * **MCP Gateway v0.2.9** ([#23513](https://github.com/github/gh-aw/pull/23513)) and **firewall v0.25.4** ([#23514](https://github.com/github/gh-aw/pull/23514)) bumped for all compiled workflows. ### [v0.64.3](https://github.com/github/gh-aw/releases/tag/v0.64.3) — March 29 [Section titled “v0.64.3 — March 29”](#v0643--march-29) A security-heavy release with one major architectural upgrade: **Integrity-aware cache-memory** is the headline. Cache storage now uses dedicated git branches — `merged`, `approved`, `unapproved`, and `none` — to enforce integrity isolation at the storage level. A run operating at `unapproved` integrity can no longer read data written by a `merged`-integrity run, and any change to your `allow-only` guard policy automatically invalidates stale cache entries. If you upgrade and see a cache miss on your first run, that’s intentional — legacy data has no integrity provenance and must be regenerated. **`patch-format: bundle`** ([#23338](https://github.com/github/gh-aw/pull/23338)) is the other highlight: code-push flows now support `git bundle` as an alternative to `git am`, preserving merge commits, authorship, and per-commit messages that were previously dropped. Security fixes: * **Secret env var exclusion** ([#23360](https://github.com/github/gh-aw/pull/23360)): AWF now strips all secret-bearing env vars (tokens, API keys, MCP secrets) from the agent container’s visible environment, closing a potential prompt-injection exfiltration path in `pull_request_target` workflows. * **Argument injection fix** ([#23374](https://github.com/github/gh-aw/pull/23374)): Package and image names in `gh aw compile --validate-packages` are validated before being passed to `npm view`, `pip index versions`, `uv pip show`, and `docker`. ### [v0.64.2](https://github.com/github/gh-aw/releases/tag/v0.64.2) — March 26 [Section titled “v0.64.2 — March 26”](#v0642--march-26) The `gh aw logs` command gained cross-run report generation via the new `--format` flag: **`gh aw logs --format`** aggregates firewall behavior across multiple workflow runs and produces an executive summary, domain inventory, and per-run breakdown: ```bash gh aw logs agent-task --format markdown --count 10 # Markdown gh aw logs --format markdown --json # JSON for dashboards gh aw logs --format pretty # Console output ``` This release also includes a **YAML env injection security fix** ([#23055](https://github.com/github/gh-aw/pull/23055)): all `env:` emission sites in the compiler now use `%q`-escaped YAML scalars, preventing newlines or quote characters in frontmatter values from injecting sibling env variables into `.lock.yml` files. ### [v0.64.1](https://github.com/github/gh-aw/releases/tag/v0.64.1) — March 26 [Section titled “v0.64.1 — March 26”](#v0641--march-26) **`gh aw audit diff`** ([#22996](https://github.com/github/gh-aw/pull/22996)) lets you compare two workflow runs side-by-side — firewall behavior, MCP tool invocations, token usage, and duration — to spot regressions and behavioral drift before they become incidents: ```bash gh aw audit diff --format markdown ``` Five new sections also landed in the standard `gh aw audit` report: Engine Configuration, Prompt Analysis, Session & Agent Performance, Safe Output Summary, and MCP Server Health. One report now gives you the full picture. ### [v0.64.0](https://github.com/github/gh-aw/releases/tag/v0.64.0) — March 25 [Section titled “v0.64.0 — March 25”](#v0640--march-25) **Bot-actor concurrency isolation**: Workflows combining `safe-outputs.github-app` with `issue_comment`-capable triggers now automatically get bot-isolated concurrency keys, preventing the workflow from cancelling itself mid-run when the bot posts a comment that re-triggers the same workflow. ### [v0.63.1](https://github.com/github/gh-aw/releases/tag/v0.63.1) — March 24 [Section titled “v0.63.1 — March 24”](#v0631--march-24) A focused patch adding the **`skip-if-check-failing`** pre-activation gate — workflows can now bail out before the agent runs if a named CI check is currently failing, avoiding wasted inference on a broken codebase. Also ships an improved fuzzy schedule algorithm with weighted preferred windows and peak avoidance to reduce queue contention on shared runners. *** ## Agent of the Week: auto-triage-issues [Section titled “ Agent of the Week: auto-triage-issues”](#-agent-of-the-week-auto-triage-issues) The self-appointed gatekeeper of the issue tracker — reads every new issue and assigns labels so the right people see it. This week, `auto-triage-issues` handled three runs. Two of them were textbook efficiency: triggered the moment a new issue landed, ran the pre-activation check, decided there was nothing worth labeling, and wrapped up in under 42 seconds flat. No fuss, no drama. Then came the Monday scheduled sweep. That run went a different direction: 18 turns, 817,000 tokens, and after all that contemplation… a failure. Somewhere between turn one and turn eighteen, the triage workflow decided this batch of issues deserved its most thoughtful analysis yet, burned through a frontier model’s patience, and still couldn’t quite close the loop. It’s the classic overachiever problem — sometimes the issues that look the simplest turn out to be the ones that take all day. **Usage tip**: If your `auto-triage-issues` scheduled runs are consistently expensive, the new `agentic_fraction` metric in `gh aw audit` can help you identify which turns are pure data-gathering and could be moved to deterministic shell steps. → [View the workflow on GitHub](https://github.com/github/gh-aw/blob/main/.github/workflows/auto-triage-issues.md) *** ## Try It Out [Section titled “Try It Out”](#try-it-out) Update to [v0.64.4](https://github.com/github/gh-aw/releases/tag/v0.64.4) today with `gh extension upgrade aw`. The integrity-aware cache-memory migration will trigger a one-time cache miss on first run — expected and safe. As always, questions and contributions are welcome in [github/gh-aw](https://github.com/github/gh-aw). # Weekly Update – April 6, 2026 > Ten releases in seven days: full OpenTelemetry distributed tracing, a new report_incomplete safe output, Claude Code 1.0.0 support, and security hardening across the board. Ten releases landed in [github/gh-aw](https://github.com/github/gh-aw) between March 31 and April 6 — a relentless pace that delivered production-ready distributed tracing, new safe output signals, and a sweeping security cleanup. Here’s what shipped. ## Release Highlights [Section titled “Release Highlights”](#release-highlights) ### [v0.67.1](https://github.com/github/gh-aw/releases/tag/v0.67.1) — OpenTelemetry Overhaul & Security Hardening (April 6) [Section titled “v0.67.1 — OpenTelemetry Overhaul & Security Hardening (April 6)”](#v0671--opentelemetry-overhaul--security-hardening-april-6) The headline release of the week polishes the OTLP tracing story introduced in v0.67.0 and adds a wave of security fixes. * **Accurate span names and real job durations** ([#24823](https://github.com/github/gh-aw/pull/24823)): Job lifecycle spans now use the actual job name (e.g. `gh-aw.agent.conclusion`) and record real execution time — previously spans always reported 2–5 ms due to a missing `startMs`. * **OTLP payload sanitization**: Sensitive values (`token`, `secret`, `key`, `auth`, etc.) in span attributes are automatically redacted before sending to any OTLP collector. * **OTLP headers masking** ([#24805](https://github.com/github/gh-aw/pull/24805)): `OTEL_EXPORTER_OTLP_HEADERS` is masked with `::add-mask::` in every job, preventing auth tokens from leaking into GitHub Actions debug logs. * **MCP Gateway OpenTelemetry** ([#24697](https://github.com/github/gh-aw/pull/24697)): The MCP Gateway now receives OpenTelemetry config derived from `observability.otlp` frontmatter and the `actions/setup` trace IDs, correlating all MCP tool-call traces under the workflow root trace. * **`report_incomplete` safe output** ([#24796](https://github.com/github/gh-aw/pull/24796)): A new first-class signal lets agents surface infrastructure or tool failures without being misclassified as successful runs. When an agent emits `report_incomplete`, the safe-outputs handler activates failure handling regardless of agent exit code. * **`checks` as a first-class MCP tool** ([#24818](https://github.com/github/gh-aw/pull/24818)): The `checks` tool is now registered in the gh-aw MCP server, returning a normalized CI verdict (`success`, `failed`, `pending`, `no_checks`, `policy_blocked`). * **Token/secret injection prevention**: 422 instances of `${{ secrets.* }}` interpolated directly into `run:` blocks were moved to `env:` mappings across lock files. * **Claude Code 1.0.0 compatibility** ([#24807](https://github.com/github/gh-aw/pull/24807)): Removed the `--disable-slash-commands` flag that was dropped in Claude Code 1.0.0. ### [v0.67.0](https://github.com/github/gh-aw/releases/tag/v0.67.0) — OTLP Trace Export & GitHub API Rate Limit Analytics (April 5) [Section titled “v0.67.0 — OTLP Trace Export & GitHub API Rate Limit Analytics (April 5)”](#v0670--otlp-trace-export--github-api-rate-limit-analytics-april-5) The milestone release that first shipped distributed tracing support: * **`observability.otlp` frontmatter**: Workflows can now export structured OpenTelemetry spans to any OTLP-compatible backend (Honeycomb, Grafana Tempo, Sentry) with a single frontmatter block. Every job emits setup and conclusion spans; cross-job trace correlation is wired automatically with a single trace ID from the activation job. * **GitHub API rate limit analytics**: `gh aw audit`, `gh aw logs`, and `gh aw audit diff` now show GitHub API quota consumed per run, per resource. * **Environment Variable Reference**: A new comprehensive reference section covers all CLI configuration variables. ### [v0.66.1](https://github.com/github/gh-aw/releases/tag/v0.66.1) — Richer `gh aw logs` & Breaking Change (April 4) [Section titled “v0.66.1 — Richer gh aw logs & Breaking Change (April 4)”](#v0661--richer-gh-aw-logs--breaking-change-april-4) **! Breaking change**: `gh aw audit report` has been removed. Cross-run security reports are now generated directly by `gh aw logs --format`. The new `--last` flag aliases `--count` to ease migration. * **Flat run classification** in `gh aw logs --json`: Each run now carries a top-level `classification` string (`"risky"`, `"normal"`, `"baseline"`, or `"unclassified"`), eliminating null-guard gymnastics. * **Per-tool-call metrics in logs**: Granular token usage, failure counts, and latency per tool — perfect for identifying which tools consume the most resources. ### [v0.66.0](https://github.com/github/gh-aw/releases/tag/v0.66.0) — Token Usage Artifacts & Threat Detection Extensibility (April 3) [Section titled “v0.66.0 — Token Usage Artifacts & Threat Detection Extensibility (April 3)”](#v0660--token-usage-artifacts--threat-detection-extensibility-april-3) * **Token Usage Artifact** ([#24315](https://github.com/github/gh-aw/pull/24315)): Agent token usage is now uploaded as a workflow artifact, making it easy to track spend over time. * Workflow reliability and threat detection extensibility improvements shipped alongside. ### Earlier in the week [Section titled “Earlier in the week”](#earlier-in-the-week) [v0.65.7](https://github.com/github/gh-aw/releases/tag/v0.65.7) through [v0.65.2](https://github.com/github/gh-aw/releases/tag/v0.65.2) (March 31–April 3) focused on cross-repo workflow reliability, MCP gateway keepalive configuration, safe-outputs improvements, and token optimization tooling. *** ## Agent of the Week: agentic-observability-kit [Section titled “ Agent of the Week: agentic-observability-kit”](#-agent-of-the-week-agentic-observability-kit) The tireless watchdog that monitors your entire fleet of agentic workflows and escalates when things go sideways. Every day, `agentic-observability-kit` pulls logs from all running workflows, classifies their behavior, and posts a structured observability report as a GitHub Discussion — then files issues when patterns of waste or failure cross defined thresholds. This past week it had a particularly eventful run: on April 6 it spotted that `smoke-copilot` and `smoke-claude` had each burned through 675K–1.7M tokens across multiple runs (flagged as `resource_heavy_for_domain` with high severity), and it filed an issue titled *“Smoke Copilot and Smoke Claude repeatedly resource-heavy”* before anyone on the team had noticed. It also caught that the GitHub Remote MCP Authentication Test workflow had a 100% failure rate across two runs — one of which completed at zero tokens, suggesting a config or auth problem rather than an agent misbehaving. In a delightfully meta moment, the observability kit itself hit token-limit errors while trying to ingest its own log data — it made four attempts with progressively smaller `count` and `max_tokens` parameters before it could fit the output into context. It got there in the end. **Usage tip**: Pair `agentic-observability-kit` with Slack or email notifications so escalation issues trigger an alert — otherwise the issues it files can sit unread while the token bill quietly grows. → [View the workflow on GitHub](https://github.com/github/gh-aw/blob/main/.github/workflows/agentic-observability-kit.md) *** ## Try It Out [Section titled “Try It Out”](#try-it-out) Update to [v0.67.1](https://github.com/github/gh-aw/releases/tag/v0.67.1) and start exporting traces from your workflows today — all it takes is an `observability.otlp` block in your frontmatter. Feedback and contributions are always welcome in [github/gh-aw](https://github.com/github/gh-aw). # Weekly Update – April 13, 2026 > Five releases this week: engine.bare context control, a critical Copilot CLI hotfix, cross-job distributed tracing, and a wave of security hardening. It was a busy week in [github/gh-aw](https://github.com/github/gh-aw) — five releases shipped between April 6 and April 10, addressing everything from a critical Copilot CLI reliability crisis to shiny new workflow composition features. Here’s the full rundown. ## Release Highlights [Section titled “Release Highlights”](#release-highlights) ### [v0.68.1](https://github.com/github/gh-aw/releases/tag/v0.68.1) — April 10 [Section titled “v0.68.1 — April 10”](#v0681--april-10) The headline of this patch is a **critical Copilot CLI reliability hotfix**. Workflows using the Copilot engine were hanging indefinitely or producing zero-byte output due to an incompatibility introduced in v1.0.22 of the Copilot CLI. [v0.68.1](https://github.com/github/gh-aw/releases/tag/v0.68.1) pins the CLI back to v1.0.21 — the last confirmed-working version — and gets everyone’s workflows running again ([#25689](https://github.com/github/gh-aw/pull/25689)). Beyond the hotfix, this release also ships: * **`engine.bare` frontmatter field** ([#25661](https://github.com/github/gh-aw/pull/25661)): Set `bare: true` to suppress automatic context loading — `AGENTS.md` and user instructions for Copilot, `CLAUDE.md` memory files for Claude. Great when you want the AI to start from a clean slate. * **Improved stale lock file diagnostics** ([#25571](https://github.com/github/gh-aw/pull/25571)): When the activation job detects a stale hash, it now emits step-by-step `[hash-debug]` log lines and opens an actionable issue guiding you to fix it. * **`actions/github-script` upgraded to v9** ([#25553](https://github.com/github/gh-aw/pull/25553)): Scripts now get `getOctokit` as a built-in context parameter, removing the need for manual `@actions/github` imports in safe-output handlers. * **Squash-merge fallback in `gh aw add`** ([#25609](https://github.com/github/gh-aw/pull/25609)): If a repo disallows merge commits, the setup PR now automatically falls back to squash merge instead of failing. * **Security: `agent-stdio.log` permissions hardened** — Log files are now pre-created with `0600` permissions before `tee` writes, preventing world-readable exposure of MCP gateway bearer tokens. ### [v0.68.0](https://github.com/github/gh-aw/releases/tag/v0.68.0) — April 10 [Section titled “v0.68.0 — April 10”](#v0680--april-10) This release brings [distributed tracing](https://github.com/github/gh-aw/releases/tag/v0.68.0) improvements and a cleaner comment API: * **OpenTelemetry cross-job trace hierarchy** ([#25540](https://github.com/github/gh-aw/pull/25540)): Parent span IDs now propagate through `aw_context` across jobs, giving you end-to-end distributed trace visibility for multi-job workflows in backends like Tempo, Honeycomb, and Datadog. * **Simplified discussion comment API** ([#25532](https://github.com/github/gh-aw/pull/25532)): The deprecated `add-comment.discussion` boolean has been removed in favor of the clearer `discussions: true/false` syntax. Run `gh aw fix --write` to migrate existing workflows. * **Security: heredoc content validation** ([#25510](https://github.com/github/gh-aw/pull/25510)): `ValidateHeredocContent` checks now cover five user-controlled heredoc insertion sites, closing a class of potential injection vectors. ### [v0.67.4](https://github.com/github/gh-aw/releases/tag/v0.67.4) — April 9 [Section titled “v0.67.4 — April 9”](#v0674--april-9) This one led with **five new agentic workflow templates**: [approach-validator](https://github.com/github/gh-aw/pull/25354), [test-quality-sentinel](https://github.com/github/gh-aw/pull/25353), [refactoring-cadence](https://github.com/github/gh-aw/pull/25352), [architecture-guardian](https://github.com/github/gh-aw/pull/25334), and [design-decision-gate](https://github.com/github/gh-aw/pull/25323). These expand the built-in library for code quality, ADR enforcement, and architectural governance. The release also included Copilot driver retry logic and a `--runner-guard` compilation flag. ### [v0.67.3](https://github.com/github/gh-aw/releases/tag/v0.67.3) — April 8 [Section titled “v0.67.3 — April 8”](#v0673--april-8) The star of this release is the new **`pre-steps` frontmatter field** — inject steps that run *before* checkout and the agent inside the same job. This is the recommended pattern for token-minting actions (e.g., `actions/create-github-app-token`, `octo-sts`) that need to check out external repos. Because the minted token stays in the same job, it never gets masked when crossing a job boundary. Also shipped: `${{ github.aw.import-inputs.* }}` expression support in the `imports:` section, and `assignees` support on `create-pull-request` fallback issues. ### [v0.67.2](https://github.com/github/gh-aw/releases/tag/v0.67.2) — April 6 [Section titled “v0.67.2 — April 6”](#v0672--april-6) Reliability-focused: cross-repo workflow hash checks, checkout tokens no longer silently dropped on newer runners, `curl`/`wget` flag-bearing invocations now allowed in `network.allowed` workflows, and a `timeout-minutes` schema cap at 360. ## Notable Merged Pull Requests [Section titled “Notable Merged Pull Requests”](#notable-merged-pull-requests) Beyond the releases, the past week also delivered: * **[#25923](https://github.com/github/gh-aw/pull/25923)**: Image artifacts can now be uploaded without zip archiving using `skip-archive: true`, and the resulting artifact URLs are surfaced as outputs — enabling workflows to embed images directly in Markdown comments. * **[#25908](https://github.com/github/gh-aw/pull/25908)**: A new scheduled `cleanup-cache-memory` job was added to the agentics maintenance workflow to prune outdated cache-memory entries automatically (and can be triggered on demand). * **[#25914](https://github.com/github/gh-aw/pull/25914) + [#25972](https://github.com/github/gh-aw/pull/25972)**: OTel exception span events now emit `exception.type` alongside `exception.message` and individual error attributes are queryable — no more digging through pipe-delimited strings in Grafana. * **[#25960](https://github.com/github/gh-aw/pull/25960)**: Fixed a sneaky bug where `push_repo_memory` would run on every bot-triggered no-op because `always()` bypassed skip propagation. * **[#25971](https://github.com/github/gh-aw/pull/25971)**: Raw subprocess output from `gh aw compile --validate` is now sanitized before being embedded into issue bodies, closing a Markdown injection vector. ## Agent of the Week: auto-triage-issues [Section titled “ Agent of the Week: auto-triage-issues”](#-agent-of-the-week-auto-triage-issues) The quiet backbone of issue hygiene — reads every new issue and applies the right labels so the right people see it. This week `auto-triage-issues` proved it’s doing its job almost too well. In the scheduled run on April 13, it scanned all open issues and found exactly **zero** unlabeled issues — reporting a 100% label coverage rate with zero action required. It had already handled the labeling in near-real-time as issues arrived, including one run on April 12 where it correctly tagged a freshly opened issue with `enhancement`, `mcp`, `compiler`, and `security` in a single pass. Four labels, zero hesitation. That “security” label is doing a lot of work — the workflow spotted MCP and compiler concerns that genuinely deserved the tag, not just keyword-matched on it. We’ll take it. **Usage tip**: Pair `auto-triage-issues` with label-based notification rules so your team gets automatically paged for `security` or `critical` issues without anyone having to babysit the issue tracker. → [View the workflow on GitHub](https://github.com/github/gh-aw/blob/main/.github/workflows/auto-triage-issues.md) ## Try It Out [Section titled “Try It Out”](#try-it-out) Update to [v0.68.1](https://github.com/github/gh-aw/releases/tag/v0.68.1) today to get the Copilot CLI hotfix and the new `engine.bare` control. As always, contributions and feedback are welcome in [github/gh-aw](https://github.com/github/gh-aw). # Weekly Update – April 20, 2026 > This week brings five releases packed with a new OpenCode engine, pre-agent steps, cache-memory security hardening, and much more. What a week for [github/gh-aw](https://github.com/github/gh-aw)! Five releases dropped between April 13 and April 17, delivering a new AI engine, key security improvements, and a wave of reliability fixes. Here’s what you need to know. ## Release Highlights [Section titled “Release Highlights”](#release-highlights) ### [v0.68.7](https://github.com/github/gh-aw/releases/tag/v0.68.7) — April 17 [Section titled “v0.68.7 — April 17”](#v0687--april-17) A targeted fix-and-polish release with one standout new addition: * **`on.roles` single-string support** ([#26789](https://github.com/github/gh-aw/pull/26789)): You can now write `roles: write` instead of `roles: [write]`. Previously this produced a confusing compiler error — now it just works. * **Codex chroot fix** ([#26787](https://github.com/github/gh-aw/pull/26787)): Codex workflows on restricted filesystems were failing silently. Runtime state now lives in `/tmp` where it can actually be written. * **Cross-repo compatibility checks** ([#26802](https://github.com/github/gh-aw/pull/26802)): A new daily Claude workflow automatically discovers repositories using gh-aw and runs compile checks against the latest build. Compatibility regressions now get caught before they reach users. ### [v0.68.6](https://github.com/github/gh-aw/releases/tag/v0.68.6) — April 17 [Section titled “v0.68.6 — April 17”](#v0686--april-17) The headline release of the week, with a brand-new engine and important security improvements: * **OpenCode engine** — Set `engine: opencode` to use [OpenCode](https://opencode.ai) as your agentic engine, joining Copilot, Claude, and Codex as first-class options. * **`engine.bare` mode** — Set `engine.bare: true` to skip loading `AGENTS.md`. Perfect for triage, reporting, and ops workflows where repository code context just adds noise. * **Pre-agent steps** — The new `pre-agent-steps` frontmatter field lets you run custom GitHub Actions steps before the AI agent starts — great for authentication, environment setup, or any prerequisite work. * **`cache-memory` working-tree sanitization** — Before each agent run, the working tree is now scanned and cleaned of planted executables and disallowed files from cached memory. This closes a real supply-chain attack vector. ### [v0.68.5](https://github.com/github/gh-aw/releases/tag/v0.68.5) — April 16 [Section titled “v0.68.5 — April 16”](#v0685--april-16) Quality-of-life improvements and more security hardening: * **MCP config at `.github/mcp.json`** ([#26665](https://github.com/github/gh-aw/pull/26665)): The MCP configuration file has moved from `.mcp.json` (repo root) to `.github/mcp.json`, aligning with standard GitHub configuration conventions. The `init` flow creates the new path automatically. * **`shared/reporting-otlp.md` import bundle** ([#26655](https://github.com/github/gh-aw/pull/26655)): One import now replaces two for telemetry-enabled reporting workflows. * **Environment-level secrets fixed** ([#26650](https://github.com/github/gh-aw/pull/26650)): The `environment:` frontmatter field now correctly propagates to the activation job. ### [v0.68.4](https://github.com/github/gh-aw/releases/tag/v0.68.4) — April 16 [Section titled “v0.68.4 — April 16”](#v0684--april-16) A substantial patch resolving 21 community-reported issues: * **BYOK Copilot mode** ([#26544](https://github.com/github/gh-aw/pull/26544)): New `byok-copilot` feature flag wires offline Copilot support. * **Side repo maintenance workflow** ([#26382](https://github.com/github/gh-aw/pull/26382)): The compiler now auto-generates `agentics-maintenance.yml` for target repositories in side repository patterns. * **MCP servers as local CLIs** ([#25928](https://github.com/github/gh-aw/pull/25928)): MCP servers can now be mounted as local CLI commands after the gateway starts, enabling richer tool integrations. ### [v0.68.3](https://github.com/github/gh-aw/releases/tag/v0.68.3) — April 14 [Section titled “v0.68.3 — April 14”](#v0683--april-14) Observability and reliability improvements: * **Model-not-supported detection** ([#26229](https://github.com/github/gh-aw/pull/26229)): When a model is unavailable for your plan, the workflow now stops retrying and surfaces a clear error instead of spinning indefinitely. * **Time Between Turns (TBT) metric** ([#26321](https://github.com/github/gh-aw/pull/26321)): `gh aw audit` and `gh aw logs` now report TBT — a key indicator of whether LLM prompt caching is working for your workflows. * **`env` and `checkout` fields in shared imports** ([#26113](https://github.com/github/gh-aw/pull/26113), [#26292](https://github.com/github/gh-aw/pull/26292)): Shared importable workflows now support both `env:` and `checkout:` fields, eliminating common workarounds. ## Agent of the Week: auto-triage-issues [Section titled “ Agent of the Week: auto-triage-issues”](#-agent-of-the-week-auto-triage-issues) The unsung hero of issue hygiene — reads every unlabeled issue and applies the right labels so the right people see it, automatically, on a schedule. This week `auto-triage-issues` kept its usual steady pace, triaging issues as they came in. In one run, it spotted issue [#27290](https://github.com/github/gh-aw/issues/27290) — a question about ecosystem groups in the frontmatter/compilation pipeline — and correctly labeled it `compiler` within 24 seconds flat. In another run, it encountered an issue that the integrity policy had filtered before the agent could even read the title, so it did the responsible thing: skipped labeling, created a summary discussion, and politely told the maintainers to take a look themselves. Even when it can’t act, it doesn’t just silently fail — it leaves a breadcrumb so nothing falls through the cracks. **Usage tip**: Pair `auto-triage-issues` with a `notify` workflow on high-priority labels (like `security` or `breaking-change`) so your team gets paged for the things that actually matter. → [View the workflow on GitHub](https://github.com/github/gh-aw/blob/main/.github/workflows/auto-triage-issues.md) ## Try It Out [Section titled “Try It Out”](#try-it-out) With [v0.68.7](https://github.com/github/gh-aw/releases/tag/v0.68.7) now available, it’s a great time to update and explore the new OpenCode engine, `engine.bare` mode, or pre-agent steps. As always, feedback and contributions are very welcome in [github/gh-aw](https://github.com/github/gh-aw). # Weekly Update – April 27, 2026 > v0.71.1 lands with critical bug fixes, v0.71.0 adds threat-detection improvements and Claude engine updates, plus a spotlight on the auto-triage-issues workflow. Another productive week in [github/gh-aw](https://github.com/github/gh-aw)! Two releases dropped — v0.71.0 and v0.71.1 — bringing reliability fixes across the board, from threat-detection improvements to the Claude engine to a loop that was quietly consuming millions of tokens. Here’s what shipped. ## Release: [v0.71.1](https://github.com/github/gh-aw/releases/tag/v0.71.1) [Section titled “Release: v0.71.1”](#release-v0711) Released April 24th, this patch release is all about correctness: * **`protected-files` object form now compiles correctly** ([#28341](https://github.com/github/gh-aw/pull/28341)): Workflows using the documented `{policy, exclude}` object syntax were being rejected at compile time. That’s fixed — the schema now accepts both the string shorthand and the full object form. * **Pre-agent skills no longer overwritten on `pull_request` triggers** ([#28290](https://github.com/github/gh-aw/pull/28290)): Skills installed by `pre-agent-steps` were silently clobbered because the “Restore agent config folders” step ran *after* them. Step ordering is now correct. * **Incremental diff for `push_to_pull_request_branch` patch size** ([#28198](https://github.com/github/gh-aw/pull/28198)): The max patch size check now measures only the incremental change since the last push, not the full diff from the default branch. No more spurious size-limit rejections on long-running branches. * **`jsweep` infinite loop fixed** ([#28353](https://github.com/github/gh-aw/pull/28353)): A workflow was calling `create_pull_request` in a loop, racking up 4.64M tokens per run. It now exits after creating a PR. ## Release: [v0.71.0](https://github.com/github/gh-aw/releases/tag/v0.71.0) [Section titled “Release: v0.71.0”](#release-v0710) Released April 23rd, focused on runtime reliability and new capabilities: * **Node.js setup added to threat-detection jobs** ([#28160](https://github.com/github/gh-aw/pull/28160)): The `node: command not found` error in Copilot threat-detection workflows is gone — Node.js setup is now emitted before `copilot_driver.cjs`. * **OTLP tracing for cancelled runs** ([#28172](https://github.com/github/gh-aw/pull/28172)): Manually cancelled runs now emit a proper OpenTelemetry span, so you get full duration visibility even when a run is cut short. * **Claude engine: `bypassPermissions` → `acceptEdits`** ([#28047](https://github.com/github/gh-aw/pull/28047)): Migrates away from the deprecated flag and fixes missing MCP server entries in `--allowed-tools`, keeping Claude-powered workflows fully functional. ## Notable Merged PRs [Section titled “Notable Merged PRs”](#notable-merged-prs) Beyond the releases, this week also saw some useful quality-of-life improvements merged directly to main: * **[Add `gh aw run` guidance and CLI commands reference](https://github.com/github/gh-aw/pull/28616)**: Better docs for running workflows locally — a common source of confusion. * **[Accessibility fix: skip link anchor](https://github.com/github/gh-aw/pull/28618)**: Renamed `#_top` → `#main-content` to meet WCAG 2.4.1 requirements. * **[Fix `daily-cache-strategy-analyzer` false alarm](https://github.com/github/gh-aw/pull/28617)**: The workflow was raising spurious alerts at startup when the cache was simply empty. Now it checks properly before sounding the alarm. ## Agent of the Week: auto-triage-issues [Section titled “ Agent of the Week: auto-triage-issues”](#-agent-of-the-week-auto-triage-issues) The tireless sentinel of the issue tracker — reads every open issue and classifies it so the right people see it. This week, `auto-triage-issues` ran **three times in a single day** (April 27th alone), faithfully scanning for untriaged issues each time on a scheduled basis. Across its runs, it averaged just 4–6 turns per execution, keeping things lean while still making 6 GitHub API calls per run. The workflow even improved its own efficiency mid-day — dropping from 6 turns in the morning run down to 4 turns by afternoon, apparently learning to get to the point faster. The observability metrics politely noted it might be “partially reducible to deterministic automation,” but honestly, where’s the fun in that? One of its runs earned an honorable mention from the agentic assessment system: “This Triage run looks stable enough that deterministic automation may be a simpler fit.” The workflow responded by running again an hour later, exactly the same as before. Iconic. **Usage tip**: Pair `auto-triage-issues` with a label-based notification workflow so the right team members get pinged the moment a new issue is categorized. → [View the workflow on GitHub](https://github.com/github/gh-aw/blob/main/.github/workflows/auto-triage-issues.md) ## Try It Out [Section titled “Try It Out”](#try-it-out) Update to [v0.71.1](https://github.com/github/gh-aw/releases/tag/v0.71.1) today and check out all the fixes. Feedback and contributions are always welcome over at [github/gh-aw](https://github.com/github/gh-aw). # Weekly Update – May 4, 2026 > This week brings v0.71.3 with parameterized safe-outputs, the new A/B experiments framework, and a codex harness upgrade. Happy May the Fourth! Here’s a look at what shipped in [github/gh-aw](https://github.com/github/gh-aw) this week — a busy one packed with experiment infrastructure, compiler fixes, and engine improvements. ## Release: v0.71.3 [Section titled “Release: v0.71.3”](#release-v0713) [v0.71.3](https://github.com/github/gh-aw/releases/tag/v0.71.3) landed on April 30th, capping off a week of rapid iteration. This release delivers major improvements to safe-outputs reusability, more resilient Copilot driver behavior, and solid self-hosted runner support. ### What’s New [Section titled “ What’s New”](#-whats-new) * **Parameterized safe-outputs for reusable workflows** ([#29171](https://github.com/github/gh-aw/issues/29171)): `workflow_call` inputs can now control `safe-outputs.threat-detection`, boolean flags, PR policy fields, and list constraints. Build reusable workflows that callers can configure without forking. * **Configurable MCP gateway session timeout**: Set `engine.mcp.session-timeout` in your workflow frontmatter to keep long-running MCP sessions alive. No more premature timeouts on deep analysis workflows. * **Auto-inject `create_issue` safe output**: Workflows without explicit safe-output configuration now automatically get a `create_issue` safe output, slashing boilerplate for common workflows. * **Repo Mind Light shared workflow**: A shared `repo-mind-light.md` workflow is now available for reuse across daily issue/PR agentic workflows ([#29063](https://github.com/github/gh-aw/issues/29063)). * **Team reviewers on `add_reviewer`**: The `add_reviewer` MCP tool now supports setting `team_reviewers` on pull requests ([#29228](https://github.com/github/gh-aw/issues/29228)). * **Self-hosted runner support for non-default home directories**: Workflows now work correctly on self-hosted runners where the service account home is not `/home/runner` ([#27260](https://github.com/github/gh-aw/issues/27260)). ## Notable Pull Requests [Section titled “Notable Pull Requests”](#notable-pull-requests) Several impactful PRs landed this week beyond the release: * **[Compiler detects single-quoted bash commands that crash Copilot CLI](https://github.com/github/gh-aw/pull/30040)**: The compiler now catches and sanitizes single-quoted bash tool commands before they reach the Copilot CLI, preventing cryptic runtime crashes. A small fix with a big quality-of-life impact. * **[Default Codex harness with retry logic](https://github.com/github/gh-aw/pull/30035)**: The Codex engine now ships a default `codex_harness.cjs` with built-in retry logic, making Codex-powered workflows more resilient out of the box. * **[A/B experiments framework](https://github.com/github/gh-aw/pull/30020)**: A hidden `experiments` CLI command lets you read experiment state from storage repo branches, enabling controlled A/B testing of workflow behavior across runs. * **[Statistical analysis for experiments](https://github.com/github/gh-aw/pull/30029)**: The `experiments analyze` command now computes statistical significance, so you can tell whether a prompt change actually improved things — or just got lucky. * **[Multiple OTLP endpoints](https://github.com/github/gh-aw/pull/30021)**: The `endpoint` field in OTLP configuration is now polymorphic — send telemetry to multiple backends simultaneously. * **[Fix: round-robin random start on cache miss](https://github.com/github/gh-aw/pull/30005)**: Round-robin workflows now randomly select their starting item when the cache is cold, preventing all instances from piling onto the first item at startup. ## Agent of the Week: ab-testing-advisor [Section titled “ Agent of the Week: ab-testing-advisor”](#-agent-of-the-week-ab-testing-advisor) The world’s most meta workflow — it finds workflows that *don’t* run experiments yet, and proposes experiments for them. This week `ab-testing-advisor` ran three times, each time scanning the entire workflow catalog for experiment-free candidates, picking one, and writing a detailed GitHub issue with a full A/B experiment campaign. On May 2nd alone it created two issues: one proposing a [`prompt_style` A/B test for the `daily-news` workflow](https://github.com/github/gh-aw/issues/29660) (which it diagnosed as “highly prescriptive” and worth loosening up), and another ([#29661](https://github.com/github/gh-aw/issues/29661)) calling for improvements to the experiment infrastructure itself — the advisor advising on how to improve the advisor. Very on-brand. It spent roughly 500k tokens per run carefully reading workflow files, thinking through experiment dimensions, and writing crisp implementation specs. For a workflow that runs daily and quietly, it’s doing serious intellectual heavy lifting behind the scenes. **Usage tip**: Use `ab-testing-advisor` as inspiration for your own repos — it’s a great example of a meta-workflow that uses AI to drive continuous improvement of *other* AI workflows. → [View the workflow on GitHub](https://github.com/github/gh-aw/blob/main/.github/workflows/ab-testing-advisor.md) ## Try It Out [Section titled “Try It Out”](#try-it-out) Update to [v0.71.3](https://github.com/github/gh-aw/releases/tag/v0.71.3) today to get parameterized safe-outputs, the new experiment infrastructure, and all the reliability fixes. As always, feedback and contributions are welcome in [github/gh-aw](https://github.com/github/gh-aw). # Weekly Update – May 11, 2026 > Four releases in one week: gh aw lint, inline sub-agents default-on, a new forecast command, and Claude /tmp access — plus the story of our tireless Auto-Triage Issues agent. It was a busy week in [github/gh-aw](https://github.com/github/gh-aw)! Four releases landed between May 4 and May 7, paired with a wave of pull requests that delivered new commands, security hardening, and developer-experience polish. Here’s everything that shipped. ## Releases This Week [Section titled “Releases This Week”](#releases-this-week) ### [v0.72.1](https://github.com/github/gh-aw/releases/tag/v0.72.1) — May 7 [Section titled “v0.72.1 — May 7”](#v0721--may-7) The headline feature is a new `gh aw lint` command that runs [actionlint](https://github.com/rhysd/actionlint) directly against your existing `.lock.yml` files — no recompile required. It’s a lightweight CI gate you can drop into any pipeline to catch syntax errors early. Pass `--shellcheck` or `--pyflakes` for deeper script analysis, or point it at specific files with `--dir`. Other highlights: * **Shared workflow `engine.mcp.tool-timeout` inheritance** ([#30634](https://github.com/github/gh-aw/issues/30634)): Shared workflows that wrap slow MCP servers can now declare timeout values once and have consumers inherit them automatically — no more duplicating `engine.mcp.tool-timeout` in every downstream workflow. * **First-party coding-agent skill** ([#27259](https://github.com/github/gh-aw/issues/27259)): Copilot, Claude, and other coding agents now get structured guidance on creating, debugging, and updating agentic workflows via a router skill shipped with `gh aw`. * **`&&` preserved in compiled expressions** ([#30695](https://github.com/github/gh-aw/issues/30695)): A sneaky Go HTML-escaping bug was silently turning `&&` into `\u0026\u0026` inside `.lock.yml` files, corrupting `${{ ... && ... }}` expressions. Fixed. ### [v0.72.0](https://github.com/github/gh-aw/releases/tag/v0.72.0) — May 6 [Section titled “v0.72.0 — May 6”](#v0720--may-6) Inline sub-agents are now **default-on** — the `features.inline-agents: true` flag is deprecated. Run `gh aw fix --write` to auto-remove it from existing workflows via the new `features-inline-agents-removal` codemod. This release also fixed a community-reported `push_to_pull_request_branch` rerun failure: when an agent reran and its patch reintroduced a file already on the branch, `git am --3way` produced an unresolvable add/add conflict. The fix detects add/add-only conflicts and resolves them by taking the patch side automatically. ### [v0.71.6](https://github.com/github/gh-aw/releases/tag/v0.71.6) and [v0.71.5](https://github.com/github/gh-aw/releases/tag/v0.71.5) — May 5–6 [Section titled “v0.71.6 and v0.71.5 — May 5–6”](#v0716-and-v0715--may-56) These patch releases addressed Claude engine stability (no more mid-session crashes from “Fast mode unavailable”), fixed multi-line `engine.env` block-scalar values that compiled to broken YAML, added gateway RPC message rendering in step summaries, and switched inline sub-agent blocks to the `small` model alias by default to reduce cost and latency. ## Notable Pull Requests [Section titled “Notable Pull Requests”](#notable-pull-requests) Beyond the releases, several PRs merged this week are worth highlighting: * **[`gh aw forecast` command (experimental)](https://github.com/github/gh-aw/pull/31377)** — A new command for projecting workflow effective token usage before you run it. Useful for budgeting and capacity planning. * **[Grant Claude default `/tmp` read/write in sandboxed workflows](https://github.com/github/gh-aw/pull/31357)** — Claude-engine workflows can now read and write to `/tmp` by default in sandboxed environments, eliminating a common pain point when agents need temporary scratch space. * **[Rename `rate-limit` → `user-rate-limit` and `max-runs` → `max-runs-per-window`](https://github.com/github/gh-aw/pull/31390)** — Clearer naming for rate-limiting configuration fields. * **[OTel `gen_ai.response.finish_reasons`](https://github.com/github/gh-aw/pull/31332)** — Agent spans now emit finish reasons (e.g., `stop`, `length`, `tool_calls`) as an OpenTelemetry attribute, improving observability dashboards. * **[Synthetic OTel exception events for silent failures](https://github.com/github/gh-aw/pull/31334)** — When a workflow fails but the agent produces no readable output, a synthetic exception event is now emitted so traces still surface the failure. ## Agent of the Week: auto-triage-issues [Section titled “ Agent of the Week: auto-triage-issues”](#-agent-of-the-week-auto-triage-issues) The unsung inbox manager of the repository — reads every new issue the moment it’s opened and figures out where it belongs. This week `auto-triage-issues` ran three times in quick succession (May 9–10), successfully triaging two issues and stumbling on a third that triggered a failure — a small battle scar it wore with dignity. In its successful runs it stayed impressively lean: nine API requests, \~270 K input tokens pulled from cache, and a turnaround of under 40 seconds per issue. It never wastes a compute cycle it doesn’t have to. The run summary noted with mild concern that `auto-triage-issues` is so reliable and narrow in its tool usage that it might be “overkill for agentic” — meaning deterministic automation could theoretically do its job. The workflow appears to have taken this note personally and immediately triaged the next issue without comment. **Usage tip**: Pair `auto-triage-issues` with a `notify` or `discussion` workflow on high-priority labels so the right people are paged the moment a critical bug or security issue lands. → [View the workflow on GitHub](https://github.com/github/gh-aw/blob/main/.github/workflows/auto-triage-issues.md) ## Try It Out [Section titled “Try It Out”](#try-it-out) Update to [v0.72.1](https://github.com/github/gh-aw/releases/tag/v0.72.1) today — `gh extension upgrade gh-aw` — and try the new `gh aw lint` and experimental `gh aw forecast` commands. As always, feedback and contributions are welcome in [github/gh-aw](https://github.com/github/gh-aw). # Agent of the Day – May 15, 2026 > Meet the AI Moderator: a Codex-powered workflow that reviews every PR, issue, and comment for policy compliance — automatically. Every open-source repo has the same invisible tax: someone has to watch the door. Label the PR. Check if the commenter is a member or an outsider. Hide the policy violation before it spreads. Flag the ambiguous case for a human. It’s repetitive, important, and easy to miss at 2 AM when CI is green and you’re trying to ship. That’s the gap the AI Moderator workflow fills — automatically, on every event, before a human even opens their notifications. *** ## Agent of the Day: AI Moderator [Section titled “Agent of the Day: AI Moderator”](#agent-of-the-day-ai-moderator) The AI Moderator is a Codex-powered agentic workflow in the `github/gh-aw` repository. It fires on pull requests, new issues, and comments — running a structured investigation each time to determine who’s knocking, what they brought, and what action to take. Label it. Hide it. Escalate it. Or stand down. It’s not a simple rule-based bot. It reasons. On a recent run — [Actions run 25924881974](https://github.com/github/gh-aw/actions/runs/25924881974) — the agent woke up when [PR #32406](https://github.com/github/gh-aw/pull/32406) landed: a work-in-progress branch titled *“Experiment with output format in daily compiler quality”* from `copilot/ab-advisorexperiment-output-format`. Sixteen turns later, it had done its job. ### What it actually did [Section titled “What it actually did”](#what-it-actually-did) The agent didn’t guess. It looked things up. It started by orienting itself — calling `github___get_me` to confirm its own identity, then `github-search_repositories` to verify the repo context it was operating in. From there it fanned out: `github-list_branches`, `github-list_tags`, `github-list_releases`, `github-get_teams`, `github-get_team_members`. It was building a picture of who belongs here and what the repo looks like right now. Then it turned to the PR itself. It pulled the PR details with `github___pull_request_read`, searched related issues with `github___search_issues` and `github___search_pull_requests`, reviewed the commit history via `github___list_commits`, and read any linked issue context through `github-issue_read`. That’s a broad sweep — the kind a human reviewer would do informally, but inconsistently. The agent did it every time, in the same order, with a logged record of each step. The conclusion: `action_required`. The agent applied labels through `safeoutputs-add_labels`, hid at least one comment using `safeoutputs___hide_comment`, and raised a flag with `safeoutputs-report_incomplete` to signal that follow-up was needed. Where checks passed cleanly, it called `safeoutputs-noop` — explicit confirmation that nothing warranted action, not just silence. ### Sixteen turns, and that’s notable [Section titled “Sixteen turns, and that’s notable”](#sixteen-turns-and-thats-notable) The audit system tracks behavioral baselines. On the same day, a reference run ([25924730956](https://github.com/github/gh-aw/actions/runs/25924730956)) completed with zero turns and a `success` conclusion. This run took 16. The delta was flagged automatically as a `turns_increase` requiring review. That flag matters. It means the system caught a meaningful deviation in how the agent behaved — not a failure, but a signal worth inspecting. Did the PR have unusual characteristics? Was the team membership lookup more complex than usual? The audit trail is there. The observation is already logged. This is what makes agentic workflows different from scripts: the behavior changes with the input, and the monitoring has to account for that. ### Why it’s worth watching [Section titled “Why it’s worth watching”](#why-its-worth-watching) Community moderation is one of those problems where the cost of under-investing is invisible until it isn’t. A missed label means a misrouted PR. A comment that should have been hidden lingers. An external contributor gets treated the same as a maintainer when they shouldn’t. The AI Moderator closes that gap without requiring a human to be on-call for it. It checks team membership — not just assumed from a username, but verified against `github-get_team_members`. It applies structured outputs through the `safeoutputs` interface, which means every action is auditable. And when it can’t confidently resolve a case, it says so explicitly via `report_incomplete`, rather than silently doing nothing. Fast, too. This run completed in seconds. ### Try it [Section titled “Try it”](#try-it) The workflow is part of the `github/gh-aw` agentic workflows project — a growing collection of Codex-powered agents built to automate the unglamorous parts of software engineering. If your team maintains a repository and you’re tired of playing gatekeeper manually, this is a good place to start. Head to [github.com/github/gh-aw](https://github.com/github/gh-aw) to see the workflows, read the specs, and explore what’s already running in production. *** *Agent of the Day is a recurring look at agentic workflows built and run inside the GitHub engineering org.* # Agent of the Day – May 20, 2026 > Architecture Guardian workflow intelligently skips analysis when no code changes are detected You know that sinking feeling when your CI pipeline kicks off a full build-test-deploy cycle because someone fixed a typo in the README? Or when your security scanner churns through every line of code at 2 AM, finds nothing new, and emails you a 47-page report that’s identical to yesterday’s? Yeah, we’ve all been there. The robot dutifully did its job. You dutifully archived the notification. Nobody won. Enter **Architecture Guardian**, a scheduled workflow that’s learned the ancient DevOps virtue of knowing when *not* to run. ## The Setup: Daily Architecture Audits [Section titled “The Setup: Daily Architecture Audits”](#the-setup-daily-architecture-audits) This workflow runs every weekday around 14:00 UTC with a straightforward mission: scan Go and JavaScript source files for architecture drift, naming violations, or structural anti-patterns that might’ve slipped through code review. It’s the kind of governance check that *should* run regularly—but doesn’t need to re-analyze the entire codebase when nothing has changed. On [run 26171885477](https://github.com/github/gh-aw/actions/runs/26171885477), Architecture Guardian demonstrated exactly how a smart agent should behave: it showed up, looked around, realized there was no work to do, and gracefully bowed out. ## The Smart Skip: 5.5 Minutes of Doing Nothing (Efficiently) [Section titled “The Smart Skip: 5.5 Minutes of Doing Nothing (Efficiently)”](#the-smart-skip-55-minutes-of-doing-nothing-efficiently) Here’s what happened under the hood: The workflow spun up, spent three agent turns checking for recent changes, and concluded: **zero Go or JavaScript files modified in the last 24 hours**. Instead of proceeding with the full architecture scan—parsing files, running static analysis, generating reports—it called `safeoutputs.noop` with a clear message: > “No Go or JavaScript source files changed in the last 24 hours. Architecture scan skipped.” Total runtime? 5.5 minutes. Token usage? 123k—mostly spent confirming the skip was valid. No unnecessary compute, no noise in the logs, no pointless notifications. Compare that to a naïve scheduled job that runs the full analysis every single day regardless of activity. Over a month of weekdays (roughly 22 runs), this skip-when-idle logic could save hours of compute time and thousands of tokens on quiet days. ## The Read-Only Posture: Analysis, Not Automation Chaos [Section titled “The Read-Only Posture: Analysis, Not Automation Chaos”](#the-read-only-posture-analysis-not-automation-chaos) Architecture Guardian operates in **read-only mode**—it never writes back to GitHub, never auto-fixes violations, never opens PRs. It’s pure analysis. When it *does* find issues, it surfaces them cleanly for human review. When it finds nothing (or nothing *new*), it stays silent. This run hit some network friction—3 blocked requests out of 8 total, a 38% block rate—but still completed successfully. The agent adapted, worked within constraints, and delivered its finding: nothing to report. Two anomalous event patterns flagged during the run suggest the reliability monitoring is working as intended, catching edge cases for future iteration. ## Why This Matters: Respecting Developer Time [Section titled “Why This Matters: Respecting Developer Time”](#why-this-matters-respecting-developer-time) The real win isn’t the 5.5 minutes saved on one run. It’s the **cognitive load reduction**. When your scheduled jobs only notify you about *actual changes*, you start trusting them again. The alert fatigue drops. The “mark all as read” reflex fades. Architecture Guardian isn’t trying to impress you with how much work it can do. It’s trying to impress you by doing *only the work that matters*. That’s automation maturity.  *** **Want workflows that know when to quit while they’re ahead?** Check out the [gh-aw project on GitHub](https://github.com/github/gh-aw) and see how agentic workflows can respect your time as much as your architecture. # Error Messages > Write actionable, constructive error messages with examples. # Error message style guide [Section titled “Error message style guide”](#error-message-style-guide) Use actionable messages that explain what went wrong, what is expected, and how to fix it. ## Prefer constructive language [Section titled “Prefer constructive language”](#prefer-constructive-language) * Avoid: `invalid`, `cannot`, `must`, `failed` without guidance. * Prefer adding: `expected`, `requires`, `should`, `example`. ✓ `invalid repo format 'gh-aw' — expected 'owner/repo' format (for example: 'github/gh-aw')` ✗ `invalid repo format` ## When to use `NewValidationError` vs `fmt.Errorf` [Section titled “When to use NewValidationError vs fmt.Errorf”](#when-to-use-newvalidationerror-vs-fmterrorf) Use `NewValidationError(field, value, reason, suggestion)` in validation code (`*_validation.go`) so users get a structured reason and suggestion. Use `fmt.Errorf` for operational wrapping (`%w`) outside validation logic when you include specific context and recovery guidance. ## Error type selection [Section titled “Error type selection”](#error-type-selection) * `NewValidationError(...)`: bad input/config shape, missing fields, unsupported values. * `NewOperationError(...)`: runtime actions fail (fetching, file IO, network, command execution). * `NewConfigurationError(...)`: safe-outputs/config wiring errors. * `fmt.Errorf(...%w...)`: wrap lower-level errors with actionable context. ## Suggestion text requirements [Section titled “Suggestion text requirements”](#suggestion-text-requirements) Good suggestions: 1. Say what to change 2. Include a concrete YAML/code example 3. Prefer ✓/✗ examples when ambiguity is likely Example: ```text Use a supported engine. ✓ Example: engine: copilot ✗ Avoid: engine: unknown ``` ## YAML example guidance [Section titled “YAML example guidance”](#yaml-example-guidance) * Keep examples minimal and valid YAML * Use real field names from frontmatter * Quote only when required by YAML syntax # Multi-Repository Examples > Complete examples for managing workflows across multiple GitHub repositories, including feature synchronization, cross-repo tracking, quality monitoring, and organization-wide updates. Multi-repository operations enable coordinating work across multiple GitHub repositories while maintaining security and proper access controls. These examples demonstrate common patterns for cross-repo workflows. ## Featured Examples [Section titled “Featured Examples”](#featured-examples) ### [Triage from Side Repo](/gh-aw/examples/multi-repo/triage-from-side-repo/) [Section titled “Triage from Side Repo”](#triage-from-side-repo) Runs automated issue triage on a main repository from an isolated side repository, with a slash-command bridge for real-time `/triage` response. Keeps all automation logic separate from the main codebase. Use when you want to experiment with agentic triage without touching your main repository. ### [Code Quality Monitoring](/gh-aw/examples/multi-repo/code-quality-monitoring/) [Section titled “Code Quality Monitoring”](#code-quality-monitoring) Runs weekly code quality analysis from a side repository by checking out the target codebase locally, running linters and complexity checks, and creating focused actionable issues. Use for ongoing quality gates across repositories you don’t want to modify. ### [Feature Synchronization](/gh-aw/examples/multi-repo/feature-sync/) [Section titled “Feature Synchronization”](#feature-synchronization) Automates code synchronization from main repositories to sub-repositories or downstream services through pull requests with change detection, path filters, and bidirectional sync support. Use for monorepo alternatives, shared component libraries, multi-platform deployments, or fork maintenance. ### [Cross-Repository Issue Tracking](/gh-aw/examples/multi-repo/issue-tracking/) [Section titled “Cross-Repository Issue Tracking”](#cross-repository-issue-tracking) Centralizes issue tracking by automatically creating tracking issues in a central repository with status synchronization and multi-component coordination. Use for component-based architecture visibility, multi-team coordination, cross-project initiatives, or upstream dependency tracking. ### [Dependabot Rollout](/gh-aw/examples/multi-repo/dependabot-rollout/) [Section titled “Dependabot Rollout”](#dependabot-rollout) Rolls out a customized Dependabot configuration across many repositories using an orchestrator + worker pair from a central control repository. The orchestrator filters and prioritizes targets, then dispatches workers that analyze each repo and create tailored pull requests. Use for org-wide config standardization, security patch rollouts, or any scheduled multi-repo operation. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) - Design patterns for multi-repository workflows * [Cross-Repository Reference](/gh-aw/reference/cross-repository/) - Checkout and target-repo configuration * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Configuration options * [GitHub Tools](/gh-aw/reference/github-tools/) - API access configuration * [Security Best Practices](/gh-aw/introduction/architecture/) - Authentication and security * [Reusing Workflows](/gh-aw/guides/packaging-imports/) - Sharing workflows # Code Quality Monitoring > Run weekly code quality analysis on a main repository from a side repository, checking out the code locally to run linters and producing actionable issues. This example shows how to run weekly code quality checks on `my-org/main-repo` from a dedicated side repository. The agent checks out the target repository, runs linters and complexity analysis locally, and creates prioritized issues in the main repo — keeping automation infrastructure entirely separate from the codebase it monitors. ## How It Works [Section titled “How It Works”](#how-it-works) ``` flowchart LR subgraph side["Side repo (automation)"] schedule([Weekly schedule]) --> agent[Quality agent] agent -->|checkout| clone[Local clone\nof main-repo] clone --> lint[Run linters /\nanalyze code] end lint -->|create-issue| main[main-repo] ``` The agent: 1. Checks out `main-repo` into the workflow runner 2. Runs linters, counts complexity, and scans for security patterns 3. Creates focused, actionable issues in the main repo for significant findings ## Setup [Section titled “Setup”](#setup) ### 1. Create the Side Repository [Section titled “1. Create the Side Repository”](#1-create-the-side-repository) ```bash gh repo create my-org/main-repo-quality --private gh repo clone my-org/main-repo-quality cd main-repo-quality ``` ### 2. Create the Authentication Token [Section titled “2. Create the Authentication Token”](#2-create-the-authentication-token) Create a fine-grained PAT (`GH_AW_MAIN_REPO_TOKEN`) scoped **only to `my-org/main-repo`** with these permissions: | Permission | Level | Purpose | | ---------- | ------------ | ----------------------- | | Contents | Read-only | Checkout the repository | | Issues | Read & write | Create quality issues | Store it as a secret in the **side repository**: ```bash gh secret set GH_AW_MAIN_REPO_TOKEN --repo my-org/main-repo-quality ``` Note The default `GITHUB_TOKEN` cannot access other repositories. The explicit token must be set on both `checkout` and `safe-outputs`. For enhanced security, use a [GitHub App token](/gh-aw/reference/auth/#using-a-github-app-for-authentication) — minted on demand and automatically revoked after each job. ### 3. Create the Workflow [Section titled “3. Create the Workflow”](#3-create-the-workflow) In the side repository, create `.github/workflows/code-quality.md`: ````aw --- on: weekly on monday permissions: contents: read checkout: repository: my-org/main-repo github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} path: repo current: true tools: github: github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} toolsets: [repos, pull_requests] bash: - "npx:*" - "eslint:*" - "pip:*" safe-outputs: github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} create-issue: target-repo: "my-org/main-repo" title-prefix: "[quality] " labels: [code-quality, automation] max: 10 --- # Weekly Code Quality Review The target repository has been checked out to `${{ github.workspace }}/repo`. Start by navigating there: ``` cd ${{ github.workspace }}/repo ``` ## What to Analyze ### 1. JavaScript / TypeScript (if package.json exists) ```bash npx eslint . --format json --max-warnings 0 2>/dev/null | head -200 ``` Look for: - Files with >5 ESLint errors (flag for immediate fix) - Patterns that indicate missing error handling (`catch(e) {}`, empty catch blocks) - Unused imports and variables accumulating across many files ### 2. Complexity (any language) Count lines per file and flag files over 500 lines — they are candidates for splitting. Use `wc -l` on source files: ```bash find . -name "*.ts" -o -name "*.js" -o -name "*.py" | xargs wc -l | sort -rn | head -20 ``` ### 3. Python (if requirements.txt or pyproject.toml exists) ```bash pip install flake8 --quiet && flake8 . --count --statistics 2>/dev/null | tail -20 ``` Flag modules with >10 flake8 errors. ### 4. Dependency staleness Check for packages with known security advisories using GitHub tools — look at open Dependabot alerts on `my-org/main-repo`. ### 5. Recent PR patterns Use GitHub tools to look at the last 10 merged PRs. Note recurring themes: are tests consistently skipped? Are the same files always modified together (coupling indicator)? ## What to Create Create **one issue per distinct finding category** (not one issue per file). Each issue should: - Name the specific files or modules involved (link to them via GitHub URL) - Explain why it matters (performance, maintainability, security) - Suggest a concrete first step to address it - Include a severity: High (security/crashes), Medium (maintainability), Low (style) Skip findings with fewer than 3 instances — they are not worth the noise. ## What to Skip Do not create issues for: - Style preferences without an established linter rule - Files with a `// quality-exempt` comment - Test files (`*.test.*`, `*.spec.*`, `__tests__/`) ```` Compile: `gh aw compile`. ## Customizing the Analysis [Section titled “Customizing the Analysis”](#customizing-the-analysis) ### Running Type Checkers [Section titled “Running Type Checkers”](#running-type-checkers) Add TypeScript checking to the bash tools and prompt: ```aw --- tools: bash: - "npx:*" - "tsc:*" --- # ... Run `npx tsc --noEmit 2>&1 | head -50` and flag any type errors in non-test files. ``` ### Targeting a Specific Directory [Section titled “Targeting a Specific Directory”](#targeting-a-specific-directory) Use `path:` in checkout and navigate into a subdirectory: ```aw --- checkout: repository: my-org/monorepo github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} path: repo current: true --- # ... Navigate to `${{ github.workspace }}/repo/packages/api` and run analysis only on that package. ``` ### Checking Out Multiple Repositories [Section titled “Checking Out Multiple Repositories”](#checking-out-multiple-repositories) Compare quality trends across related repos: ```aw --- checkout: - repository: my-org/service-alpha path: alpha github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} - repository: my-org/service-beta path: beta github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} current: true # Issues created here --- # ... Compare complexity metrics between alpha/ and beta/ and create a comparative report issue. ``` ## Important: `current: true` and Working Directory [Section titled “Important: current: true and Working Directory”](#important-current-true-and-working-directory) `current: true` tells the agent which repository to treat as the primary target for GitHub operations (issue creation, PR references). It does **not** automatically change the working directory. Always include an explicit `cd` in the prompt: ```plaintext cd ${{ github.workspace }}/repo ``` Without it, the agent starts in `$GITHUB_WORKSPACE` (the side repo) and may analyze the wrong directory. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) — Side repository pattern and other topologies * [Triage from Side Repo](/gh-aw/examples/multi-repo/triage-from-side-repo/) — Issue triage from a side repo * [Cross-Repository Operations](/gh-aw/reference/cross-repository/) — Checkout configuration and `current: true` * [Authentication](/gh-aw/reference/auth/) — PAT and GitHub App setup * [Safe Outputs](/gh-aw/reference/safe-outputs/) — Issue creation with `max` and labels # Dependabot Rollout > Roll out a customized Dependabot configuration across many repositories using an orchestrator and worker workflow pair from a central control repository. This example shows how to roll out a new Dependabot configuration across 100 repositories using the [central control plane pattern](/gh-aw/patterns/multi-repo-ops/#the-central-control-plane-pattern-org-wide-rollouts). An **orchestrator** workflow filters and prioritizes target repositories, then dispatches a **worker** workflow that analyzes each repo and creates an intelligently customized pull request. Both workflows live in a single private control repository. ## How It Works [Section titled “How It Works”](#how-it-works) ``` flowchart LR subgraph central["Central control repo"] schedule([Weekly schedule]) --> orch[Orchestrator\nfilter & prioritize] end orch -->|dispatch_workflow| w1[Worker: Repo A\ncreate PR] orch -->|dispatch_workflow| w2[Worker: Repo B\ncreate PR] orch -->|dispatch_workflow| w3[Worker: Repo N\ncreate PR] ``` 1. The orchestrator runs weekly, scans org repos, skips ones that already have Dependabot configured, and dispatches up to 5 workers per run. 2. Each worker checks out the target repo, analyzes its structure, and creates a customized `dependabot.yml` pull request — or opens an issue if Renovate or other conflicts are detected. ## Setup [Section titled “Setup”](#setup) ### 1. Create the Orchestrator [Section titled “1. Create the Orchestrator”](#1-create-the-orchestrator) In your central control repository, create `.github/workflows/dependabot-rollout-orchestrator.md`: ```aw --- on: schedule: weekly on monday tools: github: github-token: ${{ secrets.GH_AW_READ_ORG_TOKEN }} toolsets: [repos] safe-outputs: dispatch-workflow: workflows: [dependabot-rollout] max: 5 --- # Dependabot Rollout Orchestrator Categorize and orchestrate Dependabot rollout across repositories. **Target repos**: All repos in the organization ## Task 1. **Filter** - Parse repos (from input or variable), check each for existing `.github/dependabot.yml`, keep only repos without it 2. **Categorize** - Read repo contents to assess complexity: - Simple: Single package.json, <50 dependencies, standard structure - Complex: Multiple package.json files, >100 deps, or multiple ecosystems - Conflicting: Has Renovate config or custom update scripts - Security: Open security alerts or public with dependencies 3. **Prioritize** - Order repos by rollout preference: simple → security → complex → conflicting 4. **Dispatch** - Dispatch `dependabot-rollout` worker for every prioritized repository 5. **Summarize** - Report total candidates, categorization breakdown, selected repos with rationale ``` Compile this workflow: `gh aw compile`. Then create the `GH_AW_READ_ORG_TOKEN` secret — a fine-grained PAT with `Contents: Read-only` scoped to all target repositories. See [Authentication](/gh-aw/reference/auth/) for PAT and GitHub App setup. ### 2. Create the Worker [Section titled “2. Create the Worker”](#2-create-the-worker) Create the worker workflow `.github/workflows/dependabot-rollout.md` in the same central repository. It checks out each target repo via `checkout:` and creates a customized PR (or issue) via cross-repo safe outputs: ````aw --- on: workflow_dispatch: inputs: target_repo: description: 'Target repository (owner/repo format)' required: true type: string run-name: Dependabot rollout for ${{ github.event.inputs.target_repo }} concurrency: group: gh-aw-${{ github.workflow }}-${{ github.event.inputs.target_repo }} engine: concurrency: group: gh-aw-copilot-${{ github.workflow }}-${{ github.event.inputs.target_repo }} checkout: repository: ${{ github.event.inputs.target_repo }} github-token: ${{ secrets.ORG_REPO_CHECKOUT_TOKEN }} current: true permissions: contents: read issues: read pull-requests: read tools: github: github-token: ${{ secrets.GH_AW_READ_ORG_TOKEN }} toolsets: [repos] safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: ${{ github.event.inputs.target_repo }} title-prefix: '[dependabot] ' max: 1 create-issue: target-repo: ${{ github.event.inputs.target_repo }} title-prefix: '[dependabot-config] ' max: 1 --- # Intelligent Dependabot Configuration You are creating a **customized** Dependabot configuration based on analyzing this specific repository. **Target Repository**: ${{ github.event.inputs.target_repo }} ## Why AI is Required You must analyze the repository structure and create an intelligent, customized configuration - not a generic template. ## Step 1: Analyze Repository **Check for conflicts:** - Does `.github/dependabot.yml` already exist? → Stop, create issue explaining it exists - Does `.github/renovate.json` or `renovate.json` exist? → Create issue about migrating from Renovate - Are there custom dependency update scripts? → Create issue suggesting Dependabot alternative **Analyze package manager complexity:** For **npm** (if package.json exists): - Count total dependencies (dependencies + devDependencies) - Check for monorepo: Are there multiple package.json files in subdirectories? - Simple: <20 dependencies, single package.json - Complex: >100 dependencies OR monorepo structure For **Python** (requirements.txt, setup.py, pyproject.toml): - Count dependencies - Check for multiple requirement files For **Go** (go.mod): - Note if present For **GitHub Actions** (.github/workflows/*.yml): - Count workflow files **Security context:** - Use GitHub tools to check for open security alerts - If critical alerts exist, prioritize security updates ## Step 2: Create Customized Configuration Based on your analysis, create an appropriate config: ### Simple Repository (<20 npm deps, no monorepo) ```yaml version: 2 updates: - package-ecosystem: "npm" directory: "/" schedule: interval: "daily" # Low complexity = more frequent - package-ecosystem: "github-actions" directory: "/" schedule: interval: "weekly" ``` ### Complex Repository (>100 deps OR security alerts) ```yaml version: 2 updates: - package-ecosystem: "npm" directory: "/" schedule: interval: "weekly" # High complexity = less frequent groups: production: patterns: ["*"] exclude-patterns: ["@types/*", "@jest/*"] dev-dependencies: patterns: ["@types/*", "@jest/*", "eslint*"] ``` ### Monorepo (multiple package.json) ```yaml version: 2 updates: - package-ecosystem: "npm" directory: "/packages/frontend" schedule: interval: "weekly" - package-ecosystem: "npm" directory: "/packages/backend" schedule: interval: "weekly" ``` ## Step 3: Deliver Configuration **If config is straightforward (no Renovate conflict):** - Create `.github/dependabot.yml` with your customized config - Create pull request with: - Title: "[dependabot] Add customized Dependabot configuration" - Body explaining: dependency count, why weekly vs daily, grouping strategy, etc. **If Renovate detected:** - Create issue explaining migration benefits and proposed config - Include generated config in issue body **If no package managers found:** - Create issue: "No supported package managers detected" ## Key: Explain Your Reasoning In the PR/issue body, explain **why** you chose this specific configuration (not a generic template). ```` Compile: `gh aw compile`. ### 3. Create Secrets [Section titled “3. Create Secrets”](#3-create-secrets) Create two fine-grained PATs scoped to target repositories (see [Authentication](/gh-aw/reference/auth/) for full setup): | Secret | Permissions | Purpose | | ------------------------- | ---------------------------------------------------------- | ----------------------------------------- | | `ORG_REPO_CHECKOUT_TOKEN` | `Contents: Read & write`, `Actions: Read & write` | Checkout target repos | | `GH_AW_CROSS_REPO_PAT` | `Contents: Write`, `Issues: Write`, `Pull Requests: Write` | Create PRs and issues | | `GH_AW_READ_ORG_TOKEN` | `Contents: Read-only` | Read org repos in orchestrator and worker | ## Running the Rollout [Section titled “Running the Rollout”](#running-the-rollout) After setup, the orchestrator runs automatically every Monday, processing up to 5 repositories per run. To trigger manually: ```bash gh workflow run dependabot-rollout-orchestrator.lock.yml ``` Track progress by reviewing the Actions runs and the PRs created in each target repository. ## Best Practices [Section titled “Best Practices”](#best-practices) * Keep `max: 5` on the orchestrator during initial rollout; increase once you’ve validated the worker output * Add `[dependabot]` title-prefix to make PRs easy to filter across repositories * Use `concurrency` groups to prevent duplicate worker runs for the same target repo * Review a few worker PRs manually before trusting the full automation ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) — Central control plane pattern and other topologies * [Feature Synchronization](/gh-aw/examples/multi-repo/feature-sync/) — Upstream-to-downstream sync example * [Cross-Repository Issue Tracking](/gh-aw/examples/multi-repo/issue-tracking/) — Hub-and-spoke tracking example * [Cross-Repository Operations](/gh-aw/reference/cross-repository/) — Checkout and `target-repo` configuration * [Authentication](/gh-aw/reference/auth/) — PAT and GitHub App setup * [Safe Outputs](/gh-aw/reference/safe-outputs/) — Secure write operations # Feature Synchronization > Synchronize features from a main repository to sub-repositories or downstream services with automated pull requests. Feature synchronization workflows propagate changes from a main repository to related sub-repositories, ensuring downstream projects stay current with upstream improvements while maintaining proper change tracking through pull requests. ## When to Use [Section titled “When to Use”](#when-to-use) Use feature sync when maintaining related projects in separate repositories (monorepo alternative), propagating library updates to dependent projects, updating platform-specific repos after core changes, or keeping downstream forks synchronized with upstream. ## How It Works [Section titled “How It Works”](#how-it-works) ``` flowchart LR subgraph upstream["Upstream repo"] push([Push to main]) --> agent[Sync agent] end agent -->|create-pull-request| ds1[downstream-service] agent -->|create-pull-request| ds2[api-service] agent -->|create-pull-request| ds3[mobile-backend] ``` The workflow monitors specific paths in the main repository and creates pull requests in target repositories when changes occur, adapting the changes for each target’s structure while maintaining full audit trails. ## Basic Feature Sync [Section titled “Basic Feature Sync”](#basic-feature-sync) Synchronize changes from shared directory to downstream repository: ```aw --- on: push: branches: [main] paths: - 'shared/**' permissions: contents: read actions: read tools: github: toolsets: [repos] edit: bash: - "git:*" safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/downstream-service" title-prefix: "[sync] " labels: [auto-sync, upstream-update] reviewers: [team-lead] draft: true --- # Sync Shared Components to Downstream Service When shared components change, synchronize them to `myorg/downstream-service`. Review the git diff, read current versions from the target repo, adapt paths if needed, and create a PR with descriptive commit messages linking to original commits. Include structural adaptations and migration notes for breaking changes. ``` ## Multi-Target Sync [Section titled “Multi-Target Sync”](#multi-target-sync) Synchronize to multiple repositories simultaneously: ```aw --- on: push: branches: [main] paths: - 'core/**' permissions: contents: read actions: read tools: github: toolsets: [repos] edit: bash: - "git:*" safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: max: 3 title-prefix: "[core-sync] " labels: [automated-sync] draft: true --- # Sync Core Library to All Services When core library files change, create PRs in dependent services (`myorg/api-service`, `myorg/web-frontend`, `myorg/mobile-backend`). For each target, check if they use the changed modules, adapt imports/paths, and create a PR with compatibility notes and links to source commits. ``` ## Release-Based Sync [Section titled “Release-Based Sync”](#release-based-sync) Synchronize when new releases are published: ```aw --- on: release: types: [published] permissions: contents: read actions: read tools: github: toolsets: [repos] edit: bash: - "git:*" safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/production-service" title-prefix: "[upgrade] " labels: [version-upgrade, auto-generated] reviewers: [release-manager] draft: false --- # Upgrade Production Service to New Release When a new release is published (version ${{ github.event.release.tag_name }}), create an upgrade PR that updates version references, applies API changes from release notes, updates configuration for breaking changes, and includes a migration guide with testing recommendations. ``` ## Selective File Sync [Section titled “Selective File Sync”](#selective-file-sync) Synchronize only specific file types or patterns: ```aw --- on: push: branches: [main] paths: - 'types/**/*.ts' - 'interfaces/**/*.ts' permissions: contents: read actions: read tools: github: toolsets: [repos] edit: bash: - "git:*" safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/client-sdk" title-prefix: "[types] " labels: [type-definitions] draft: true --- # Sync TypeScript Type Definitions Synchronize TypeScript type definitions to client SDK. Identify changed `.ts` files in `types/` and `interfaces/`, update them in `myorg/client-sdk` while preserving client-specific extensions, validate no breaking changes, and document any compatibility concerns. ``` ## Bidirectional Sync with Conflict Detection [Section titled “Bidirectional Sync with Conflict Detection”](#bidirectional-sync-with-conflict-detection) Handle bidirectional synchronization with conflict awareness: ```aw --- on: push: branches: [main] paths: - 'shared-config/**' permissions: contents: read actions: read tools: github: toolsets: [repos, pull_requests] edit: bash: - "git:*" safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/sister-project" title-prefix: "[config-sync] " labels: [config-update, needs-review] draft: true --- # Bidirectional Config Sync Synchronize shared configuration between this project and `myorg/sister-project`, which may be modified independently. Compare timestamps and change history; if conflicts are detected, create a PR marked for manual review with conflict notes. If no conflict, apply changes automatically and record sync timestamp. ``` ## Feature Branch Sync [Section titled “Feature Branch Sync”](#feature-branch-sync) Synchronize feature branches between repositories: ```aw --- on: pull_request: types: [opened, synchronize] branches: - 'feature/**' permissions: contents: read pull-requests: read actions: read tools: github: toolsets: [repos, pull_requests] edit: bash: - "git:*" safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/integration-tests" title-prefix: "[feature-test] " labels: [feature-branch, auto-sync] draft: true --- # Sync Feature Branch for Integration Testing When feature branch ${{ github.event.pull_request.head.ref }} (PR #${{ github.event.pull_request.number }}) is updated, create a matching branch in the integration test repo, sync relevant changes, update test configurations, and create a PR linking to the source with test scenarios and integration points. ``` ## Scheduled Sync Check [Section titled “Scheduled Sync Check”](#scheduled-sync-check) Regularly check for sync drift and create catch-up PRs: ```aw --- on: weekly on monday permissions: contents: read actions: read tools: github: toolsets: [repos, pull_requests] edit: bash: - "git:*" safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: "myorg/downstream-fork" title-prefix: "[weekly-sync] " labels: [scheduled-sync] draft: true --- # Weekly Sync Check Check for accumulated changes needing synchronization to downstream fork. Find the last sync PR, identify all commits since then, categorize changes (features, fixes, docs), and create a comprehensive PR grouping commits by category with breaking changes highlighted and migration guidance. ``` ## Authentication Setup [Section titled “Authentication Setup”](#authentication-setup) Cross-repo sync workflows require authentication via PAT or GitHub App. ### PAT Configuration [Section titled “PAT Configuration”](#pat-configuration) Create a PAT with `repo`, `contents: write`, and `pull-requests: write` permissions, then store it as a repository secret: ```bash gh aw secrets set GH_AW_CROSS_REPO_PAT --value "ghp_your_token_here" ``` ### GitHub App Configuration [Section titled “GitHub App Configuration”](#github-app-configuration) For enhanced security, use GitHub App installation tokens. See [Using a GitHub App for Authentication](/gh-aw/reference/auth/#using-a-github-app-for-authentication) for complete configuration including repository scoping options. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MultiRepoOps Design Pattern](/gh-aw/patterns/multi-repo-ops/) - Complete multi-repo overview * [Cross-Repo Issue Tracking](/gh-aw/examples/multi-repo/issue-tracking/) - Issue management patterns * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Pull request configuration * [GitHub Tools](/gh-aw/reference/github-tools/) - Repository access tools # Cross-Repository Issue Tracking > Centralize issue tracking across multiple repositories with automated tracking issue creation and status synchronization. Cross-repository issue tracking enables organizations to maintain a centralized view of work across multiple component repositories. When issues are created in component repos, tracking issues are automatically created in a central repository, providing visibility without requiring direct access to all repositories. ## When to Use [Section titled “When to Use”](#when-to-use) Use cross-repo issue tracking for component-based architectures where multiple teams need centralized visibility, when tracking external dependencies, coordinating cross-project initiatives, or aggregating metrics from distributed repositories. ## How It Works [Section titled “How It Works”](#how-it-works) ``` flowchart LR subgraph comp["Component repos"] ev1([Issue opened component-alpha]) --> agent1[Tracking agent] ev2([Issue opened component-beta]) --> agent2[Tracking agent] end agent1 -->|create-issue| central[central-tracker] agent2 -->|create-issue| central ``` Workflows in component repositories create tracking issues in a central repository when local issues are opened, updated, or closed. The central repository maintains references to all component issues, enabling organization-wide visibility and reporting. ## Basic Tracking Issue Creation [Section titled “Basic Tracking Issue Creation”](#basic-tracking-issue-creation) Create tracking issues in central repository when component issues are opened: ``` flowchart LR subgraph comp["component-alpha"] ev([Issue opened]) --> agent[Tracking agent] end agent -->|create-issue| central["central-tracker\n[component-alpha] ..."] ``` ```aw --- on: issues: types: [opened] permissions: contents: read actions: read tools: github: toolsets: [issues] safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: target-repo: "myorg/central-tracker" title-prefix: "[component-alpha] " labels: [from-component-alpha, tracking-issue] --- # Create Central Tracking Issue When an issue is opened in component-alpha, create a corresponding tracking issue in the central tracker. **Original issue:** ${{ github.event.issue.html_url }} **Issue number:** ${{ github.event.issue.number }} **Content:** "${{ steps.sanitized.outputs.text }}" Create tracking issue with link to original, component identifier, summary, suggested priority, and labels `from-component-alpha` and `tracking-issue`. ``` ## Status Synchronization [Section titled “Status Synchronization”](#status-synchronization) Update tracking issues when component issues change status: ``` flowchart LR subgraph comp["component-alpha"] ev(["Issue closed /\nreopened / labeled"]) --> agent[Tracking agent] end agent -->|find tracking issue| central[central-tracker] agent -->|add-comment| central ``` ```aw --- on: issues: types: [closed, reopened, labeled, unlabeled] permissions: contents: read actions: read tools: github: toolsets: [issues] safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} add-comment: target-repo: "myorg/central-tracker" target: "*" # Find related tracking issue --- # Update Central Tracking Issue Status When this component issue changes status, update the central tracking issue. **Original issue:** ${{ github.event.issue.html_url }} **Action:** ${{ github.event.action }} Search for tracking issue in `myorg/central-tracker` and add comment with status update (✓ resolved, reopened, or label changes), issue link, and timestamp. ``` ## Multi-Component Tracking [Section titled “Multi-Component Tracking”](#multi-component-tracking) Track issues that span multiple component repositories: ``` flowchart LR subgraph comp["Component repos"] ev([Cross-component\nissue opened]) --> agent[Tracking agent] end agent -->|create-issue primary| central[central-tracker] agent -->|create-issue child| a[component-alpha] agent -->|create-issue child| b[component-beta] ``` ```aw --- on: issues: types: [opened] # Triggered when issue has 'cross-component' label permissions: contents: read actions: read tools: github: toolsets: [issues] safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: max: 3 # May create issues in multiple tracking repos target-repo: "myorg/central-tracker" title-prefix: "[cross-component] " labels: [cross-component, needs-coordination] --- # Track Cross-Component Issues When an issue is marked as cross-component, create coordinated tracking issues. **Original issue:** ${{ github.event.issue.html_url }} Identify affected components, create primary tracking issue in central tracker with affected components list and coordination requirements, and create child issues in component repos if needed. Tag team leads and schedule coordination meeting for high-priority issues. ``` ## External Dependency Tracking [Section titled “External Dependency Tracking”](#external-dependency-tracking) Track issues from external/upstream repositories: ``` flowchart LR subgraph trigger["Manual trigger"] ev([workflow_dispatch\nexternal URL]) --> agent[Tracking agent] end agent -->|web-fetch| ext[External issue] agent -->|create-issue| tracker["dependency-tracker\n[upstream] ..."] ``` ```aw --- on: workflow_dispatch: inputs: external_issue_url: description: 'URL of external issue to track' required: true type: string permissions: contents: read tools: github: toolsets: [issues] web-fetch: safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: target-repo: "myorg/dependency-tracker" title-prefix: "[upstream] " labels: [external-dependency, upstream-issue] --- # Track External Dependency Issue Create tracking issue for external dependency problem. **External issue URL:** ${{ github.event.inputs.external_issue_url }} Fetch external issue details, identify affected internal projects, and create tracking issue with external link, status, impact assessment, affected repositories, and monitoring plan. Set weekly reminder and notify affected teams. ``` ## Automated Triage and Routing [Section titled “Automated Triage and Routing”](#automated-triage-and-routing) Triage component issues and route to appropriate trackers: ``` flowchart LR subgraph comp["component-alpha"] ev([Issue opened]) --> agent[Triage agent] end agent -->|security| sec[security-tracker] agent -->|feature| feat[feature-tracker] agent -->|bug| bugs[bug-tracker] agent -->|infra| ops[ops-tracker] ``` ```aw --- on: issues: types: [opened] permissions: contents: read actions: read tools: github: toolsets: [issues] safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: max: 2 title-prefix: "[auto-triaged] " --- # Triage and Route to Tracking Repos Analyze new issues and create tracking issues in appropriate repositories. **Original issue:** ${{ github.event.issue.html_url }} **Content:** "${{ steps.sanitized.outputs.text }}" Analyze issue severity and route to appropriate tracker: security issues to `myorg/security-tracker`, features to `myorg/feature-tracker`, bugs to `myorg/bug-tracker`, or infrastructure to `myorg/ops-tracker`. Include original link, triage reasoning, priority, affected components, and SLA targets. ``` ## Aggregated Reporting [Section titled “Aggregated Reporting”](#aggregated-reporting) Create weekly summary of tracked issues: ``` flowchart LR schedule([Weekly schedule]) --> agent[Report agent] subgraph sources["Component repos"] a[component-alpha] b[component-beta] n[component-N] end agent -->|query issues| a & b & n agent -->|create-discussion| central["central-tracker\nweekly summary"] ``` ```aw --- on: weekly on monday permissions: contents: read tools: github: toolsets: [issues] safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-discussion: target-repo: "myorg/central-tracker" category: "Status Reports" title-prefix: "[weekly] " --- # Weekly Cross-Repo Issue Summary Generate weekly summary of tracked issues across all component repositories. Summarize issues from all component repositories including open counts by priority, issues opened/closed this week, stale issues (>30 days), and blockers. Create discussion with executive summary, per-repo breakdown, trending analysis, and action items formatted as markdown table. ``` ## Bidirectional Linking [Section titled “Bidirectional Linking”](#bidirectional-linking) Maintain references between component and tracking issues: ``` flowchart LR subgraph comp["component-alpha"] ev([Issue opened]) --> agent[Tracking agent] original[original issue] end agent -->|create-issue| central["central-tracker\n[linked] ..."] agent -->|add-comment| original ``` ```aw --- on: issues: types: [opened] permissions: contents: read actions: read tools: github: toolsets: [issues] safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: target-repo: "myorg/central-tracker" title-prefix: "[linked] " add-comment: max: 1 --- # Create Tracking Issue with Bidirectional Links Create tracking issue and add comment to original with link. **Original issue:** ${{ github.event.issue.html_url }} Create tracking issue in `myorg/central-tracker` with title "[linked] ${{ github.event.issue.title }}" and body linking to original. Add comment to original issue with tracking link. This enables easy navigation, automatic GitHub reference detection, and clear audit trail. ``` ## Priority-Based Routing [Section titled “Priority-Based Routing”](#priority-based-routing) Route issues to different trackers based on priority: ``` flowchart LR subgraph comp["component-alpha"] ev(["Issue opened /\nlabeled"]) --> agent[Priority router] end agent -->|P0| inc[incidents] agent -->|P1| p1[priority-tracker] agent -->|P2| central[central-tracker] agent -->|P3| backlog[backlog] ``` ```aw --- on: issues: types: [opened, labeled] permissions: contents: read actions: read tools: github: toolsets: [issues] safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-issue: max: 1 title-prefix: "[priority-routed] " --- # Route Issues Based on Priority Route issues to appropriate tracking repository based on priority level. **Original issue:** ${{ github.event.issue.html_url }} **Labels:** Check for priority labels (P0, P1, P2, P3) Route by priority: P0 → `myorg/incidents`, P1 → `myorg/priority-tracker`, P2 → `myorg/central-tracker`, P3 → `myorg/backlog`. Include original link, priority, SLA expectations, and escalation path. For P0, alert on-call team and include incident response checklist. ``` ## Authentication Setup [Section titled “Authentication Setup”](#authentication-setup) Cross-repo issue tracking requires appropriate authentication: ### PAT Configuration [Section titled “PAT Configuration”](#pat-configuration) ```bash # Create PAT with issues and repository read permissions gh aw secrets set GH_AW_CROSS_REPO_PAT --value "ghp_your_token_here" ``` **Required Permissions:** * `repo` (for private repositories) * `public_repo` (for public repositories) ### GitHub App Configuration [Section titled “GitHub App Configuration”](#github-app-configuration) For enhanced security, use GitHub App installation tokens. See [Using a GitHub App for Authentication](/gh-aw/reference/auth/#using-a-github-app-for-authentication) for complete configuration including repository scoping options. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MultiRepoOps Design Pattern](/gh-aw/patterns/multi-repo-ops/) - Complete multi-repo overview * [Feature Synchronization](/gh-aw/examples/multi-repo/feature-sync/) - Code sync patterns * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Issue creation configuration * [GitHub Tools](/gh-aw/reference/github-tools/) - API access configuration # Triage from Side Repo > Run automated issue triage on a main repository from an isolated automation repository, with a slash-command bridge for real-time response. This example shows how to run automated triage on `my-org/main-repo` from a dedicated side repository. The side repo hosts all automation workflows; the main repo receives only the resulting labels and comments. A slash-command bridge is included for real-time `/triage` response alongside the scheduled triage run. ## How It Works [Section titled “How It Works”](#how-it-works) ``` flowchart LR subgraph side["Side repo (automation)"] schedule([Every 6h / dispatch]) --> triage[Triage agent] end triage -->|add-labels / add-comment| main[main-repo] subgraph main_repo["main-repo"] slash(["/triage comment"]) --> relay[Relay workflow] end relay -->|workflow_dispatch| triage ``` * **Scheduled triage** runs every 6 hours from the side repo, finding unlabeled issues and adding appropriate labels and a triage comment. * **Slash-command triage** is triggered by `/triage` in the main repo. Because GitHub webhooks only fire in the repository where the event occurs, a thin relay workflow in the main repo forwards the command to the side repo via `workflow_dispatch`. ## Setup [Section titled “Setup”](#setup) ### 1. Create the Side Repository [Section titled “1. Create the Side Repository”](#1-create-the-side-repository) ```bash gh repo create my-org/main-repo-automation --private gh repo clone my-org/main-repo-automation cd main-repo-automation ``` ### 2. Create the Authentication Token [Section titled “2. Create the Authentication Token”](#2-create-the-authentication-token) Create a fine-grained PAT (`GH_AW_MAIN_REPO_TOKEN`) scoped **only to `my-org/main-repo`** with these permissions: | Permission | Level | Purpose | | ---------- | ------------ | -------------------------------------- | | Issues | Read & write | Read issues, add labels and comments | | Contents | Read-only | Read repo structure (for GitHub tools) | Store it as a secret in the **side repository**: ```bash gh secret set GH_AW_MAIN_REPO_TOKEN --repo my-org/main-repo-automation ``` Note The default `GITHUB_TOKEN` cannot access other repositories. You must use this additional token for both `tools.github` and `safe-outputs`. For enhanced security, use a [GitHub App token](/gh-aw/reference/auth/#using-a-github-app-for-authentication) instead of a PAT — tokens are minted on demand and automatically revoked after each job. ### 3. Create the Scheduled Triage Workflow [Section titled “3. Create the Scheduled Triage Workflow”](#3-create-the-scheduled-triage-workflow) In the side repository, create `.github/workflows/triage.md`: ```aw --- on: every 6h permissions: contents: read safe-outputs: github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} add-labels: target-repo: "my-org/main-repo" allowed-labels: - bug - enhancement - question - documentation - good first issue - wontfix - duplicate - needs-info add-comment: target-repo: "my-org/main-repo" target: "*" tools: github: github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} toolsets: [issues] --- # Triage Main Repository Issues Find all unlabeled issues in my-org/main-repo opened in the last 7 days. For each issue: 1. Read the title and body carefully 2. Assign one primary label (bug / enhancement / question / documentation / good first issue) 3. Add a second label if clearly applicable (e.g., duplicate, needs-info, wontfix) 4. Post a brief triage comment explaining the label choice and any suggested next step Limit to 20 issues per run to avoid rate limits. ``` Compile: `gh aw compile`. ### 4. Create the Slash-Command Bridge [Section titled “4. Create the Slash-Command Bridge”](#4-create-the-slash-command-bridge) Because webhook events only fire in the repository where they occur, you need two workflows for slash-command support. **Step 1** — Relay workflow in **`my-org/main-repo`** (`.github/workflows/triage-relay.yml`): Note This is a plain GitHub Actions YAML file, not a compiled agentic workflow. Create it directly as `.yml`. ```yaml name: Triage relay on: issue_comment: types: [created] jobs: relay: if: github.event.comment.body == '/triage' && github.event.issue.pull_request == null runs-on: ubuntu-latest steps: - name: Forward to automation repo uses: actions/github-script@v7 with: github-token: ${{ secrets.GH_AW_SIDE_REPO_TOKEN }} script: | await github.rest.actions.createWorkflowDispatch({ owner: 'my-org', repo: 'main-repo-automation', workflow_id: 'triage-on-demand.lock.yml', ref: 'main', inputs: { issue_number: String(context.issue.number), issue_url: context.payload.issue.html_url, } }); ``` This relay needs a `GH_AW_SIDE_REPO_TOKEN` secret in `main-repo` — a PAT with `Actions: write` on `main-repo-automation`. **Step 2** — On-demand triage workflow in the **side repo** (`.github/workflows/triage-on-demand.md`): ```aw --- on: workflow_dispatch: inputs: issue_number: description: "Issue number to triage" required: true issue_url: description: "Issue URL for context" required: true permissions: contents: read safe-outputs: github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} add-labels: target-repo: "my-org/main-repo" allowed-labels: - bug - enhancement - question - documentation - good first issue - wontfix - duplicate - needs-info add-comment: target-repo: "my-org/main-repo" target: "${{ github.event.inputs.issue_number }}" tools: github: github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} toolsets: [issues] --- # Triage Issue on Demand Triage issue #${{ github.event.inputs.issue_number }} in my-org/main-repo. Read the issue at ${{ github.event.inputs.issue_url }}, assign the most appropriate label, and post a brief comment explaining the triage decision. ``` Compile: `gh aw compile`. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) — Side repository pattern and other topologies * [IssueOps](/gh-aw/patterns/issue-ops/) — Event-driven issue automation in the main repo * [ChatOps](/gh-aw/patterns/chat-ops/) — Slash command workflows * [Cross-Repository Operations](/gh-aw/reference/cross-repository/) — `target-repo` configuration * [Authentication](/gh-aw/reference/auth/) — PAT and GitHub App setup * [Safe Outputs](/gh-aw/reference/safe-outputs/) — Labels, comments, and allowed-labels # AWF Reflect Route > Use the AWF /reflect route to discover gateway inference endpoints and available models at runtime. Experimental The AWF `/reflect` route and its response shape are currently experimental and subject to change. Do not rely on this API for production use or in shared workflow logic. Inside the AWF runtime network, the AWF API proxy exposes `GET /reflect` at `http://api-proxy:10000/reflect`. Use this route when building shared workflows, tools, or extensions that need runtime model routing. ## Why use `/reflect` [Section titled “Why use /reflect”](#why-use-reflect) `/reflect` returns the currently configured inference providers and their model availability for the active run. This allows a shared workflow or tool to: * Discover which gateway endpoints are available * Check whether each endpoint is configured * Read or refresh model availability * Select a provider/model dynamically at runtime Caution Do not hardcode direct upstream model API URLs in shared workflow logic. All inference requests should go through the AWF gateway so usage remains controllable and observable for cost control, tracking, and optimization. ## Response shape [Section titled “Response shape”](#response-shape) The response includes an `endpoints` array and a `models_fetch_complete` flag: * `endpoints[].provider`: provider identifier (e.g., `openai`, `anthropic`, `copilot`, `gemini`) * `endpoints[].base_url`: gateway base URL for inference calls * `endpoints[].configured`: whether credentials/config are present for that provider * `endpoints[].models`: discovered model IDs, or `null` when model discovery is not yet complete * `endpoints[].models_url`: gateway URL used to query models for that provider * `models_fetch_complete`: whether startup model discovery is complete ## Recommended selection flow for shared tools [Section titled “Recommended selection flow for shared tools”](#recommended-selection-flow-for-shared-tools) 1. Query `/reflect` at start of execution. 2. Filter endpoints to `configured: true`. 3. Prefer endpoints with a non-empty `models` list. 4. Match requested model aliases/patterns against available models. 5. Route inference to the selected endpoint `base_url`. 6. If `models` is `null`, retry discovery with bounded backoff (for example, every 3 seconds up to 5 attempts) before failing. This keeps shared tooling portable across repositories and environments where available providers differ. ## Example request [Section titled “Example request”](#example-request) ```bash curl -s http://api-proxy:10000/reflect ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MCP Gateway](/gh-aw/reference/mcp-gateway/) * [Cost Management](/gh-aw/reference/cost-management/) * [Model Aliases & Multipliers](/gh-aw/reference/model-tables/) # CorrectionOps > Improve agentic workflows from trusted human corrections without retraining the underlying model Experimental CorrectionOps is an experimental pattern. The guidance and workflow shape on this page may change as the pattern is tested in more real-world workflows. CorrectionOps is a workflow pattern that improves the workflow *around* the model rather than retraining it. It stores predictions at decision time, compares them with later trusted human truth, and uses that evidence to update instructions, routing, thresholds, and rollout decisions. The basic loop: 1. Save what the workflow predicted 2. Collect what humans later decided 3. Use the difference to improve the workflow ## When to Use CorrectionOps [Section titled “When to Use CorrectionOps”](#when-to-use-correctionops) Use CorrectionOps when humans still make or correct the real decision and you want the workflow to improve iteratively — by updating instructions, routing, thresholds, or rollout state — rather than all at once. Typical fits include labeling and classification, routing and prioritization, moderation and approvals, and summaries or recommendations that humans later correct. It is especially useful when the rollout path is gradual: start with `staged: true`, keep evaluation and reporting in Ops, use corrections to improve the workflow, and promote to direct writes only when the evidence is strong enough. ## How It Works [Section titled “How It Works”](#how-it-works) A clean CorrectionOps setup has two long-lived surfaces. Production stays authoritative. Ops hosts prediction, correction intake, reporting, instruction updates, and rollout control — early on without writing back to production, later with direct writes once promoted. Most implementations reduce to three workflow classes: a thin relay that forwards stable facts into ops, a prediction workflow that persists snapshots and writes safely, and a compare/report/decide workflow that checks later human truth and updates the system when the evidence is strong enough. Keep relays, snapshot resolution, diffing, and grouping deterministic. Use the agent for semantic judgment, not for reconstructing event history or inferring provenance after the fact. ## Example: Issue Labeling [Section titled “Example: Issue Labeling”](#example-issue-labeling) ``` flowchart TB subgraph ProductionRepo[Production Repo] A[Issue or item in production] D[Later human correction in production] B[Thin relay] end subgraph OpsRepo[Ops Repo] C[Store prediction snapshot] E[Collect correction evidence] F[Build deterministic diff] G[Publish report or open instruction PR] H[Make rollout decision] end A -->|item-created event| B B --> C D -->|truth-feedback event| E C --> F E --> F F --> G G --> H H -.->|improves next run| A ``` A single CorrectionOps worker can carry the pattern when permissions and triggers fit cleanly together: ```aw --- on: schedule: daily workflow_dispatch: repository_dispatch: types: [truth-feedback] permissions: contents: read issues: read safe-outputs: create-issue: create-pull-request: --- # CorrectionOps Worker Read persisted predictions and later trusted truth, compare them deterministically, then either publish a health report or open a draft PR updating instructions. ``` Unlike Reinforcement Learning from Human Feedback (RLHF), which updates model weights, CorrectionOps changes instruction files, routing rules, deterministic checks, thresholds, or rollout decisions — no separate evaluation repository required. ### Full Workflow Pieces [Section titled “Full Workflow Pieces”](#full-workflow-pieces) The example above breaks into four pieces: #### 1. Relay In The Source Repo [Section titled “1. Relay In The Source Repo”](#1-relay-in-the-source-repo) Forwards stable facts and provenance into ops only — no diffs, no human-intent inference, no correctness decisions. prod-repo/.github/workflows/relay-correction-signals.yml ```yaml name: Relay Correction Signals on: issues: types: [opened, labeled, unlabeled] jobs: relay: runs-on: ubuntu-latest steps: - name: Forward stable facts to ops uses: actions/github-script@v8 with: github-token: ${{ secrets.OPS_DISPATCH_TOKEN }} script: | await github.rest.repos.createDispatchEvent({ owner: 'org', repo: 'ops-repo', event_type: context.payload.action === 'opened' ? 'item-created' : 'truth-feedback', client_payload: { data: { source_repository: `${context.repo.owner}/${context.repo.repo}`, source_type: 'issue', item_number: context.payload.issue.number, item_title: context.payload.issue.title, item_url: context.payload.issue.html_url, event_type: context.payload.action, label: context.payload.label?.name || null, actor: context.actor, actor_type: context.actor.endsWith('[bot]') ? 'bot' : 'human', occurred_at: new Date().toISOString(), }, }, }); ``` #### 2. Prediction Workflow In Ops [Section titled “2. Prediction Workflow In Ops”](#2-prediction-workflow-in-ops) Consumes normalized inputs, applies the current instructions, and persists a durable snapshot for later comparison. ops-repo/.github/workflows/predict-items.md ```aw --- name: Predict Items on: schedule: daily workflow_dispatch: repository_dispatch: types: [item-created] tools: github: toolsets: [issues, repos] safe-outputs: create-issue: update-issue: --- # Predict Items Read prepared items from `/tmp/gh-aw/agent/item-scan`, apply the current instructions, write review artifacts through safe outputs in Ops, and append a prediction snapshot containing the source identifier, predicted action, instruction version, and timestamp. ``` #### 3. Compare, Report, And Decide In Ops [Section titled “3. Compare, Report, And Decide In Ops”](#3-compare-report-and-decide-in-ops) Reads predictions and later human truth, builds deterministic diffs first, then asks the agent to summarize patterns or propose instruction updates. ops-repo/.github/workflows/review-corrections.md ```aw --- name: Review Corrections on: schedule: weekly workflow_dispatch: inputs: mode: description: report or adaptation required: false default: report type: choice options: [report, adaptation] safe-outputs: create-issue: create-pull-request: --- # Review Corrections Read `correction-diffs.json` from `/tmp/gh-aw/agent/correction-review`. In `report` mode, publish a health summary. In `adaptation` mode, open a draft PR updating the instruction file only when the grouped evidence is strong enough. ``` #### 4. Optional Deterministic Collector [Section titled “4. Optional Deterministic Collector”](#4-optional-deterministic-collector) Add a separate collector when the later-truth boundary needs its own trigger, permissions, or serialized write path. ops-repo/.github/workflows/collect-corrections.yml ```yaml name: Collect Corrections on: repository_dispatch: types: [truth-feedback] jobs: collect: runs-on: ubuntu-latest steps: - name: Resolve authoritative truth and store correction evidence run: ./scripts/store-correction-evidence.sh ``` ### Stable Contracts To Define First [Section titled “Stable Contracts To Define First”](#stable-contracts-to-define-first) Before adding rollout logic or adaptation prompts, define four small deterministic contracts: 1. relay payload: the minimal source identity, object identity, event type, actor facts, and timestamps forwarded into ops 2. prediction snapshot: the durable record of what the workflow predicted and under which instruction version 3. correction review input: the deterministic diff artifact used by reporting and adaptation 4. rollout gate contract: what evidence or approvals are required before direct production writes are enabled The production object changes across use cases, but the CorrectionOps shape does not. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Staged Mode](/gh-aw/reference/staged-mode/) for the optional safe-write rollout guidance inside CorrectionOps * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) for separating workflow infrastructure from the production repository * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) for coordinating workflows across repository boundaries * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) for controlling write targets and protections * [GitHub Tools](/gh-aw/reference/github-tools/) for cross-repository reads and operations # Monitoring with Projects > Use GitHub Projects + safe-outputs to track and monitor workflow work items and progress. Experimental The monitoring with projects pattern is experimental and subject to change. Use this pattern when you want a durable “source of truth” for what your agentic workflows discovered, decided, and did. ## What this pattern is [Section titled “What this pattern is”](#what-this-pattern-is) * **Projects** are the dashboard: a GitHub Projects v2 board holds issues/PRs and custom fields. * **Monitoring** is the behavior: workflows continuously add/update items, and periodically post status updates. ## Building blocks [Section titled “Building blocks”](#building-blocks) ### 1) Track items with `update-project` [Section titled “1) Track items with update-project”](#1-track-items-with-update-project) Enable the safe output and point it at your project URL: ```yaml safe-outputs: update-project: project: https://github.com/orgs/myorg/projects/123 max: 10 github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} ``` * Adds issues/PRs to the board and updates custom fields. * Can also create views and custom fields when configured. See the full reference: [/reference/safe-outputs/#project-board-updates-update-project](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) ### 2) Post run summaries with `create-project-status-update` [Section titled “2) Post run summaries with create-project-status-update”](#2-post-run-summaries-with-create-project-status-update) Use project status updates to communicate progress and next steps: ```yaml safe-outputs: create-project-status-update: project: https://github.com/orgs/myorg/projects/123 max: 1 github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} ``` This is useful for scheduled workflows (daily/weekly) or orchestrator workflows. See the full reference: [/reference/safe-outputs/#project-status-updates-create-project-status-update](/gh-aw/reference/safe-outputs/#project-status-updates-create-project-status-update) ### 3) Correlate work with a Tracker Id field [Section titled “3) Correlate work with a Tracker Id field”](#3-correlate-work-with-a-tracker-id-field) If you want to correlate multiple runs, add a custom field like **Tracker Id** (text) and populate it from your workflow prompt/output (for example, a run ID, issue number, or “initiative” key). ## Run failure issues [Section titled “Run failure issues”](#run-failure-issues) When a workflow run fails, the system automatically posts a failure notification on the triggering issue or pull request. To track failures as searchable GitHub issues, enable `create-issue` in `safe-outputs`: ```yaml safe-outputs: create-issue: title-prefix: "[failed] " labels: [automation, failed] ``` The issue body includes the workflow name, run URL, and failure status, making it easy to find and triage recurring failures. ### Grouping failures as sub-issues [Section titled “Grouping failures as sub-issues”](#grouping-failures-as-sub-issues) When multiple workflow runs fail, the `group-reports` option links each failure report as a sub-issue under a shared parent issue titled “\[aw] Failed runs”. This is useful for scheduled or high-frequency workflows where failures can accumulate. ```yaml safe-outputs: create-issue: title-prefix: "[failed] " labels: [automation, failed] group-reports: true # Group failure reports under a shared parent issue (default: false) ``` When `group-reports` is enabled: * A parent “\[aw] Failed runs” issue is automatically created and managed. * Each failure run report is linked as a sub-issue under the parent. * Up to 64 sub-issues are tracked per parent issue. See the full reference: [/reference/safe-outputs/#group-reports-group-reports](/gh-aw/reference/safe-outputs/#group-reports-group-reports) ## No-op run reports [Section titled “No-op run reports”](#no-op-run-reports) When an agent determines that no action is needed (for example, no issues were found), it outputs a no-op message. By default, this message is posted as a comment on the triggering issue or pull request, keeping a visible record of runs that intentionally did nothing. To disable posting no-op messages as issue comments: ```yaml safe-outputs: create-issue: noop: report-as-issue: false # Disable posting noop messages as issue comments ``` No-op messages still appear in the workflow step summary even when `report-as-issue` is `false`. To disable the no-op output entirely: ```yaml safe-outputs: create-issue: noop: false # Disable noop output completely ``` See the full reference: [/reference/safe-outputs/#no-op-logging-noop](/gh-aw/reference/safe-outputs/#no-op-logging-noop) ## Operational monitoring [Section titled “Operational monitoring”](#operational-monitoring) Use `gh aw status` to see which workflows are enabled and their latest run state. For deeper investigation, the audit commands are the primary monitoring tool for agentic workflows: * `gh aw audit ` — single-run report with tool usage, MCP failures, firewall activity, and cost metrics * `gh aw audit ` — compare two runs to detect behavioral regressions or new network accesses (pass additional IDs to compare base against multiple runs) * `gh aw logs --format markdown [workflow]` — cross-run security and performance report for trend monitoring ```bash # Audit the most recent run gh aw audit 12345678 # Compare two runs for regressions gh aw audit 12345678 12345679 # Compare base against multiple runs at once gh aw audit 12345678 12345679 12345680 # Trend report across the last 10 runs of a workflow gh aw logs my-workflow --format markdown --count 10 ``` Tip Use `gh aw logs --format markdown` inside a scheduled workflow agent to automate trend monitoring and surface cost or security regressions without manual intervention. See [Audit Commands](/gh-aw/reference/audit/) for full flag documentation, and [CLI Reference](/gh-aw/setup/cli/) for all available commands. # OpenTelemetry > Use OpenTelemetry in GitHub Agentic Workflows for enterprise-scale observability: export workflow traces to OTLP backends and inspect telemetry without leaning on GitHub API-heavy workflows. Experimental This guide is experimental. The recommended backend integrations, shared imports, and setup flow on this page may change as the observability story is tested across more real-world workflows. Observability in GitHub Agentic Workflows often begins with inspecting a single run. That is usually enough at first, but it breaks down once you need retained telemetry, visibility across runs, and a way to investigate without repeatedly spending GitHub API quota or running into rate limits. OpenTelemetry is the standard way to do that. It lets you export workflow traces through the [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/reference/specification/protocol/otlp/) to backends such as Datadog, Grafana, or Sentry, and read telemetry back through MCP when agents need to investigate. Most workflows should use either write-side OTLP or read-side MCP. Use both only when you need to correlate newly emitted spans with traces already in the backend. ## Choose a backend [Section titled “Choose a backend”](#choose-a-backend) OpenTelemetry gives you a standard way to export workflow traces. The main choice is which backend should receive and surface that telemetry. * **Datadog** is a strong fit when workflow telemetry needs to plug into broader operational monitoring and service health. * **Grafana** is a strong fit for teams that want an OpenTelemetry-first stack for traces, dashboards, and investigation. * **Sentry** is a strong fit when workflow telemetry should live next to application errors and performance debugging. ## Write telemetry through OTLP [Section titled “Write telemetry through OTLP”](#write-telemetry-through-otlp) This is configured with [`observability.otlp`](/gh-aw/reference/frontmatter/#observability-observability) in workflow frontmatter: * Datadog .github/workflows/daily-report.md ```aw --- network: allowed: - "*.datadoghq.com" - "*.datadoghq.eu" - "*.ddog-gov.com" observability: otlp: endpoint: - url: ${{ secrets.GH_AW_OTEL_DATADOG_ENDPOINT }} headers: DD-API-KEY: ${{ secrets.DD_API_KEY }} --- ``` * Grafana .github/workflows/daily-report.md ```aw --- network: allowed: - "*.grafana.net" observability: otlp: endpoint: - url: ${{ secrets.GH_AW_OTEL_GRAFANA_ENDPOINT }} headers: Authorization: ${{ secrets.GH_AW_OTEL_GRAFANA_AUTHORIZATION }} --- ``` * Sentry .github/workflows/daily-report.md ```aw --- network: allowed: - "*.sentry.io" observability: otlp: endpoint: - url: ${{ secrets.GH_AW_OTEL_SENTRY_ENDPOINT }} headers: Authorization: ${{ secrets.GH_AW_OTEL_SENTRY_AUTHORIZATION }} --- ``` We also support sending to multiple OTLP endpoints in the same workflow. Use the array form when the workflow should fan out to more than one collector, for example Datadog and Grafana or Datadog and Sentry. Once configured, GitHub Agentic Workflows exports built-in workflow spans such as setup and conclusion events to the configured OTLP backend or backends, such as Datadog, Grafana, Sentry, or another OTLP-compatible system. You can also emit custom spans from your workflow code using the OpenTelemetry API and an OTLP-compatible client library in your workflow language. In the backend, those spans are available as traces for querying and drilldown. ## Read telemetry through MCP [Section titled “Read telemetry through MCP”](#read-telemetry-through-mcp) This is configured with [`mcp-servers`](/gh-aw/reference/frontmatter-full/) in workflow frontmatter. Use the read path when the agent needs to inspect telemetry that already exists in a backend such as Datadog, Grafana, Sentry, Tempo, or another OpenTelemetry-compatible system. * Datadog .github/workflows/telemetry-investigation.md ```aw --- mcp-servers: datadog: url: "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp" headers: DD_API_KEY: "${{ secrets.DD_API_KEY }}" DD_APPLICATION_KEY: "${{ secrets.DD_APPLICATION_KEY }}" DD_SITE: "${{ secrets.DD_SITE || 'datadoghq.com' }}" allowed: - search_datadog_dashboards - search_datadog_slos - search_datadog_metrics - get_datadog_metric --- ``` * Grafana .github/workflows/telemetry-investigation.md ```aw --- mcp-servers: grafana: container: "grafana/mcp-grafana" entrypointArgs: - "-t" - "stdio" - "--disable-write" allowed: - list_datasources - tempo_traceql-search - tempo_get-trace - tempo_get-attribute-names - tempo_get-attribute-values env: GRAFANA_URL: "${{ secrets.GRAFANA_URL }}" GRAFANA_SERVICE_ACCOUNT_TOKEN: "${{ secrets.GRAFANA_SERVICE_ACCOUNT_TOKEN }}" --- ``` * Sentry .github/workflows/telemetry-investigation.md ```aw --- mcp-servers: sentry: command: "npx" args: ["@sentry/mcp-server@0.33.0"] allowed: - whoami - find_organizations - find_projects - get_trace_details - search_events - search_issues env: SENTRY_ACCESS_TOKEN: ${{ secrets.SENTRY_ACCESS_TOKEN }} SENTRY_HOST: ${{ env.SENTRY_HOST || 'sentry.io' }} --- ``` In this model, the workflow does not emit new spans by itself. It gives the agent a tool that can query existing traces and spans from an external backend. > Keep both write-side OTLP configuration and read-side MCP configuration in [shared workflow files](/gh-aw/reference/imports/) and import them where needed. In this repository, that usually means [shared/otlp.md](https://github.com/github/gh-aw/blob/main/.github/workflows/shared/otlp.md) for the combined Sentry and Grafana OTLP pattern, [shared/mcp/grafana.md](https://github.com/github/gh-aw/blob/main/.github/workflows/shared/mcp/grafana.md) or [shared/mcp/datadog.md](https://github.com/github/gh-aw/blob/main/.github/workflows/shared/mcp/datadog.md) for read access, and [shared/otel-queries.md](https://github.com/github/gh-aw/blob/main/.github/workflows/shared/otel-queries.md) for the query playbook. ## Setup [Section titled “Setup”](#setup) Choose your backend here and follow the matching setup path. When many workflows need the same observability wiring, shared imports are usually the right default. * Datadog To set up Datadog as an OTLP write backend and an MCP read source, follow these steps. Datadog uses one OTLP endpoint plus `DD_API_KEY` for write, and `DD_API_KEY`, `DD_APPLICATION_KEY`, and `DD_SITE` for read. 1. **Choose the Datadog site you will use.** Keep write-side OTLP export and read-side MCP access pointed at the same Datadog site. Store that site in `DD_SITE`. Common values include `datadoghq.com`, `datadoghq.eu`, `ddog-gov.com`, `us5.datadoghq.com`, and `ap1.datadoghq.com`. 2. **Create a Datadog API key.** In Datadog, open `Organization Settings`, then `API Keys`, and create a key for workflow telemetry. Store it as `DD_API_KEY`. This key is used for OTLP write and is also sent to the Datadog MCP server. 3. **Create a Datadog application key.** In Datadog, open `Organization Settings`, then `Application Keys`, and create a key for read-side investigation workflows. Store it as `DD_APPLICATION_KEY`. The MCP configuration needs this key in addition to `DD_API_KEY`. 4. **Store the OTLP endpoint for the same site.** Get the Datadog OTLP traces endpoint for the site selected in step 1 and store it as `GH_AW_OTEL_DATADOG_ENDPOINT`. Keep `GH_AW_OTEL_DATADOG_ENDPOINT`, `DD_API_KEY`, `DD_APPLICATION_KEY`, and `DD_SITE` aligned to the same Datadog account and site. 5. **Run one workflow to write and one workflow to read.** Trigger a workflow that exports spans through OTLP, then run a Datadog-backed investigation workflow that imports [shared/mcp/datadog.md](https://github.com/github/gh-aw/blob/main/.github/workflows/shared/mcp/datadog.md). If write-side OTLP and read-side MCP point at different Datadog sites, export may succeed while the investigation workflow reads the wrong account or environment. Note The Datadog MCP configuration documented here is read-side only. It gives the workflow access to dashboards, metrics, and SLOs that already exist in Datadog. OTLP export is a separate write-side configuration. * Grafana To set up Grafana as both an OTLP backend and an MCP source, follow these steps: 1. **Choose a Grafana stack.** To start, create or choose a dedicated non-production stack such as a dev, staging, or sandbox stack. If multiple stacks exist, choose one that both exposes OTLP connection details for trace ingestion and is the Grafana instance whose Tempo datasource should be queried by workflows. 2. **Get the OTLP write credentials.** Open the selected stack and get to the OpenTelemetry setup page. Depending on where Grafana sends you, this is usually either the Grafana Cloud Portal OpenTelemetry tile with `Configure`, or the Grafana app UI under `Connections`, `Add new connection`, and `OpenTelemetry (OTLP)`. Copy the generated OTLP endpoint and authorization header values. Map those values to gh-aw secrets as follows: `GH_AW_OTEL_GRAFANA_ENDPOINT` should be the value shown for `OTEL_EXPORTER_OTLP_ENDPOINT`, and `GH_AW_OTEL_GRAFANA_AUTHORIZATION` should be the value used in the `Authorization` header, typically `Basic ...`. Use only the header value for `GH_AW_OTEL_GRAFANA_AUTHORIZATION`. gh-aw adds the `Authorization:` header name when compiling the workflow. 3. **Get the Grafana read credentials.** In Grafana for the same stack, open `Administration`, go to `Users and access`, then `Service accounts`, create a service account for workflow telemetry queries, and add a token for it. Map those values to gh-aw secrets as follows: `GRAFANA_URL` should be the base URL of the selected stack, typically `https://.grafana.net`, and `GRAFANA_SERVICE_ACCOUNT_TOKEN` should be the generated service account token. Start with a read-oriented role such as `Viewer`. If the token can connect to Grafana but cannot query traces, the next thing to check is datasource or Tempo permissions for that service account. 4. **Store all four values for the same stack.** For a Grafana-backed workflow, `GH_AW_OTEL_GRAFANA_ENDPOINT`, `GH_AW_OTEL_GRAFANA_AUTHORIZATION`, `GRAFANA_URL`, and `GRAFANA_SERVICE_ACCOUNT_TOKEN` must all point to the same stack. It is normal for the write-side and read-side credentials to be different values. Grafana OTLP write uses `GH_AW_OTEL_GRAFANA_AUTHORIZATION`, while Grafana MCP read uses `GRAFANA_SERVICE_ACCOUNT_TOKEN`. #### Import a starter dashboard template [Section titled “Import a starter dashboard template”](#import-a-starter-dashboard-template) If you want a dashboard people can upload instead of building from scratch, start with [gh-aw-observability-starter.json](https://github.com/github/gh-aw/blob/main/grafana/gh-aw-observability-starter.json). Import it in Grafana with `Dashboards`, then `New`, then `Import dashboard`, upload the JSON file, and select your Tempo datasource when Grafana prompts for it. This starter focuses on the telemetry GitHub Agentic Workflows already emits today: * workflow run volume * P95 agent span duration * input and output tokens over time * cache-read token reuse * engine mix and model mix * recent matching traces for drilldown It is intentionally a first-pass operations and token-economics dashboard. Cost-versus-value, agentic-versus-deterministic, and portfolio-management views need extra outcome instrumentation in your spans, such as execution mode, accepted outcomes, escalations, or review-required markers. Caution Different credentials for write and read are expected. What must stay aligned is the backend you expect to query. If traces are written to one Grafana stack but the workflow reads from another Grafana stack, export may succeed while Grafana queries still return no current-run spans. It is also valid to write to Sentry and Grafana at the same time. In that setup, Sentry uses its own OTLP endpoint and auth, while Grafana still uses a separate OTLP auth value for write and a service account token for read. * Sentry To set up Sentry as an OTLP write backend, follow these steps. This section is write-side only. Sentry uses one OTLP endpoint plus one Sentry OTLP auth value, and there is no separate Sentry read token in this guide. If your workflow reads telemetry from another backend, that backend has its own read credentials and they are independent from the Sentry write secrets. 1. **Choose or create a Sentry project.** Start with a dedicated non-production project such as `gh-aw-dev` or `gh-aw-sandbox`. If your organization already has several Sentry projects, choose the one that should receive workflow traces from GitHub Agentic Workflows. Keep the first setup isolated from production alerting until export is working the way you expect. 2. **Open the project keys page.** In Sentry for that project, do not use the project overview or details page. Open `Project Settings`, then `Client Keys (DSN)` instead. This is the page Sentry uses for first-time setup and it is also where Sentry exposes the values needed for direct OTLP trace export. 3. **Get the OTLP write credentials.** On the same project, copy the direct OTLP traces endpoint and the authentication header Sentry provides for OpenTelemetry export. The header Sentry expects for direct OTLP traces is `x-sentry-auth`, and the value is commonly in the form `sentry sentry_key=...`. In other words, the wire format Sentry expects is `x-sentry-auth: sentry sentry_key=...`. Map those values to gh-aw secrets as follows: `GH_AW_OTEL_SENTRY_ENDPOINT` should be the direct OTLP traces endpoint for that project, and `GH_AW_OTEL_SENTRY_AUTHORIZATION` should hold only the Sentry header value, typically `sentry sentry_key=...`. Do not use the DSN itself as the OTLP endpoint. Use the direct OTLP traces URL for the project. For direct Sentry OTLP, the value is typically not `Bearer ...` or `Basic ...`. If Sentry shows you a full header expression, store only the header value in `GH_AW_OTEL_SENTRY_AUTHORIZATION`, not the header name. 4. **Store both values for the same Sentry project.** `GH_AW_OTEL_SENTRY_ENDPOINT` and `GH_AW_OTEL_SENTRY_AUTHORIZATION` must refer to the same Sentry project. Mixing an endpoint from one project with auth from another is an easy first-time setup mistake and usually results in export failures or data arriving in the wrong place. If you are splitting write and read across different systems, that does not create a second Sentry credential here. It only means Sentry keeps its write-side endpoint and auth, while the separate read backend uses its own read-side credentials. 5. **Run a workflow once and verify traces arrive in Sentry.** Trigger a workflow that imports the shared OTLP configuration, then open the same Sentry project and check the trace or performance views for a new run. If nothing arrives, the first things to check are that the secrets were copied from the correct project, the OTLP endpoint is the direct traces endpoint rather than the DSN, and the auth value was stored without the header name. ## Related documentation [Section titled “Related documentation”](#related-documentation) * [Imports](/gh-aw/reference/imports/) for bundling shared observability configuration * [Architecture](/gh-aw/introduction/architecture/#observability) for the broader runtime observability model # TrialOps > Test and validate agentic workflows in isolated trial repositories before deploying to production Experimental TrialOps features are experimental. TrialOps uses temporary trial repositories for safely validating and iterating on workflows before deployment to target repositories. The `trial` command creates isolated private repos where workflows execute and capture safe outputs (issues, PRs, comments) without affecting your actual codebase. ## How Trial Mode Works [Section titled “How Trial Mode Works”](#how-trial-mode-works) ```bash gh aw trial githubnext/agentics/weekly-research ``` The CLI creates a temporary private repository (default: `gh-aw-trial`), installs and executes the workflow via `workflow_dispatch`. Results are saved locally in `trials/weekly-research.DATETIME-ID.json`, in the trial repository on GitHub, and summarized in the console. ## Repository Modes [Section titled “Repository Modes”](#repository-modes) | Mode | Flag | Description | | ------- | ---------------------------------- | ----------------------------------------------------------------- | | Default | (none) | `github.repository` points to your repo; outputs go to trial repo | | Direct | `--repo myorg/test-repo` | Runs in specified repo; creates real issues/PRs there | | Logical | `--logical-repo myorg/target-repo` | Simulates running against specified repo; outputs in trial repo | | Clone | `--clone-repo myorg/real-repo` | Clones repo contents so workflows can analyze actual code | ## Basic Usage [Section titled “Basic Usage”](#basic-usage) ### Dry-Run Mode [Section titled “Dry-Run Mode”](#dry-run-mode) Preview what would happen without executing workflows or creating repositories: ```bash gh aw trial ./my-workflow.md --dry-run ``` ### Single Workflow [Section titled “Single Workflow”](#single-workflow) ```bash gh aw trial githubnext/agentics/weekly-research # From GitHub gh aw trial ./my-workflow.md # Local file ``` ### Multiple Workflows [Section titled “Multiple Workflows”](#multiple-workflows) Compare workflows side-by-side with combined results: ```bash gh aw trial githubnext/agentics/daily-plan githubnext/agentics/weekly-research ``` Outputs: individual result files plus `trials/combined-results.DATETIME.json`. ### Repeated Trials [Section titled “Repeated Trials”](#repeated-trials) Test consistency by running multiple times: ```bash gh aw trial githubnext/agentics/my-workflow --repeat 3 ``` ### Custom Trial Repository [Section titled “Custom Trial Repository”](#custom-trial-repository) ```bash gh aw trial githubnext/agentics/my-workflow --host-repo my-custom-trial gh aw trial ./my-workflow.md --host-repo . # Use current repo ``` ## Advanced Patterns [Section titled “Advanced Patterns”](#advanced-patterns) ### Issue Context [Section titled “Issue Context”](#issue-context) Provide issue context for issue-triggered workflows: ```bash gh aw trial githubnext/agentics/triage-workflow \ --trigger-context "https://github.com/myorg/repo/issues/123" ``` ### Append Instructions [Section titled “Append Instructions”](#append-instructions) Test workflow responses to additional constraints without modifying the source: ```bash gh aw trial githubnext/agentics/my-workflow \ --append "Focus on security issues and create detailed reports." ``` ### Cleanup Options [Section titled “Cleanup Options”](#cleanup-options) ```bash gh aw trial ./my-workflow.md --delete-host-repo-after # Delete after completion gh aw trial ./my-workflow.md --force-delete-host-repo-before # Clean slate before running ``` ## Understanding Trial Results [Section titled “Understanding Trial Results”](#understanding-trial-results) Results are saved in `trials/*.json` with workflow runs, issues, PRs, and comments viewable in the trial repository’s Actions and Issues tabs. **Result file structure:** ```json { "workflow_name": "weekly-research", "run_id": "12345678", "safe_outputs": { "issues_created": [{ "number": 5, "title": "Research quantum computing trends", "url": "https://github.com/user/gh-aw-trial/issues/5" }] }, "agentic_run_info": { "duration_seconds": 45, "token_usage": 2500 } } ``` **Success indicators:** Green checkmark, expected outputs created, no errors in logs. **Common issues:** * **Workflow dispatch failed** - Add `workflow_dispatch` trigger * **No safe outputs** - Configure safe outputs in workflow * **Permission errors** - Verify API keys * **Timeout** - Use `--timeout 60` (minutes) ## Comparing Multiple Workflows [Section titled “Comparing Multiple Workflows”](#comparing-multiple-workflows) Run multiple workflows to compare quality, quantity, performance, and consistency: ```bash gh aw trial v1.md v2.md v3.md --repeat 2 cat trials/combined-results.*.json | jq '.results[] | {workflow: .workflow_name, issues: .safe_outputs.issues_created | length}' ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) — Run workflows from separate repositories * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) - Coordinate across multiple repositories * [OrchestratorOps](/gh-aw/patterns/orchestrator-ops/) — Orchestrate multi-step initiatives * [CLI Commands](/gh-aw/setup/cli/) - Complete CLI reference * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Configuration options * [Workflow Triggers](/gh-aw/reference/triggers/) - Including workflow\_dispatch * [Security Best Practices](/gh-aw/introduction/architecture/) - Authentication and security # Agentic Authoring > More advanced techniques to author agentic workflows using agents. Using our authoring agent is an effective way to create, debug, optimize your agentic workflows. This is a continuation of the [Create Agentic Workflows](/gh-aw/setup/creating-workflows/) page. ## Configuring Your Repository [Section titled “Configuring Your Repository”](#configuring-your-repository) In order to enable the agentic authoring experience, you will need to configure your repository with a few files. Run this prompt or the `init` command. ```text Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md ``` or ```plaintext gh aw init ``` Make sure to commit and push the files to your repository. ## Using the GitHub Web Interface [Section titled “Using the GitHub Web Interface”](#using-the-github-web-interface) **If you have access to GitHub Copilot**, you can create and edit Agentic Workflows directly from the web interface. While non-interactive, it’s useful for quickly turning an idea into a working workflow. For a more interactive experience, use a coding agent (see below). Your browser doesn't support HTML5 video. [Download Create an agentic workflow from the GitHub web interface](/gh-aw/videos/create-workflow-on-github.mp4). Create an agentic workflow from the GitHub web interface Tip On the first run in a new repository, the workflow will surely fail because the secrets are not configured. The agentic workflow should detect the missing tokens and create an issue with instructions on how to configure them. ## Remixing Workflows Between Repositories [Section titled “Remixing Workflows Between Repositories”](#remixing-workflows-between-repositories) When you need to adapt an existing workflow from another repository, use the `create-agentic-agent` to perform AI-assisted migration. The agent analyzes the source workflow, identifies dependencies, adapts configuration for your repository, and validates the result. This is useful for forking workflows as starting points or one-time migrations requiring substantial changes. For synchronized updates across repositories, use [Reusing Workflows](/gh-aw/guides/packaging-imports/) with `gh aw add` instead. Example prompt for migration: ```text Migrate the release.md workflow from github/gh-aw to this repository. Adapt permissions and repository-specific references for our structure. ``` ## Debugging Workflows [Section titled “Debugging Workflows”](#debugging-workflows) Use the agentic workflows agent to diagnose and fix failing workflow runs. ### Through Copilot [Section titled “Through Copilot”](#through-copilot) If your repository is [configured for agentic authoring](#configuring-your-repository), use the `agentic-workflows` agent in Copilot Chat: ```text /agent agentic-workflows debug https://github.com/OWNER/REPO/actions/runs/RUN_ID ``` The agent audits the run, identifies the root cause (missing tools, permission errors, network blocks), and suggests targeted fixes. Tip Copy this prompt, replace `OWNER`, `REPO`, and `RUN_ID` with your values, and paste it into Copilot Chat. You can find the run URL on the GitHub Actions run page. ### Self-Contained (with URL) [Section titled “Self-Contained (with URL)”](#self-contained-with-url) For any AI assistant or coding agent, share the URL to the standalone debugging prompt: ```text Debug this workflow run using https://raw.githubusercontent.com/github/gh-aw/main/debug.md The failed workflow run is at https://github.com/OWNER/REPO/actions/runs/RUN_ID ``` Copy debug instructions The `debug.md` file is a self-contained prompt. The agent fetches it and follows the instructions to install the `gh aw` CLI, analyze logs, apply fixes, and open a pull request with the changes. ## Advanced Techniques [Section titled “Advanced Techniques”](#advanced-techniques) ### Planner [Section titled “Planner”](#planner) If you prefer to use an AI chatbot to author agentic workflows, use the [agentic-chat instructions](https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/agentic-chat.md) with any conversational AI to create clear, actionable task descriptions. Copy agentic-chat instructions Copy the instructions, paste into your AI chat, then describe your workflow goal. The assistant asks clarifying questions and generates a structured task description (wrapped in 5 backticks) ready to use in your workflow. It focuses on what needs to be done rather than how, making it ideal for creating specifications that coding agents can execute. ### Dictation [Section titled “Dictation”](#dictation) When creating agentic workflows using speech-to-text, use the [dictation instructions prompt](https://raw.githubusercontent.com/github/gh-aw/main/DICTATION.md) to correct terminology mismatches and formatting issues. Copy dictation instructions This prompt corrects terminology (e.g., “ghaw” → “gh-aw”, “work flow” → “workflow”), transforms casual speech into imperative task descriptions, removes filler words, and adds implicit context. Load it into your AI assistant before or after dictating. # Editing Workflows > Learn when you can edit workflows directly on GitHub.com versus when recompilation is required, and best practices for iterating on agentic workflows. Agentic workflows consist of two parts: the **YAML frontmatter** (compiled into the lock file; changes require recompilation) and the **markdown body** (loaded at runtime; changes take effect immediately). This lets you iterate on AI instructions without recompilation while maintaining strict control over security-sensitive configuration. See [Creating Agentic Workflows](/gh-aw/setup/creating-workflows/) for guidance on creating workflows with AI assistance. ## Editing Without Recompilation [Section titled “Editing Without Recompilation”](#editing-without-recompilation) You can edit the **markdown body** directly on GitHub.com or in any editor without recompiling. Changes take effect on the next workflow run. ### What You Can Edit [Section titled “What You Can Edit”](#what-you-can-edit) The markdown body is loaded at runtime from the original `.md` file. You can freely edit task instructions, output templates, conditional logic (“If X, then do Y”), context explanations, and examples. ### Example: Adding Instructions [Section titled “Example: Adding Instructions”](#example-adding-instructions) **Before** (in `.github/workflows/issue-triage.md`): ```markdown --- on: issues: types: [opened] --- # Issue Triage Read issue #${{ github.event.issue.number }} and add appropriate labels. ``` **After** (edited on GitHub.com): ```markdown --- on: issues: types: [opened] --- # Issue Triage Read issue #${{ github.event.issue.number }} and add appropriate labels. ## Labeling Criteria Apply these labels based on content: - `bug`: Issues describing incorrect behavior with reproduction steps - `enhancement`: Feature requests or improvements - `question`: Help requests or clarifications needed - `documentation`: Documentation updates or corrections For priority, consider: - `high-priority`: Security issues, critical bugs, blocking issues - `medium-priority`: Important features, non-critical bugs - `low-priority`: Nice-to-have improvements, minor enhancements ``` ✓ This change takes effect immediately without recompilation. ## Editing With Recompilation Required [Section titled “Editing With Recompilation Required”](#editing-with-recompilation-required) Caution Changes to the **YAML frontmatter** always require recompilation. These are security-sensitive configuration options. ### What Requires Recompilation [Section titled “What Requires Recompilation”](#what-requires-recompilation) Any changes to the frontmatter configuration between `---` markers: * **Triggers** (`on:`): Event types, filters, schedules * **Permissions** (`permissions:`): Repository access levels * **Tools** (`tools:`): Tool configurations, MCP servers, allowed tools * **Network** (`network:`): Allowed domains, firewall rules * **Safe outputs** (`safe-outputs:`): Output types, threat detection * **MCP Scripts** (`mcp-scripts:`): Custom MCP tools defined inline * **Runtimes** (`runtimes:`): Node, Python, Go version overrides * **Imports** (`imports:`): Shared configuration files * **Custom jobs** (`jobs:`): Additional workflow jobs * **Engine** (`engine:`): AI engine selection (copilot, claude, codex) * **Timeout** (`timeout-minutes:`): Maximum execution time * **Roles** (`roles:`): Permission requirements for actors ### Example: Adding a Tool (Requires Recompilation) [Section titled “Example: Adding a Tool (Requires Recompilation)”](#example-adding-a-tool-requires-recompilation) **Before**: ```yaml --- on: issues: types: [opened] --- ``` **After** (must recompile): ```yaml --- on: issues: types: [opened] tools: github: toolsets: [issues] --- ``` ! Run `gh aw compile my-workflow` before committing this change. ## Expressions and Environment Variables [Section titled “Expressions and Environment Variables”](#expressions-and-environment-variables) ### Allowed Expressions [Section titled “Allowed Expressions”](#allowed-expressions) You can safely use these expressions in markdown without recompilation: ```markdown # Process Issue Read issue #${{ github.event.issue.number }} in repository ${{ github.repository }}. Issue title: "${{ github.event.issue.title }}" Use sanitized content: "${{ steps.sanitized.outputs.text }}" Actor: ${{ github.actor }} Repository: ${{ github.repository }} ``` These expressions are evaluated at runtime and validated for security. See [Templating](/gh-aw/reference/templating/) for the complete list of allowed expressions. ### Prohibited Expressions [Section titled “Prohibited Expressions”](#prohibited-expressions) Arbitrary expressions are blocked for security. This will fail at runtime: ```markdown # ✗ WRONG - Will be rejected Run this command: ${{ github.event.comment.body }} ``` Use `steps.sanitized.outputs.text` for sanitized user input instead. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Workflow Structure](/gh-aw/reference/workflow-structure/) - Overall file organization * [Frontmatter Reference](/gh-aw/reference/frontmatter/) - All configuration options * [Markdown Reference](/gh-aw/reference/markdown/) - Writing effective instructions * [Compilation Process](/gh-aw/reference/compilation-process/) - How compilation works * [Templating](/gh-aw/reference/templating/) - Expression syntax and substitution # GitHub Actions Primer > A comprehensive guide to understanding GitHub Actions, from its history and core concepts to testing workflows and comparing with agentic workflows **GitHub Actions** is GitHub’s integrated automation platform for building, testing, and deploying code from your repository. It enables automated workflows triggered by repository events, schedules, or manual triggers — all defined in YAML files in your repository. Agentic workflows compile from markdown files into secure GitHub Actions YAML, inheriting these core concepts while adding AI-driven decision-making and enhanced security. ## Core Concepts [Section titled “Core Concepts”](#core-concepts) ### YAML Workflows [Section titled “YAML Workflows”](#yaml-workflows) A **YAML workflow** is an automated process defined in `.github/workflows/`. Each workflow consists of jobs that execute when triggered by events. Workflows must be stored on the **main** or default branch to be active and are versioned alongside your code. **Example** (`.github/workflows/ci.yml`): ```yaml name: CI on: push: branches: [main] pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - name: Run tests run: npm test ``` ### Jobs [Section titled “Jobs”](#jobs) A **job** is a set of steps that execute on the same runner (virtual machine). Jobs run in parallel by default but can depend on each other with `needs:`. Each job runs in a fresh VM, and results are shared between jobs using artifacts. Default timeout is 360 minutes for standard GitHub Actions jobs; the agent execution step in agentic workflows defaults to 20 minutes. ```yaml jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - run: npm run build test: needs: build runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - run: npm test ``` ### Steps [Section titled “Steps”](#steps) **Steps** are individual tasks within a job, running sequentially. They can execute shell commands or use pre-built actions from the GitHub Marketplace. Steps share the same filesystem and environment; a failed step stops the job by default. ```yaml steps: # Action step - uses a pre-built action - uses: actions/checkout@v6 # Run step - executes a shell command - name: Install dependencies run: npm install # Action with inputs - uses: actions/setup-node@v4 with: node-version: '20' ``` ## Security Model [Section titled “Security Model”](#security-model) ### Workflow Storage and Execution [Section titled “Workflow Storage and Execution”](#workflow-storage-and-execution) Workflows must be stored in `.github/workflows/` on the **default branch** to be active and trusted. This ensures changes undergo code review, maintains an audit trail, prevents privilege escalation from feature branches, and treats the default branch as a trust boundary. ```yaml # Workflows on main branch can access secrets on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest environment: production steps: - run: echo "Has access to production secrets" ``` ### Permission Model [Section titled “Permission Model”](#permission-model) GitHub Actions uses the **principle of least privilege** with explicit permission declarations. Fork pull requests are read-only by default; all required permissions should be explicitly declared. ```yaml permissions: contents: read # Read repository contents issues: write # Create/modify issues pull-requests: write # Create/modify PRs jobs: example: runs-on: ubuntu-latest steps: - run: echo "Job has specified permissions only" ``` With GItHub Agentic Workflows, **write permissions are not used explicitly**. Instead much more restricted capabilities to write to GitHub are declared through **safe outputs**, which validate, constrain and sanitize all GitHub API interactions. ### Secret Management [Section titled “Secret Management”](#secret-management) **Secrets** are encrypted environment variables stored at the repository, organization, or environment level. They are never exposed in logs, only accessible to workflows on default/protected branches, and scoped by environment for additional protection. ```yaml jobs: deploy: runs-on: ubuntu-latest steps: - name: Deploy to production env: API_KEY: ${{ secrets.API_KEY }} run: ./deploy.sh ``` ## Testing and Debugging Workflows [Section titled “Testing and Debugging Workflows”](#testing-and-debugging-workflows) ### Testing from Branches with workflow\_dispatch [Section titled “Testing from Branches with workflow\_dispatch”](#testing-from-branches-with-workflow_dispatch) The **`workflow_dispatch`** trigger allows manual workflow execution from any branch, invaluable for development and testing: ```yaml name: Test Workflow on: workflow_dispatch: inputs: environment: description: 'Target environment' required: true default: 'staging' type: choice options: - staging - production debug: description: 'Enable debug logging' required: false type: boolean jobs: test: runs-on: ubuntu-latest steps: - run: echo "Testing in ${{ inputs.environment }}" - run: echo "Debug mode: ${{ inputs.debug }}" ``` To run: navigate to the **Actions** tab → select your workflow → click **Run workflow** → choose your branch and provide inputs. Tip Enable debug logging by setting repository secrets `ACTIONS_STEP_DEBUG: true` and `ACTIONS_RUNNER_DEBUG: true`. **Note:** The workflow definition must be merged to the main branch before it can be executed. Only `workflow_dispatch` works on non-default branches — event triggers do not. ### Debugging Workflow Runs [Section titled “Debugging Workflow Runs”](#debugging-workflow-runs) View logs in the **Actions** tab by clicking a run, then a job, then individual steps. Use workflow commands for structured output: ```yaml steps: - name: Debug context run: | echo "::debug::Debugging workflow context" echo "::notice::This is a notice" echo "::warning::This is a warning" echo "::error::This is an error" - name: Debug environment run: | echo "GitHub event: ${{ github.event_name }}" echo "Actor: ${{ github.actor }}" printenv | sort ``` ## Agentic Workflows vs Traditional GitHub Actions [Section titled “Agentic Workflows vs Traditional GitHub Actions”](#agentic-workflows-vs-traditional-github-actions) While agentic workflows compile to GitHub Actions YAML and run on the same infrastructure, they introduce significant enhancements in security, simplicity, and AI-powered decision-making. | Feature | Traditional GitHub Actions | Agentic Workflows | | ------------------------- | -------------------------------------- | ---------------------------------------- | | **Definition Language** | YAML with explicit steps | Natural language markdown | | **Complexity** | Requires YAML expertise, API knowledge | Describe intent in plain English | | **Decision Making** | Fixed if-then logic | AI-powered contextual decisions | | **Security Model** | Token-based with broad permissions | Sandboxed with safe-outputs | | **Write Operations** | Direct API access with `GITHUB_TOKEN` | Sanitized through safe-output validation | | **Network Access** | Unrestricted by default | Allowlisted domains only | | **Execution Environment** | Standard runner VM | Enhanced sandbox with MCP isolation | | **Tool Integration** | Manual action selection | MCP server automatic tool discovery | | **Testing** | `workflow_dispatch` on branches | Same, plus local compilation | | **Auditability** | Standard workflow logs | Enhanced with agent reasoning logs | ## Next Steps and Resources [Section titled “Next Steps and Resources”](#next-steps-and-resources) * **[Quick Start](/gh-aw/setup/quick-start/)** - Create your first agentic workflow * **[Security Best Practices](/gh-aw/introduction/architecture/)** - Deep dive into agentic security model * **[Safe Outputs](/gh-aw/reference/safe-outputs/)** - Learn about validated GitHub operations * **[Workflow Structure](/gh-aw/reference/workflow-structure/)** - Understand markdown workflow syntax * **[Design Patterns](/gh-aw/patterns/issue-ops/)** - Real-world agentic workflow patterns * **[Glossary](/gh-aw/reference/glossary/)** - Key terms and concepts * **[GitHub Actions Documentation](https://docs.github.com/en/actions)** - Official reference * **[Workflow Syntax](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions)** - Complete YAML reference * **[Security Hardening](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)** - Security best practices # Using MCPs > How to use Model Context Protocol (MCP) servers with GitHub Agentic Workflows to connect AI agents to GitHub, databases, and external services. [Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol) (MCP) is a standard for AI tool integration, allowing agents to securely connect to external tools, databases, and services. GitHub Agentic Workflows includes built-in GitHub MCP integration and supports custom MCP servers for external services. ## Quick Start [Section titled “Quick Start”](#quick-start) Get your first MCP integration running in under 5 minutes. ### Step 1: Add GitHub Tools [Section titled “Step 1: Add GitHub Tools”](#step-1-add-github-tools) Create a workflow file at `.github/workflows/my-workflow.md`: ```aw --- on: issues: types: [opened] permissions: contents: read issues: read tools: github: toolsets: [default] --- # Issue Analysis Agent Analyze the issue and provide a summary of similar existing issues. ``` The `toolsets: [default]` configuration gives your agentic workflow access to repository, issue, and pull request tools. ### Step 2: Compile and Test [Section titled “Step 2: Compile and Test”](#step-2-compile-and-test) ```bash gh aw compile my-workflow gh aw mcp inspect my-workflow ``` ## GitHub MCP Server [Section titled “GitHub MCP Server”](#github-mcp-server) The GitHub MCP server is built into agentic workflows and provides comprehensive access to GitHub’s API. ### Available Toolsets [Section titled “Available Toolsets”](#available-toolsets) | Toolset | Description | Tools | | --------------- | --------------------------- | ----------------------------------------------------- | | `context` | User and team information | `get_teams`, `get_team_members` | | `repos` | Repository operations | `get_repository`, `get_file_contents`, `list_commits` | | `issues` | Issue management | `list_issues`, `create_issue`, `update_issue` | | `pull_requests` | PR operations | `list_pull_requests`, `create_pull_request` | | `actions` | Workflow runs and artifacts | `list_workflows`, `list_workflow_runs` | | `discussions` | GitHub Discussions | `list_discussions`, `create_discussion` | | `code_security` | Security alerts | `list_code_scanning_alerts` | | `users` | User profiles | `get_me`, `get_user`, `list_users` | The `default` toolset includes: `context`, `repos`, `issues`, `pull_requests`. When used in workflows, `[default]` expands to action-friendly toolsets that work with GitHub Actions tokens. Note: The `users` toolset is not included by default as GitHub Actions tokens do not support user operations. ### Operating Modes [Section titled “Operating Modes”](#operating-modes) Remote mode (`mode: remote`) connects to a hosted server with no Docker required. Local mode (`mode: local`) runs in Docker, enabling version pinning for offline or restricted environments. See [Remote vs Local Mode](/gh-aw/reference/github-tools/#github-tools-access-modes). The GitHub MCP server always operates read-only. Write operations are handled through [safe outputs](/gh-aw/reference/safe-outputs/), which run in a separate permission-controlled job. ## Manually Configuring a Custom MCP Server [Section titled “Manually Configuring a Custom MCP Server”](#manually-configuring-a-custom-mcp-server) Caution Custom MCP servers should be **read-only**. Write operations must go through [safe outputs](/gh-aw/reference/safe-outputs/) or [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/). Ensure your MCP server implements authentication and authorization to prevent unauthorized write access. Add MCP servers to your workflow’s frontmatter using the `mcp-servers:` section: ```aw --- on: issues permissions: contents: read mcp-servers: microsoftdocs: url: "https://learn.microsoft.com/api/mcp" allowed: ["*"] notion: container: "mcp/notion" env: NOTION_TOKEN: "${{ secrets.NOTION_TOKEN }}" allowed: - "search_pages" - "get_page" - "get_database" - "query_database" --- # Your workflow content here ``` ## Custom MCP Server Types [Section titled “Custom MCP Server Types”](#custom-mcp-server-types) ### Stdio MCP Servers [Section titled “Stdio MCP Servers”](#stdio-mcp-servers) Execute commands with stdin/stdout communication for Python modules, Node.js scripts, and local executables: ```yaml mcp-servers: serena: command: "uvx" args: ["--from", "git+https://github.com/oraios/serena", "serena"] allowed: ["*"] ``` ### Docker Container MCP Servers [Section titled “Docker Container MCP Servers”](#docker-container-mcp-servers) Run containerized MCP servers with environment variables, volume mounts, and network restrictions: ```yaml mcp-servers: custom-tool: container: "mcp/custom-tool:v1.0" args: ["-v", "/host/data:/app/data"] # Volume mounts before image entrypointArgs: ["serve", "--port", "8080"] # App args after image env: API_KEY: "${{ secrets.API_KEY }}" allowed: ["tool1", "tool2"] network: allowed: - defaults - api.example.com ``` The `container` field generates `docker run --rm -i `. ### HTTP MCP Servers [Section titled “HTTP MCP Servers”](#http-mcp-servers) Remote MCP servers accessible via HTTP. Configure authentication using the `headers` field for static API keys, or the `auth` field for dynamic token acquisition: ```yaml mcp-servers: deepwiki: url: "https://mcp.deepwiki.com/sse" allowed: - read_wiki_structure - read_wiki_contents - ask_question authenticated-api: url: "https://api.example.com/mcp" headers: Authorization: "Bearer ${{ secrets.API_TOKEN }}" allowed: ["*"] ``` #### GitHub Actions OIDC Authentication [Section titled “GitHub Actions OIDC Authentication”](#github-actions-oidc-authentication) For MCP servers that accept GitHub Actions OIDC tokens, use the `auth` field instead of a static `headers` value. The gateway acquires a short-lived JWT from the GitHub Actions OIDC endpoint and injects it as an `Authorization: Bearer` header on every outgoing request. ```yaml permissions: id-token: write # required for OIDC token acquisition mcp-servers: my-secure-server: url: "https://my-server.example.com/mcp" auth: type: github-oidc audience: "https://my-server.example.com" # optional; defaults to the server URL allowed: ["*"] ``` The `auth.type: github-oidc` field is only valid on HTTP servers. The MCP server is responsible for validating the token; the gateway acts as a token forwarder. See [MCP Gateway — Upstream Authentication](/gh-aw/reference/mcp-gateway/#76-upstream-authentication-oidc) for full specification details. ### Registry-based MCP Servers [Section titled “Registry-based MCP Servers”](#registry-based-mcp-servers) Reference MCP servers from the GitHub MCP registry (the `registry` field provides metadata for tooling and is not enforced by gh-aw): ```yaml mcp-servers: markitdown: registry: https://api.mcp.github.com/v0/servers/microsoft/markitdown container: "ghcr.io/microsoft/markitdown" allowed: ["*"] ``` ## MCP Tool Filtering [Section titled “MCP Tool Filtering”](#mcp-tool-filtering) Use `allowed:` to specify which tools are available, or `["*"]` to allow all: ```yaml mcp-servers: notion: container: "mcp/notion" allowed: ["search_pages", "get_page"] # or ["*"] to allow all ``` The `allowed:` filter is enforced at the **MCP gateway level** — the gateway only exposes the listed tools to the agent. This enforcement applies regardless of which AI engine or permission mode is in use. ## Shared MCP Configurations [Section titled “Shared MCP Configurations”](#shared-mcp-configurations) Pre-configured MCP server specifications are available in [`.github/workflows/shared/mcp/`](https://github.com/github/gh-aw/tree/main/.github/workflows/shared/mcp) and can be copied or imported directly. Examples include: | MCP Server | Import Path | Key Capabilities | | ----------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Jupyter** | `shared/mcp/jupyter.md` | Execute code, manage notebooks, visualize data | | **Drain3** | `shared/mcp/drain3.md` | Log pattern mining with 8 tools including `index_file`, `list_clusters`, `find_anomalies` | | **AgentDB** | `shared/mcp/agentdb.md` | Semantic and hybrid retrieval over agent-collected corpora (e.g. discussions, issues), backed by a runtime store at `AGENTDB_PATH` | | **Others** | `shared/mcp/*.md` | AST-Grep, Azure, Brave Search, Context7, DataDog, DeepWiki, Fabric RTI, MarkItDown, Microsoft Docs, Notion, Sentry, Serena, Server Memory, Slack, Tavily | ## Adding MCP Servers from the Registry [Section titled “Adding MCP Servers from the Registry”](#adding-mcp-servers-from-the-registry) Use `gh aw mcp add` to browse and add servers from the GitHub MCP registry (default: `https://api.mcp.github.com/v0`): ```bash gh aw mcp add # List available servers gh aw mcp add my-workflow makenotion/notion-mcp-server # Add server gh aw mcp add my-workflow makenotion/notion-mcp-server --transport stdio # Specify transport gh aw mcp add my-workflow makenotion/notion-mcp-server --tool-id my-notion # Custom tool ID gh aw mcp add my-workflow server-name --registry https://custom.registry.com/v1 # Custom registry ``` ## Practical Examples [Section titled “Practical Examples”](#practical-examples) ### Example 1: Basic Issue Triage [Section titled “Example 1: Basic Issue Triage”](#example-1-basic-issue-triage) ```aw --- on: issues: types: [opened] permissions: contents: read issues: read tools: github: toolsets: [default] safe-outputs: add-comment: --- # Issue Triage Agent Analyze issue #${{ github.event.issue.number }} and add a comment with category, related issues, and suggested labels. ``` ### Example 2: Security Audit with Discussions [Section titled “Example 2: Security Audit with Discussions”](#example-2-security-audit-with-discussions) ```aw --- on: weekly on sunday permissions: contents: read security-events: read discussions: write tools: github: toolsets: [default, code_security, discussions] safe-outputs: create-discussion: category: "Security" title-prefix: "[security-scan] " --- # Security Audit Agent Review code scanning alerts and create weekly security discussions with findings. ``` ## Debugging and Troubleshooting [Section titled “Debugging and Troubleshooting”](#debugging-and-troubleshooting) Inspect MCP configurations with CLI commands: `gh aw mcp inspect my-workflow` (add `--server --verbose` for details) or `gh aw mcp list-tools my-workflow`. For advanced debugging, import `shared/mcp-debug.md` to access diagnostic tools and the `report_diagnostics_to_pull_request` custom safe-output. **Common issues**: Connection failures (verify syntax, env vars, network) or tool not found (check toolsets configuration or `allowed` list with `gh aw mcp inspect`). ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MCP Scripts](/gh-aw/reference/mcp-scripts/) - Define custom inline tools without external MCP servers * [Tools](/gh-aw/reference/tools/) - Complete tools reference * [CLI Commands](/gh-aw/setup/cli/) - CLI commands including `mcp inspect` * [Imports](/gh-aw/reference/imports/) - Modularizing workflows with includes * [Frontmatter](/gh-aw/reference/frontmatter/) - All configuration options * [Workflow Structure](/gh-aw/reference/workflow-structure/) - Directory organization * [Model Context Protocol Specification](https://github.com/modelcontextprotocol/specification) * [GitHub MCP Server](https://github.com/github/github-mcp-server) # Network Configuration Guide > Common network configurations for package registries, CDNs, and development tools This guide provides practical examples for configuring network access in GitHub Agentic Workflows while maintaining security. ## Quick Start [Section titled “Quick Start”](#quick-start) Configure network access by adding ecosystem identifiers to the `network.allowed` list. Always include `defaults` for basic infrastructure: ```yaml network: allowed: - defaults # Required: Basic infrastructure - python # PyPI, conda (for Python projects) - node # npm, yarn, pnpm (for Node.js projects) - go # Go module proxy (for Go projects) - containers # Docker Hub, GHCR (for container projects) ``` ## Available Ecosystems [Section titled “Available Ecosystems”](#available-ecosystems) For the full list of ecosystem identifiers and the domains they include, see the [Ecosystem Identifiers reference](/gh-aw/reference/network/#ecosystem-identifiers). ## Common Configuration Patterns [Section titled “Common Configuration Patterns”](#common-configuration-patterns) ```yaml # Python project with containers network: allowed: - defaults - python - containers # Full-stack web development network: allowed: - defaults - node - playwright - github # DevOps automation network: allowed: - defaults - terraform - containers - github ``` ## Custom Domains [Section titled “Custom Domains”](#custom-domains) Add specific domains for your services. Both base domains and wildcard patterns are supported: ```yaml network: allowed: - defaults - python - "api.example.com" # Matches api.example.com and subdomains - "*.cdn.example.com" # Wildcard: matches any subdomain of cdn.example.com ``` **Wildcard pattern behavior:** * `*.example.com` matches `sub.example.com`, `deep.nested.example.com`, and `example.com` * Only single wildcards at the start are supported (e.g., `*.*.example.com` is invalid) Tip Both `example.com` and `*.example.com` match subdomains. Use wildcards when you want to explicitly document that subdomain access is expected. ## Protocol-Specific Filtering [Section titled “Protocol-Specific Filtering”](#protocol-specific-filtering) Restrict domains to specific protocols for enhanced security (Copilot engine with AWF firewall): ```yaml engine: copilot network: allowed: - defaults - "https://secure.api.example.com" # HTTPS-only - "http://legacy.internal.com" # HTTP-only - "example.org" # Both protocols (default) sandbox: agent: awf # Firewall enabled ``` **Validation:** Invalid protocols (e.g., `ftp://`) are rejected at compile time. See [Network Permissions - Protocol-Specific Filtering](/gh-aw/reference/network/#protocol-specific-domain-filtering) for complete details. ## Strict Mode and Ecosystem Identifiers [Section titled “Strict Mode and Ecosystem Identifiers”](#strict-mode-and-ecosystem-identifiers) Workflows use [strict mode](/gh-aw/reference/frontmatter/#strict-mode-strict) by default, which enforces ecosystem identifiers instead of individual domains for security. This applies to all engines. ```yaml # ✗ Rejected in strict mode network: allowed: - "pypi.org" # Error: use 'python' ecosystem instead - "npmjs.org" # Error: use 'node' ecosystem instead # ✓ Accepted in strict mode network: allowed: - python # Ecosystem identifier - node # Ecosystem identifier ``` ### Error Messages [Section titled “Error Messages”](#error-messages) When strict mode rejects a domain that belongs to a known ecosystem, the error message suggests the ecosystem identifier: ```text error: strict mode: network domains must be from known ecosystems (e.g., 'defaults', 'python', 'node') for all engines in strict mode. Custom domains are not allowed for security. Did you mean: 'pypi.org' belongs to ecosystem 'python'? ``` When strict mode rejects a custom domain: ```text error: strict mode: network domains must be from known ecosystems (e.g., 'defaults', 'python', 'node') for all engines in strict mode. Custom domains are not allowed for security. Set 'strict: false' to use custom domains. ``` ### Using Custom Domains [Section titled “Using Custom Domains”](#using-custom-domains) To use custom domains (domains not in known ecosystems), disable strict mode: ```yaml --- strict: false # Required for custom domains network: allowed: - python # Ecosystem identifier - "api.example.com" # Custom domain (only allowed with strict: false) --- ``` **Security Note**: Custom domains bypass ecosystem validation. Only disable strict mode when necessary and ensure you trust the custom domains you allow. ## Security Best Practices [Section titled “Security Best Practices”](#security-best-practices) 1. **Start minimal** - Only add ecosystems you actually use 2. **Use ecosystem identifiers** - Don’t list individual domains (use `python` instead of `pypi.org`, `files.pythonhosted.org`, etc.) 3. **Keep strict mode enabled** - Provides enhanced security validation (enabled by default) 4. **Add incrementally** - Start with `defaults`, add ecosystems as needed based on firewall denials ## Troubleshooting Firewall Blocking [Section titled “Troubleshooting Firewall Blocking”](#troubleshooting-firewall-blocking) View firewall activity with `gh aw logs --run-id ` to identify blocked domains: ```text Firewall Log Analysis Blocked Domains: ✗ registry.npmjs.org:443 (3 requests) → Add `node` ecosystem ✗ pypi.org:443 (2 requests) → Add `python` ecosystem ``` Common mappings: npm/Node.js → `node`, PyPI/Python → `python`, Docker → `containers`, Go modules → `go`. ## Advanced Options [Section titled “Advanced Options”](#advanced-options) Disable all external network access (engine communication still allowed): ```yaml network: {} ``` View complete ecosystem domain lists in the [ecosystem domains source](https://github.com/github/gh-aw/blob/main/pkg/workflow/data/ecosystem_domains.json). ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Network Permissions Reference](/gh-aw/reference/network/) - Complete network configuration reference * [Playwright Reference](/gh-aw/reference/playwright/) - Browser automation and network requirements * [Security Guide](/gh-aw/introduction/architecture/) - Security best practices * [Troubleshooting](/gh-aw/troubleshooting/common-issues/) - Common issues and solutions # Reusing Workflows > How to reuse, add, share, update, and distribute workflows. ## Adding Workflows [Section titled “Adding Workflows”](#adding-workflows) You can add any existing workflow you have access to from external repositories. Use the `gh aw add-wizard` command to add a workflow with interactive guidance: ```bash gh aw add-wizard ``` For example, to add the `daily-repo-status` workflow from the `githubnext/agentics` repository: ```bash # Full GitHub URL gh aw add-wizard https://github.com/githubnext/agentics/blob/main/workflows/daily-repo-status.md # Short form (for workflows in top-level workflows/ directory) gh aw add-wizard githubnext/agentics/daily-repo-status # Skip the API key prompt when a secret is already configured gh aw add-wizard githubnext/agentics/daily-repo-status --skip-secret ``` This checks requirements, adds the workflow markdown file to your repository, and generates the corresponding YAML workflow. After adding, commit and push the changes to your repository. The `--skip-secret` flag bypasses the interactive API key prompt. Use it when the required secret (e.g., `COPILOT_GITHUB_TOKEN`) is already configured at the organization or repository level. For non-interactive installation, use `gh aw add` with optional versioning. By default this looks in the `workflows/` directory, but you can specify an explicit path if needed: ```bash gh aw add githubnext/agentics/ci-doctor # short form gh aw add githubnext/agentics/ci-doctor@v1.0.0 # with version gh aw add githubnext/agentics/workflows/ci-doctor.md # explicit path ``` Use `--name`, `--pr`, `--force`, `--engine`, or `--verbose` flags to customize installation. The `source` field is automatically added to workflow frontmatter for tracking origin and enabling updates. When installing a workflow, `gh aw add` also automatically fetches: * Workflows referenced in the workflow’s [`dispatch-workflow`](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow) safe output. * Files declared in the workflow’s [`resources:`](/gh-aw/reference/frontmatter/#resources-resources) frontmatter field (companion workflows, custom actions). Note Check carefully that the workflow comes from a trusted source and is appropriate for your use in your repository. Review the workflow’s content and understand what it does before adding it to your repository. Note Workflows marked with `private: true` in their frontmatter cannot be added to other repositories. Attempting to do so will fail with an error. See [Private Workflows](/gh-aw/reference/frontmatter/#private-workflows-private) for details. ## Using an Agent to Import and Adapt a Workflow [Section titled “Using an Agent to Import and Adapt a Workflow”](#using-an-agent-to-import-and-adapt-a-workflow) You can use a coding agent to import a workflow from another repository and adapt it for your own. The agent reads the source workflow, customizes repository-specific configuration (labels, assignees, branch names, permissions), and sets up the repository — including initialization if needed. Tip Use this approach when you want to significantly customize a workflow before using it. For straightforward imports without modification, use [`gh aw add`](#adding-workflows) or [`gh aw add-wizard`](#adding-workflows) instead. ### GitHub Web Interface [Section titled “GitHub Web Interface”](#github-web-interface) **If you have access to GitHub Copilot**, use one of these prompts in your repository to import and adapt a workflow from another repo. Each prompt also initializes the repository for GitHub Agentic Workflows if it has not been set up yet. * Daily Status Report ```markdown Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md Then import and adapt the daily-repo-status workflow from githubnext/agentics. The source is at https://github.com/githubnext/agentics/blob/main/workflows/daily-repo-status.md. Adapt any labels, team references, and output format to suit this repository. ``` * Issue Triage ```markdown Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md Then import and adapt an issue triage workflow from github/gh-aw. Find a suitable issue triage workflow in that repository and adapt it: update the labels, assignee logic, and any repository-specific rules to match this project's conventions. ``` * CI Doctor ```markdown Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md Then import and adapt the CI Doctor workflow from githubnext/agentics. The source is at https://github.com/githubnext/agentics/blob/main/workflows/ci-doctor.md. Adapt the workflow to match this repository's CI setup, branch naming, and issue labeling conventions. ``` Tip On the first run in a new repository, the workflow may fail because secrets are not yet configured. The agentic workflow should detect missing tokens and open an issue with setup instructions. ### Coding Agent [Section titled “Coding Agent”](#coding-agent) Follow these steps to import and adapt a workflow using VSCode, Claude, Codex, or Copilot in your terminal. 1. **Start your coding agent** in the context of your repository. 2. **Enter the following prompt**, replacing `SOURCE_WORKFLOW`, `OWNER`, and `REPO` with the workflow you want to import: ```text Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md Then import and adapt the SOURCE_WORKFLOW workflow from OWNER/REPO. The source is at https://github.com/OWNER/REPO/blob/main/workflows/SOURCE_WORKFLOW.md. Adapt the workflow for this repository: update any labels, assignees, branch names, and permissions to match this project's structure. Keep the overall purpose and logic of the workflow intact. ``` You can add as much extra context, constraints, or customization goals after the last line as you need. 3. **Set up required secrets** if you haven’t done so already. See [Engines](/gh-aw/reference/engines/) for the secrets your chosen engine requires. After the agent finishes, review the adapted workflow, merge the pull request, and trigger a run from the Actions tab or with `gh aw run`. ## Updating Workflows [Section titled “Updating Workflows”](#updating-workflows) When you add a workflow, a tracking `source:` entry remembers where it came from. You can keep workflows synchronized with their source repositories: ```bash gh aw update # update all workflows gh aw update ci-doctor # update specific workflow gh aw update ci-doctor issue-triage # update multiple ``` Use `--major`, `--force`, `--no-merge`, `--engine`, or `--verbose` flags to control update behavior. Semantic versions (e.g., `v1.2.3`) update to latest compatible release within same major version. Branch references update to latest commit. SHA references update to the latest commit on the default branch. Updates use 3-way merge by default to preserve local changes; use `--no-merge` to replace with the upstream version. When merge conflicts occur, manually resolve conflict markers and run `gh aw compile`. ## Imports [Section titled “Imports”](#imports) Import reusable components using the `imports:` field in frontmatter. File paths are relative to the workflow location: ```yaml --- on: issues engine: copilot imports: - shared/common-tools.md - shared/security-setup.md - shared/mcp/tavily.md --- ``` During `gh aw add`, imports are expanded to track source repository (e.g., `shared/common-tools.md` becomes `githubnext/agentics/shared/common-tools.md@abc123def`). Remote imports are automatically cached in `.github/aw/imports/` by commit SHA. This enables offline workflow compilation once imports have been downloaded. The cache is shared across different refs pointing to the same commit, reducing redundant downloads. See [Imports Reference](/gh-aw/reference/imports/) for path formats, merge semantics, and field-specific behavior. ## Importing Agent Files [Section titled “Importing Agent Files”](#importing-agent-files) Agent files provide specialized AI instructions and behavior. See [Importing Copilot Copilot Agent Files](/gh-aw/reference/copilot-custom-agents/) for details on creating and importing agent files from external repositories. ## Example: Modular Workflow with Imports [Section titled “Example: Modular Workflow with Imports”](#example-modular-workflow-with-imports) Create a shared Model Context Protocol (MCP) server configuration in `.github/workflows/shared/mcp/tavily.md`: ```yaml --- mcp-servers: tavily: url: "https://mcp.tavily.com/mcp/?tavilyApiKey=${{ secrets.TAVILY_API_KEY }}" allowed: ["*"] network: allowed: - mcp.tavily.com --- ``` Reference it in your workflow to include the Tavily MCP server alongside other tools: ```yaml --- on: issues: types: [opened] imports: - shared/mcp/tavily.md tools: github: toolsets: [issues] permissions: contents: read --- # Research Agent Perform web research using Tavily and respond to issues. ``` **Result**: The compiled workflow includes both the Tavily MCP server from the import and the GitHub tools from the main workflow, with network permissions automatically merged to allow access to both `mcp.tavily.com` and GitHub API endpoints. ## Best Practices [Section titled “Best Practices”](#best-practices) Use semantic versioning for stable workflows and agent files, branches for development, and commit SHAs for immutability. **Related:** [CLI Commands](/gh-aw/setup/cli/) | [Workflow Structure](/gh-aw/reference/workflow-structure/) | [Frontmatter](/gh-aw/reference/frontmatter/) | [Imports](/gh-aw/reference/imports/) | [Copilot Agent Files](/gh-aw/reference/copilot-custom-agents/) # Self-Hosted Runners > How to configure and run agentic workflows on self-hosted runners, ARC/Kubernetes, and GHES environments. Use the `runs-on` frontmatter field to target a self-hosted runner instead of the default `ubuntu-latest`. Runners must be Linux with Docker support. macOS and Windows are not supported. Self-hosted runners must allow `sudo` for agentic workflows. This is a requirement to allow all GH-AW security features to be enabled. Specific technical needs are: * AWF (Agentic Workflow Firewall) applies host-level `iptables` rules to the Linux kernel `DOCKER-USER` chain to enforce network egress filtering for all agent containers on the AWF bridge network. This outer security boundary requires root UID. * Container-level `iptables`, Squid proxy ACLs, and capability drops add additional defense in depth, but they do not replace host-level filtering. For these reasons, a non-sudo mode is not supported, including ARC configurations with `allowPrivilegeEscalation: false`. ## ARC with Docker-in-Docker (DinD) [Section titled “ARC with Docker-in-Docker (DinD)”](#arc-with-docker-in-docker-dind) Actions Runner Controller (ARC) deployments that use a Docker-in-Docker sidecar split the runner container and the Docker daemon container across separate filesystems, so bind mounts constructed from the runner’s perspective fail inside the daemon. `gh aw compile` emits a runtime probe in generated workflows that inspects `DOCKER_HOST` and appends `--docker-host-path-prefix /tmp/gh-aw` to the AWF invocation when the value matches `tcp://localhost:` or `tcp://127.0.0.1:`. No workflow-level configuration is required. The probe is gated on AWF `v0.25.43` or newer. Workflows pinned to an older AWF version, or running on GitHub-hosted runners (where `DOCKER_HOST` is unset or points at a Unix socket), are unaffected. ## runs-on formats [Section titled “runs-on formats”](#runs-on-formats) **String** — single runner label: ```aw --- on: issues runs-on: self-hosted --- ``` **Array** — runner must have *all* listed labels (logical AND): ```aw --- on: issues runs-on: [self-hosted, linux, x64] --- ``` **Object** — named runner group, optionally filtered by labels: ```aw --- on: issues runs-on: group: my-runner-group labels: [linux, x64] --- ``` ## Sharing configuration via imports [Section titled “Sharing configuration via imports”](#sharing-configuration-via-imports) `runs-on` must be set in each workflow — it is not merged from imports. Other settings like `network` and `tools` can be shared: .github/workflows/shared/runner-config.md ```aw --- network: allowed: - defaults - private-registry.example.com tools: bash: {} --- ``` ```aw --- on: issues imports: - shared/runner-config.md runs-on: [self-hosted, linux, x64] --- Triage this issue. ``` ## Configuring the detection job runner [Section titled “Configuring the detection job runner”](#configuring-the-detection-job-runner) When [threat detection](/gh-aw/reference/threat-detection/) is enabled, the detection job runs on the agent job’s runner by default. Override it with `safe-outputs.threat-detection.runs-on`: ```aw --- on: issues runs-on: [self-hosted, linux, x64] safe-outputs: create-issue: {} threat-detection: runs-on: ubuntu-latest --- ``` This is useful when your self-hosted runner lacks outbound internet access for AI detection, or when you want to run the detection job on a cheaper runner. ## Configuring the framework job runner [Section titled “Configuring the framework job runner”](#configuring-the-framework-job-runner) Framework jobs — activation, pre-activation, safe-outputs, unlock, APM, update\_cache\_memory, and push\_repo\_memory — default to `ubuntu-slim`. Use `runs-on-slim:` to override all of them at once: ```aw --- on: issues runs-on: [self-hosted, linux, x64] runs-on-slim: self-hosted safe-outputs: create-issue: {} --- ``` Note `runs-on` controls only the main agent job. `runs-on-slim` controls all framework/generated jobs. `safe-outputs.runs-on` still takes precedence over `runs-on-slim` for safe-output jobs specifically. ## Configuring the maintenance workflow runner [Section titled “Configuring the maintenance workflow runner”](#configuring-the-maintenance-workflow-runner) The generated `agentics-maintenance.yml` workflow defaults to `ubuntu-slim` for all its jobs. To use a self-hosted runner for maintenance jobs, set `runs_on` in `.github/workflows/aw.json`: **Single label:** ```json { "maintenance": { "runs_on": "self-hosted" } } ``` **Multiple labels** (runner must match all): ```json { "maintenance": { "runs_on": ["self-hosted", "linux", "x64"] } } ``` This setting applies to every job in `agentics-maintenance.yml` (close-expired-entities, cleanup-cache-memory, run\_operation, apply\_safe\_outputs, create\_labels, validate\_workflows, and activity\_report). Re-run `gh aw compile` after changing `aw.json` to regenerate the workflow. Note `aw.json` is separate from individual workflow frontmatter. It provides repository-level settings for generated infrastructure workflows. ## Related documentation [Section titled “Related documentation”](#related-documentation) * [Frontmatter](/gh-aw/reference/frontmatter/#run-configuration-run-name-runs-on-runs-on-slim-timeout-minutes) — `runs-on` and `runs-on-slim` syntax reference * [Imports](/gh-aw/reference/imports/) — importable fields and merge semantics * [Threat Detection](/gh-aw/reference/threat-detection/) — detection job configuration * [Network Access](/gh-aw/reference/network/) — configuring outbound network permissions * [Sandbox](/gh-aw/reference/sandbox/) — container and Docker requirements * [Ephemerals](/gh-aw/reference/ephemerals/#maintenance-configuration) — full `aw.json` maintenance configuration reference * [Enterprise Configuration](/gh-aw/reference/enterprise-configuration/) — custom API endpoints for GHEC/GHES ## Runner environment requirements [Section titled “Runner environment requirements”](#runner-environment-requirements) Self-hosted runners must meet these requirements for agentic workflows to run reliably. ### Docker [Section titled “Docker”](#docker) A working Docker daemon is required. The MCP gateway and sandbox run as containers. * **Unix socket**: Docker must be accessible via a Unix socket (typically `/var/run/docker.sock`). If `DOCKER_HOST` is unset, the gateway mounts `/var/run/docker.sock`. If `DOCKER_HOST` is `unix://...` or a bare absolute path, the gateway mounts that socket path. Other schemes (for example `tcp://...`) are ignored for mounts and default back to `/var/run/docker.sock`. * **Docker group**: The runner user must be in the `docker` group, or the socket must be world-readable. * **ARC/Kubernetes**: If using [actions-runner-controller](https://github.com/actions/actions-runner-controller) with Docker-in-Docker (dind), the dind sidecar must share the Docker socket via an `emptyDir` volume. The gateway will retry the socket check for up to 10 seconds to handle startup race conditions. ### Filesystem [Section titled “Filesystem”](#filesystem) * **Use `RUNNER_TEMP` for transient state.** Put sandbox state, tool downloads, and intermediate outputs in `$RUNNER_TEMP`, which is cleaned between jobs. On shared runners, avoid writing arbitrary workflow data to `/tmp` because it can persist across jobs. The `/tmp/gh-aw` prefix is reserved for gh-aw/AWF ARC DinD path rewriting. `actions/setup` resets `/tmp/gh-aw` at job start, and your normal runner `/tmp` cleanup policy should handle stale data from interrupted jobs. * **No root or sudo assumption.** The runner user may not have root or `sudo` access (except for the initial iptables setup, which requires `sudo`). Tool installs, file operations, and sandbox setup should work as the unprivileged runner user. * **No global installs.** Do not install packages to `/usr/local/`, `/opt/hostedtoolcache/`, or other system-wide paths. These may be read-only, shared across runners, or bind-mounted read-only inside the sandbox. Use job-scoped writable locations instead. * **No hardcoded `HOME` paths.** The runner’s home directory may not be `/home/runner`. Use `$HOME` or `$RUNNER_TEMP` instead of hardcoded paths. ### Post-job cleanup [Section titled “Post-job cleanup”](#post-job-cleanup) Self-hosted runners persist between jobs. Agentic workflows should clean up after themselves: * Files written to `$RUNNER_TEMP` are automatically cleaned. * Docker containers on the `awf-net` bridge are stopped and removed by the sandbox teardown. * If your workflow creates files outside `$RUNNER_TEMP` (e.g. in `$GITHUB_WORKSPACE`), the runner’s built-in workspace cleanup handles this. ### Network [Section titled “Network”](#network) Self-hosted runners need outbound HTTPS access to: * `api.githubcopilot.com` (or your enterprise Copilot endpoint) * `github.com` (or your GHES instance) * `ghcr.io` (to pull the MCP gateway container image) * Any domains listed in your workflow’s `network.allowed` configuration ## GHES (GitHub Enterprise Server) [Section titled “GHES (GitHub Enterprise Server)”](#ghes-github-enterprise-server) Agentic workflows can run on GHES with some additional configuration. ### Artifact compatibility [Section titled “Artifact compatibility”](#artifact-compatibility) GHES does not support the `@actions/artifact` v2.0.0+ backend used by `upload-artifact@v4+` and `download-artifact@v4+`. Compiled workflows use the latest artifact action versions by default, which fail on GHES with `GHESNotSupportedError`. Enable GHES compatibility mode in `.github/workflows/aw.json` to use compatible v3.x artifact actions: ```json { "ghes": true } ``` Or compile with `--ghes` for one-off workflow generation: ```bash gh aw compile --ghes my-workflow.md ``` This makes the compiler emit `upload-artifact@v3.2.2` and `download-artifact@v3.1.0` instead of the latest versions, which are compatible with all GHES versions. ### API endpoint [Section titled “API endpoint”](#api-endpoint) GHES instances need the `api-target` engine configuration. See [Enterprise Configuration](/gh-aw/reference/enterprise-configuration/) for full setup instructions. ```aw --- engine: id: copilot api-target: api.enterprise.githubcopilot.com network: allowed: - defaults - github.company.com - api.enterprise.githubcopilot.com --- ``` ## ARC (Actions Runner Controller) [Section titled “ARC (Actions Runner Controller)”](#arc-actions-runner-controller) When running on [ARC](https://github.com/actions/actions-runner-controller) with Kubernetes: ### Docker-in-Docker (dind) sidecar [Section titled “Docker-in-Docker (dind) sidecar”](#docker-in-docker-dind-sidecar) The standard ARC dind pattern with a shared `emptyDir` for the Docker socket is supported. The MCP gateway: 1. Resolves the Docker socket path from `DOCKER_HOST` (supports `unix://` paths and bare absolute paths) 2. Auto-detects the socket’s group ID for correct permissions 3. Retries the socket check for up to 10 seconds to handle the race condition where the gateway starts before `dockerd` ### Pod security [Section titled “Pod security”](#pod-security) The runner pod requires `privileged: true` on both the dind sidecar and the runner container. This is needed for: * `dockerd` in the dind sidecar * `iptables` rules for the agentic workflow firewall * Chroot/sandbox setup in the runner container # Upgrading Agentic Workflows > Step-by-step guide to upgrade your repository to the latest version of agentic workflows, including updating extensions, applying codemods, compiling workflows, and validating changes. This guide walks you through upgrading agentic workflows. `gh aw upgrade` handles the full process: updating the dispatcher agent file, migrating deprecated workflow syntax, and recompiling all workflows. Tip Quick Upgrade For most users, upgrading is a single command: ```bash gh aw upgrade ``` This updates agent files, applies codemods, and compiles all workflows. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) Before upgrading, ensure you have GitHub CLI (`gh`) v2.0.0+, the latest gh-aw extension, and a clean working directory in your Git repository. Verify with `gh --version`, `gh extension list | grep gh-aw`, and `git status`. Create a backup branch before upgrading so you can recover if something goes wrong: ```bash git checkout -b backup-before-upgrade git checkout - # return to your previous branch ``` ## Step 1: Upgrade the Extension [Section titled “Step 1: Upgrade the Extension”](#step-1-upgrade-the-extension) Upgrade the `gh aw` extension to get the latest features and codemods: ```bash gh extension upgrade gh-aw ``` Check your version with `gh aw version` and compare against the [latest release](https://github.com/github/gh-aw/releases). If you encounter issues, try a clean reinstall with `gh extension remove gh-aw` followed by `gh extension install github/gh-aw`. ## Step 2: Run the Upgrade Command [Section titled “Step 2: Run the Upgrade Command”](#step-2-run-the-upgrade-command) Run the upgrade command from your repository root: ```bash gh aw upgrade ``` This command performs three main operations: ### 2.1 Updates Dispatcher Agent File [Section titled “2.1 Updates Dispatcher Agent File”](#21-updates-dispatcher-agent-file) Updates `.github/agents/agentic-workflows.agent.md` to the latest template. Workflow prompt files (`.github/aw/*.md`) are resolved directly from GitHub by the agent — they’re no longer managed by the CLI. ### 2.2 Applies Codemods to All Workflows [Section titled “2.2 Applies Codemods to All Workflows”](#22-applies-codemods-to-all-workflows) The upgrade automatically applies codemods to fix deprecated fields in all workflow files (`.github/workflows/*.md`). ### 2.3 Compiles All Workflows [Section titled “2.3 Compiles All Workflows”](#23-compiles-all-workflows) The upgrade automatically compiles all workflows to generate or update `.lock.yml` files, ensuring they’re ready to run in GitHub Actions. ### Command Options [Section titled “Command Options”](#command-options) ```bash gh aw upgrade # updates agent files + codemods + compiles gh aw upgrade -v # verbose output gh aw upgrade --no-fix # skip codemods and compilation gh aw upgrade --dir custom/workflows ``` ## Step 3: Review the Changes [Section titled “Step 3: Review the Changes”](#step-3-review-the-changes) Run `git diff .github/workflows/` to verify the changes. Typical migrations include `sandbox: false` → `sandbox.agent: false`, `app:` → `github-app:`, `safe-inputs:` → `mcp-scripts:`, `daily at` → `daily around`, and removal of deprecated `network.firewall` and `mcp-scripts.mode` fields. ## Step 4: Commit and Push [Section titled “Step 4: Commit and Push”](#step-4-commit-and-push) Stage and commit your changes: ```bash git add .github/workflows/ .github/agents/ git commit -m "Upgrade agentic workflows to latest version" git push origin main ``` Always commit both `.md` and `.lock.yml` files together. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **Extension upgrade fails:** Try a clean reinstall with `gh extension remove gh-aw && gh extension install github/gh-aw`. **Codemods not applied:** Manually apply with `gh aw fix --write -v`. **Compilation errors:** Review errors with `gh aw compile my-workflow --validate` and fix YAML syntax in source files. **Workflows not running:** Verify `.lock.yml` files are committed, check status with `gh aw status`, and confirm secrets are valid with `gh aw secrets bootstrap`. **Breaking changes:** Revert with `git checkout backup-before-upgrade` and review [release notes](https://github.com/github/gh-aw/releases). ## Advanced Topics [Section titled “Advanced Topics”](#advanced-topics) **Upgrading across versions:** Review the [changelog](https://github.com/github/gh-aw/blob/main/CHANGELOG.md) for cumulative changes when upgrading across multiple releases. See the [troubleshooting guide](/gh-aw/troubleshooting/common-issues/) if you run into issues. # Security Architecture > Comprehensive security architecture overview for GitHub Agentic Workflows, including defense-in-depth mechanisms against rogue MCP servers and malicious agents. GitHub Agentic Workflows implements a defense-in-depth security architecture that protects against untrusted Model Context Protocol (MCP) servers and compromised agents. This document provides an overview of our security model and visual diagrams of the key components. ## Security Model [Section titled “Security Model”](#security-model) Agentic Workflows (AW) adopts a layered approach that combines substrate-enforced isolation, declarative specification, and staged execution. Each layer enforces distinct security properties under different assumptions and constrains the impact of failures above it. ### Threat Model [Section titled “Threat Model”](#threat-model) We consider an adversary that may compromise untrusted user-level components, e.g., containers, and may cause them to behave arbitrarily within the privileges granted to them. The adversary may attempt to: * Access or corrupt the memory or state of other components * Communicate over unintended channels * Abuse legitimate channels to perform unintended actions * Confuse higher-level control logic by deviating from expected workflows We assume the adversary does not compromise the underlying hardware or cryptographic primitives. Attacks exploiting side channels and covert channels are also out of scope. *** ### Layer 1: Substrate-Level Trust [Section titled “Layer 1: Substrate-Level Trust”](#layer-1-substrate-level-trust) AWs run on a GitHub Actions runner virtual machine (VM) and trust Actions’ hardware and kernel-level enforcement mechanisms, including the CPU, MMU, kernel, and container runtime. AWs also rely on three privileged containers: (1) a network firewall that is trusted to configure connectivity for other components via `iptables` and launch the agent container, (2) an API proxy that routes model traffic and may hold endpoint-specific credentials or routing configuration for supported engines, and (3) an MCP Gateway that is trusted to configure and spawn isolated MCP-server containers. Collectively, the substrate level ensures memory isolation between components, CPU and resource isolation, mediation of privileged operations and system calls, and explicit, kernel-enforced communication boundaries. These guarantees hold even if an untrusted user-level component is fully compromised and executes arbitrary code. Trust violations at the substrate level require vulnerabilities in the firewall, MCP Gateway, container runtime, kernel, hypervisor, or hardware. If this layer fails, higher-level security guarantees may not hold. *** ### Layer 2: Configuration-Level Trust [Section titled “Layer 2: Configuration-Level Trust”](#layer-2-configuration-level-trust) AW trusts declarative configuration artifacts, e.g., Action steps, network-firewall policies, MCP server configurations, and the toolchains that interpret them to correctly instantiate system structure and connectivity. The configuration level constrains which components are loaded, how components are connected, which communication channels are permitted, and what component privileges are assigned. Externally minted authentication tokens, e.g., agent API keys and GitHub access tokens, are a critical configuration input and are treated as imported capabilities that bound components’ external effects; declarative configuration controls their distribution, e.g., which tokens are loaded into which containers. Security violations arise due to misconfigurations, overly permissive specifications, and limitations of the declarative model. This layer defines what components exist and how they communicate, but it does not constrain how components use those channels over time. *** ### Layer 3: Plan-Level Trust [Section titled “Layer 3: Plan-Level Trust”](#layer-3-plan-level-trust) AW additionally relies on plan-level trust to constrain component behavior over time. At this layer, the trusted compiler decomposes a workflow into stages. For each stage, the plan specifies (1) which components are active and their permissions, (2) the data produced by the stage, and (3) how that data may be consumed by subsequent stages. In particular, plan-level trust ensures that important external side effects are explicit and undergo thorough vetting. A primary instantiation of plan-level trust is the **SafeOutputs** subsystem. SafeOutputs is a set of trusted components that operate on external state. An agent can interact with read-only MCP servers, e.g., the GitHub MCP server, but externalized writes, such as creating GitHub pull requests, are buffered as artifacts by SafeOutputs rather than applied immediately. When the agent finishes, SafeOutputs’ buffered artifacts can be processed by a deterministic sequence of filters and analyses defined by configuration. These checks can include structural constraints, e.g., limiting the number of pull requests, policy enforcement, and automated sanitization to ensure that sensitive information such as authentication tokens are not exported. These filtered and transformed artifacts are passed to a subsequent stage in which they are externalized. Security violations at the planning layer arise from incorrect plan construction, incomplete or overly permissive stage definitions, or errors in the enforcement of plan transitions. This layer does not protect against failures of substrate-level isolation or mis-allocation of permissions at credential-minting or configuration time. However, it limits the blast radius of a compromised component to the stage in which it is active and its influence on the artifacts passed to the next stage. ## Component Overview [Section titled “Component Overview”](#component-overview) The security architecture operates across multiple layers: compilation-time validation, runtime isolation, permission separation, network controls, and output sanitization. The following diagram illustrates the relationships between these components and the flow of data through the system. ``` flowchart TB subgraph Input[" Input Layer"] WF[/"Workflow (.md)"/] IMPORTS[/"Imports & Includes"/] EVENT[/"GitHub Event
(Issue, PR, Comment)"/] end subgraph Compile[" Compilation-Time Security"] SCHEMA["Schema Validation"] EXPR["Expression Safety Check"] PIN["Action SHA Pinning"] SCAN["Security Scanners
(actionlint, zizmor, poutine)"] end subgraph Runtime[" Runtime Security"] PRE["Pre-Activation
Role & Permission Checks"] ACT["Activation
Content Sanitization"] AGENT["Agent Execution
Read-Only Permissions"] REDACT_MAIN["Secret Redaction
Credential Protection"] end subgraph Isolation[" Isolation Layer"] AWF["Agent Workflow Firewall
Network Egress Control"] PROXY["API Proxy
Agent auth-token isolation"] MCP["MCP Server Sandboxing
Container Isolation"] TOOL["Tool Allowlisting
Explicit Permissions"] end subgraph Output[" Output Security"] DETECT["Threat Detection
AI-Powered Analysis"] SAFE["Safe Outputs
Permission Separation"] SANITIZE["Output Sanitization
Content Validation"] end subgraph Result["✓ Controlled Actions"] ISSUE["Create Issue"] PR["Create PR"] COMMENT["Add Comment"] end WF --> SCHEMA IMPORTS --> SCHEMA SCHEMA --> EXPR EXPR --> PIN PIN --> SCAN SCAN -->|".lock.yml"| PRE EVENT --> ACT PRE --> ACT ACT --> AGENT AGENT <--> AWF AGENT <--> PROXY AGENT <--> MCP AGENT <--> TOOL AGENT --> REDACT_MAIN REDACT_MAIN --> DETECT DETECT --> SAFE SAFE --> SANITIZE SANITIZE --> ISSUE SANITIZE --> PR SANITIZE --> COMMENT ``` ## Safe Outputs: Permission Isolation [Section titled “Safe Outputs: Permission Isolation”](#safe-outputs-permission-isolation) The SafeOutputs subsystem enforces permission isolation by ensuring that agent execution never has direct write access to external state. The agent job runs with minimal read-only permissions, while write operations are deferred to separate jobs that execute only after the agent completes. This separation ensures that even a fully compromised agent cannot directly modify repository state. ``` flowchart LR subgraph AgentJob["Agent Job
Read-Only Permissions"] AGENT["AI Agent Execution"] OUTPUT[/"agent_output.json
(Artifact)"/] AGENT --> OUTPUT end subgraph Detection["Threat Detection Job"] ANALYZE["Analyze for:
• Secret Leaks
• Malicious Patches"] end subgraph SafeJobs["Safe Output Jobs
Write Permissions (Scoped)"] direction TB ISSUE["create_issue
issues: write"] COMMENT["add_comment
issues: write"] PR["create_pull_request
contents: write
pull-requests: write"] LABEL["add_labels
issues: write"] end subgraph GitHub["GitHub API"] API["GitHub REST/GraphQL API"] end OUTPUT -->|"Download Artifact"| ANALYZE ANALYZE -->|"✓ Approved"| SafeJobs ANALYZE -->|"✗ Blocked"| BLOCKED["Workflow Fails"] ISSUE --> API COMMENT --> API PR --> API LABEL --> API ``` Tip The SafeOutputs subsystem provides security by design: the agent never requires write permissions because all write operations are performed by separate, validated jobs with minimal scoped permissions. ## Agent Workflow Firewall (AWF) [Section titled “Agent Workflow Firewall (AWF)”](#agent-workflow-firewall-awf) The Agent Workflow Firewall (AWF) containerizes the agent, binds it to a Docker network, and uses iptables to redirect HTTP/HTTPS traffic through a Squid proxy container. The Squid proxy controls the agent’s egress traffic via a configurable domain allowlist to prevent data exfiltration and restrict compromised agents to permitted domains. The AWF setup process drops its iptables capabilities before launching the agent. Containerizing an agent improves security by limiting its access to the host, but this may come at a cost. In particular, many coding agents expect full access to the host and break if containerized naively. To support agents that need more access to the host, AWF provides a more permissive ‘chroot mode’ that mounts a subset of host system directories read-only under ‘/host’, mounts the host’s HOME and ‘/tmp’ directories read-write, imports a subset of host environment variables like USER and PATH, and then launches the agent in a ‘/host’ chroot jail. This allows the agent to safely use host-installed binaries (Python, Node.js, Go, etc.) from their normal paths, while controlling access to the host network, environment variables, and other sensitive resources. Thus, AWF separates two concerns: * **Filesystem**: Controlled access to host binaries and runtimes via chroot * **Network**: All traffic routed through proxy enforcing the domain allowlist ``` flowchart TB subgraph Agent["AI Agent Process"] COPILOT["Agent CLI"] WEB["WebFetch Tool"] SEARCH["WebSearch Tool"] end subgraph Firewall["Agent Workflow Firewall (AWF)"] WRAP["Process Wrapper"] ALLOW["Domain Allowlist"] LOG["Activity Logging"] WRAP --> ALLOW ALLOW --> LOG end subgraph Network["Network Layer"] direction TB ALLOWED_OUT["✓ Allowed Domains"] BLOCKED_OUT["✗ Blocked Domains"] end subgraph Ecosystems["Ecosystem Bundles"] direction TB DEFAULTS["defaults
certificates, JSON schema"] PYTHON["python
PyPI, Conda"] NODE["node
npm, npmjs.com"] CUSTOM["Custom Domains
api.example.com"] end COPILOT --> WRAP WEB --> WRAP SEARCH --> WRAP ALLOW --> ALLOWED_OUT ALLOW --> BLOCKED_OUT DEFAULTS --> ALLOW PYTHON --> ALLOW NODE --> ALLOW CUSTOM --> ALLOW ALLOWED_OUT --> INTERNET[" Internet"] BLOCKED_OUT --> DROP[" Dropped"] ``` **Configuration Example:** ```yaml engine: copilot network: firewall: true allowed: - defaults # Basic infrastructure - python # PyPI ecosystem - node # npm ecosystem - "api.example.com" # Custom domain ``` ## MCP Gateway and Firewall Integration [Section titled “MCP Gateway and Firewall Integration”](#mcp-gateway-and-firewall-integration) When the MCP gateway is enabled, it operates in conjunction with AWF to ensure that MCP traffic remains contained within trusted boundaries. The gateway spawns isolated containers for MCP servers while AWF mediates all network egress, ensuring that agent-to-server communication traverses only approved channels. ``` flowchart LR subgraph Host["Host machine"] GATEWAY["gh-aw-mcpg\nDocker container\nHost port 80 maps to container port 8000"] GH_MCP["GitHub MCP Server\nspawned via Docker socket"] GATEWAY -->|"spawns"| GH_MCP end subgraph AWFNet["AWF network namespace"] AGENT["Agent container\nAgent CLI + MCP client\n172.30.0.20"] PROXY["Squid proxy\n172.30.0.10"] end AGENT -->|"CONNECT host.docker.internal:80"| PROXY PROXY -->|"allowed domain\n(host.docker.internal)"| GATEWAY GATEWAY -->|"forwards to"| GH_MCP ``` **Architecture Summary** 1. AWF establishes an isolated network with a Squid proxy that enforces the workflow `network.allowed` list. 2. The agent container can only egress through Squid. To reach the gateway, it uses `host.docker.internal:80` (Docker’s host alias). This hostname must be included in the firewall’s allowed list. 3. The `gh-aw-mcpg` container publishes host port 80 mapped to container port 8000. It uses the Docker socket to spawn MCP server containers. 4. All MCP traffic remains within the host boundary: AWF restricts egress, and the gateway routes requests to sandboxed MCP servers. 5. When supported by an agent, AWF creates a trusted `api-proxy` that routes model traffic on the agent’s behalf while keeping that traffic behind AWF’s network controls. This proxy should not be treated as a separate caller-authentication boundary for arbitrary code already running inside the agent container. Caution The MCP gateway API key that is mounted into the agent container is not a strong security boundary against a compromised or malicious agent. An agent running arbitrary code may extract the key from process memory, runtime state, or other in-container channels. Treat this key as leaked by design and rely on substrate isolation, network policy, and staged permission separation for security. ## MCP Server Sandboxing [Section titled “MCP Server Sandboxing”](#mcp-server-sandboxing) MCP servers execute within isolated containers, enforcing substrate-level separation between the agent and each server instance. Tool filtering at the configuration level restricts which operations each server may expose, limiting the attack surface available to a compromised agent. This isolation ensures that even if an MCP server is compromised, it cannot access the memory or state of other components. ``` flowchart TB subgraph Agent["AI Agent"] ENGINE["AI Engine
(Copilot, Claude, Codex)"] end subgraph MCPLayer["MCP Server Layer"] direction TB subgraph GitHub["GitHub MCP"] GH_TOOLS["Enabled Tools:
• issue_read
• list_commits
• search_code"] GH_BLOCKED["Blocked Tools:
• delete_repository
• update_branch_protection"] end subgraph Custom["Custom MCP (Docker)"] CONTAINER[" Isolated Container"] NET["Network Allowlist"] ENV["Env Var Injection"] end subgraph HTTP["HTTP MCP"] ENDPOINT["HTTPS Endpoint"] HEADERS["Secure Headers"] end end subgraph Toolfilter["Tool Filtering"] ALLOWED["allowed: [tool1, tool2]"] DENIED["✗ Unlisted tools blocked"] end ENGINE <-->|"stdio/HTTP"| GitHub ENGINE <-->|"stdio"| CONTAINER ENGINE <-->|"HTTP"| ENDPOINT ALLOWED --> GH_TOOLS ALLOWED --> GH_BLOCKED CONTAINER --> NET CONTAINER --> ENV ENDPOINT --> HEADERS ``` **Isolation Properties:** * **Container Isolation**: Custom MCP servers run in Docker containers with no shared state * **Network Controls**: Per-container domain allowlists enforced via Squid proxy * **Tool Allowlisting**: Explicit `allowed:` lists restrict available operations * **Secret Injection**: Secrets are passed via environment variables, never in configuration files ## Threat Detection Pipeline [Section titled “Threat Detection Pipeline”](#threat-detection-pipeline) The threat detection job is a sub-stage within the SafeOutputs subsystem. After the agent job completes and its outputs are buffered as artifacts, a separate detection job downloads these artifacts and invokes a prompted AI agent to analyze them for suspicious content. This detection agent operates with a security-focused system prompt and examines the agent’s outputs, patches, and execution context. The detection job runs in isolation from the original agent and has no access to write permissions; its sole responsibility is to emit a pass/fail verdict that gates the subsequent safe output jobs. Detection checks include identification of secret leakage, malicious code patterns, and policy violations. If the detection agent identifies threats, the workflow terminates before any writes are externalized. Workflow authors can customize detection behavior by providing additional detection prompts or integrating external security scanners. ``` flowchart TB subgraph Input["SafeOutputs Artifacts"] JSON[/"agent_output.json
(Buffered actions)"/] PATCH[/"aw.patch
(Git diff from agent)"/] PROMPT[/"prompt.txt
(Original workflow context)"/] end subgraph DetectionJob["Threat Detection Job"] direction TB DOWNLOAD["Download artifacts"] AGENT["Detection Agent
(Security-focused prompt)"] subgraph Checks["Analysis Targets"] SECRETS["Secret Leaks
API keys, tokens
Credentials in outputs"] MALICIOUS["Malicious Patches
Backdoors, vulnerabilities
Suspicious modifications"] POLICY["Policy Violations
Scope violations
Unauthorized operations"] end CUSTOM["Custom Detection Steps"] end subgraph Verdict["Verdict"] SAFE_CHECK{{"Threats
Detected?"}} end subgraph Outcome["Outcome"] PROCEED["✓ Safe output jobs proceed"] BLOCK["✗ Workflow fails
No writes externalized"] end JSON --> DOWNLOAD PATCH --> DOWNLOAD PROMPT --> DOWNLOAD DOWNLOAD --> AGENT AGENT --> Checks Checks --> CUSTOM CUSTOM --> SAFE_CHECK SAFE_CHECK -->|"No"| PROCEED SAFE_CHECK -->|"Yes"| BLOCK ``` **Detection Job Properties:** * **Isolated Execution**: The detection agent runs in a separate job with no write permissions and no access to the original agent’s runtime state * **Prompted Analysis**: Detection uses the same AI engine as the workflow, but with a security-focused system prompt that instructs the agent to identify threats * **Artifact-Based**: The detection agent only sees the buffered artifacts (outputs, patches, context), not live repository state * **Blocking Verdict**: The detection job must complete successfully and emit a “safe” verdict before any safe output jobs execute **Detection Mechanisms:** * **AI Detection**: Default AI-powered analysis using the workflow engine with a security-focused detection prompt * **Custom Steps**: Integration with security scanners (Semgrep, TruffleHog, LlamaGuard) via `threat-detection.steps` configuration * **Custom Prompts**: Domain-specific detection instructions for specialized threat models via `threat-detection.prompt` configuration **Configuration Example:** ```yaml threat-detection: prompt: | Additionally check for: - References to internal infrastructure URLs - Attempts to modify CI/CD configuration files - Changes to security-sensitive files (.github/workflows, package.json scripts) steps: - name: Run TruffleHog run: trufflehog filesystem /tmp/gh-aw --only-verified - name: Run Semgrep run: semgrep scan /tmp/gh-aw/aw.patch --config=auto ``` ## Compilation-Time Security [Section titled “Compilation-Time Security”](#compilation-time-security) AW enforces security constraints at compilation time through schema validation, expression allowlisting, and action pinning. The trusted compiler validates declarative configuration artifacts before they are deployed, rejecting misconfigurations and overly permissive specifications. This layer constrains what components may be loaded and how they may be connected, but it does not constrain runtime behavior. ``` flowchart TB subgraph Source["Source Files"] MD[/"workflow.md"/] IMPORTS[/"imports/*.md"/] end subgraph Validation["Schema & Expression Validation"] SCHEMA["JSON Schema Validation
• Valid frontmatter fields
• Correct types & formats"] EXPR["Expression Safety
• Allowlisted expressions only
• No secrets in expressions"] end subgraph Pinning["Action Pinning"] SHA["SHA Resolution
actions/checkout@sha # v4"] CACHE[/"actions-lock.json
(Cached SHAs)"/] end subgraph Scanners["Security Scanners"] ACTIONLINT["actionlint
Workflow linting
(includes shellcheck & pyflakes)"] ZIZMOR["zizmor
Security vulnerabilities
Privilege escalation"] POUTINE["poutine
Supply chain risks
Third-party actions"] end subgraph Strict["Strict Mode Enforcement"] PERMS["✗ No write permissions"] NETWORK["✓ Explicit network config"] WILDCARD["✗ No wildcard domains"] DEPRECATED["✗ No deprecated fields"] end subgraph Output["Compilation Output"] LOCK[/".lock.yml
(Validated Workflow)"/] ERROR["✗ Compilation Error"] end MD --> SCHEMA IMPORTS --> SCHEMA SCHEMA --> EXPR EXPR --> SHA SHA <--> CACHE SHA --> ACTIONLINT ACTIONLINT --> ZIZMOR ZIZMOR --> POUTINE POUTINE --> Strict Strict -->|"All Checks Pass"| LOCK Strict -->|"Violation Found"| ERROR ``` **Compilation Commands:** ```bash # Generate the lock file from the workflow frontmatter, which includes schema validation, # expression safety checks, action pinning, and security scanning gh aw compile # Enable added security scanners for additional validation gh aw compile --actionlint --zizmor --poutine ``` ## Content Sanitization [Section titled “Content Sanitization”](#content-sanitization) User-generated content is sanitized before being passed to the agent. The sanitization pipeline applies a series of transformations to normalize potentially problematic content. This mechanism operates at the activation stage boundary, ensuring that untrusted input is processed before it is passed to the agent. ``` flowchart LR subgraph Raw["Raw Event Content"] TITLE["Issue Title"] BODY["Issue/PR Body"] COMMENT["Comment Text"] end subgraph Sanitization["Content Sanitization Pipeline"] direction TB MENTIONS["@mention Neutralization
@user → `@user`"] BOTS["Bot Trigger Protection
fixes #123 → `fixes #123`"] XML["XML/HTML Tag Conversion
<script> → (script)"] URI["URI Filtering
Only HTTPS from trusted domains"] SPECIAL["Special Character Handling
Unicode normalization"] LIMIT["Content Limits
0.5MB max, 65k lines"] CONTROL["Control Character Removal
ANSI escapes stripped"] end subgraph Safe["Sanitized Output"] SAFE_TEXT["needs.activation.outputs.text
✓ Safe for AI consumption"] end TITLE --> MENTIONS BODY --> MENTIONS COMMENT --> MENTIONS MENTIONS --> BOTS BOTS --> XML XML --> URI URI --> SPECIAL SPECIAL --> LIMIT LIMIT --> CONTROL CONTROL --> SAFE_TEXT ``` **Sanitization Properties:** | Mechanism | Input | Output | Protection | | --------------------------- | ------------------ | ------------------ | --------------------------------------- | | **@mention Neutralization** | `@user` | `` `@user` `` | Prevents unintended user notifications | | **Bot Trigger Protection** | `fixes #123` | `` `fixes #123` `` | Prevents automatic issue linking | | **XML/HTML Tag Conversion** | ` → (script)alert('xss')(/script) → (img src=x onerror=...) → (!-- hidden comment --) ``` ## Integrity Filtering [Section titled “Integrity Filtering”](#integrity-filtering) Integrity filtering controls which GitHub content an agent can access during a workflow run, based on **author trust** and **merge status** rather than push access alone. The MCP gateway intercepts tool calls and filters content below the configured `min-integrity` threshold before the AI engine sees it — items from blocked users or below the minimum trust level are removed transparently. For public repositories, `min-integrity: approved` is applied automatically — restricting content to owners, members, and collaborators — even without additional authentication. The four configurable levels (`merged`, `approved`, `unapproved`, `none`) are cumulative from most to least restrictive. Individual users can be blocked unconditionally, and trusted reviewers can promote specific items via approval labels. See [Integrity Filtering Reference](/gh-aw/reference/integrity/) for configuration options, integrity levels, and examples. ## Secret Redaction [Section titled “Secret Redaction”](#secret-redaction) Before workflow artifacts are uploaded, all files in the `/tmp/gh-aw` directory are scanned for secret values and redacted. This mechanism prevents accidental credential leakage through logs, outputs, or artifacts. Secret redaction executes unconditionally (with `if: always()`), ensuring that secrets are protected even if the workflow fails at an earlier stage. ``` flowchart LR subgraph Sources["Secret Sources"] YAML["Workflow YAML"] ENV["Environment Variables"] MCP_CONF["MCP Server Config"] end subgraph Collection["Secret Collection"] SCAN["Scan for secrets.* patterns"] EXTRACT["Extract secret names:
SECRET_NAME_1
SECRET_NAME_2"] end subgraph Redaction["Secret Redaction Step"] direction TB FIND["Find files in /tmp/gh-aw
(.txt, .json, .log, .md, .yml)"] MATCH["Match exact secret values"] REPLACE["Replace with masked value:
abc***** (first 3 chars + asterisks)"] end subgraph Output["Safe Artifacts"] LOGS["Redacted Logs"] JSON_OUT["Sanitized JSON"] PROMPT["Clean Prompt Files"] end YAML --> SCAN ENV --> SCAN MCP_CONF --> SCAN SCAN --> EXTRACT EXTRACT --> FIND FIND --> MATCH MATCH --> REPLACE REPLACE --> LOGS REPLACE --> JSON_OUT REPLACE --> PROMPT ``` **Redaction Properties:** * **Automatic Detection**: Scans workflow YAML for `secrets.*` patterns and collects all secret references * **Exact String Matching**: Uses safe string matching (not regex) to prevent injection attacks * **Partial Visibility**: Displays first 3 characters followed by asterisks for debugging without exposing full secrets * **Custom Masking**: Supports additional custom secret masking steps via `secret-masking:` configuration **Configuration Example:** ```yaml secret-masking: steps: - name: Redact custom patterns run: | find /tmp/gh-aw -type f -exec sed -i 's/password123/REDACTED/g' {} + ``` Secret redaction executes with `if: always()` to ensure secrets are never leaked, even if the workflow fails at an earlier stage. ## Job Execution Flow [Section titled “Job Execution Flow”](#job-execution-flow) Workflow execution follows a strict dependency order that enforces security checks at each stage boundary. The plan-level decomposition ensures that each stage has explicit inputs and outputs, and that transitions between stages are mediated by validation steps. ``` flowchart TB subgraph PreActivation["Pre-Activation Job"] ROLE["Role Permission Check"] DEADLINE["Stop-After Deadline"] SKIP["Skip-If-Match Check"] COMMAND["Command Position Validation"] end subgraph Activation["Activation Job"] CONTEXT["Prepare Workflow Context"] SANITIZE["Sanitize Event Text"] LOCK_CHECK["Validate Lock File"] end subgraph Agent["Agent Job"] CHECKOUT["Repository Checkout"] RUNTIME["Runtime Setup
(Node.js, Python)"] CACHE_RESTORE["Cache Restore"] MCP_START["Start MCP Containers"] PROMPT["Generate Prompt"] EXECUTE["Execute AI Engine"] REDACT[" Secret Redaction"] UPLOAD["Upload Output Artifact"] CACHE_SAVE["Save Cache"] end subgraph Detection["Detection Job"] DOWNLOAD_DETECT["Download Artifact"] ANALYZE["AI + Custom Analysis"] VERDICT["Security Verdict"] end subgraph SafeOutputs["Safe Output Jobs"] CREATE_ISSUE["create_issue"] ADD_COMMENT["add_comment"] CREATE_PR["create_pull_request"] end subgraph Conclusion["Conclusion Job"] AGGREGATE["Aggregate Results"] SUMMARY["Generate Summary"] end ROLE --> DEADLINE DEADLINE --> SKIP SKIP --> COMMAND COMMAND -->|"✓ Pass"| CONTEXT COMMAND -->|"✗ Fail"| SKIP_ALL["Skip All Jobs"] CONTEXT --> SANITIZE SANITIZE --> LOCK_CHECK LOCK_CHECK --> CHECKOUT CHECKOUT --> RUNTIME RUNTIME --> CACHE_RESTORE CACHE_RESTORE --> MCP_START MCP_START --> PROMPT PROMPT --> EXECUTE EXECUTE --> REDACT REDACT --> UPLOAD UPLOAD --> CACHE_SAVE CACHE_SAVE --> DOWNLOAD_DETECT DOWNLOAD_DETECT --> ANALYZE ANALYZE --> VERDICT VERDICT -->|"✓ Safe"| CREATE_ISSUE VERDICT -->|"✓ Safe"| ADD_COMMENT VERDICT -->|"✓ Safe"| CREATE_PR VERDICT -->|"✗ Threat"| BLOCK_ALL["Block All Safe Outputs"] CREATE_ISSUE --> AGGREGATE ADD_COMMENT --> AGGREGATE CREATE_PR --> AGGREGATE AGGREGATE --> SUMMARY ``` ## Observability [Section titled “Observability”](#observability) AW provides comprehensive observability through GitHub Actions runs and artifacts. Workflow artifacts preserve prompts, outputs, patches, and logs for post-hoc analysis. This observability layer supports debugging, security auditing, and cost monitoring without compromising runtime isolation. ``` flowchart TB subgraph Workflow["Workflow Execution"] RUN["GitHub Actions Run"] JOBS["Job Logs"] STEPS["Step Outputs"] end subgraph Artifacts["Workflow Artifacts"] AGENT_OUT[/"agent_output.json
AI decisions & actions"/] PROMPT[/"prompt.txt
Generated prompts"/] PATCH[/"aw.patch
Code changes"/] LOGS[/"engine logs
Token usage & timing"/] FIREWALL[/"firewall logs
Network requests"/] end subgraph CLI["CLI Tools"] AW_LOGS["gh aw logs
Download & analyze runs"] AW_AUDIT["gh aw audit
Investigate failures"] AW_STATUS["gh aw status
Workflow health"] end subgraph Insights["Observability Insights"] COST[" Cost Tracking
Token usage per run"] DEBUG[" Debugging
Step-by-step trace"] SECURITY[" Security Audit
Network & tool access"] PERF[" Performance
Duration & bottlenecks"] end RUN --> JOBS JOBS --> STEPS STEPS --> Artifacts AGENT_OUT --> AW_LOGS PROMPT --> AW_LOGS PATCH --> AW_AUDIT LOGS --> AW_LOGS FIREWALL --> AW_AUDIT AW_LOGS --> COST AW_LOGS --> PERF AW_AUDIT --> DEBUG AW_AUDIT --> SECURITY AW_STATUS --> DEBUG ``` **Observability Properties:** * **Artifact Preservation**: All workflow outputs (prompts, patches, logs) are saved as downloadable artifacts * **Cost Monitoring**: Token usage and costs across workflow runs are tracked via `gh aw logs` * **Failure Analysis**: Failed runs can be investigated with `gh aw audit` to examine prompts, errors, and network activity * **Firewall Logs**: All network requests made by the agent are logged for security auditing * **Step Summaries**: Rich markdown summaries in GitHub Actions display agent decisions and outputs **CLI Commands for Observability:** ```bash # Download and analyze workflow run logs gh aw logs # Investigate a specific workflow run gh aw audit # Check workflow health and status gh aw status ``` ## Security Layers Summary [Section titled “Security Layers Summary”](#security-layers-summary) | Layer | Mechanism | Protection Against | | ----------------- | ----------------------------------------------- | ----------------------------------------------------------- | | **Substrate** | GitHub Actions runner (VM, kernel, hypervisor) | Memory corruption, privilege escalation, host escape | | **Substrate** | Docker container runtime | Process isolation bypass, shared state access | | **Substrate** | AWF network controls (iptables) | Data exfiltration, unauthorized API calls | | **Substrate** | MCP sandboxing (container isolation) | Container escape, unauthorized tool access | | **Configuration** | Schema validation, expression allowlist | Invalid configurations, unauthorized expressions | | **Configuration** | Action SHA pinning | Supply chain attacks, tag hijacking | | **Configuration** | Security scanners (actionlint, zizmor, poutine) | Privilege escalation, misconfigurations, supply chain risks | | **Configuration** | Pre-activation checks (role/permission) | Unauthorized users, expired workflows | | **Plan** | Integrity filtering (`min-integrity`) | Untrusted user input, context poisoning, social engineering | | **Plan** | Content sanitization | @mention abuse, bot triggers | | **Plan** | Secret redaction | Credential leakage in logs/artifacts | | **Plan** | Threat detection | Malicious patches, secret leaks | | **Plan** | Permission separation (SafeOutputs) | Direct write access abuse | | **Plan** | Output sanitization | Content injection, XSS | | **Plan** | Artifact preservation, CLI tools | Debugging failures, auditing security, cost tracking | ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Integrity Filtering](/gh-aw/reference/integrity/) - Author-trust and merge-status content filtering * [Threat Detection Guide](/gh-aw/reference/threat-detection/) - Configuring threat analysis * [Network Permissions](/gh-aw/reference/network/) - Network access control * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Output processing configuration * [AI Engines](/gh-aw/reference/engines/) - Engine-specific security features * [Compilation Process](/gh-aw/reference/compilation-process/) - Build-time security validation * [CLI Commands](/gh-aw/setup/cli/) - Workflow management and observability tools # How They Work > Understanding the core concepts and architecture of GitHub Agentic Workflows, from compilation to execution GitHub Agentic Workflows hosts coding agents in [GitHub Actions](https://docs.github.com/en/actions), to perform complex, multi-step tasks automatically. This enables [Continuous AI](https://githubnext.com/projects/continuous-ai) - systematic, automated application of AI to software collaboration. ## Workflow Structure [Section titled “Workflow Structure”](#workflow-structure) Each workflow contains [frontmatter](/gh-aw/reference/glossary/#frontmatter) (the YAML configuration section between `---` markers) and markdown instructions. The frontmatter defines [triggers](/gh-aw/reference/triggers/) (when the workflow runs), [permissions](/gh-aw/reference/permissions/) (what it can access), and [tools](/gh-aw/reference/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. ```aw --- on: ... permissions: ... tools: ... --- # Natural Language Instructions Analyze this issue and provide helpful triage comments... ``` ## AI Engines [Section titled “AI Engines”](#ai-engines) Workflows support **GitHub Copilot** (default), **Claude by Anthropic**, **Codex**, and **Gemini by Google**. Each [engine](/gh-aw/reference/engines/) (AI model/provider) interprets natural language instructions and executes them using configured tools and permissions. ## Tools and Model Context Protocol (MCP) [Section titled “Tools and Model Context Protocol (MCP)”](#tools-and-model-context-protocol-mcp) Workflows use [tools](/gh-aw/reference/tools/) through the **[Model Context Protocol](/gh-aw/reference/glossary/#mcp-model-context-protocol)** (MCP, a standardized protocol for connecting AI agents to external tools and services) for GitHub operations, external APIs, file operations, and custom integrations. ## Agentic vs. Traditional Workflows [Section titled “Agentic vs. Traditional Workflows”](#agentic-vs-traditional-workflows) **Traditional workflows** execute pre-programmed steps with fixed if/then logic. They do exactly what you tell them, every time, in the same way. **[Agentic workflows](/gh-aw/reference/glossary/#agentic)** (workflows that have agency-the ability to make autonomous decisions) use AI to understand context, make decisions, and generate content by interpreting natural language instructions flexibly. They combine deterministic GitHub Actions infrastructure with AI-driven decision-making, adapting their behavior based on the specific situation they encounter. ## Security Design [Section titled “Security Design”](#security-design) Agentic workflows implement a defense-in-depth security architecture that protects against prompt injection, rogue MCP servers, and malicious agents. The architecture operates across multiple layers: compilation-time validation, runtime isolation, permission separation, network controls, and output sanitization. ``` flowchart LR INPUT[" Input"] --> COMPILE[" Compile"] COMPILE --> RUNTIME[" Runtime"] RUNTIME --> ISOLATION[" Isolation"] ISOLATION --> OUTPUT[" Output"] OUTPUT --> ACTIONS["✓ Actions"] ``` Workflows run with minimal permissions (no write access by default), use tool allowlists, and process outputs through a [safety layer](/gh-aw/introduction/architecture/) before applying changes. Critical actions can require human approval. For detailed security documentation, see the [Security Architecture](/gh-aw/introduction/architecture/) page. ## MCP Scripts and Safe Outputs [Section titled “MCP Scripts and Safe Outputs”](#mcp-scripts-and-safe-outputs) * **[MCP Scripts](/gh-aw/reference/mcp-scripts/)** (custom inline tools) - Custom MCP tools defined inline in workflow frontmatter * **[Safe outputs](/gh-aw/reference/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”](#regenerating-the-lock-file) Use `gh aw compile` to generate [`.lock.yml` files](/gh-aw/reference/glossary/#workflow-lock-file-lockyml) 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”](#continuous-ai-patterns) Enable [Continuous AI](https://githubnext.com/projects/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”](#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`](/gh-aw/reference/safe-outputs/) (pre-approved GitHub operations) for controlled creation of issues, comments, and PRs. # About Workflows > Understanding how GitHub Agentic Workflows transforms natural language into automated AI-powered workflows ## What are Agentic Workflows? [Section titled “What are Agentic Workflows?”](#what-are-agentic-workflows) **[Agentic workflows](/gh-aw/reference/glossary/#agentic-workflow)** are AI-powered automation that can understand context, make decisions, and take meaningful actions-all from natural language instructions you write in markdown. Unlike traditional automation with fixed if-then rules, agentic workflows use coding agents (like Copilot CLI, Claude by Anthropic, or Codex) 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 [Section titled “Coding agents, running with tools, in GitHub Actions”](#coding-agents-running-with-tools-in-github-actions) With coding agents, you describe your automation needs in plain language. GitHub Agentic Workflows makes this possible by running natural language markdown files as agents in [GitHub Actions](https://github.com/features/actions) that are executed by AI coding agents (AI systems that execute your instructions). Instead of writing intricate scripts to handle issue triage, code reviews, or release management, you simply describe what you want to happen. The AI agent understands your repository context, interprets the situation, and takes appropriate actions-all from a few lines of markdown. Here’s a simple example: ```markdown --- 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**](/gh-aw/reference/frontmatter/)-it configures when the workflow runs and what it can do. The markdown body contains your natural language instructions. See [Workflow Structure](/gh-aw/reference/workflow-structure/) for details. The `gh aw compile` command this markdown file into a hardened [GitHub Actions Workflow](https://docs.github.com/en/actions/concepts/workflows-and-actions/workflows#about-workflows) [`.lock.yml` file](/gh-aw/reference/glossary/#workflow-lock-file-lockyml) (the compiled workflow that GitHub Actions runs) that embeds the frontmatter and loads the markdown body at runtime. This runs an AI agent in a containerized environment whenever a new issue is opened. [Compilation](/gh-aw/reference/glossary/#compilation) (converting markdown to GitHub Actions YAML) validates your configuration, applies security hardening, and generates the final workflow file that GitHub Actions can execute. Think of it like compiling code-you write human-friendly markdown, 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. Workflows use read-only permissions by default, with write operations only allowed through sanitized [`safe-outputs`](/gh-aw/reference/safe-outputs/) (validated GitHub operations) that enable creating issues, comments, and PRs without giving the AI direct write access. Access can be gated to team members only, ensuring AI agents operate within controlled boundaries. More sample workflows can be found in the [Agentics collection](https://github.com/githubnext/agentics). # Presentation Slides > View the GitHub Agentic Workflows presentation slides View the GitHub Agentic Workflows presentation slides to learn about the evolution from CI/CD to Continuous AI, how agentic workflows enable AI automation in natural language, security features, and real-world examples. [April 7, 2026 PDF ](/gh-aw/slides/20260407-github-agentic-workflows.pdf)[February 24, 2026 PDF ](/gh-aw/slides/20260224-github-agentic-workflows.pdf)[Interactive HTML ](/gh-aw/slides/) ## Walkthroughs [Section titled “Walkthroughs”](#walkthroughs) ### DeepResearch [Section titled “DeepResearch”](#deepresearch) * DeepResearch * Discussion Miner * * Issue Monster * Copilot ### Version Updater [Section titled “Version Updater”](#version-updater) * * Issue Monster * Copilot ### Workflow Skill Extractor [Section titled “Workflow Skill Extractor”](#workflow-skill-extractor) * Report * Plan (Human) * Copilot ### Agent Persona Exploration [Section titled “Agent Persona Exploration”](#agent-persona-exploration) * Persona Simulator * Plan * Issue Monster * Copilot ### Q - the Agent optimizer [Section titled “Q - the Agent optimizer”](#q---the-agent-optimizer) * * ### Multi Resolution Web Tester [Section titled “Multi Resolution Web Tester”](#multi-resolution-web-tester) * * ### Release notes [Section titled “Release notes”](#release-notes) * ### Issues as Spec [Section titled “Issues as Spec”](#issues-as-spec) * Community * Copilot ### Report Assign Fix [Section titled “Report Assign Fix”](#report-assign-fix) * AW self reported failure * Copilot # BatchOps > Process large volumes of work in parallel or chunked batches using matrix jobs, rate-limit-aware throttling, and result aggregation BatchOps is a pattern for processing large volumes of work items efficiently. Instead of iterating sequentially through hundreds of items in a single workflow run, BatchOps splits work into chunks, parallelizes where possible, handles partial failures gracefully, and aggregates results into a consolidated report. ``` flowchart LR trigger([Trigger]) --> workers[Parallel batch workers] workers --> agg[Aggregate results] ``` ## When to Use BatchOps [Section titled “When to Use BatchOps”](#when-to-use-batchops) | Scenario | Recommendation | | ------------------------------------- | ----------------------------------------------------------- | | < 50 items, order matters | Sequential ([WorkQueueOps](/gh-aw/patterns/workqueue-ops/)) | | 50–500 items, order doesn’t matter | BatchOps with chunked processing | | > 500 items, high parallelism safe | BatchOps with matrix fan-out | | Items have dependencies on each other | Sequential (WorkQueueOps) | | Items are fully independent | BatchOps (any strategy) | | Strict rate limits or quotas | Rate-limit-aware batching | ## Batch Strategy 1: Chunked Processing [Section titled “Batch Strategy 1: Chunked Processing”](#batch-strategy-1-chunked-processing) Split work into fixed-size pages using `GITHUB_RUN_NUMBER`. Each run processes one page, picking up the next slice on the next scheduled run. Items must have a stable sort key (creation date, issue number) so pagination is deterministic. ``` flowchart LR run([Run N]) --> fetch[Fetch page N] fetch --> agent[AI processes batch] agent --> next([Run N+1, next page]) ``` Example workflow: .github/workflows/stale-processor.md ```aw --- on: schedule: daily on weekdays workflow_dispatch: tools: github: toolsets: [issues] bash: - "jq" - "date" safe-outputs: add-labels: allowed: [stale, needs-triage, archived] max: 30 add-comment: max: 30 steps: - name: compute-page id: compute-page run: | PAGE_SIZE=25 # Use run number mod to cycle through pages; reset every 1000 runs PAGE=$(( (GITHUB_RUN_NUMBER % 1000) * PAGE_SIZE )) echo "page_offset=$PAGE" >> "$GITHUB_OUTPUT" echo "page_size=$PAGE_SIZE" >> "$GITHUB_OUTPUT" --- # Chunked Issue Processor This run covers offset ${{ steps.compute-page.outputs.page_offset }} with page size ${{ steps.compute-page.outputs.page_size }}. 1. List issues sorted by creation date (oldest first), skipping the first ${{ steps.compute-page.outputs.page_offset }} and taking ${{ steps.compute-page.outputs.page_size }}. 2. For each issue: add `stale` if last updated > 90 days ago with no recent comments; add `needs-triage` if it has no labels; post a stale warning comment if applicable. 3. Summarize: issues labeled, comments posted, any errors. ``` ## Batch Strategy 2: Fan-Out with Matrix [Section titled “Batch Strategy 2: Fan-Out with Matrix”](#batch-strategy-2-fan-out-with-matrix) Use GitHub Actions matrix to run multiple batch workers in parallel, each responsible for a non-overlapping shard. Use `fail-fast: false` so one shard failure doesn’t cancel the others. Each shard gets its own token and API rate limit quota. ``` flowchart LR trigger([Trigger]) --> s0[Shard 0] trigger --> s1[Shard 1] trigger --> s2[Shard 2] ``` Example workflow: .github/workflows/batch-worker.md ```aw --- on: workflow_dispatch: inputs: total_shards: description: "Number of parallel workers" default: "4" required: false jobs: batch: strategy: matrix: shard: [0, 1, 2, 3] fail-fast: false # Continue other shards even if one fails tools: github: toolsets: [issues, pull_requests] safe-outputs: add-labels: allowed: [reviewed, duplicate, wontfix] max: 50 --- # Matrix Batch Worker — Shard ${{ matrix.shard }} of ${{ inputs.total_shards }} Process only issues where `(issue_number % ${{ inputs.total_shards }}) == ${{ matrix.shard }}` — this ensures no two shards process the same issue. 1. List all open issues (up to 500) and keep only those assigned to this shard. 2. For each issue: check for duplicates (similar title/content); add label `reviewed`; if a duplicate is found, add `duplicate` and reference the original. 3. Report: issues in this shard, how many labeled, any failures. ``` ## Batch Strategy 3: Rate-Limit-Aware Batching [Section titled “Batch Strategy 3: Rate-Limit-Aware Batching”](#batch-strategy-3-rate-limit-aware-batching) Throttle API calls by processing items in small sub-batches with explicit pauses. Slower than unbounded processing but dramatically reduces rate-limit errors. Use [Rate Limiting Controls](/gh-aw/reference/rate-limiting-controls/) for built-in throttling. ``` flowchart LR trigger([Trigger]) --> batch[Process sub-batch] batch --> pause[Pause between batches] pause --> report[Report totals] ``` Example workflow: .github/workflows/rate-limited-batch.md ```aw --- on: workflow_dispatch: inputs: batch_size: description: "Items per sub-batch" default: "10" pause_seconds: description: "Seconds to pause between sub-batches" default: "30" tools: github: toolsets: [repos, issues] bash: - "sleep" - "jq" safe-outputs: add-comment: max: 100 add-labels: allowed: [labeled-by-bot] max: 100 --- # Rate-Limited Batch Processor Process all open issues in sub-batches of ${{ inputs.batch_size }}, pausing ${{ inputs.pause_seconds }} seconds between batches. 1. Fetch all open issue numbers (paginate if needed). 2. For each sub-batch: read each issue body, determine the correct label, add the label, then pause before the next sub-batch. 3. On HTTP 429: pause 60 seconds and retry once before marking the item as failed. 4. Report: total processed, failed, skipped. ``` ## Batch Strategy 4: Result Aggregation [Section titled “Batch Strategy 4: Result Aggregation”](#batch-strategy-4-result-aggregation) Collect results from multiple batch workers or runs and aggregate them into a single summary issue. Use [cache-memory](/gh-aw/reference/cache-memory/) to store intermediate results when runs span multiple days. ``` flowchart LR runs[Past batch runs] --> cache[cache-memory] cache --> agent[AI agent] agent --> issue[Update tracking issue] ``` Example workflow: .github/workflows/batch-aggregator.md ```aw --- on: workflow_dispatch: inputs: report_issue: description: "Issue number to aggregate results into" required: true tools: cache-memory: true github: toolsets: [issues, repos] bash: - "jq" safe-outputs: add-comment: max: 1 update-issue: body: true steps: - name: collect-results run: | # Aggregate results from all result files written by previous batch runs RESULTS_DIR="/tmp/gh-aw/cache-memory/batch-results" if [ -d "$RESULTS_DIR" ]; then jq -s ' { total_processed: (map(.processed) | add // 0), total_failed: (map(.failed) | add // 0), total_skipped: (map(.skipped) | add // 0), runs: length, errors: (map(.errors // []) | add // []) } ' "$RESULTS_DIR"/*.json > /tmp/gh-aw/cache-memory/aggregate.json cat /tmp/gh-aw/cache-memory/aggregate.json else echo '{"total_processed":0,"total_failed":0,"total_skipped":0,"runs":0,"errors":[]}' \ > /tmp/gh-aw/cache-memory/aggregate.json fi --- # Batch Result Aggregator Aggregate results from previous batch runs stored in `/tmp/gh-aw/cache-memory/batch-results/` into issue #${{ inputs.report_issue }}. 1. Read `/tmp/gh-aw/cache-memory/aggregate.json` for totals and each individual result file for per-run breakdowns. 2. Update issue #${{ inputs.report_issue }} body with a Markdown table: summary row (processed/failed/skipped) plus per-run breakdown. List any errors requiring manual intervention. 3. Add a comment: "Batch complete ✓" if no failures, or "Batch complete with failures !" with a list of failed items. 4. For each failed item, create a sub-issue so it can be retried. ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [WorkQueueOps](/gh-aw/patterns/workqueue-ops/) — Sequential queue processing with issue checklists, sub-issues, cache-memory, and Discussions * [ResearchPlanAssignOps](/gh-aw/patterns/research-plan-assign-ops/) — Research → Plan → Assign for developer-supervised work * [Cache Memory](/gh-aw/reference/cache-memory/) — Persistent state storage across workflow runs * [Repo Memory](/gh-aw/reference/repo-memory/) — Git-committed persistent state * [Rate Limiting Controls](/gh-aw/reference/rate-limiting-controls/) — Built-in throttling for API-heavy workflows * [Concurrency](/gh-aw/reference/concurrency/) — Prevent overlapping batch runs # ChatOps > Interactive automation triggered by slash commands (/review, /deploy) in issues and PRs - human-in-the-loop workflows ChatOps brings automation into GitHub conversations through [command triggers](/gh-aw/reference/command-triggers/) that respond to slash commands in issues, pull requests, and comments. Team members can trigger workflows by typing commands like `/review` or `/deploy` directly in discussions. ``` flowchart LR user(["/command"]) --> auth[Auth check] auth --> agent[AI agent] agent --> output[Safe outputs] ``` By default, only users with write permissions can trigger ChatOps commands. Narrow or widen that with `on.roles:` — see [Repository Access Roles](/gh-aw/reference/triggers/#filtering-by-repository-access-roles-onroles-onskip-roles). ## Example: Code Reviewer [Section titled “Example: Code Reviewer”](#example-code-reviewer) In the following example, when someone types `/review`, the AI analyzes code changes and posts review comments. The agent runs with read-only permissions while [safe-outputs](/gh-aw/reference/safe-outputs/) (validated GitHub operations) handle write operations securely. The example uses `events:` to restrict which comment contexts activate a command — in this case `[pull_request_comment]` to respond only in PR threads. See [Filtering Command Events](/gh-aw/reference/command-triggers/#filtering-command-events). The example also references the triggering content via `steps.sanitized.outputs.text`, which strips injection attempts, excessive content, and untrusted mentions — see [Context Text](/gh-aw/reference/command-triggers/#context-text). ```aw --- on: slash_command: name: review events: [pull_request_comment] # Only respond to /review in PR comments permissions: contents: read pull-requests: read safe-outputs: create-pull-request-review-comment: max: 5 add-comment: --- # Code Review Assistant When someone types /review in a pull request comment, perform a thorough analysis of the changes. Examine the diff for potential bugs, security vulnerabilities, performance implications, code style issues, and missing tests or documentation. Create specific review comments on relevant lines of code and add a summary comment with overall observations and recommendations. ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [IssueOps](/gh-aw/patterns/issue-ops/) — Event-driven issue automation * [DispatchOps](/gh-aw/patterns/dispatch-ops/) — Manual workflow triggers * [LabelOps](/gh-aw/patterns/label-ops/) — Label-triggered automation * [MultiRepoOps — Side Repository](/gh-aw/patterns/multi-repo-ops/#the-side-repository-pattern-isolated-automation) — Isolated workflow execution * [Command Triggers](/gh-aw/reference/command-triggers/) — Slash command configuration * [Safe Outputs](/gh-aw/reference/safe-outputs/) — Secure write operations * [Authentication](/gh-aw/reference/auth/) — PAT and GitHub App setup # DeterministicOps > Combine deterministic computation and data extraction with agentic reasoning in GitHub Agentic Workflows for powerful hybrid automation. GitHub Agentic Workflows can combine deterministic computation ([`steps:`](/gh-aw/reference/steps-jobs/#custom-steps-steps) and [`jobs:`](/gh-aw/reference/steps-jobs/#custom-jobs-jobs)) with AI reasoning, enabling hybrid agentic data preprocessing. This pattern can reliably collect and prepare data, then the AI agent reads the results and generates insights. Use this for data aggregation, report generation, trend analysis, auditing, and any hybrid pipeline. ## When to Use [Section titled “When to Use”](#when-to-use) Combine deterministic steps with AI agents to precompute data, filter triggers, preprocess inputs, post-process outputs, or build multi-stage computation and reasoning pipelines. ## Example: Release Highlights Generator [Section titled “Example: Release Highlights Generator”](#example-release-highlights-generator) This workflow generates release highlights for new tags. It uses deterministic steps to fetch structured data about the release and recent PRs, then the AI agent synthesizes this into a release summary. When using `steps:` or `jobs:`, files placed in `/tmp/gh-aw/agent/` are automatically uploaded as artifacts and available to the AI agent. ``` flowchart TD det[Deterministic steps] -- artifacts --> agent[AI agent] agent -- safe-outputs --> so[Safe output jobs] ``` Example workflow: .github/workflows/release-highlights.md ```aw --- on: push: tags: ['v*.*.*'] safe-outputs: update-release: steps: - run: | gh release view "${GITHUB_REF#refs/tags/}" --json name,tagName,body > /tmp/gh-aw/agent/release.json gh pr list --state merged --limit 100 --json number,title,labels > /tmp/gh-aw/agent/prs.json env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} --- # Release Highlights Generator Generate release highlights for `${GITHUB_REF#refs/tags/}`. Analyze PRs in `/tmp/gh-aw/agent/prs.json`, categorize changes, and use update-release to prepend highlights to the release notes. ``` ## Data Caching [Section titled “Data Caching”](#data-caching) For workflows that run frequently or process large datasets, use GitHub Actions caching to avoid redundant API calls: ```aw --- cache: - key: pr-data-${{ github.run_id }} path: /tmp/gh-aw/pr-data restore-keys: | pr-data- steps: - name: Check cache and fetch only new data run: | if [ -f /tmp/gh-aw/pr-data/recent-prs.json ]; then echo "Using cached data" else gh pr list --limit 100 --json ... > /tmp/gh-aw/pr-data/recent-prs.json fi --- ``` ## Deterministic Trigger Filtering [Section titled “Deterministic Trigger Filtering”](#deterministic-trigger-filtering) Deterministic steps can also be used for [Custom Trigger Filtering](/gh-aw/reference/triggers/#filtering-by-custom-steps-onsteps), to control whether the agentic workflow should run based on complex conditions that are easier to express in code than in workflow expressions. ## Deterministic Post-Processing [Section titled “Deterministic Post-Processing”](#deterministic-post-processing) [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/) can also be used for deterministic post-processing of AI outputs. .github/workflows/code-review\.md ```yaml --- on: pull_request: types: [opened] safe-outputs: jobs: format-and-notify: description: "Format and post review" runs-on: ubuntu-latest inputs: summary: {required: true, type: string} steps: - ... --- # Code Review Agent Review the pull request and use format-and-notify to post your summary. ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Pre-Activation Steps](/gh-aw/reference/triggers/#pre-activation-steps-onsteps) — Inline step injection into the pre-activation job * [Pre-Activation Permissions](/gh-aw/reference/triggers/#pre-activation-permissions-onpermissions) — Grant additional scopes for `on.steps:` API calls * [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/) — Custom post-processing jobs * [Frontmatter Reference](/gh-aw/reference/frontmatter/) — Configuration options * [Compilation Process](/gh-aw/reference/compilation-process/) — How jobs are orchestrated * [Imports](/gh-aw/reference/imports/) — Sharing configurations across workflows * [Templating](/gh-aw/reference/templating/) — Using GitHub Actions expressions # DispatchOps > Manually trigger and test agentic workflows with custom inputs using workflow_dispatch DispatchOps is the design pattern where workflows are designed primarily for manual execution via the GitHub Actions UI or CLI. This is used for on-demand tasks, testing, and other workflows that need human judgment about timing. The [`workflow_dispatch` trigger](/gh-aw/reference/triggers/) lets you run workflows with custom inputs whenever needed, with [safe outputs](/gh-aw/reference/safe-outputs/) handling write operations securely. Use manual dispatch for research tasks, operational commands, testing workflows during development, debugging production issues, or any task that doesn’t fit a schedule or event trigger. ``` flowchart LR user([Developer]) --> trigger[workflow_dispatch with inputs] trigger --> agent[AI agent] agent --> outputs[Safe outputs] ``` ## Example: Research Assistant [Section titled “Example: Research Assistant”](#example-research-assistant) This example shows a workflow with a string input and a choice input, using conditional logic to adjust behavior at runtime: ```aw --- on: workflow_dispatch: inputs: topic: description: 'Research topic' required: true type: string depth: description: 'Analysis depth' type: choice options: - brief - detailed default: brief permissions: contents: read safe-outputs: create-discussion: --- # Research Assistant Research the following topic: "${{ github.event.inputs.topic }}" {{#if (eq github.event.inputs.depth "detailed")}} Provide an in-depth analysis: background, key findings, trade-offs, and concrete recommendations with supporting evidence. {{else}} Provide a concise summary: top 3 findings and a single recommendation. {{/if}} ``` Reference inputs with `${{ github.event.inputs.INPUT_NAME }}`. Supported types: `string`, `boolean`, `choice`, `environment`. See [Triggers Reference](/gh-aw/reference/triggers/) for full input syntax and [Templating](/gh-aw/reference/templating/) for conditionals. ## Manually Running Workflows [Section titled “Manually Running Workflows”](#manually-running-workflows) **From GitHub.com**: Go to the **Actions** tab, select the workflow, click **Run workflow**, fill in inputs, and confirm. **Via CLI**: ```bash gh aw run research --raw-field topic="quantum computing" --raw-field depth=detailed ``` ```bash gh aw run research --wait # Wait for completion gh aw run research --ref branch # Run from a specific branch ``` See [CLI Commands](/gh-aw/setup/cli/) for the full `gh aw run` reference. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Triggers Reference](/gh-aw/reference/triggers/) — Complete `workflow_dispatch` syntax including all input types * [Templating](/gh-aw/reference/templating/) — Expressions and conditionals in workflow prompts * [TrialOps](/gh-aw/experimental/trial-ops/) — Testing workflows in isolation * [CLI Commands](/gh-aw/setup/cli/) — Complete `gh aw run` reference # IssueOps > Automate issue triage, categorization, and responses when issues are opened - fully automated issue management IssueOps transforms GitHub issues into automation triggers that analyze, categorize, and respond to issues automatically. Use it for auto-triage, smart routing, initial responses, and quality checks. GitHub Agentic Workflows makes this natural through [issue triggers](/gh-aw/reference/triggers/) and [safe-outputs](/gh-aw/reference/safe-outputs/) that handle automated responses securely without write permissions for the main AI job. When issues are created, workflows activate automatically. The AI analyzes content and provides intelligent responses through automated comments. ## Example: Issue Triage Assistant [Section titled “Example: Issue Triage Assistant”](#example-issue-triage-assistant) This workflow responds to new issues with contextual guidance. It analyzes the title and description for bug reports needing information, feature requests to categorize, questions to answer, or potential duplicates. The AI then comments with helpful next steps or immediate assistance. ``` flowchart LR event([Issue opened]) --> agent[AI triage] agent --> label[Labels] agent --> comment[Comment] ``` Example workflow: .github/workflows/issue-triage.md ```aw --- on: issues: types: [opened] permissions: contents: read actions: read safe-outputs: add-comment: max: 2 --- # Issue Triage Assistant Analyze new issue content and provide helpful guidance. Examine the title and description for bug reports needing information, feature requests to categorize, questions to answer, or potential duplicates. Respond with a comment guiding next steps or providing immediate assistance. ``` This creates an intelligent triage system that responds to new issues with contextual guidance. ## Organizing Work with Sub-Issues [Section titled “Organizing Work with Sub-Issues”](#organizing-work-with-sub-issues) Break large work into agent-ready tasks using parent-child issue hierarchies. Create hierarchies with the `parent` field and temporary IDs, or link existing issues with `link-sub-issue`: ```aw --- on: command: name: plan safe-outputs: create-issue: title-prefix: "[task] " max: 6 --- # Planning Assistant Create a parent tracking issue, then sub-issues linked via parent field: {"type": "create_issue", "temporary_id": "aw_abc123", "title": "Feature X", "body": "Tracking issue"} {"type": "create_issue", "parent": "aw_abc123", "title": "Task 1", "body": "First task"} ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [ChatOps](/gh-aw/patterns/chat-ops/) — Interactive slash command automation * [LabelOps](/gh-aw/patterns/label-ops/) — Label-triggered automation * [WorkQueueOps](/gh-aw/patterns/workqueue-ops/) — Sequential queue processing * [ResearchPlanAssignOps](/gh-aw/patterns/research-plan-assign-ops/) — Research → Plan → Assign * [Safe Outputs](/gh-aw/reference/safe-outputs/) — Secure write operations * [GitHub Tools](/gh-aw/reference/github-tools/) — GitHub API toolsets * [Concurrency](/gh-aw/reference/concurrency/) — Prevent race conditions * [Cache Memory](/gh-aw/reference/cache-memory/) — Persistent state across runs # LabelOps > Workflows triggered by label changes - automate actions when specific labels are added or removed LabelOps uses GitHub labels as workflow triggers, metadata, and state markers. GitHub Agentic Workflows supports two distinct approaches to label-based triggers: [`label_command`](/gh-aw/reference/command-triggers/) for command-style one-shot activation, and [`names:` filtering](/gh-aw/reference/triggers/#filtering-with-labels-names) for persistent label-state awareness. ``` flowchart LR label([Label applied]) --> cmd{label_command?} cmd -- yes --> remove[Auto-removed] cmd -- no --> keep[Stays on item] ``` The `label_command` trigger treats a label as a one-shot command: applying the label fires the workflow, and the label is **automatically removed** so it can be re-applied to re-trigger. This is the right choice when you want a label to mean “do this now” rather than “this item has this property.” ## Example: Deploy Preview [Section titled “Example: Deploy Preview”](#example-deploy-preview) This workflow triggers when a `deploy` label is applied to a pull request. It builds and deploys a preview environment, then posts the URL as a comment. The workflow runs with read-only permissions while [safe-outputs](/gh-aw/reference/safe-outputs/) handle the comment creation securely. ``` flowchart LR apply([Apply deploy label]) --> fire[Trigger fires, label removed] fire --> agent[AI agent] agent --> comment[Comment with URL] ``` Example workflow: .github/workflows/deploy-preview\.md ```aw --- on: label_command: deploy permissions: contents: read safe-outputs: add-comment: max: 1 --- # Deploy Preview A `deploy` label was applied to this pull request. Build and deploy a preview environment and post the URL as a comment. The matched label name is available as `${{ needs.activation.outputs.label_command }}` if needed to distinguish between multiple label commands. ``` After activation the `deploy` label is removed from the pull request, so a reviewer can apply it again to trigger another deployment without any cleanup step. The label that triggered the workflow is exposed as an output of the activation job: ```plaintext ${{ needs.activation.outputs.label_command }} ``` This is useful when a workflow handles multiple label commands and needs to branch on which one was applied. ### Combining with slash commands [Section titled “Combining with slash commands”](#combining-with-slash-commands) `label_command` can be combined with [`slash_command:`](/gh-aw/patterns/chat-ops/) in the same workflow. The two triggers are OR’d — the workflow activates when either condition is met: ```yaml on: slash_command: deploy label_command: name: deploy events: [pull_request] ``` This lets a workflow be triggered both by a `/deploy` comment and by applying a `deploy` label, sharing the same agent logic. ## Label Filtering [Section titled “Label Filtering”](#label-filtering) Another way to relate workflows to labels is to use [Label Trigger Filtering](/gh-aw/reference/triggers/#filtering-with-labels-names) to ensure that a workflow only runs when a particular label is present on an item. For example: ```aw --- on: issues: types: [labeled] names: [bug, critical, security] permissions: contents: read actions: read safe-outputs: add-comment: max: 1 --- # Critical Issue Handler When a critical label is added to an issue, analyze the severity and provide immediate triage guidance. Check the issue for: - Impact scope and affected users - Reproduction steps - Related dependencies or systems - Recommended priority level Respond with a comment outlining next steps and recommended actions. ``` In this example, the workflow activates only when the `bug`, `critical`, or `security` labels are added to an issue, not for other label changes. The labels remain on the issue after the workflow runs. ## Applying and Removing Labels [Section titled “Applying and Removing Labels”](#applying-and-removing-labels) To let an agent apply or remove labels, use the [`add-labels`](/gh-aw/reference/safe-outputs/#add-labels-add-labels) and [`remove-labels`](/gh-aw/reference/safe-outputs/#remove-labels-remove-labels) safe outputs. Use `allowed` to restrict which labels the agent can touch: ```yaml safe-outputs: add-labels: allowed: [bug, team-*, area/*] # restrict to specific labels or glob patterns remove-labels: allowed: [needs-triage] # agents can remove triage label after processing ``` Both operations accept glob patterns in `allowed` and `blocked`, and support cross-repository targets via `target-repo`. See the [Add Labels](/gh-aw/reference/safe-outputs/#add-labels-add-labels) and [Remove Labels](/gh-aw/reference/safe-outputs/#remove-labels-remove-labels) reference for the full set of options. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [IssueOps](/gh-aw/patterns/issue-ops/) — Issue-triggered workflows * [ChatOps](/gh-aw/patterns/chat-ops/) — Slash command automation * [Trigger Events](/gh-aw/reference/triggers/) — Complete trigger configuration including label filtering * [Safe Outputs](/gh-aw/reference/safe-outputs/) — Secure write operations * [Frontmatter Reference](/gh-aw/reference/frontmatter/) — Complete workflow configuration options # MemoryOps > Design patterns for using memory to build stateful workflows that track progress, share data, and compute trends MemoryOps is a set of design patterns using [Cache Memory](/gh-aw/reference/cache-memory/) and [Repo Memory](/gh-aw/reference/repo-memory/) to persist state across workflow runs. Use memory to build workflows that record their progress, resume after interruptions, share data between workflows, incremental processing, trend analysis, multi-step tasks, and workflow coordination. ``` flowchart LR r1([Run 1]) --> s1[memory\nstate 1] s1 --> r2([Run 2]) r2 --> s2[memory\nstate 2] s2 --> r3([Run 3]) ``` When writing prompting for using memory, you can usually use surprisingly high level descriptions of the information to be stored. You often don’t even need to write a schema for the memory. The first run will write data with an appropriate schema, later runs will read it and see the implicit schema. The agent can adapt to changes in the schema over time as long as the data is still there. This makes memory a very flexible tool for stateful workflows without needing to define rigid schemas upfront. ## Memory Types [Section titled “Memory Types”](#memory-types) Two types of memory stores are available. Each has different use cases and access patterns. [Cache Memory](/gh-aw/reference/cache-memory/) gives fast, ephemeral storage using GitHub Actions cache (7 days retention): ```yaml tools: cache-memory: key: my-workflow-state ``` Use for temporary state, session data, short-term caching. The memory is available at `/tmp/gh-aw/cache-memory/`. [Repo Memory](/gh-aw/reference/repo-memory/) gives persistent, version-controlled storage in a dedicated Git branch: ```yaml tools: repo-memory: branch-name: memory/my-workflow file-glob: ["*.json", "*.jsonl"] ``` Use for historical data, trend tracking, permanent state. By default the memory is available at `/tmp/gh-aw/repo-memory/default/`. ## Pattern 1: Exhaustive Processing [Section titled “Pattern 1: Exhaustive Processing”](#pattern-1-exhaustive-processing) Track progress through large datasets with todo/done lists to ensure complete coverage across multiple runs. ```markdown Analyze all open issues in the repository. Track your progress in cache-memory so you can resume if the workflow times out. Mark each issue as done after processing it. Generate a final report with statistics. ``` The agent maintains a state file with items to process and completed items, updating it after each item so the workflow can resume if interrupted: ```json { "todo": [123, 456, 789], "done": [101, 102], "errors": [], "last_run": 1705334400 } ``` Real examples: `.github/workflows/repository-quality-improver.md`, `.github/workflows/copilot-agent-analysis.md` ## Pattern 2: State Persistence [Section titled “Pattern 2: State Persistence”](#pattern-2-state-persistence) Save workflow checkpoints to resume long-running tasks that may timeout. ```markdown Migrate 10,000 records from the old format to the new format. Process 500 records per run and save a checkpoint. Each run should resume from the last checkpoint until all records are migrated. ``` The agent stores a checkpoint with the last processed position and resumes from it each run: ```json { "last_processed_id": 1250, "batch_number": 13, "total_migrated": 1250, "status": "in_progress" } ``` Real examples: `.github/workflows/daily-news.md`, `.github/workflows/cli-consistency-checker.md` ## Pattern 3: Shared Information [Section titled “Pattern 3: Shared Information”](#pattern-3-shared-information) Share data between workflows using [repo-memory](/gh-aw/reference/repo-memory/) branches. A producer workflow stores data; consumers read it using the same branch name. *Producer workflow:* ```markdown Every 6 hours, collect repository metrics (issues, PRs, stars) and store them in repo-memory so other workflows can analyze the data later. ``` *Consumer workflow:* ```markdown Load the historical metrics from repo-memory and compute weekly trends. Generate a trend report with visualizations. ``` Both workflows reference the same branch: ```yaml tools: repo-memory: branch-name: memory/shared-data ``` Real examples: `.github/workflows/metrics-collector.md` (producer), trend analysis workflows (consumers) ## Pattern 4: Data Caching [Section titled “Pattern 4: Data Caching”](#pattern-4-data-caching) Cache API responses to avoid rate limits and reduce workflow time. The agent checks for fresh cached data before making API calls, using suggested TTLs: repository metadata (24h), contributor lists (12h), issues/PRs (1h), workflow runs (30m). ```markdown Fetch repository metadata and contributor lists. Cache the data for 24 hours to avoid repeated API calls. If the cache is fresh, use it. Otherwise, fetch new data and update the cache. ``` Real examples: `.github/workflows/daily-news.md` ## Pattern 5: Trend Computation [Section titled “Pattern 5: Trend Computation”](#pattern-5-trend-computation) Store time-series data and compute trends, moving averages, and statistics. The agent appends new data points to a JSON Lines history file and computes trends using Python. ```markdown Collect daily build times and test times. Store them in repo-memory as time-series data. Compute 7-day and 30-day moving averages. Generate trend charts showing whether performance is improving or declining over time. ``` Real examples: `.github/workflows/daily-code-metrics.md`, `.github/workflows/shared/charts-with-trending.md` ## Pattern 6: Multiple Memory Stores [Section titled “Pattern 6: Multiple Memory Stores”](#pattern-6-multiple-memory-stores) Use multiple memory instances for different lifecycles — cache-memory for temporary session data, separate repo-memory branches for metrics, configuration, and archives. ```markdown Use cache-memory for temporary API responses during this run. Store daily metrics in one repo-memory branch for trend analysis. Keep data schemas in another branch. Archive full snapshots in a third branch with compression. ``` ```yaml tools: cache-memory: key: session-data # Fast, temporary repo-memory: - id: metrics branch-name: memory/metrics # Time-series data - id: config branch-name: memory/config # Schema and metadata - id: archive branch-name: memory/archive # Compressed backups ``` ## Best Practices [Section titled “Best Practices”](#best-practices) ### Use JSON Lines for Time-Series Data [Section titled “Use JSON Lines for Time-Series Data”](#use-json-lines-for-time-series-data) Append-only format ideal for logs and metrics: ```bash # Append without reading entire file echo '{"date": "2024-01-15", "value": 42}' >> data.jsonl ``` ### Include Metadata [Section titled “Include Metadata”](#include-metadata) Document your data structure: ```json { "dataset": "performance-metrics", "schema": { "date": "YYYY-MM-DD", "value": "integer" }, "retention": "90 days" } ``` ### Implement Data Rotation [Section titled “Implement Data Rotation”](#implement-data-rotation) Prevent unbounded growth: ```bash # Keep only last 90 entries tail -n 90 history.jsonl > history-trimmed.jsonl mv history-trimmed.jsonl history.jsonl ``` ## Security Considerations [Section titled “Security Considerations”](#security-considerations) Memory stores are visible to anyone with repository access. Never store credentials, API tokens, PII, or secrets — only aggregate statistics and anonymized data. ```bash # ✓ GOOD - Aggregate statistics echo '{"open_issues": 42}' > metrics.json # ✗ BAD - Individual user data echo '{"user": "alice", "email": "alice@example.com"}' > users.json ``` ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **Cache not persisting**: Verify cache key is consistent across runs **Repo memory not updating**: Check `file-glob` patterns match your files and files are within `max-file-size` limit **Out of memory errors**: Process data in chunks instead of loading entirely, implement data rotation **Merge conflicts**: Use JSON Lines format (append-only), separate branches per workflow, or add run ID to filenames ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Cache Memory](/gh-aw/reference/cache-memory/) — Full cache-memory reference * [Repository Memory](/gh-aw/reference/repo-memory/) — Full repo-memory reference * [MCP Servers](/gh-aw/guides/mcps/) - Memory MCP server configuration * [DeterministicOps](/gh-aw/patterns/deterministic-ops/) - Data preprocessing and extraction * [Safe Outputs](/gh-aw/reference/custom-safe-outputs/) - Storing workflow outputs * [Frontmatter Reference](/gh-aw/reference/frontmatter/) - Configuration options # MonitorOps > Monitor agentic workflows across a repository, publish observability reports, and escalate recurring failures or waste. Use this pattern when you want a scheduled workflow to inspect other agentic workflows using [workflow logs and auditing](/gh-aw/reference/audit/), summarize what happened, and escalate unusual cost or failure patterns. The [agentic-ops repository](https://github.com/githubnext/agentic-ops) provides the reference implementation for this approach. ``` flowchart LR schedule([Schedule]) --> analyze[Analyze workflow logs] analyze --> report[Report to Discussion] analyze --> escalate[Escalate failures to issue] ``` ## What this pattern does [Section titled “What this pattern does”](#what-this-pattern-does) This pattern reviews workflow logs across a repository, classifies notable behavior, and publishes a structured report. When it detects repeated failures, abnormal token consumption, or other unhealthy patterns, it can escalate those findings into issues for follow-up. This pattern is useful for repository-wide monitoring because it creates a durable operational record instead of relying on ad hoc inspection of individual workflow runs. ## Typical workflow [Section titled “Typical workflow”](#typical-workflow) 1. Run on a schedule to collect recent workflow activity. 2. Analyze logs, costs, and failure signals across runs. 3. Post a summary report to a GitHub Discussion or another durable destination. 4. Open or update issues when the same problem crosses a threshold. ## When to use it [Section titled “When to use it”](#when-to-use-it) Use this pattern when a repository has enough workflow activity that maintainers need a regular summary instead of checking each run manually. It also helps when workflows span multiple teams and failures or waste need to be surfaced in a shared location. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [BatchOps](/gh-aw/patterns/batch-ops/) — Process large volumes in parallel chunks * [Audit Commands](/gh-aw/reference/audit/) — Investigate individual runs and regressions * [OpenTelemetry](/gh-aw/reference/open-telemetry/) — Workflow telemetry and spans * [Cache Memory](/gh-aw/reference/cache-memory/) — Persistent state across runs * [Concurrency](/gh-aw/reference/concurrency/) — Prevent overlapping workflow runs * [Monitoring with Projects](/gh-aw/experimental/monitoring-with-projects/) — Durable tracking with Projects # MultiRepoOps > Coordinate agentic workflows across multiple GitHub repositories with automated issue tracking, feature synchronization, and organization-wide enforcement MultiRepoOps extends operational automation patterns (IssueOps, ChatOps, etc.) across multiple GitHub repositories. Using [cross-repository safe outputs](/gh-aw/reference/cross-repository/) and [secure authentication](/gh-aw/reference/auth/), MultiRepoOps enables coordinating work between related projects — creating tracking issues in central repos, synchronizing features to sub-repositories, and enforcing organization-wide policies — all through AI-powered workflows. ``` flowchart LR subgraph source["Source repo"] event([Event]) --> agent[AI agent] end agent --> targetA[Target repo A] agent --> targetB[Target repo B] ``` ## Common MultiRepoOps Patterns [Section titled “Common MultiRepoOps Patterns”](#common-multirepoops-patterns) Four topologies cover most use cases: | Pattern | Description | Examples | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Side repository** | Workflows live in a dedicated automation repo and target one or more main repos — keeps AI-generated content isolated from your main codebase | [Triage from Side Repo](/gh-aw/examples/multi-repo/triage-from-side-repo/), [Code Quality Monitoring](/gh-aw/examples/multi-repo/code-quality-monitoring/) | | **Central control plane** | A private control repo runs a scheduled orchestrator that filters, prioritizes, and dispatches per-repo worker workflows | [Dependabot Rollout](/gh-aw/examples/multi-repo/dependabot-rollout/) | | **Hub-and-spoke** | Component repos each push events to a central tracker via `target-repo` — aggregates signals from many sources into one place | [Cross-Repo Issue Tracking](/gh-aw/examples/multi-repo/issue-tracking/) | | **Upstream-to-downstream** | Source repo propagates changes outward to one or more downstream repos via PRs; `max` controls fan-out breadth | [Feature Synchronization](/gh-aw/examples/multi-repo/feature-sync/) | ## The Side Repository Pattern (Isolated Automation) [Section titled “The Side Repository Pattern (Isolated Automation)”](#the-side-repository-pattern-isolated-automation) A **side repository** is a dedicated automation repo that runs workflows targeting one or more main codebases. This keeps AI-generated issues, comments, and workflow runs isolated from your main repository — no changes needed to existing projects and no mixing of automation infrastructure with production code. ``` flowchart LR subgraph side["Side repo (workflows)"] event([Schedule / dispatch]) --> agent[AI agent] end agent -->|target-repo| main[Main repo] ``` Teams new to agentic workflows can adopt this pattern: create a private repository, add a PAT as a secret, and point `target-repo` at your main codebase. No changes required to the main repo. ```aw --- on: weekly on monday safe-outputs: github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} create-issue: target-repo: "my-org/main-repo" labels: [automation, weekly-check] max: 5 tools: github: github-token: ${{ secrets.GH_AW_MAIN_REPO_TOKEN }} toolsets: [repos, issues, pull_requests] --- # Weekly Repository Health Check Analyze my-org/main-repo and create issues for stale PRs (>30 days), failed CI runs on main, and open security advisories. ``` Using [Slash commands](/gh-aw/reference/command-triggers/) from a side repo require a bridge: a thin relay workflow in the main repo listens for the command and forwards it via `workflow_dispatch` to the side repo. See [Triage from Side Repo](/gh-aw/examples/multi-repo/triage-from-side-repo/) for a complete walkthrough. Authentication details and step-by-step setup are covered in the [Triage from Side Repo](/gh-aw/examples/multi-repo/triage-from-side-repo/) and [Code Quality Monitoring](/gh-aw/examples/multi-repo/code-quality-monitoring/) examples, and in the [Authentication reference](/gh-aw/reference/auth/). ## The Central Control Plane Pattern (Org-Wide Rollouts) [Section titled “The Central Control Plane Pattern (Org-Wide Rollouts)”](#the-central-control-plane-pattern-org-wide-rollouts) For large-scale operations — security patches, policy rollouts, configuration standardization — use a **single private repository as a control plane**. An orchestrator workflow filters and prioritizes targets, then dispatches per-repo worker workflows. ``` flowchart LR subgraph central["Central control repo"] schedule([Schedule]) --> orch[Orchestrator\nfilter & prioritize] end orch --> w1[Repo A] orch --> w2[Repo B] orch --> w3[Repo N] ``` This pattern supports phased adoption (pilot waves first), central governance, security-aware prioritization, and a complete decision trail — without pushing `main` changes to individual target repositories. **Orchestrator** (`dispatch-workflow` safe output + `max` limit): ```aw --- on: schedule: weekly on monday tools: github: github-token: ${{ secrets.GH_AW_READ_ORG_TOKEN }} toolsets: [repos] safe-outputs: dispatch-workflow: workflows: [worker-workflow] max: 5 --- # Rollout Orchestrator Filter repositories, categorize by complexity, prioritize the rollout order, and dispatch the worker workflow for each selected repository. Summarize candidates, breakdown, and rationale. ``` **Worker** (`checkout` + `target-repo` safe outputs per dispatched repo): ```aw --- on: workflow_dispatch: inputs: target_repo: description: 'Target repository (owner/repo format)' required: true type: string checkout: repository: ${{ github.event.inputs.target_repo }} github-token: ${{ secrets.ORG_REPO_CHECKOUT_TOKEN }} current: true safe-outputs: github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} create-pull-request: target-repo: ${{ github.event.inputs.target_repo }} max: 1 --- # Worker: Apply Changes to Target Repository Analyze ${{ github.event.inputs.target_repo }}, apply the required changes, and create a pull request explaining what was changed and why. ``` Keep orchestrator permissions narrow; delegate repo-specific writes to workers. Add correlation IDs to dispatch inputs for tracking. See the [Dependabot Rollout example](/gh-aw/examples/multi-repo/dependabot-rollout/) for a complete end-to-end walkthrough. ## The Hub-and-Spoke Pattern [Section titled “The Hub-and-Spoke Pattern”](#the-hub-and-spoke-pattern) Each component repository runs its own workflow that forwards events to a central tracker via `target-repo`. The central repository accumulates a unified view without needing direct access to individual component repos. ``` flowchart LR compA[Component repo A] -->|create-issue| hub[Central tracker] compB[Component repo B] -->|create-issue| hub compC[Component repo C] -->|create-issue| hub ``` Useful for component-based architectures where multiple teams need a shared visibility layer, cross-project initiatives, or aggregating metrics from distributed repositories. See [Cross-Repo Issue Tracking](/gh-aw/examples/multi-repo/issue-tracking/) for a complete example. ## The Upstream-to-Downstream Pattern [Section titled “The Upstream-to-Downstream Pattern”](#the-upstream-to-downstream-pattern) The source repository propagates changes outward to downstream repos whenever relevant paths change. The agent adapts the changes for each target’s structure and opens a pull request for review. ``` flowchart LR src[Source repo] -->|create-pull-request| d1[Downstream A] src -->|create-pull-request| d2[Downstream B] src -->|create-pull-request| d3[Downstream N] ``` Use `max` to control fan-out breadth, and `title-prefix` plus labels to make the automated PRs easy to filter. See [Feature Synchronization](/gh-aw/examples/multi-repo/feature-sync/) for a complete example. ## Cross-Repository Safe Outputs [Section titled “Cross-Repository Safe Outputs”](#cross-repository-safe-outputs) Most safe output types support `target-repo` to write to external repositories, and `allowed-repos` for dynamic multi-target workflows. See [Cross-Repository Safe Outputs](/gh-aw/reference/cross-repository/#cross-repository-safe-outputs) for the complete list and configuration options, including `target-repo: "*"` for runtime-determined targets and the [GitHub Tools reference](/gh-aw/reference/cross-repository/#cross-repository-reading) for reading from private repositories. ## Deterministic Multi-Repo Workflows [Section titled “Deterministic Multi-Repo Workflows”](#deterministic-multi-repo-workflows) For direct repository access without agent involvement, check out multiple repositories using `checkout:` frontmatter or `actions/checkout` steps. See the [Deterministic Multi-Repo example](/gh-aw/reference/cross-repository/#example-deterministic-multi-repo-workflows) in the cross-repository reference. ## Example Workflows [Section titled “Example Workflows”](#example-workflows) Explore detailed MultiRepoOps examples: * **[Feature Synchronization](/gh-aw/examples/multi-repo/feature-sync/)** — Sync code changes from main repo to sub-repositories * **[Cross-Repo Issue Tracking](/gh-aw/examples/multi-repo/issue-tracking/)** — Hub-and-spoke tracking architecture * **[Dependabot Rollout](/gh-aw/examples/multi-repo/dependabot-rollout/)** — Org-wide orchestrator + worker rollout from a central control repo * **[Triage from Side Repo](/gh-aw/examples/multi-repo/triage-from-side-repo/)** — Automated issue triage running from an isolated automation repository * **[Code Quality Monitoring](/gh-aw/examples/multi-repo/code-quality-monitoring/)** — Scheduled quality checks from a side repository with checkout ## Best Practices [Section titled “Best Practices”](#best-practices) Use GitHub Apps over PATs for automatic token revocation; scope tokens minimally to target repositories. Set appropriate `max` limits and consistent label/prefix conventions. Test against public repositories first before rolling out to private or org-wide targets. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [IssueOps](/gh-aw/patterns/issue-ops/) — Single-repo issue automation * [ChatOps](/gh-aw/patterns/chat-ops/) — Command-driven workflows * [Cross-Repository Operations](/gh-aw/reference/cross-repository/) — Checkout and `target-repo` configuration * [Safe Outputs](/gh-aw/reference/safe-outputs/) — Complete safe output configuration * [GitHub Tools](/gh-aw/reference/github-tools/) — GitHub API toolsets * [Authentication](/gh-aw/reference/auth/) — PAT and GitHub App setup * [Reusing Workflows](/gh-aw/guides/packaging-imports/) — Sharing workflows across repos # OrchestratorOps > Coordinate multiple agentic workflows using an orchestrator/worker pattern — one workflow decides what to do, dispatches workers to do the concrete work. OrchestratorOps is a pattern where one workflow (the **orchestrator**) fans out work to one or more **worker** workflows. The orchestrator decides what to do and in what order; workers execute concrete tasks with scoped permissions and tools. This keeps complex multi-step operations manageable, observable, and independently resumable. ``` flowchart LR trigger([Trigger]) --> orch[Orchestrator\ndecide & dispatch] orch --> w1[Worker A] orch --> w2[Worker B] orch --> w3[Worker N] ``` ## When to Use OrchestratorOps [Section titled “When to Use OrchestratorOps”](#when-to-use-orchestratorops) Use OrchestratorOps when a single workflow run is too coarse — the work spans multiple repositories, requires different tools or permissions per step, benefits from parallel execution, or needs intermediate human review between phases. Common cases include multi-repo rollouts, phased dependency upgrades, and initiative-level automation that touches many issues or PRs. ## The Orchestrator/Worker Pattern [Section titled “The Orchestrator/Worker Pattern”](#the-orchestratorworker-pattern) * **Orchestrator**: decides what to do next, splits work into units, dispatches workers. * **Worker(s)**: do the concrete work (triage, code changes, analysis) with scoped permissions and tools. * **Optional monitoring**: both orchestrator and workers can update a GitHub Project board for visibility. ## Dispatch Workers with `dispatch-workflow` [Section titled “Dispatch Workers with dispatch-workflow”](#dispatch-workers-with-dispatch-workflow) Allow dispatching specific workflows via GitHub’s `workflow_dispatch` API: ```yaml safe-outputs: dispatch-workflow: workflows: [repo-triage-worker, dependency-audit-worker] max: 10 ``` During compilation, gh-aw validates the target workflows exist and support `workflow_dispatch`. Workers receive a JSON payload and run asynchronously as independent workflow runs. See [`dispatch-workflow` safe output](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow). ## Call Workers with `call-workflow` [Section titled “Call Workers with call-workflow”](#call-workers-with-call-workflow) Call reusable workflows (`workflow_call`) via compile-time fan-out — no API call at runtime: ```yaml safe-outputs: call-workflow: workflows: [spring-boot-bugfix, frontend-dep-upgrade] max: 1 ``` The compiler validates that each worker declares `workflow_call`, generates a typed MCP tool per worker from its inputs, and emits a conditional `uses:` job. At runtime the worker whose name the agent selected executes as part of the same workflow run — preserving `github.actor` and billing attribution. See [`call-workflow` safe output](/gh-aw/reference/safe-outputs/#workflow-call-call-workflow). Use `call-workflow` when actor attribution matters, workers must finish before the orchestrator concludes, or you want zero API overhead. Use `dispatch-workflow` when workers should run asynchronously, outlive the parent run, or need `workflow_dispatch` inputs. ## Passing Correlation IDs [Section titled “Passing Correlation IDs”](#passing-correlation-ids) If your workers need shared context, pass an explicit input such as `tracker_id` (string) and include it in worker outputs (e.g., writing it into a Project custom field). ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [BatchOps](/gh-aw/patterns/batch-ops/) — Parallel processing of large item volumes * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) — Central control plane pattern (orchestrator + worker across repos) * [WorkQueueOps](/gh-aw/patterns/workqueue-ops/) — Sequential processing with ordering guarantees * [Safe Outputs (`dispatch-workflow`)](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow) — Dispatching workers * [Safe Outputs (`call-workflow`)](/gh-aw/reference/safe-outputs/#workflow-call-call-workflow) — Calling reusable workflows * [Monitoring with Projects](/gh-aw/experimental/monitoring-with-projects/) — Tracking orchestrator/worker progress # OrchestratorOps > Coordinate multiple agentic workflows using an orchestrator/worker pattern — one workflow decides what to do, dispatches workers to do the concrete work. OrchestratorOps is a pattern where one workflow (the **orchestrator**) fans out work to one or more **worker** workflows. The orchestrator decides what to do and in what order; workers execute concrete tasks with scoped permissions and tools. This keeps complex multi-step operations manageable, observable, and independently resumable. ``` flowchart LR trigger([Trigger]) --> orch[Orchestrator\ndecide & dispatch] orch --> w1[Worker A] orch --> w2[Worker B] orch --> w3[Worker N] ``` ## When to Use OrchestratorOps [Section titled “When to Use OrchestratorOps”](#when-to-use-orchestratorops) Use OrchestratorOps when a single workflow run is too coarse — the work spans multiple repositories, requires different tools or permissions per step, benefits from parallel execution, or needs intermediate human review between phases. Common cases include multi-repo rollouts, phased dependency upgrades, and initiative-level automation that touches many issues or PRs. ## The Orchestrator/Worker Pattern [Section titled “The Orchestrator/Worker Pattern”](#the-orchestratorworker-pattern) * **Orchestrator**: decides what to do next, splits work into units, dispatches workers. * **Worker(s)**: do the concrete work (triage, code changes, analysis) with scoped permissions and tools. * **Optional monitoring**: both orchestrator and workers can update a GitHub Project board for visibility. ## Dispatch Workers with `dispatch-workflow` [Section titled “Dispatch Workers with dispatch-workflow”](#dispatch-workers-with-dispatch-workflow) Allow dispatching specific workflows via GitHub’s `workflow_dispatch` API: ```yaml safe-outputs: dispatch-workflow: workflows: [repo-triage-worker, dependency-audit-worker] max: 10 ``` During compilation, gh-aw validates the target workflows exist and support `workflow_dispatch`. Workers receive a JSON payload and run asynchronously as independent workflow runs. See [`dispatch-workflow` safe output](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow). ## Call Workers with `call-workflow` [Section titled “Call Workers with call-workflow”](#call-workers-with-call-workflow) Call reusable workflows (`workflow_call`) via compile-time fan-out — no API call at runtime: ```yaml safe-outputs: call-workflow: workflows: [spring-boot-bugfix, frontend-dep-upgrade] max: 1 ``` The compiler validates that each worker declares `workflow_call`, generates a typed MCP tool per worker from its inputs, and emits a conditional `uses:` job. At runtime the worker whose name the agent selected executes as part of the same workflow run — preserving `github.actor` and billing attribution. See [`call-workflow` safe output](/gh-aw/reference/safe-outputs/#workflow-call-call-workflow). Use `call-workflow` when actor attribution matters, workers must finish before the orchestrator concludes, or you want zero API overhead. Use `dispatch-workflow` when workers should run asynchronously, outlive the parent run, or need `workflow_dispatch` inputs. ## Passing Correlation IDs [Section titled “Passing Correlation IDs”](#passing-correlation-ids) If your workers need shared context, pass an explicit input such as `tracker_id` (string) and include it in worker outputs (e.g., writing it into a Project custom field). ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [BatchOps](/gh-aw/patterns/batch-ops/) — Parallel processing of large item volumes * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) — Central control plane pattern (orchestrator + worker across repos) * [WorkQueueOps](/gh-aw/patterns/workqueue-ops/) — Sequential processing with ordering guarantees * [Safe Outputs (`dispatch-workflow`)](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow) — Dispatching workers * [Safe Outputs (`call-workflow`)](/gh-aw/reference/safe-outputs/#workflow-call-call-workflow) — Calling reusable workflows * [Monitoring with Projects](/gh-aw/experimental/monitoring-with-projects/) — Tracking orchestrator/worker progress # ProjectOps > Automate GitHub Projects with agentic routing, field updates, and controlled write operations ProjectOps helps teams run project operations with less manual upkeep. It builds on [GitHub Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects), which provides the core planning and tracking layer for issues and pull requests, and adds support for judgment-heavy decisions. ProjectOps reads project state with GitHub tools and applies changes through [safe-outputs](/gh-aw/reference/safe-outputs/). It is most useful when you need context-aware routing and field updates. For simple, rule-based transitions, [built-in automations](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations) are usually enough. In practice, this gives teams faster triage decisions, cleaner board state, stronger planning signals across related issues and pull requests, and more decision-ready status updates. ## How it works [Section titled “How it works”](#how-it-works) ``` flowchart LR ev([Issue / PR event\nor schedule]) --> agent[ProjectOps agent] subgraph gh["GitHub Projects"] board[(board\nfields & items)] end agent -->|read — projects toolset| board board -->|project state| agent agent -->|update-project\nadd-comment| board ``` A practical way to adopt ProjectOps is to start with read-only MCP/GitHub analysis, then gradually add targeted write operations as workflow confidence and policy maturity increase. ProjectOps combines two capability layers: * **GitHub tools (`tools.github` + `projects` toolset)** for reading and analyzing project state. * **Safe outputs** for controlled write operations, including: * **[`update-project`](/gh-aw/reference/safe-outputs/#project-board-updates-update-project)** — use when you want to add issues/PRs to a project or update fields (status, priority, owner, dates, custom values). * **[`create-project-status-update`](/gh-aw/reference/safe-outputs/#project-status-updates-create-project-status-update)** — use when you want a stakeholder-facing summary in the project Updates tab (weekly health, blockers, risks, next decisions). * **[`create-project`](/gh-aw/reference/safe-outputs/#project-creation-create-project)** — use when automation needs to bootstrap a new board for an initiative or team. * **[`add-comment`](/gh-aw/reference/safe-outputs/#comment-creation-add-comment)** — use when you want to explain routing decisions or request missing info on the triggering issue/PR. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) 1. **A Project board** and copy the project URL. See [Creating a project](https://docs.github.com/en/issues/planning-and-tracking-with-projects/creating-projects/creating-a-project#creating-a-project). 2. **A Project token** (PAT or GitHub App token). See [Authentication (Projects)](/gh-aw/reference/auth-projects/). 3. **A field contract** (for example: Status, Priority, Team, Iteration, Target Date). See [Understanding fields](https://docs.github.com/en/issues/planning-and-tracking-with-projects/understanding-fields). ## Project Token Authentication [Section titled “Project Token Authentication”](#project-token-authentication) The default `GITHUB_TOKEN` is repository-scoped and cannot access the Projects API. See [Authentication (Projects)](/gh-aw/reference/auth-projects/) for PAT, GitHub App, and secret layout instructions. ## Examples [Section titled “Examples”](#examples) Let’s look at examples of these in action, starting with the [Project Board Summarizer](#project-board-summarizer) (read-only analysis), then moving to controlled write operations with the [Project Board Maintainer](#project-board-maintainer) example. ### Project Board Summarizer [Section titled “Project Board Summarizer”](#project-board-summarizer) Let’s start with a simple agentic workflow that reviews project board state and generates a summary without applying any changes. ```aw --- on: schedule: weekly on monday permissions: contents: read actions: read tools: github: github-token: ${{ secrets.GH_AW_READ_PROJECT_TOKEN }} toolsets: [default, projects] --- # Project Board Summarizer Review [project 1](https://github.com/orgs/my-mona-org/projects/1). Return only: - New this week - Blocked + why - Stale/inconsistent fields - Top 3 human actions Read-only. Do not update the project. ``` Our project board might look like this:  Running the agentic workflow generates a concise summary of project status. We can find this in the GitHub Actions agent run output:  ### Project Board Maintainer [Section titled “Project Board Maintainer”](#project-board-maintainer) Let’s write an agentic workflow that applies changes to a project board based on issue content and context. This workflow will run on new issues, analyze the issue and project state, and decide whether to add the issue to the project board and how to set key fields. ```aw --- on: issues: types: [opened] permissions: contents: read actions: read tools: github: github-token: ${{ secrets.GH_AW_READ_PROJECT_TOKEN }} toolsets: [default, projects] safe-outputs: update-project: github-token: ${{ secrets.GH_AW_WRITE_PROJECT_TOKEN }} project: https://github.com/orgs/my-mona-org/projects/1 max: 1 add-comment: max: 1 --- # Intelligent Issue Triage Analyze each new issue in this repository and decide whether it belongs on the project board. Set structured fields only from allowed values: - Status: Needs Triage | Proposed | In Progress | Blocked - Priority: Low | Medium | High - Team: Platform | Docs | Product Post a short comment on the issue explaining your routing decision and any uncertainty. ``` Once this workflow is compiled and running, it will automatically triage new issues with controlled write operations to the project board and issue comments. Let’s create a new issue to see this in action:  The Project Board Maintainer analyzes the issue content and context, then decides to add it to the project board with specific field values (for example, Status: Proposed, Priority: Medium, Team: Docs). It also posts a comment on the issue explaining the decision and any uncertainty.  ## Best practices [Section titled “Best practices”](#best-practices) In production, keep the loop simple: issue arrives, agent classifies and proposes/sets fields, safe outputs apply allowed writes, and humans review high-impact changes and exceptions. * **Auto-apply** low-risk hygiene (add item, set initial status/team). * **Suggest-only** commitments (priority/date/iteration changes). * **Always gate** cross-team or cross-repo impact. * Use `max` caps, allowlists, and explicit approvals to control writes. * Keep single-select values exact to avoid field drift. * If you only need simple event-based transitions, prefer [built-in GitHub Project workflows](https://docs.github.com/en/issues/planning-and-tracking-with-projects/automating-your-project/using-the-built-in-automations). ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [IssueOps](/gh-aw/patterns/issue-ops/) — Event-driven issue automation * [Safe Outputs](/gh-aw/reference/safe-outputs/) — Secure write operations * [GitHub Tools](/gh-aw/reference/github-tools/) — GitHub API toolsets for reading project state * [Monitoring with Projects](/gh-aw/experimental/monitoring-with-projects/) — Durable tracking with Projects * [Authentication (Projects)](/gh-aw/reference/auth-projects/) — PAT and GitHub App setup for Projects # ResearchPlanAssignOps > Orchestrate deep research, structured planning, and automated assignment to drive AI-powered development cycles from insight to merged PR ResearchPlanAssignOps is a four-phase development pattern that moves from automated discovery to merged code with human control at every decision point. A research agent surfaces insights, a planning agent converts them into actionable issues, a coding agent implements the work by [assigning issues to GitHub Copilot](/gh-aw/reference/assign-to-copilot/), and a human reviews and merges. ## The Four Phases [Section titled “The Four Phases”](#the-four-phases) ``` flowchart LR research([Research]) --> plan[Plan issues] plan --> assign[Assign to Copilot] assign --> merge[Review & merge] ``` Each phase produces a concrete artifact consumed by the next, and every transition is a human checkpoint. ### Phase 1: Research [Section titled “Phase 1: Research”](#phase-1-research) A scheduled workflow investigates the codebase from a specific angle and publishes its findings as a GitHub discussion. The discussion is the contract between the research phase and everything that follows—it contains the analysis, recommendations, and context a planner needs. The [`go-fan`](https://github.com/github/gh-aw/blob/main/.github/workflows/go-fan.md) workflow is a live example: it runs each weekday, picks one Go dependency, compares current usage against upstream best practices, and creates a `[go-fan]` discussion under the `audits` category. ```aw --- name: Go Fan on: schedule: daily on weekdays workflow_dispatch: engine: claude safe-outputs: create-discussion: title-prefix: "[go-fan] " category: "audits" max: 1 close-older-discussions: true tools: cache-memory: true github: toolsets: [default] --- Analyze today's Go dependency. Compare current usage in this repository against upstream best practices and recent releases. Save a summary to scratchpad/mods/ and create a discussion with findings and improvement recommendations. ``` The research agent uses `cache-memory` to track which modules have been reviewed so it rotates through them systematically across runs. ### Phase 2: Plan [Section titled “Phase 2: Plan”](#phase-2-plan) After reading the research discussion, a developer triggers the `/plan` command on it. The [`plan`](https://github.com/github/gh-aw/blob/main/.github/workflows/plan.md) workflow reads the discussion, extracts concrete work items, and creates up to five sub-issues grouped under a parent tracking issue. ```plaintext /plan focus on the quick wins and API simplifications ``` The planner formats each sub-issue for a coding agent: a clear objective, the files to touch, step-by-step implementation guidance, and acceptance criteria. Issues are tagged `[plan]` and `ai-generated`. Tip The `/plan` command accepts inline guidance. Steer it toward high-priority findings or away from lower-priority ones before it generates issues. ### Phase 3: Assign [Section titled “Phase 3: Assign”](#phase-3-assign) With well-scoped issues in hand, the developer [assigns them to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) for automated implementation. Copilot opens a pull request and posts progress updates as it works. Issues can be assigned individually through the GitHub UI, or pre-assigned in bulk via an orchestrator workflow: ```aw --- name: Auto-assign plan issues to Copilot on: issues: types: [labeled] engine: copilot safe-outputs: assign-to-user: target: "*" add-comment: target: "*" --- When an issue is labeled `plan` and has no assignee, assign it to Copilot and add a comment indicating automated assignment. ``` For multi-issue plans, assignments can run in parallel—Copilot works independently on each issue and opens separate PRs. ### Phase 4: Merge [Section titled “Phase 4: Merge”](#phase-4-merge) Copilot’s pull request is reviewed by a human maintainer. The maintainer checks correctness, runs tests, and merges. The tracking issue created in Phase 2 closes automatically when all sub-issues are resolved. ## End-to-End Example [Section titled “End-to-End Example”](#end-to-end-example) The following trace shows the full cycle using `go-fan` as the research driver. **Monday 7 AM** — `go-fan` runs and creates a discussion: > **\[go-fan] Go Module Review: spf13/cobra** > > Current usage creates a new `Command` per invocation. cobra v1.8 introduced `SetContext` for propagating cancellation. Quick wins: pass context through subcommands, use `PersistentPreRunE` for shared setup. **Monday afternoon** — Developer reads the discussion and types: ```plaintext /plan ``` The planner creates a parent tracking issue `[plan] cobra improvements` with three sub-issues: * `[plan] Pass context through subcommands using cobra SetContext` * `[plan] Refactor shared setup into PersistentPreRunE` * `[plan] Add context cancellation tests` **Monday afternoon** — Developer assigns the first two issues to Copilot. Both open PRs within minutes. **Tuesday** — Developer reviews PRs, requests a minor change on one, approves the other. Both merge by end of day. The tracking issue closes. ## Workflow Configuration Patterns [Section titled “Workflow Configuration Patterns”](#workflow-configuration-patterns) ### Research: produce one discussion per run [Section titled “Research: produce one discussion per run”](#research-produce-one-discussion-per-run) ```aw safe-outputs: create-discussion: expires: 1d category: "research" max: 1 close-older-discussions: true ``` `close-older-discussions: true` prevents discussion accumulation—only the latest finding stays open for the planner. ### Research: maintain memory across runs [Section titled “Research: maintain memory across runs”](#research-maintain-memory-across-runs) ```aw tools: cache-memory: true ``` Use `cache-memory` to track state between scheduled runs—which items have been reviewed, trend data, or historical baselines. ### Plan: issue grouping [Section titled “Plan: issue grouping”](#plan-issue-grouping) ```aw safe-outputs: create-issue: expires: 2d title-prefix: "[plan] " labels: [plan, ai-generated] max: 5 group: true ``` `group: true` creates a parent tracking issue automatically. Do not create the parent manually—the workflow handles it. ### Assign: pre-assign via `assignees` [Section titled “Assign: pre-assign via assignees”](#assign-pre-assign-via-assignees) For research workflows that produce self-contained, well-scoped issues, skip the manual plan phase and assign directly: ```aw safe-outputs: create-issue: title-prefix: "[fix] " labels: [ai-generated] assignees: copilot ``` The `duplicate-code-detector` workflow uses this approach—duplication fixes are narrow enough that a planning phase adds no value. ## Customization [Section titled “Customization”](#customization) Adapt this pattern by varying: * **Research focus**: static analysis, performance metrics, documentation quality, security, code duplication, test coverage * **Frequency**: daily, weekly, on-demand * **Report format**: discussions (for open-ended findings), issues (for self-contained tasks) * **Planning approach**: automatic (well-scoped research goes straight to Copilot via `assignees: copilot`) vs. manual (developer reviews before assigning) * **Assignment method**: pre-assign in the research workflow, bulk-assign via an orchestrator workflow, or assign individually through the GitHub UI ## Limitations [Section titled “Limitations”](#limitations) The multi-phase approach takes longer than direct execution and requires developers to review research reports and generated issues. Research agents may surface findings that don’t require action (false positives), and each phase transition needs clear handoffs. Research agents often require specialized MCPs (Serena, Tavily, etc.) for deeper analysis. ## When to Use ResearchPlanAssignOps [Section titled “When to Use ResearchPlanAssignOps”](#when-to-use-researchplanassignops) This pattern fits when: * The scope of work is unknown until analysis runs * Issues need human prioritization before implementation * Research findings vary in quality (some runs find nothing actionable) * Multiple work items can be executed in parallel Prefer a simpler pattern when: * The work is already well-defined (use [IssueOps](/gh-aw/patterns/issue-ops/)) * Issues can go directly to Copilot without review (use the `assignees: copilot` shortcut in your research workflow) * Work spans multiple repositories (use [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/)) ## Existing Workflows [Section titled “Existing Workflows”](#existing-workflows) | Phase | Workflow | Description | | -------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Research | [`go-fan`](https://github.com/github/gh-aw/blob/main/.github/workflows/go-fan.md) | Daily Go dependency analysis with best-practice comparison | | Research | [`copilot-cli-deep-research`](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-cli-deep-research.md) | Weekly analysis of Copilot CLI feature usage | | Research | [`static-analysis-report`](https://github.com/github/gh-aw/blob/main/.github/workflows/static-analysis-report.md) | Daily security scan with clustered findings | | Research | [`duplicate-code-detector`](https://github.com/github/gh-aw/blob/main/.github/workflows/duplicate-code-detector.md) | Daily semantic duplication analysis (auto-assigns) | | Plan | [`plan`](https://github.com/github/gh-aw/blob/main/.github/workflows/plan.md) | `/plan` slash command—converts issues or discussions into sub-issues | | Assign | GitHub UI / workflow | [Assign issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot) for automated PR creation | ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [DispatchOps](/gh-aw/patterns/dispatch-ops/) — Manually triggered research and one-off investigations * [WorkQueueOps](/gh-aw/patterns/workqueue-ops/) — Sequential queue processing for large backlogs * [Safe Outputs](/gh-aw/reference/safe-outputs/) — Secure write operations * [Assign to Copilot](/gh-aw/reference/assign-to-copilot/) — Assigning issues to GitHub Copilot # SpecOps > Maintain and propagate W3C-style specifications using agentic workflows SpecOps is a pattern for maintaining formal specifications using agentic workflows. It leverages the [`w3c-specification-writer` agent](https://github.com/github/gh-aw/blob/main/.github/agents/w3c-specification-writer.agent.md) to create W3C-style specifications with RFC 2119 keywords (MUST, SHALL, SHOULD, MAY) and automatically propagates changes to consuming implementations via [cross-repository workflows](/gh-aw/reference/cross-repository/). ``` flowchart LR update([Update spec]) --> review[Review & merge spec PR] review --> propagate[Propagate to consumer repos] ``` ## How SpecOps Works [Section titled “How SpecOps Works”](#how-specops-works) 1. **Update specification** — Trigger a workflow with the `w3c-specification-writer` agent to edit the spec document (RFC 2119 keywords, version bump, change log). 2. **Review changes** — Approve the specification pull request. 3. **Propagate automatically** — On merge, workflows detect updates and create PRs in consuming repositories (like [gh-aw-mcpg](https://github.com/github/gh-aw-mcpg)) to maintain compliance. 4. **Verify compliance** — Test generation workflows update compliance test suites against the new requirements. ## Update Specifications [Section titled “Update Specifications”](#update-specifications) Create a workflow to update specifications using the [`w3c-specification-writer` agent](https://github.com/github/gh-aw/blob/main/.github/agents/w3c-specification-writer.agent.md): ```yaml --- name: Update MCP Gateway Spec on: workflow_dispatch: inputs: change_description: description: 'What needs to change in the spec?' required: true type: string engine: copilot strict: true safe-outputs: create-pull-request: title-prefix: "[spec] " labels: [documentation, specification] tools: edit: bash: --- # Specification Update Workflow Update the MCP Gateway specification using the w3c-specification-writer agent. **Change Request**: ${{ inputs.change_description }} ## Your Task 1. Review the current specification at `docs/src/content/docs/reference/mcp-gateway.md` 2. Apply the requested changes following W3C conventions: - Use RFC 2119 keywords (MUST, SHALL, SHOULD, MAY) - Update version number (major/minor/patch) - Add entry to Change Log section - Update Status of This Document if needed 3. Ensure changes maintain clear conformance requirements, testable specifications, and complete examples 4. Create a pull request with the updated specification ``` ## Propagate Changes [Section titled “Propagate Changes”](#propagate-changes) After specification updates merge, automatically propagate changes to consuming repositories: ```yaml --- name: Propagate Spec Changes on: push: branches: - main paths: - 'docs/src/content/docs/reference/mcp-gateway.md' engine: copilot strict: true safe-outputs: create-pull-request: title-prefix: "[spec-update] " labels: [dependencies, specification] tools: github: toolsets: [repos, pull_requests] edit: bash: --- # Specification Propagation Workflow The MCP Gateway specification has been updated. Propagate changes to consuming repositories. ## Consuming Repositories - **gh-aw-mcpg**: Update implementation compliance, schemas, and tests - **gh-aw**: Update MCP gateway validation and documentation ## Your Task 1. Read the latest specification version and change log 2. Identify breaking changes and new requirements 3. For each consuming repository: - Update implementation to match spec - Run tests to verify compliance - Create pull request with changes 4. Create tracking issue linking all PRs ``` ## Specification Structure [Section titled “Specification Structure”](#specification-structure) W3C-style specifications require: Abstract, Status, Introduction, Conformance, numbered technical sections with RFC 2119 keywords, Compliance testing, References, and a Change log. **Example RFC 2119 usage**: ```markdown ## 3. Gateway Configuration The gateway MUST validate all configuration fields before startup. The gateway SHOULD log validation errors with field names. The gateway MAY cache validated configurations. ``` See the [`w3c-specification-writer` agent](https://github.com/github/gh-aw/blob/main/.github/agents/w3c-specification-writer.agent.md) for a complete template and guidelines. ## Semantic Versioning [Section titled “Semantic Versioning”](#semantic-versioning) | Bump | When | | ----------------- | --------------------------------- | | **Major (X.0.0)** | Breaking changes | | **Minor (0.Y.0)** | New features, backward-compatible | | **Patch (0.0.Z)** | Bug fixes, clarifications | The [MCP Gateway Specification](/gh-aw/reference/mcp-gateway/) is a live example — maintained by the `layout-spec-maintainer` workflow and implemented in [gh-aw-mcpg](https://github.com/github/gh-aw-mcpg). ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) — Cross-repository coordination * [Cross-Repository Operations](/gh-aw/reference/cross-repository/) — Checkout and target-repo configuration * [Safe Outputs](/gh-aw/reference/safe-outputs/) — Secure write operations # WorkQueueOps > Process a queue of work items using GitHub issues, sub-issues, cache-memory, or Discussions as durable queue backends WorkQueueOps is a pattern for systematically processing a large backlog of work items. Instead of processing everything at once, work is queued using issue checklists, [cache-memory](/gh-aw/reference/cache-memory/), or Discussions as durable backends, tracked, and consumed incrementally — surviving interruptions, rate limits, and multi-day horizons. Use it when operations are idempotent and progress visibility matters. ``` flowchart LR queue[(Queue)] --> process[Process next N items] process --> mark[Mark complete] mark --> queue ``` ## Queue Strategy 1: Issue Checklist as Queue [Section titled “Queue Strategy 1: Issue Checklist as Queue”](#queue-strategy-1-issue-checklist-as-queue) Use GitHub issue checkboxes as a lightweight, human-readable queue. The agent reads the issue body, finds unchecked items, processes each one, and checks it off. Best for small-to-medium batches (< 100 items). Use [Concurrency](/gh-aw/reference/concurrency/) controls to prevent race conditions between parallel runs. ```aw --- on: workflow_dispatch: inputs: queue_issue: description: "Issue number containing the checklist queue" required: true tools: github: toolsets: [issues] safe-outputs: update-issue: body: true add-comment: max: 1 concurrency: group: workqueue-${{ inputs.queue_issue }} cancel-in-progress: false --- # Checklist Queue Processor You are processing a work queue stored as checkboxes in issue #${{ inputs.queue_issue }}. 1. Read issue #${{ inputs.queue_issue }} and find all unchecked items (`- [ ]`). 2. For each unchecked item (at most 10 per run): perform the required work, then edit the issue body to change `- [ ]` to `- [x]`. 3. Add a comment summarizing what was completed and what remains. 4. If all items are checked, close the issue with a summary comment. ``` ``` flowchart LR issue[Issue checklist] --> process[Process unchecked items] process --> check[Check off completed] ``` ## Queue Strategy 2: Sub-Issues as Queue [Section titled “Queue Strategy 2: Sub-Issues as Queue”](#queue-strategy-2-sub-issues-as-queue) Create one sub-issue per work item. The agent queries open sub-issues of a parent tracking issue, processes each one, and closes it when done. Scales to hundreds of items with individual discussion threads per item. Use `max:` limits on `close-issue` to avoid notification storms. ```aw --- on: schedule: hourly workflow_dispatch: tools: github: toolsets: [issues] safe-outputs: add-comment: max: 5 close-issue: max: 5 concurrency: group: sub-issue-queue cancel-in-progress: false --- # Sub-Issue Queue Processor You are processing a queue of open sub-issues. The parent tracking issue is labeled `queue-tracking`. 1. Find the open issue labeled `queue-tracking` — this is the queue parent. 2. List its open sub-issues and process at most 5 per run. 3. For each sub-issue: read the body, perform the work, add a result comment, then close the issue. 4. Add a progress comment on the parent issue showing how many items remain. If no sub-issues are open, post a comment on the parent issue saying the queue is empty. ``` ``` flowchart LR parent[Parent tracking issue] --> subissues[Open sub-issues] subissues --> process[Process & close per item] ``` ## Queue Strategy 3: Cache-Memory Queue [Section titled “Queue Strategy 3: Cache-Memory Queue”](#queue-strategy-3-cache-memory-queue) Store queue state as a JSON file in [cache-memory](/gh-aw/reference/cache-memory/). Each run loads the file, picks up where the last run left off, and saves the updated state. Best for large queues and multi-day processing horizons where items are generated programmatically. Cache-memory is scoped to a single branch; use filesystem-safe timestamps in filenames (no colons — e.g., `YYYY-MM-DD-HH-MM-SS-sss`). ````aw --- on: schedule: daily on weekdays workflow_dispatch: tools: cache-memory: true github: toolsets: [repos, issues] bash: - "jq" safe-outputs: add-comment: max: 10 add-labels: allowed: [processed, needs-review] max: 10 --- # Cache-Memory Queue Processor You process items from a persistent JSON queue at `/tmp/gh-aw/cache-memory/workqueue.json`: ```json { "pending": ["item-1", "item-2"], "in_progress": [], "completed": ["item-0"], "failed": [], "last_run": "2026-04-07-06-00-00" } ```` 1. Load the queue file. If it doesn’t exist, initialize it by listing all open issues without the label `processed` and populating `pending` with their numbers. 2. Move up to 10 items from `pending` to `in_progress`. 3. For each item: perform the required operation, then move it to `completed` on success or `failed` (with an error note) on failure. 4. Save the updated queue JSON and report: X completed, Y failed, Z remaining. If `pending` is empty, announce that the queue is exhausted. ````plaintext ```mermaid flowchart LR json[workqueue.json] --> process[Process pending items] process --> save[Save updated queue] ```` ## Queue Strategy 4: Discussion-Based Queue [Section titled “Queue Strategy 4: Discussion-Based Queue”](#queue-strategy-4-discussion-based-queue) Use a GitHub Discussion to track pending work items. Unresolved replies represent pending work; processing an item means resolving its reply. Best for community-sourced queues and async collaboration where humans need to inspect items before or after processing. Requires `discussions` in the GitHub toolset. ```aw --- on: schedule: daily workflow_dispatch: tools: github: toolsets: [discussions] safe-outputs: add-comment: max: 5 create-discussion: title-prefix: "[queue-log] " category: "General" concurrency: group: discussion-queue cancel-in-progress: false --- # Discussion Queue Processor A GitHub Discussion titled "Work Queue" (category "General") tracks pending items. Each unresolved top-level reply is a work item. 1. Find the "Work Queue" discussion and list all unresolved replies (`isAnswered: false`). 2. For each unresolved reply (at most 5 per run): parse the work description, perform the work, then reply with the result. 3. Create a summary discussion post documenting what was processed today. ``` ``` flowchart LR discussion[Work Queue discussion] --> replies[Unresolved replies] replies --> process[Process & resolve] ``` ## Idempotency and Concurrency [Section titled “Idempotency and Concurrency”](#idempotency-and-concurrency) All WorkQueueOps patterns should be **idempotent**: running the same item twice should not cause double processing. | Technique | How | | -------------------- | --------------------------------------------------------------------------------- | | Check before acting | Query current state (label present? comment exists?) before making changes | | Atomic state updates | Write queue state in a single step; avoid partial updates | | Concurrency groups | Use `concurrency.group` with `cancel-in-progress: false` to prevent parallel runs | | Retry budgets | Track failed items separately; set a retry limit before giving up | ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [BatchOps](/gh-aw/patterns/batch-ops/) — Process large volumes in parallel chunks rather than sequentially * [ResearchPlanAssignOps](/gh-aw/patterns/research-plan-assign-ops/) — Research → Plan → Assign pattern for developer-supervised work * [Cache Memory](/gh-aw/reference/cache-memory/) — Persistent state storage across workflow runs * [Repo Memory](/gh-aw/reference/repo-memory/) — Git-committed persistent state for cross-branch sharing * [Concurrency](/gh-aw/reference/concurrency/) — Prevent race conditions in queue-based workflows # A/B Experiments > Run A/B experiments in GitHub Agentic Workflows to test prompt variants and measure the effect of different instructions across runs. The `experiments` section of the workflow frontmatter enables statistical A/B testing by defining named experiments, each with a set of variant values. At runtime the activation job selects one variant per experiment using a balanced round-robin counter and exposes the selection to the workflow prompt. ## Declaring experiments [Section titled “Declaring experiments”](#declaring-experiments) Add an `experiments` map to the workflow frontmatter. Each key names an experiment; the value is either a simple array of variants (bare-array form) or a rich object with additional metadata fields. ### Bare-array form [Section titled “Bare-array form”](#bare-array-form) ```aw --- on: issues: types: [opened] engine: copilot experiments: style: [concise, detailed] --- Summarize this issue in a **${{ experiments.style }}** way. ``` ### Rich object form [Section titled “Rich object form”](#rich-object-form) Use the object form to attach metadata that drives automated reporting, guardrail enforcement, and lifecycle tracking: ```aw --- on: schedule: daily on weekdays engine: copilot experiments: prompt_style: variants: [concise, detailed] description: "Test whether a concise prompt reduces token cost without quality loss" hypothesis: "H0: no change in effective_tokens. H1: concise reduces tokens by >=15%" metric: effective_tokens secondary_metrics: [duration_ms, discussion_word_count] guardrail_metrics: - name: success_rate threshold: ">=0.95" - name: empty_output_rate threshold: "==0" weight: [50, 50] min_samples: 25 start_date: "2026-05-05" end_date: "2026-07-25" issue: 1234 --- Summarize the findings in a **${{ experiments.prompt_style }}** way. ``` Note Experiment names must be valid identifiers: start with a letter or underscore, followed by letters, digits, or underscores (e.g. `style`, `feature_1`). Names that do not match this pattern are ignored. ## Using variants in the prompt [Section titled “Using variants in the prompt”](#using-variants-in-the-prompt) Reference a variant with `${{ experiments. }}`. At runtime this is substituted with the selected variant string (e.g. `concise`). Use the `{{#if experiments. }}` block syntax for conditional prompt sections. A variant value of `no` is treated as falsy, enabling yes/no flag experiments: ```aw --- experiments: caveman: [yes, no] --- {{#if experiments.caveman }} Talk like a caveman in all your responses. Me test. You run. {{/if}} Address the issue described above. ``` ## Statistical balancing [Section titled “Statistical balancing”](#statistical-balancing) The activation job maintains a per-variant invocation counter that is persisted according to the `storage` setting in the `experiments:` block (see [Storage Configuration](#storage-configuration) below). The variant with the lowest cumulative count is selected on each run; when multiple variants share the lowest count (including the very first run when state is empty), one is chosen at random so no variant is systematically favoured. Over N runs every variant is used approximately N/K times (K = variant count), providing basic A/B balance with no configuration. When a `weight` array is provided, weighted-random selection is used instead of round-robin. Each variant is chosen with probability proportional to its weight (e.g. `[70, 30]` gives the first variant a 70% probability). When `start_date` or `end_date` is set and today falls outside the window, the control variant (first entry) is returned without incrementing any counter. ## Storage Configuration [Section titled “Storage Configuration”](#storage-configuration) The `storage` key inside the `experiments:` map controls how experiment state is persisted: ```yaml experiments: storage: repo # or: cache (default: repo) prompt_style: [concise, detailed] ``` | Value | Behavior | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `repo` (**default**) | Commits state to a git branch named `experiments/{sanitizedWorkflowID}` (workflow ID lowercased with hyphens removed, e.g. `my-workflow` → `experiments/myworkflow`). Durable — survives cache evictions. Requires `contents: write` permission (added automatically by the compiler). | | `cache` | Uses GitHub Actions cache (legacy). State may be evicted after 7 days of inactivity. | When `storage: repo`, the compiler adds a `push_experiments_state` job that runs after the activation job and commits the updated `state.json` to the experiments branch. ## Accessing assignments downstream [Section titled “Accessing assignments downstream”](#accessing-assignments-downstream) Each experiment exposes its selected variant as an activation job output: | Expression | Description | | -------------------------------------- | ---------------------------------------- | | `needs.activation.outputs.` | Selected variant for experiment `` | | `needs.activation.outputs.experiments` | All assignments as a JSON object | Use these expressions in downstream jobs defined in the `jobs:` frontmatter section. ## Analyzing results [Section titled “Analyzing results”](#analyzing-results) The activation job uploads the counter state as an `experiment` artifact. Download and inspect it with the `gh aw` CLI: ```bash # Download the experiment artifact for a specific run gh aw audit --artifacts experiment # Display experiment assignments in the audit report gh aw audit ``` The `A/B Experiments` section of the audit report shows the variant chosen on the most recent run and the cumulative counts across all runs: ```plaintext A/B Experiments • caveman = yes (cumulative: no:4, yes:5) • style = concise (cumulative: concise:5, detailed:4) ``` ### Filtering audit results by variant [Section titled “Filtering audit results by variant”](#filtering-audit-results-by-variant) Use `--experiment` and `--variant` to filter audit runs to a specific variant: ```bash gh aw audit --experiment prompt_style --variant concise ``` ### Step summary [Section titled “Step summary”](#step-summary) Each activation job writes a Markdown step summary that shows variant assignments, cumulative counts, and — when the rich object form is used — progress toward `min_samples`: ```plaintext ## A/B Experiment Assignments | Experiment | Selected Variant | All Variants | Cumulative Counts | | --- | --- | --- | --- | | prompt_style | concise | concise, detailed | concise: 8, detailed: 7| ### Sampling Progress prompt_style (target: 25 per variant) concise: ████████░░░░░░░░░░░░ 8/25 (32%) detailed: ███████░░░░░░░░░░░░░ 7/25 (28%) ### Experiment Details **prompt_style** > Test whether a concise prompt reduces token cost without quality loss **Hypothesis:** H0: no change in effective_tokens. H1: concise reduces tokens by >=15% **Guardrail metrics:** - `success_rate` >=0.95 - `empty_output_rate` ==0 Tracking issue: [#1234](https://github.com/owner/repo/issues/1234) ``` ## Frontmatter reference [Section titled “Frontmatter reference”](#frontmatter-reference) ### Bare-array form [Section titled “Bare-array form”](#bare-array-form-1) | Field | Type | Description | | -------------------- | ---------- | ------------------------------------------------------- | | `experiments` | `object` | Map of experiment name → variant array or config object | | `experiments.` | `string[]` | Array of two or more variant strings for one experiment | ### Object form fields [Section titled “Object form fields”](#object-form-fields) | Field | Type | Required | Description | | ------------------- | ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `variants` | `string[]` | ✓ | Array of two or more variant strings | | `description` | `string` | | Human-readable explanation of what the experiment tests | | `hypothesis` | `string` | | Null and alternative hypothesis (e.g. `"H0: no change. H1: concise reduces tokens by >=15%"`) | | `metric` | `string` | | Primary metric to observe (e.g. `effective_tokens`, `duration_ms`) | | `secondary_metrics` | `string[]` | | Additional metrics to track alongside the primary metric | | `guardrail_metrics` | `object[]` | | List of `{name, threshold}` pairs that must not degrade. Threshold is a comparison expression like `>=0.95` or `==0` | | `min_samples` | `integer` | | Minimum runs per variant required before statistical analysis is considered reliable. The step summary shows a progress bar toward this target. | | `weight` | `integer[]` | | Per-variant probability weights (same length as `variants`). Enables weighted-random selection; values are relative and need not sum to 100. | | `issue` | `integer` | | GitHub issue number that tracks this experiment’s lifecycle | | `start_date` | `string` | | ISO-8601 date (`YYYY-MM-DD`) before which the experiment is inactive. The control variant is returned before this date without incrementing any counter. | | `end_date` | `string` | | ISO-8601 date (`YYYY-MM-DD`) after which the experiment is inactive. The control variant is returned after this date without incrementing any counter. | # A/B Experiments Specification > Formal W3C-style specification for the GitHub Agentic Workflows A/B experiment system — frontmatter schema, variant selection, state persistence, expression integration, audit CLI, and statistical reporting. # A/B Experiments Specification [Section titled “A/B Experiments Specification”](#ab-experiments-specification) **Version**: 1.0.0\ **Status**: Draft\ **Latest Version**: [experiments-specification](/gh-aw/practices/experiments-specification/)\ **Editors**: gh-aw maintainers *** ## Abstract [Section titled “Abstract”](#abstract) This specification defines the A/B experiment system for GitHub Agentic Workflows (gh-aw). It covers the `experiments:` frontmatter schema, variant selection algorithms, state persistence backends, expression and template integration, activation job structure, audit CLI integration, and statistical analysis requirements. Conforming implementations provide operators with a zero-infrastructure mechanism to conduct controlled experiments on agentic workflow behavior using only workflow frontmatter declarations, without any external service dependency. This document consolidates and supersedes the normative sections of ADR-29534, ADR-29618, ADR-29628, ADR-29985, and ADR-29996. It also incorporates corrective requirements identified during an expert review of the implementation in May 2026. *** ## Status of This Document [Section titled “Status of This Document”](#status-of-this-document) This is a **Draft** specification. It may be updated, replaced, or made obsolete at any time. A future revision will promote this document to Candidate Recommendation once the reference implementation (gh-aw v1.x) satisfies all conformance requirements below. Promotion from **Draft** to **Candidate Recommendation** requires all of the following: 1. **Reference implementation completeness**: 100% of normative requirements in §§4–12 are implemented in `gh-aw` and mapped to concrete implementation files (**tracking issue**: [#31983](https://github.com/github/gh-aw/issues/31983)). 2. **Compliance coverage**: At least 95% of normative requirements have automated tests, and all MUST/MUST NOT requirements have at least one passing automated test (**tracking issue**: [#31983](https://github.com/github/gh-aw/issues/31983)). 3. **CI stability window**: The experiments-related test suite passes on the default branch for 30 consecutive days with no unresolved regression in variant selection, persistence, or reporting behavior (**tracking issue**: [#31983](https://github.com/github/gh-aw/issues/31983)). 4. **Interoperability evidence**: At least two production workflows using `experiments:` run for a minimum of 500 total assignments each with valid assignment artifacts and reproducible audit output (**tracking issue**: [#31983](https://github.com/github/gh-aw/issues/31983)). 5. **Review sign-off**: Written approval from at least two gh-aw maintainers that Sections 10–14 are complete, internally consistent, and suitable for Candidate Recommendation publication (**tracking issue**: [#31983](https://github.com/github/gh-aw/issues/31983)). ### Sync [Section titled “Sync”](#sync) * **Who reviews**: The experiments specification editors (`gh-aw maintainers`) perform the primary review; one release owner for the current minor version performs final sign-off. * **When**: Review occurs on the first business day of each month and during every minor-release cut. * **What triggers an immediate sync update**: 1. Any change to `experiments:` schema fields or validation behavior (§4) 2. Any change to variant selection, gating, or persistence logic (§§5–7) 3. Any change to audit/reporting output contracts (§§10–11) 4. Any incident postmortem that identifies spec/implementation drift When a trigger occurs, spec updates **SHOULD** be merged in the same PR as the implementation change or in a linked follow-up PR within 3 business days. Feedback should be filed as GitHub issues against the `github/gh-aw` repository with the `experiments` label. *** ## Table of Contents [Section titled “Table of Contents”](#table-of-contents) 1. [Introduction](#1-introduction) 2. [Conformance](#2-conformance) 3. [Definitions](#3-definitions) 4. [Frontmatter Schema](#4-frontmatter-schema) 5. [Variant Selection Algorithms](#5-variant-selection-algorithms) 6. [Date-Range Gating](#6-date-range-gating) 7. [State Persistence](#7-state-persistence) 8. [Expression and Template Integration](#8-expression-and-template-integration) 9. [Activation Job Structure](#9-activation-job-structure) 10. [Audit CLI Integration](#10-audit-cli-integration) 11. [Statistical Analysis and Reporting](#11-statistical-analysis-and-reporting) 12. [Simultaneous Experiments and Interaction Effects](#12-simultaneous-experiments-and-interaction-effects) 13. [Security Considerations](#13-security-considerations) 14. [Compliance Testing](#14-compliance-testing) 15. [References](#15-references) 16. [Appendices](#appendices) 17. [Change Log](#change-log) *** ## 1. Introduction [Section titled “1. Introduction”](#1-introduction) ### 1.1 Purpose [Section titled “1.1 Purpose”](#11-purpose) Agentic workflows compiled by gh-aw use a frontmatter-driven configuration model. Teams running these workflows need a first-class mechanism to test different prompt variants (tone, verbosity, persona, feature flags embedded in the prompt) across successive workflow runs. Without such a mechanism, variant testing is ad-hoc, untracked, and statistically unbalanced. This specification defines a self-contained A/B experiment system that requires no external service, no manual coordination, and no changes outside the workflow frontmatter. ### 1.2 Scope [Section titled “1.2 Scope”](#12-scope) This specification covers: * The `experiments:` frontmatter schema and its two syntactic forms (bare-array, rich-object). * Variant selection algorithms: balanced round-robin (least-used), weighted random, and date-gated fallback. * State persistence backends: git-branch (`repo`) and GitHub Actions cache (`cache`). * Expression and Handlebars template integration in the compiled workflow prompt. * The activation job structure generated by the compiler. * The `gh aw audit` CLI filtering interface for experiment-annotated runs. * Requirements for statistical analysis and reporting workflows that consume experiment artifacts. This specification does **not** cover: * The internal compiler architecture beyond what is observable at the compiled YAML boundary. * External analytics dashboards or third-party experiment platforms. * Multi-armed bandit or adaptive allocation algorithms (considered future work). ### 1.3 Design Goals [Section titled “1.3 Design Goals”](#13-design-goals) 1. **Zero external dependencies** — all state is stored within the repository or GitHub Actions infrastructure. 2. **Declarative** — the complete experiment configuration lives in the workflow frontmatter. 3. **Backward compatible** — adding `experiments:` to an existing workflow MUST NOT break any existing compiled output; removing it MUST restore the original output exactly. 4. **Statistically sound** — the default selection algorithm guarantees approximate variant balance in the minimum number of runs. 5. **Observable** — every run produces a durable artifact recording the variant assignment, and OTEL attributes propagate assignments to distributed-tracing backends automatically. *** ## 2. Conformance [Section titled “2. Conformance”](#2-conformance) ### 2.1 Requirements Notation [Section titled “2.1 Requirements Notation”](#21-requirements-notation) The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). ### 2.2 Conformance Classes [Section titled “2.2 Conformance Classes”](#22-conformance-classes) This specification defines three conformance classes: | Class | Requirements | | ---------------------- | ---------------------------------------------------------------------------------------- | | **Level 1 — Basic** | Satisfies all MUST/MUST NOT requirements in §4, §5, §8, and §9 | | **Level 2 — Standard** | Level 1 plus §6 (date gating), §7 (state persistence), §10 (audit CLI) | | **Level 3 — Complete** | Level 2 plus §11 (statistical analysis and reporting) and §12 (simultaneous experiments) | An implementation is considered **non-conformant** if it fails any MUST or MUST NOT requirement at the level it claims to implement. ### 2.3 Normative vs. Informative Content [Section titled “2.3 Normative vs. Informative Content”](#23-normative-vs-informative-content) Sections containing numbered requirements (e.g., “R-SCHEMA-001”) are **normative**. Notes, rationale blocks, and appendices are **informative** and carry no conformance weight. *** ## 3. Definitions [Section titled “3. Definitions”](#3-definitions) | Term | Definition | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **Experiment** | A named A/B test declared in workflow frontmatter, associating an identifier with two or more variant strings. | | **Variant** | A named string value representing one treatment arm in an experiment. | | **Control variant** | The first variant in the declared `variants` array; used as baseline and as fallback during date gating. | | **Invocation counter** | A per-experiment, per-variant integer stored in `state.json` that records the cumulative number of times a variant has been selected. | | **state.json** | The JSON file that stores invocation counters and per-run assignment history for all experiments in a single workflow. | | **Run record** | An entry in the `state.json` `runs` array recording the run ID, timestamp, and variant assignments for one workflow run. | | **Sanitized workflow ID** | The workflow basename (without `.md`) with hyphens removed and lowercased, used as a cache/branch key component. | | **Activation job** | The `activation` GitHub Actions job generated by the compiler that picks variants and exposes them to downstream jobs. | | **Experiment artifact** | A GitHub Actions artifact named `{sanitizedID}-experiment` uploaded by the activation job and containing `state.json` and `assignments.json`. | | **assignments.json** | A file in the experiment artifact containing only the current run’s variant assignments as a flat JSON object. | *** ## 4. Frontmatter Schema [Section titled “4. Frontmatter Schema”](#4-frontmatter-schema) ### 4.1 Field Declaration [Section titled “4.1 Field Declaration”](#41-field-declaration) **R-SCHEMA-001**: Workflow frontmatter **MAY** include an `experiments` field. Its absence **MUST** produce no change in compiled output. **R-SCHEMA-002**: The value of `experiments` **MUST** be a YAML map. Non-map values **MUST** be rejected at compile time with a descriptive error. **R-SCHEMA-003**: Every key in the `experiments` map, except the reserved `storage` key (§7.1), **MUST** be an experiment name that matches the regular expression `^[a-zA-Z_][a-zA-Z0-9_]*$`. Keys that do not match **MUST** be silently skipped with a compile-time warning emitted to stderr. > **Note (informative)**: The identifier pattern ensures experiment names can be used as GitHub Actions step output names and embedded in `${{ experiments. }}` expressions without bracket notation. ### 4.2 Bare-Array Form [Section titled “4.2 Bare-Array Form”](#42-bare-array-form) **R-SCHEMA-004**: Each experiment value **MAY** be declared as a YAML sequence of two or more strings: ```yaml experiments: prompt_style: [concise, detailed] ``` **R-SCHEMA-005**: A bare-array value with fewer than two entries **MUST NOT** be accepted; the compiler **MUST** emit a compile-time error. ### 4.3 Rich Object Form [Section titled “4.3 Rich Object Form”](#43-rich-object-form) **R-SCHEMA-006**: Each experiment value **MAY** alternatively be declared as a YAML object with a required `variants` field and optional metadata fields. The two forms **MUST** be accepted in the same `experiments` map without conflict. **R-SCHEMA-007**: The `variants` field **MUST** be an array of two or more non-empty strings. The same minimum-two-variants constraint from R-SCHEMA-005 applies. **R-SCHEMA-008**: The following optional fields are defined for the object form: | Field | Type | Description | | ------------------- | ------------------- | --------------------------------------------------------------------- | | `description` | string | Human-readable explanation of what the experiment tests. | | `hypothesis` | string | Null and alternative hypothesis statements. | | `metric` | string | Primary metric name to observe (e.g., `effective_tokens`). | | `secondary_metrics` | string\[] | Additional metrics to collect. | | `guardrail_metrics` | object\[] | Thresholds that must not degrade (see §4.4). | | `min_samples` | integer ≥ 1 | Minimum runs per variant before analysis is reliable. Defaults to 20. | | `weight` | integer\[] | Per-variant probability weights (see §5.2). | | `issue` | integer ≥ 1 | GitHub issue number tracking this experiment. | | `start_date` | string (YYYY-MM-DD) | Experiment is inactive before this date (see §6). | | `end_date` | string (YYYY-MM-DD) | Experiment is inactive after this date (see §6). | | `analysis_type` | string enum | Statistical test for automated reporting (see §11.2). | | `tags` | string\[] | Free-form labels for dashboard filtering. | | `notify` | object | Significance-alert destination (see §4.5). | **R-SCHEMA-009**: The `weight`, `issue`, `min_samples`, `start_date`, `end_date`, `analysis_type`, `tags`, and `notify` fields carry no effect on variant assignment outside their documented subsections. `description`, `hypothesis`, `metric`, `secondary_metrics`, and `tags` are purely informative at runtime. **R-SCHEMA-010**: Implementations **MUST NOT** introduce additional properties in the object form without a corresponding schema update; the compiler **MUST** reject unknown keys under strict mode. ### 4.4 Guardrail Metrics [Section titled “4.4 Guardrail Metrics”](#44-guardrail-metrics) **R-SCHEMA-011**: Each entry in `guardrail_metrics` **MUST** be an object with exactly two string fields: `name` and `threshold`. The `threshold` **MUST** match the pattern `^(>=|<=|==|>|<)-?\d+(\.\d+)?$` (e.g., `>=0.95`, `==0`, `<=0.05`). **R-SCHEMA-012**: Guardrail evaluation is **INFORMATIVE** at the schema level — the compiler does not enforce guardrails at compile time. Reporting tooling (§11) **MUST** evaluate each guardrail and include pass/fail status in its output. ### 4.5 Notify Object [Section titled “4.5 Notify Object”](#45-notify-object) **R-SCHEMA-013**: The `notify` object **MUST** contain only the keys `discussion` and/or `issue`, each of which **MUST** be a positive integer (minimum 1). Unknown keys in `notify` **MUST** be rejected by schema validation. **R-SCHEMA-014**: When `notify.issue` is set and the reporting workflow posts a comment to that issue, the compiled workflow **MUST** declare `permissions: issues: write`. Implementations that generate reporting workflows **MUST** automatically add this permission when `notify.issue` is present in any experiment configuration within the scope of that workflow. > **Note (informative)**: Failure to include `issues: write` causes comment posting to silently fail with a 403 response. This was identified as a defect in the `daily-experiment-report` workflow (May 2026 review). *** ## 5. Variant Selection Algorithms [Section titled “5. Variant Selection Algorithms”](#5-variant-selection-algorithms) ### 5.1 Balanced Round-Robin (Least-Used) [Section titled “5.1 Balanced Round-Robin (Least-Used)”](#51-balanced-round-robin-least-used) **R-SELECT-001**: When `weight` is absent or invalid (§5.2), implementations **MUST** select the variant with the lowest cumulative invocation count stored in `state.json`. **R-SELECT-002**: When two or more variants share the lowest count — including the initial state where all counts are zero — implementations **MUST** break ties by selecting uniformly at random from the tied variants. No variant **MUST** be systematically favoured by position. **R-SELECT-003**: After selecting a variant via round-robin, implementations **MUST** increment the invocation counter for that variant in `state.json` before persisting state. > **Note (informative)**: Round-robin guarantees that over K×N runs each variant appears approximately N times, achieving balance in far fewer runs than random selection. The random tie-breaking on the first run ensures no variant is systematically advantaged. ### 5.2 Weighted Random Selection [Section titled “5.2 Weighted Random Selection”](#52-weighted-random-selection) **R-SELECT-004**: When `weight` is provided and its length equals the length of `variants`, implementations **MUST** use weighted random selection: each variant is chosen with probability proportional to its weight value. **R-SELECT-005**: When all weight values are zero, implementations **MUST** return the control variant (first entry in `variants`) without erroring. **R-SELECT-006**: Weighted random selection **MUST** increment the invocation counter for the selected variant before persisting state. > **Note (normative correction)**: ADR-29618 Rule 9 incorrectly stated that weighted selection “MUST NOT increment any variant counter.” This rule is hereby superseded. Counter increments for weighted selection are required to enable `min_samples` progress tracking and accurate per-run history. The reference implementation (`pick_experiment.cjs`) already implements this correct behavior by calling `recordVariant` unconditionally after both selection paths. **R-SELECT-007**: When `weight` is provided but its length does not equal the length of `variants`, implementations **MUST** treat `weight` as absent and fall back to round-robin selection (R-SELECT-001). > **Note (statistical, informative)**: Standard power calculations assume balanced allocations. When weights are non-uniform (e.g., `[70, 30]`), the effective sample size is reduced. The `min_samples` target should be interpreted as the minimum required for the **smaller group**. For a 70/30 split, experimenters should set `min_samples` to the desired count for the 30% arm and expect the 70% arm to accumulate proportionally more observations. ### 5.3 Variant Exposure [Section titled “5.3 Variant Exposure”](#53-variant-exposure) **R-SELECT-008**: Implementations **MUST** expose each selected variant as a named step output `steps.pick-experiment.outputs.` and **MUST** also set a combined JSON step output `steps.pick-experiment.outputs.experiments` containing all variant assignments as a serialized JSON object. **R-SELECT-009**: Experiment names **MUST** be sorted alphabetically when building the `experiments` JSON output to produce deterministic, reproducible output across runs with identical state. *** ## 6. Date-Range Gating [Section titled “6. Date-Range Gating”](#6-date-range-gating) **R-DATE-001**: When `start_date` is provided and the current date (UTC, `YYYY-MM-DD` format) is strictly before `start_date`, implementations **MUST** return the control variant without incrementing any counter. **R-DATE-002**: When `end_date` is provided and the current date (UTC, `YYYY-MM-DD` format) is strictly after `end_date`, implementations **MUST** return the control variant without incrementing any counter. **R-DATE-003**: Date comparison **MUST** use UTC date. Local timezone offsets **MUST NOT** affect the result. **R-DATE-004**: When both `start_date` and `end_date` are provided and the current UTC date is within the inclusive range `[start_date, end_date]`, the experiment is active and normal variant selection (§5) applies. **R-DATE-005**: If `start_date` or `end_date` do not match the `YYYY-MM-DD` pattern, implementations **SHOULD** treat them as absent (ignore silently) rather than hard-failing, to preserve forward compatibility. *** ## 7. State Persistence [Section titled “7. State Persistence”](#7-state-persistence) ### 7.1 Storage Configuration [Section titled “7.1 Storage Configuration”](#71-storage-configuration) **R-STORE-001**: The `experiments:` map **MUST** support a reserved `storage` key whose value is one of `"repo"` (default) or `"cache"`. Any other value **MUST** produce a compile-time warning and fall back to `"repo"`. **R-STORE-002**: When `storage` is absent, implementations **MUST** behave as if `storage: repo` was specified. **R-STORE-003**: The `storage` key **MUST NOT** be treated as an experiment name; it **MUST** be excluded from experiment configuration extraction. ### 7.2 `state.json` Format [Section titled “7.2 state.json Format”](#72-statejson-format) **R-STORE-004**: The `state.json` file **MUST** be a valid JSON object with the following top-level structure: ```json { "counts": { "": { "": } }, "runs": [ { "run_id": "", "timestamp": "", "assignments": { "": "" } } ] } ``` **R-STORE-005**: The `runs` array **MUST** be pruned to at most 512 entries (keeping the most recent) to prevent unbounded growth. **R-STORE-006**: When loading a `state.json` that has no `runs` field (legacy format), implementations **MUST** initialize `runs` to an empty array and continue normally. **R-STORE-007**: When at least one experiment is assigned on a run, implementations **MUST** append one run record to `state.runs` before persisting. Each record **MUST** contain: * `run_id`: the value of `GITHUB_RUN_ID`, or `""` when absent. * `timestamp`: an ISO-8601 UTC timestamp of the selection moment. * `assignments`: an object mapping each assigned experiment name to its selected variant. **R-STORE-008**: When no experiments are assigned (e.g., all experiments are outside their date window), implementations **MUST NOT** append a run record or rewrite `state.json`. ### 7.3 `repo` Storage Mode [Section titled “7.3 repo Storage Mode”](#73-repo-storage-mode) **R-STORE-REPO-001**: When `storage: repo` is active, the activation job **MUST** load experiment state by fetching `state.json` from the git branch named `experiments/{sanitizedWorkflowID}` via the GitHub REST API (GET /repos/{owner}/{repo}/contents/{path}). **R-STORE-REPO-002**: A 404 response (branch or file does not exist) **MUST** be treated as an empty initial state; the activation job **MUST NOT** fail. **R-STORE-REPO-003**: After the activation job completes, a dedicated `push_experiments_state` job **MUST** be generated. This job **MUST**: * Download the experiment artifact from the current run. * Commit the updated `state.json` and `assignments.json` to the experiments git branch. * Declare `permissions: contents: write`. * Be listed as a dependency of the conclusion job to ensure state is persisted before the workflow terminates. **R-STORE-REPO-004**: The commit **SHOULD** be made via the GitHub GraphQL `createCommitOnBranch` mutation (producing a verified, signed commit). A plain `git push` **MAY** be used as a fallback when the GraphQL mutation is unavailable. **R-STORE-REPO-005**: The push step **SHOULD** implement retry logic with exponential backoff (minimum 3 attempts, base delay ≥ 1 second) to handle transient API failures and concurrent push conflicts. > **Note (race condition, informative)**: When two workflow runs start concurrently, both will read the same `state.json` from the branch before either has committed its update. Both runs will therefore select the same least-used variant. The retry logic in R-STORE-REPO-005 handles write conflicts at push time but does not prevent duplicate variant selections at read time. On low-frequency workflows (daily cron) this is effectively never a problem. On high-frequency workflows (hourly or per-commit), experimenters should account for a small probability of temporarily imbalanced runs. A future revision of this specification **MAY** address this with an optimistic-concurrency guard at the fetch step. ### 7.4 `cache` Storage Mode [Section titled “7.4 cache Storage Mode”](#74-cache-storage-mode) **R-STORE-CACHE-001**: When `storage: cache` is explicitly set, the activation job **MUST** restore experiment state from GitHub Actions cache using a key of the form `experiments-{sanitizedWorkflowID}-{GITHUB_RUN_ID}` and a restore-key prefix `experiments-{sanitizedWorkflowID}-`. **R-STORE-CACHE-002**: The activation job **MUST** save experiment state back to cache after variant selection using `if: always()`. **R-STORE-CACHE-003**: When `storage: cache` is active, no `push_experiments_state` job **SHALL** be generated. **R-STORE-CACHE-004**: Implementations **MUST NOT** require `contents: write` permission when `storage: cache` is configured. > **Note (informative)**: GitHub Actions cache has a 7-day inactivity eviction policy. State accumulated during an experiment may be silently lost over holidays or between infrequent runs. For this reason `repo` is the default storage mode. Use `cache` only when `contents: write` cannot be granted to the workflow. ### 7.5 Experiment Artifact [Section titled “7.5 Experiment Artifact”](#75-experiment-artifact) **R-STORE-ARTIFACT-001**: The activation job **MUST** upload the experiment state directory as a GitHub Actions artifact named `{sanitizedWorkflowID}-experiment` (or `experiment` for `workflow_call` triggers) with `if: always()` and a retention period of at least 30 days. **R-STORE-ARTIFACT-002**: When `assignments.json` exists in the state directory, it **MUST** be included in the artifact alongside `state.json`. *** ## 8. Expression and Template Integration [Section titled “8. Expression and Template Integration”](#8-expression-and-template-integration) ### 8.1 Compiler Expression Rewriting [Section titled “8.1 Compiler Expression Rewriting”](#81-compiler-expression-rewriting) **R-EXPR-001**: The compiler **MUST** rewrite every `${{ experiments. }}` expression in the frontmatter or prompt source to `steps.pick-experiment.outputs.` during the expression extraction phase, so the runtime value is injected by the GitHub Actions expression engine. **R-EXPR-002**: Each experiment **MUST** be mapped to an environment variable named `GH_AW_EXPERIMENTS_` (uppercased) that resolves to `steps.pick-experiment.outputs.`. This environment variable **MUST** be set in every workflow step that performs prompt interpolation or template substitution. ### 8.2 Handlebars Template Integration [Section titled “8.2 Handlebars Template Integration”](#82-handlebars-template-integration) **R-EXPR-003**: Implementations **MUST** substitute `__GH_AW_EXPERIMENTS___` placeholders in the raw prompt text **before** Handlebars template rendering, so that `{{#if experiments. == "value" }}` conditionals evaluate the actual runtime variant. **R-EXPR-004**: Implementations **MUST NOT** pass raw `__GH_AW_EXPERIMENTS_*__` placeholders to the Handlebars rendering engine; all substitutions **MUST** occur in a prior step. **R-EXPR-005**: The `isTruthy` helper used in Handlebars conditionals **MUST** treat the string `"no"` as falsy, in addition to the standard falsy values `""`, `"false"`, `"0"`, `undefined`, and `null`. This enables yes/no flag experiments where `{{#if experiments.feature }}` evaluates to false when the `no` variant is active. > **Note (informative)**: The `"no"` falsy behavior is a deliberate design choice that enables simple boolean-flag experiments (`feature: [yes, no]`). It differs from standard JavaScript truthiness and should be clearly documented for contributors. *** ## 9. Activation Job Structure [Section titled “9. Activation Job Structure”](#9-activation-job-structure) **R-JOB-001**: When the `experiments` field is present in the frontmatter, the compiled activation job **MUST** include the experiment steps defined in §9.1 or §9.2 as appropriate. **R-JOB-002**: Implementations **MUST NOT** inject experiment steps into workflows that do not declare the `experiments` frontmatter field. **R-JOB-003**: The activation job **MUST** expose a `needs.activation.outputs.experiments` output containing the full JSON variant assignment object so that downstream jobs can reference it via `needs.activation.outputs.experiments`. ### 9.1 `cache` Storage Step Order [Section titled “9.1 cache Storage Step Order”](#91-cache-storage-step-order) When `storage: cache`, the activation job **MUST** include the following steps in order: 1. **Restore experiment state** — `actions/cache/restore` with the workflow-specific key. 2. **Pick experiment variants** — `pick_experiment.cjs` via `actions/github-script`. 3. **Save experiment state** — `actions/cache/save` with `if: always()`. 4. **Upload experiment artifact** — `actions/upload-artifact` with `if: always()`. ### 9.2 `repo` Storage Step Order [Section titled “9.2 repo Storage Step Order”](#92-repo-storage-step-order) When `storage: repo` (default), the activation job **MUST** include the following steps in order: 1. **Restore experiment state from git** — `load_experiment_state_from_repo.cjs` via `actions/github-script`. 2. **Pick experiment variants** — `pick_experiment.cjs` via `actions/github-script`. 3. **Upload experiment artifact** — `actions/upload-artifact` with `if: always()`. A separate `push_experiments_state` job (R-STORE-REPO-003) commits the updated state after the activation job completes. ### 9.3 OTEL Resource Attributes [Section titled “9.3 OTEL Resource Attributes”](#93-otel-resource-attributes) **R-JOB-004**: After variant selection, when at least one experiment is assigned, `pick_experiment.cjs` **MUST** call `core.exportVariable("OTEL_RESOURCE_ATTRIBUTES", …)` with key-value pairs of the form `experiment.=`, comma-separated when multiple experiments are active. **R-JOB-005**: When `OTEL_RESOURCE_ATTRIBUTES` is already set, implementations **MUST** append the experiment attributes to the existing value with a comma separator rather than overwriting it. **R-JOB-006**: When no experiments are assigned, implementations **MUST NOT** modify `OTEL_RESOURCE_ATTRIBUTES`. *** ## 10. Audit CLI Integration [Section titled “10. Audit CLI Integration”](#10-audit-cli-integration) ### 10.1 Filter Flags [Section titled “10.1 Filter Flags”](#101-filter-flags) **R-AUDIT-001**: The `gh aw audit` command **MUST** accept an `--experiment ` flag that filters runs to those with a variant assignment for the named experiment. **R-AUDIT-002**: The `gh aw audit` command **MUST** accept a `--variant ` flag that, when combined with `--experiment`, further restricts results to runs assigned that exact variant value. **R-AUDIT-003**: `--variant` used without `--experiment` **MUST** cause a non-zero exit code with an error message that includes a suggestion to add `--experiment`. **R-AUDIT-004**: When a run is skipped by the filter, an informational message **MUST** be emitted to stderr identifying the run ID, the experiment name, and (when applicable) the required variant. ### 10.2 Run Overview Display [Section titled “10.2 Run Overview Display”](#102-run-overview-display) **R-AUDIT-005**: The run Overview section **MUST** include an `Experiment` field when the run’s experiment artifact contains one or more assignments. **R-AUDIT-006**: The experiment label **MUST** be formatted as a comma-separated, alphabetically sorted list of `name=variant` pairs (e.g., `caveman=yes, style=concise`). **R-AUDIT-007**: The `Experiment` field **MUST** be omitted from console and JSON output when no experiment assignments are present (`omitempty` semantics). ### 10.3 Per-Run Assignment Lookup [Section titled “10.3 Per-Run Assignment Lookup”](#103-per-run-assignment-lookup) **R-AUDIT-008**: When `state.runs` is non-empty and the last record’s `assignments` map is non-empty, the audit reporter **MUST** use that record’s assignments directly as the current-run experiment data. **R-AUDIT-009**: When `state.runs` is empty, absent, or the last record’s `assignments` map is empty, the audit reporter **MUST** fall back to the max-count heuristic: the variant with the highest cumulative count is assumed to have been selected on the most recent run; ties are broken by sorted variant order. ### 10.4 Filter Application [Section titled “10.4 Filter Application”](#104-filter-application) **R-AUDIT-010**: Implementations **MUST** apply the experiment/variant filter before calling any report-rendering code. A filtered-out run **MUST** return `nil`, not an error. **R-AUDIT-011**: Implementations **MUST** apply the filter in both the cached-summary path and the fresh-processing path for consistent behavior. **R-AUDIT-012**: Implementations **SHOULD** extract experiment data at most once per `AuditWorkflowRun` invocation to avoid redundant artifact reads. **R-AUDIT-013**: When neither `--experiment` nor `--variant` is set, implementations **MUST NOT** read the experiment artifact solely for filtering purposes. *** ## 11. Statistical Analysis and Reporting [Section titled “11. Statistical Analysis and Reporting”](#11-statistical-analysis-and-reporting) This section applies to the **Level 3 — Complete** conformance class (§2.2) and to any automated workflow that reports on experiment outcomes. ### 11.1 Per-Run Assignment Source [Section titled “11.1 Per-Run Assignment Source”](#111-per-run-assignment-source) **R-STAT-001**: Reporting tools that consume `state.json` files **MUST** derive per-run variant assignments from the `state.runs` array when it is present and non-empty. **R-STAT-002**: Reporting tools **MUST NOT** use the cumulative-count delta inference method (comparing consecutive snapshots) as the primary assignment source when `state.runs` is available. The delta method **MAY** be used as a fallback for legacy state files with no `runs` array. > **Note (informative)**: The delta method is fragile — it fails when multiple runs complete between downloaded snapshots, when runs are cancelled before the experiment step, or when `state.json` is fetched from different points in the artifact history. The `runs` array, introduced in v1.1.0 (ADR-29985), provides exact, auditable per-run assignment records. ### 11.2 Statistical Tests [Section titled “11.2 Statistical Tests”](#112-statistical-tests) **R-STAT-003**: When `analysis_type` is declared for an experiment, reporting tools **SHOULD** use the specified test for significance analysis: | `analysis_type` value | Test to apply | | --------------------- | ------------------------------------------------------------ | | `t_test` | Welch’s two-sample t-test (does not assume equal variance) | | `mann_whitney` | Mann-Whitney U non-parametric rank test | | `proportion_test` | Two-proportion z-test | | `bayesian_ab` | Bayesian A/B analysis (posterior probability of superiority) | **R-STAT-004**: When `analysis_type` is absent, reporting tools **SHOULD** default to the two-proportion z-test for binary outcomes (success/failure) and Welch’s t-test for continuous metrics (e.g., duration). ### 11.3 Multiple Comparison Correction [Section titled “11.3 Multiple Comparison Correction”](#113-multiple-comparison-correction) **R-STAT-005**: When an experiment declares K ≥ 3 variants and reporting tools perform pairwise comparisons against the control, the significance threshold **SHOULD** be adjusted using the Bonferroni correction: `α_adjusted = 0.05 / (K − 1)`. > **Note (informative)**: Without correction, the probability of at least one false positive across K−1 pairwise tests at α = 0.05 is approximately 1 − (1 − 0.05)^(K−1). For K = 3 this is \~9.75%; for K = 5 it exceeds 18%. The Bonferroni correction is conservative but simple. The Holm-Bonferroni step-down procedure is a less conservative alternative. **R-STAT-006**: When a multiple-comparison correction is applied, reporting tools **MUST** state the correction method and the adjusted α threshold in the report output. ### 11.4 Minimum Sample Size Gate [Section titled “11.4 Minimum Sample Size Gate”](#114-minimum-sample-size-gate) **R-STAT-007**: Reporting tools **MUST NOT** issue a PROMOTE recommendation for any variant until all variants in the experiment have accumulated at least `min_samples` runs (or 20 if `min_samples` is not declared). When any variant is below threshold, the recommendation **MUST** be EXTEND. **R-STAT-008**: When weights are non-uniform (§5.2), the `min_samples` target applies to the **smallest expected group**. For a `weight: [70, 30]` experiment with `min_samples: 30`, the control arm is not eligible for analysis until the 30% arm has at least 30 observations, even if the 70% arm has accumulated many more. ### 11.5 Guardrail Evaluation [Section titled “11.5 Guardrail Evaluation”](#115-guardrail-evaluation) **R-STAT-009**: Reporting tools that evaluate `guardrail_metrics` **MUST** emit a `GUARDRAIL_FAILED` status for any variant that violates a declared threshold, and **MUST** override the recommendation to ABANDON regardless of the primary-metric p-value. **R-STAT-010**: Multi-variant experiments **MUST** show guardrail pass/fail status per variant, not aggregated across the experiment. ### 11.6 Reporting Workflow Permissions [Section titled “11.6 Reporting Workflow Permissions”](#116-reporting-workflow-permissions) **R-STAT-011**: Any automated workflow that posts comments to issues (e.g., via `notify.issue` or step-based issue comment creation) **MUST** declare `permissions: issues: write` in its frontmatter. **R-STAT-012**: Any automated workflow that posts discussions **MUST** declare `permissions: discussions: write`. *** ## 12. Simultaneous Experiments and Interaction Effects [Section titled “12. Simultaneous Experiments and Interaction Effects”](#12-simultaneous-experiments-and-interaction-effects) **R-MULTI-001**: Each experiment in the `experiments` map **MUST** be assigned independently. The selection algorithm for one experiment **MUST NOT** depend on the selected variant of any other experiment. **R-MULTI-002**: Implementations **SHOULD NOT** run more than three experiments simultaneously in a single workflow. When more than three experiments are active, a compile-time warning **SHOULD** be emitted. > **Note (statistical, informative)**: When two or more experiments are active simultaneously, observed differences in outcome metrics can be caused by either experiment individually or by their interaction (i.e., a specific combination of variant values). This violation of the Stable Unit Treatment Value Assumption (SUTVA) inflates the risk of misattribution. For example, if `prompt_style=concise` and `emoji_density=heavy` are both active, it is impossible to determine from pairwise analysis alone whether a change in output quality was caused by verbosity, emoji use, or the combination. Experimenters who need to measure interactions **MUST** use a full factorial design and ensure sufficient sample size for all K₁ × K₂ × … cell combinations. **R-MULTI-003**: Reporting tools **MUST** note in their output when multiple experiments were simultaneously active on runs included in the analysis window, to alert reviewers to potential confounding. **R-MULTI-004**: Experiments that change the `engine:` frontmatter key **MUST NOT** be implemented within a single workflow file. Engine-switching experiments **MUST** use separate compiled workflow files (one per variant), which can then be compared via their respective GitHub Actions run metrics. **R-MULTI-005**: When two or more experiments are simultaneously active in the same analysis window, reporting tools **MUST** detect and bound interaction risk by preserving the full assignment vector per run and evaluating whether each observed combination cell has sufficient sample coverage. If interaction effects cannot be bounded (for example, sparse cells below `min_samples`), the report **MUST** emit an explicit interaction-risk status and **MUST NOT** recommend PROMOTE for affected variants. ### 12.1 Conflict Resolution Norms [Section titled “12.1 Conflict Resolution Norms”](#121-conflict-resolution-norms) A **conflict** occurs when two or more simultaneously active experiments would assign incompatible configurations to the same workflow run. This subsection defines normative behavior for each storage mode. **R-CONFLICT-001 (general)**: When two experiments assign variants that together produce a logically invalid workflow configuration (e.g., two `engine:` variants via separate experiment keys), the compiler **MUST** reject the workflow at compile time with a descriptive error. Runtime conflict detection is **NOT** a substitute for compile-time validation. #### 12.1.1 Conflict Resolution for `repo` Storage Mode [Section titled “12.1.1 Conflict Resolution for repo Storage Mode”](#1211-conflict-resolution-for-repo-storage-mode) **R-CONFLICT-REPO-001**: Under `repo` storage, each experiment’s variant selection reads and writes an independent key in `state.json`. There is no shared mutable state between experiments at the selection layer. Variant assignments for experiment A **MUST NOT** block or override variant assignments for experiment B, even when both experiments are active on the same run. **R-CONFLICT-REPO-002**: When a concurrent write conflict is detected at push time (e.g., a non-fast-forward rejection from the GitHub API), the push step **MUST** retry with the merged state from both runs. The retry **MUST NOT** discard either run’s assignment record. **R-CONFLICT-REPO-003**: If two concurrent runs select the same least-used variant for the same experiment (a read-time race), both selections are considered valid. The run records **MUST** reflect each run’s independently selected variant. No conflict error is raised for this condition. #### 12.1.2 Conflict Resolution for `cache` Storage Mode [Section titled “12.1.2 Conflict Resolution for cache Storage Mode”](#1212-conflict-resolution-for-cache-storage-mode) **R-CONFLICT-CACHE-001**: Under `cache` storage, GitHub Actions cache is eventually consistent across concurrent runs. When two runs attempt to save conflicting cache entries under the same key, GitHub Actions will store one entry and silently drop the other. Implementations **MUST** treat this as an acceptable data loss (see §7.4 informative note on cache eviction) and **MUST NOT** treat a missing cache restore as an error condition. **R-CONFLICT-CACHE-002**: Because `cache` storage does not provide atomic read-modify-write semantics, implementations using `cache` mode **MUST** document to users that high-concurrency workflows may experience elevated variant imbalance compared to `repo` mode. #### 12.1.3 Conflict Resolution for Mixed Storage Mode [Section titled “12.1.3 Conflict Resolution for Mixed Storage Mode”](#1213-conflict-resolution-for-mixed-storage-mode) **R-CONFLICT-MIX-001**: All experiments within a single workflow **MUST** share the same `storage` mode. Mixed-mode configurations (some experiments in `repo`, others in `cache`) are **NOT SUPPORTED** and **MUST** produce a compile-time error. **R-CONFLICT-MIX-002**: This restriction exists because the `storage` key is a single top-level field in the `experiments` map that applies uniformly to all experiments in that map. Workflow authors who require different storage modes for different experiments **MUST** split them into separate workflow files. *** ## 13. Security Considerations [Section titled “13. Security Considerations”](#13-security-considerations) ### 13.1 State File Integrity [Section titled “13.1 State File Integrity”](#131-state-file-integrity) The experiment state is stored in a git branch (`repo` mode) or GitHub Actions cache (`cache` mode). Both backends are protected by repository access controls. However: * Any user with write access to the repository can modify `state.json` on the experiments branch, potentially manipulating variant counters or forging run records. * Implementers that require tamper-evident state **SHOULD** use signed commits via the GitHub GraphQL `createCommitOnBranch` mutation (R-STORE-REPO-004). ### 13.2 Prompt Injection via Variant Values [Section titled “13.2 Prompt Injection via Variant Values”](#132-prompt-injection-via-variant-values) Variant strings declared in frontmatter are static strings set by the workflow author. They are not derived from user-supplied input and therefore do not introduce prompt injection risk at the frontmatter level. Workflow authors **MUST NOT** use runtime user input (e.g., issue titles, PR bodies) as variant values. ### 13.3 OTEL Attribute Leakage [Section titled “13.3 OTEL Attribute Leakage”](#133-otel-attribute-leakage) Experiment assignments exported as OTEL resource attributes (§9.3) may be visible in distributed-tracing backends. Variant names and experiment names **SHOULD NOT** embed sensitive information. ### 13.4 Permission Minimization [Section titled “13.4 Permission Minimization”](#134-permission-minimization) * The `repo` storage mode requires `contents: write`. Workflows **SHOULD** limit all other permissions to `read` to minimize the blast radius of a compromised token. * Reporting workflows that post comments require `issues: write` or `discussions: write` (§11.6). These permissions **SHOULD** be granted only to the specific reporting workflow, not to the experiment-running workflow itself. *** ## 14. Compliance Testing [Section titled “14. Compliance Testing”](#14-compliance-testing) ### 14.1 Test Suite Requirements [Section titled “14.1 Test Suite Requirements”](#141-test-suite-requirements) Conformance at each level is verified by the following test categories. #### 14.1.1 Schema Tests (Level 1) [Section titled “14.1.1 Schema Tests (Level 1)”](#1411-schema-tests-level-1) | Test ID | Requirement | Description | | ------------ | ------------ | ---------------------------------------------------------------- | | T-SCHEMA-001 | R-SCHEMA-005 | Reject bare-array with fewer than 2 variants | | T-SCHEMA-002 | R-SCHEMA-003 | Skip and warn on invalid experiment name | | T-SCHEMA-003 | R-SCHEMA-007 | Reject object form with `variants` containing < 2 entries | | T-SCHEMA-004 | R-SCHEMA-011 | Reject guardrail with invalid threshold pattern | | T-SCHEMA-005 | R-SCHEMA-013 | Reject `notify` object with unknown keys | | T-SCHEMA-006 | R-SCHEMA-001 | Compile workflow without `experiments:` field — output unchanged | #### 14.1.2 Variant Selection Tests (Level 1) [Section titled “14.1.2 Variant Selection Tests (Level 1)”](#1412-variant-selection-tests-level-1) | Test ID | Requirement | Description | | ------------ | ------------ | ------------------------------------------------------- | | T-SELECT-001 | R-SELECT-001 | Round-robin: select variant with lowest count | | T-SELECT-002 | R-SELECT-002 | Round-robin: random tie-breaking on first run | | T-SELECT-003 | R-SELECT-003 | Round-robin: counter incremented after selection | | T-SELECT-004 | R-SELECT-004 | Weighted: selection probability proportional to weights | | T-SELECT-005 | R-SELECT-006 | Weighted: counter incremented after selection | | T-SELECT-006 | R-SELECT-005 | Weighted: all-zero weights return control variant | | T-SELECT-007 | R-SELECT-007 | Weighted: mismatched length falls back to round-robin | #### 14.1.3 Expression Integration Tests (Level 1) [Section titled “14.1.3 Expression Integration Tests (Level 1)”](#1413-expression-integration-tests-level-1) | Test ID | Requirement | Description | | ---------- | ----------- | --------------------------------------------------------- | | T-EXPR-001 | R-EXPR-001 | `${{ experiments.x }}` rewritten to step output reference | | T-EXPR-002 | R-EXPR-003 | Placeholder substituted before Handlebars rendering | | T-EXPR-003 | R-EXPR-005 | `"no"` treated as falsy in `isTruthy` | | T-EXPR-004 | R-EXPR-004 | Raw placeholder not passed to Handlebars engine | #### 14.1.4 State Persistence Tests (Level 2) [Section titled “14.1.4 State Persistence Tests (Level 2)”](#1414-state-persistence-tests-level-2) | Test ID | Requirement | Description | | ----------- | ----------------- | --------------------------------------------------------- | | T-STORE-001 | R-STORE-REPO-002 | Empty state on first run (404 branch) | | T-STORE-002 | R-STORE-004 | Valid `state.json` structure written after run | | T-STORE-003 | R-STORE-007 | Run record appended with correct fields | | T-STORE-004 | R-STORE-005 | `runs` pruned to ≤ 512 entries | | T-STORE-005 | R-STORE-006 | Legacy state (no `runs` field) initialized to empty array | | T-STORE-006 | R-STORE-CACHE-004 | No `contents: write` required for cache mode | #### 14.1.5 Audit CLI Tests (Level 2) [Section titled “14.1.5 Audit CLI Tests (Level 2)”](#1415-audit-cli-tests-level-2) | Test ID | Requirement | Description | | ----------- | ----------- | ---------------------------------------------------------- | | T-AUDIT-001 | R-AUDIT-003 | `--variant` without `--experiment` returns non-zero exit | | T-AUDIT-002 | R-AUDIT-008 | Assignment read from `state.runs` when available | | T-AUDIT-003 | R-AUDIT-009 | Fallback to max-count heuristic for legacy state | | T-AUDIT-004 | R-AUDIT-005 | Overview `Experiment` field present when assignments exist | | T-AUDIT-005 | R-AUDIT-007 | `Experiment` field omitted when no assignments | #### 14.1.6 Statistical Reporting Tests (Level 3) [Section titled “14.1.6 Statistical Reporting Tests (Level 3)”](#1416-statistical-reporting-tests-level-3) | Test ID | Requirement | Description | | ---------- | ----------- | ---------------------------------------------------------- | | T-STAT-001 | R-STAT-001 | Assignments derived from `state.runs`, not delta inference | | T-STAT-002 | R-STAT-005 | Bonferroni correction applied for K ≥ 3 variants | | T-STAT-003 | R-STAT-007 | PROMOTE withheld until all variants reach `min_samples` | | T-STAT-004 | R-STAT-009 | GUARDRAIL\_FAILED forces ABANDON recommendation | | T-STAT-005 | R-STAT-011 | Reporting workflow declares `issues: write` | ### 14.2 Compliance Checklist [Section titled “14.2 Compliance Checklist”](#142-compliance-checklist) | Requirement | Test ID | Level | Status | | ---------------- | ------------ | ----- | ----------- | | R-SCHEMA-001 | T-SCHEMA-006 | 1 | Required | | R-SCHEMA-005 | T-SCHEMA-001 | 1 | Required | | R-SELECT-001 | T-SELECT-001 | 1 | Required | | R-SELECT-002 | T-SELECT-002 | 1 | Required | | R-SELECT-003 | T-SELECT-003 | 1 | Required | | R-SELECT-006 | T-SELECT-005 | 1 | Required | | R-EXPR-001 | T-EXPR-001 | 1 | Required | | R-EXPR-005 | T-EXPR-003 | 1 | Required | | R-STORE-002 | — | 2 | Required | | R-STORE-REPO-002 | T-STORE-001 | 2 | Required | | R-STORE-007 | T-STORE-003 | 2 | Required | | R-AUDIT-003 | T-AUDIT-001 | 2 | Required | | R-AUDIT-008 | T-AUDIT-002 | 2 | Required | | R-STAT-001 | T-STAT-001 | 3 | Required | | R-STAT-005 | T-STAT-002 | 3 | Recommended | | R-STAT-007 | T-STAT-003 | 3 | Required | | R-STAT-011 | T-STAT-005 | 3 | Required | *** ## 15. References [Section titled “15. References”](#15-references) ### Normative References [Section titled “Normative References”](#normative-references) * **\[RFC 2119]** Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, RFC 2119, March 1997. * **\[ADR-29534]** gh-aw maintainers, “Frontmatter A/B Experiments with Balanced Variant Selection”, 2026-05-01. `docs/adr/29534-frontmatter-ab-experiments-variant-selection.md` * **\[ADR-29618]** gh-aw maintainers, “Rich Experiment Metadata Schema Extension with Weighted Selection and Date Gating”, 2026-05-01. `docs/adr/29618-rich-experiment-metadata-schema-extension.md` *(normative sections superseded by §5.2 of this document)* * **\[ADR-29628]** gh-aw maintainers, “Add `--experiment` and `--variant` Filter Flags to `gh aw audit`”, 2026-05-01. `docs/adr/29628-experiment-variant-filter-flags-for-audit.md` * **\[ADR-29985]** gh-aw maintainers, “Experiment Per-Run State, OTEL Integration, and Schema Extensions”, 2026-05-03. `docs/adr/29985-experiment-per-run-state-otel-integration-and-schema-extensions.md` * **\[ADR-29996]** gh-aw maintainers, “Experiment State Storage — Git Branch as Default, Cache as Fallback”, 2026-05-03. `docs/adr/29996-experiment-state-git-branch-storage.md` ### Informative References [Section titled “Informative References”](#informative-references) * **\[SUTVA]** Rubin, D. B., “Estimating Causal Effects of Treatments in Randomized and Nonrandomized Studies”, *Journal of Educational Psychology*, 66(5):688–701, 1974. (Stable Unit Treatment Value Assumption) * **\[BONFERRONI]** Dunn, O. J., “Multiple Comparisons Among Means”, *Journal of the American Statistical Association*, 56(293):52–64, 1961. * **\[WELCH-TTEST]** Welch, B. L., “The Generalization of Student’s Problem When Several Different Population Variances are Involved”, *Biometrika*, 34(1/2):28–35, 1947. * **\[GitHub Actions Cache]** GitHub Docs, “Caching dependencies to speed up workflows”. *** ## Appendices [Section titled “Appendices”](#appendices) ### Appendix A: Full Object-Form Example [Section titled “Appendix A: Full Object-Form Example”](#appendix-a-full-object-form-example) ```yaml --- on: schedule: daily on weekdays engine: copilot permissions: contents: read pull-requests: read experiments: storage: repo prompt_style: variants: [concise, detailed, step_by_step] description: "Test whether verbosity level affects output quality" hypothesis: "H0: no change in effective_tokens. H1: concise reduces by >=15%" metric: effective_tokens secondary_metrics: [duration_ms, discussion_word_count] guardrail_metrics: - name: success_rate threshold: ">=0.95" - name: empty_output_rate threshold: "==0" weight: [40, 40, 20] min_samples: 30 start_date: "2026-05-01" end_date: "2026-08-01" issue: 1234 analysis_type: t_test tags: [cost, prompting, verbosity] notify: issue: 1234 --- Summarize the pull requests merged today. {{#if experiments.prompt_style == "concise" }} Write a maximum of 5 bullet points. {{#else if experiments.prompt_style == "detailed" }} Write a structured report with sections for new features, bug fixes, refactors, and docs. {{#else}} Write a numbered step-by-step walkthrough of each change with rationale. {{#endif}} ``` ### Appendix A2: Weighted Variant Selection — Worked Example [Section titled “Appendix A2: Weighted Variant Selection — Worked Example”](#appendix-a2-weighted-variant-selection--worked-example) This appendix walks through the probability math for a three-variant `weighted` experiment to illustrate how the `weight` array maps to selection probability, how counters are updated, and how balance is maintained over many runs. #### A2.1 Scenario Setup [Section titled “A2.1 Scenario Setup”](#a21-scenario-setup) An experiment named `response_tone` has three variants with non-uniform weights: ```yaml experiments: storage: repo response_tone: variants: [formal, casual, neutral] weight: [20, 50, 30] ``` The weight values are **relative proportions**, not absolute percentages. The implementation normalizes them to compute probabilities: ```plaintext total_weight = 20 + 50 + 30 = 100 P(formal) = 20 / 100 = 0.20 (20%) P(casual) = 50 / 100 = 0.50 (50%) P(neutral) = 30 / 100 = 0.30 (30%) ``` For a 10-run experiment sequence, the **expected** variant distribution is: | Variant | Weight | Expected runs (of 10) | | ------- | ------ | --------------------- | | formal | 20 | 2 | | casual | 50 | 5 | | neutral | 30 | 3 | #### A2.2 Selection Algorithm (Weighted Random) [Section titled “A2.2 Selection Algorithm (Weighted Random)”](#a22-selection-algorithm-weighted-random) The `weighted` algorithm draws a uniform random number `r ∈ [0, 1)` and maps it to a variant via cumulative weight: ```plaintext Cumulative ranges: [0.00, 0.20) → formal [0.20, 0.70) → casual [0.70, 1.00) → neutral ``` Example draws: | r | Selected variant | | ---- | ---------------- | | 0.11 | formal | | 0.45 | casual | | 0.72 | neutral | | 0.19 | formal | | 0.68 | casual | #### A2.3 Counter Updates [Section titled “A2.3 Counter Updates”](#a23-counter-updates) After each run, the counter for the selected variant is incremented in `state.json`. After 10 runs with the distribution above, a typical `counts` object is: ```json { "counts": { "response_tone": { "formal": 2, "casual": 5, "neutral": 3 } } } ``` Per R-SELECT-006, the `weighted` algorithm **MUST** increment invocation counters after every selection. This allows the audit CLI and reporting workflows to verify that observed variant frequencies approximate the declared weights over time. #### A2.4 Long-Run Balance Verification [Section titled “A2.4 Long-Run Balance Verification”](#a24-long-run-balance-verification) Over N runs, the observed frequency for variant v should converge to `weight[v] / total_weight` by the Law of Large Numbers. Reporting workflows SHOULD flag experiments where any variant’s observed frequency deviates from its target weight by more than ±10 percentage points over at least 30 runs, as this may indicate a misconfigured `weight` array or a bug in the selection implementation. For the example above, after 100 runs: | Variant | Expected runs | Acceptable range (±10 pp) | | ------- | ------------- | ------------------------- | | formal | 20 | 10 – 30 | | casual | 50 | 40 – 60 | | neutral | 30 | 20 – 40 | #### A2.5 Contrast with Balanced Round-Robin [Section titled “A2.5 Contrast with Balanced Round-Robin”](#a25-contrast-with-balanced-round-robin) The `balanced` (least-used) algorithm ignores weights and selects the least-run variant deterministically. Use `weighted` when you intentionally want unequal traffic allocation (e.g., to expose fewer users to an experimental variant while still gathering comparative data). Use `balanced` when you want equal allocation and maximum statistical efficiency per total run count. ### Appendix B: `state.json` Schema [Section titled “Appendix B: state.json Schema”](#appendix-b-statejson-schema) ```json { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "required": ["counts"], "properties": { "counts": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } } }, "runs": { "type": "array", "maxItems": 512, "items": { "type": "object", "required": ["run_id", "timestamp", "assignments"], "properties": { "run_id": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "assignments": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } ``` ### Appendix C: Sample Size Reference [Section titled “Appendix C: Sample Size Reference”](#appendix-c-sample-size-reference) For a two-proportion test with 80% statistical power and α = 0.05 (two-tailed), the approximate minimum runs per variant are: | Minimum Detectable Effect (pp) | Runs per variant | | ------------------------------ | ---------------- | | 5 | \~620 | | 10 | \~160 | | 15 | \~70 | | 20 | \~40 | | 30 | \~20 | > **Note for weighted experiments**: When `weight` is non-uniform, apply these figures to the **smaller group**. For a 70/30 split aiming to detect a 10 pp effect, you need \~160 runs in the 30% arm (≈ 533 total runs). ### Appendix D: Known Limitations [Section titled “Appendix D: Known Limitations”](#appendix-d-known-limitations) 1. **Read-time race condition**: Concurrent runs with `repo` storage may read stale state and select the same variant. See R-STORE-REPO-005 and the informative note in §7.3. 2. **Interaction effects**: Running multiple experiments simultaneously can produce unattributable results. See §12 and R-MULTI-002. 3. **Engine-switching experiments**: Changing the `engine:` key requires separate workflow files; see R-MULTI-004. 4. **`analysis_type` advisory only**: Reporting workflows that do not implement all four statistical tests will fall back to defaults. The field documents intent; it does not enforce a specific computation path. 5. **State branch growth**: The experiments git branch grows monotonically. Operators **MAY** prune old commits from the experiments branch without affecting the current state. ### Sync Follow-ups (May 2026 Expert Review) [Section titled “Sync Follow-ups (May 2026 Expert Review)”](#sync-follow-ups-may-2026-expert-review) This appendix itemizes corrective follow-ups referenced in the abstract. * **FR-001 (implemented via R-SELECT-006)**: Weighted selection increments invocation counters after each selection. * **FR-002 (implemented via R-STAT-001/R-STAT-002)**: Reporting uses `state.runs` assignment records instead of count-delta inference. * **FR-003 (implemented via R-STAT-011/R-STAT-012)**: Reporting workflows that write issues/discussions declare explicit write permissions. * **FR-004 (implemented via R-MULTI-005)**: Concurrent-experiment interaction effects are explicitly detected and bounded before promotion decisions. * **FR-005 (implemented via daily-experiment-report workflow update)**: Reporting guidance now includes a factorial-interaction helper for K₁×K₂ cell-level significance output and sparse-cell risk surfacing. * **FR-006 (implemented via compiler diagnostics)**: The compiler now emits a warning when more than one experiment is active and weighted traffic is configured, indicating potential sparse interaction cells. *** ## Change Log [Section titled “Change Log”](#change-log) ### Version 1.1.0 (Draft) — 2026-05-12 [Section titled “Version 1.1.0 (Draft) — 2026-05-12”](#version-110-draft--2026-05-12) * **Added**: Daily reporting helper guidance for factorial K₁×K₂ interaction cell significance output. * **Added**: Compiler warning requirement for sparse interaction-cell risk when multiple experiments and weighted traffic are configured. * **Updated**: Sync Follow-ups appendix to replace v1.1.0 TODOs with implemented corrective items. ### Version 1.0.1 (Draft) — 2026-05-07 [Section titled “Version 1.0.1 (Draft) — 2026-05-07”](#version-101-draft--2026-05-07) * **Added**: R-MULTI-005 requiring interaction-risk detection/bounding for simultaneous experiments. * **Added**: Sync Follow-ups appendix with itemized May 2026 expert-review corrective items and owned TODOs. ### Version 1.0.0 (Draft) — 2026-05-03 [Section titled “Version 1.0.0 (Draft) — 2026-05-03”](#version-100-draft--2026-05-03) * **Initial publication** consolidating ADR-29534, ADR-29618, ADR-29628, ADR-29985, and ADR-29996. * **Correction**: R-SELECT-006 supersedes ADR-29618 Rule 9 — weighted selection MUST increment invocation counters (was incorrectly stated as MUST NOT; the reference implementation already implements the correct behavior). * **Added**: R-STAT-001/R-STAT-002 — reporting tools MUST use `state.runs` for per-run assignment lookup, not the fragile delta-count inference method. * **Added**: R-STAT-005/R-STAT-006 — Bonferroni correction SHOULD be applied for K ≥ 3 variants to control family-wise error rate. * **Added**: R-STAT-008 — `min_samples` applies to the smallest expected group when weights are non-uniform. * **Added**: R-STAT-011/R-STAT-012 — reporting workflows MUST declare `issues: write` / `discussions: write` when posting comments. * **Added**: R-MULTI-002/R-MULTI-003 — warning for > 3 simultaneous experiments; interaction effects must be noted in reports. * **Added**: §13 Security Considerations — state integrity, prompt injection, OTEL leakage, permission minimization. * **Added**: Appendix C (sample size reference) and Appendix D (known limitations). * **Informative note**: `storage: cache` default changed to `storage: repo` in ADR-29996; any documentation or issue templates that still refer to “cache-based” assignment should be updated. *** *Copyright 2026 GitHub, Inc. All rights reserved. This specification is maintained by the gh-aw project team.* # Maintaining Repos with Agentic Workflows > How to use repo-assist, safe-outputs, and integrity filtering to manage an open-source repository at scale — controlling what agents can do, filtering untrusted input, and debugging failures. Open-source maintainers face a unique challenge when running agentic workflows: anyone can open an issue or PR, triggering agent runs that consume compute and tokens — but not every contributor is equally trustworthy. gh-aw addresses this with two complementary safety mechanisms: * **Safe-outputs** — The primary mechanism for controlling *what an agent can do*. Every GitHub mutation (opening issues, commenting, creating PRs) must be explicitly declared; anything not listed is blocked. * **Integrity filtering** — The primary mechanism for controlling *what content the agent sees*. Content from untrusted authors is filtered from the agent’s context before the run starts. Together they form a defense-in-depth model: integrity filtering keeps untrusted content out of the agent’s context, and safe-outputs ensure the agent can only produce authorized side-effects. This guide shows how to use [Repo Assist](https://github.com/githubnext/agentics/blob/main/docs/repo-assist.md) as the primary entry point for managing incoming work, and how to configure both mechanisms so your repository scales safely. ## Repo Assist as Your Triage Layer [Section titled “Repo Assist as Your Triage Layer”](#repo-assist-as-your-triage-layer) [Repo Assist](https://github.com/githubnext/agentics/blob/main/docs/repo-assist.md) is a workflow that runs on every new issue or PR, classifies the content, and routes work to the right place. It is the recommended starting point for any public repository because it: * Sees all incoming content (including from untrusted users), so nothing is silently ignored. * Applies lightweight, low-cost classification (labels, comments) rather than heavy agent actions. * Acts as a gate that downstream code-modifying agents depend on before they run. ## Controlling Workflow Outputs with Safe-Outputs [Section titled “Controlling Workflow Outputs with Safe-Outputs”](#controlling-workflow-outputs-with-safe-outputs) Safe-outputs is the primary mechanism for controlling what a workflow can do. Every action that produces a side-effect on GitHub — labeling an issue, posting a comment, opening a pull request, merging — must be explicitly declared in the `safe-outputs:` block. If an action isn’t listed, the runtime blocks it before it reaches the API. This is what makes it safe to run repo-assist with `min-integrity: unapproved`: even if the agent were to generate an instruction to open a PR or close an issue, the runtime would reject it because those outputs weren’t declared. The available safe-outputs map directly to GitHub actions: | Safe-output | What it allows | | ---------------------- | ----------------------------------- | | `label-issue` | Apply or remove labels on an issue | | `comment-issue` | Post a comment on an issue | | `comment-pull-request` | Post a comment on a pull request | | `create-pull-request` | Open a new pull request | | `merge-pull-request` | Merge a pull request (experimental) | | `close-issue` | Close an issue | | `create-issue` | Open a new issue | | `assign-issue` | Assign an issue to a user or team | ## Controlling Workflow Inputs with Integrity Filtering [Section titled “Controlling Workflow Inputs with Integrity Filtering”](#controlling-workflow-inputs-with-integrity-filtering) Integrity filtering is the primary mechanism for controlling what content the agent sees. It evaluates the author of each issue, PR, or comment and removes items that don’t meet the configured trust threshold — before the agent’s context is assembled. Every public repository automatically applies `min-integrity: approved` as a baseline — repo-assist overrides this to `unapproved` so it can see issues from contributors and first-time contributors, not just trusted members. The four configurable levels, from most to least restrictive: | Level | Who qualifies | | ------------ | -------------------------------------------------------------------------------------------------------------- | | `merged` | PRs merged into the default branch; commits reachable from main | | `approved` | Owners, members, collaborators; non-fork PRs on public repos; recognized bots (`dependabot`, `github-actions`) | | `unapproved` | Contributors who have had a PR merged before; first-time contributors | | `none` | All content including users with no prior relationship | Choose based on what the workflow does: * **Repo-assist / triage workflows**: `unapproved` — classify content from contributors and first-time contributors without acting on it. * **Code-modifying workflows** (open PRs, apply patches, close issues): `approved` or `merged` — only act on trusted input. * **Spam detection or analytics**: `none` — see everything, but produce no direct GitHub mutations. ### Reactions as Trust Signals [Section titled “Reactions as Trust Signals”](#reactions-as-trust-signals) Maintainers can use GitHub reactions (, ) to promote content past the integrity filter without modifying labels. This is useful in repo-assist workflows where a maintainer wants to fast-track an external contribution. To enable reactions, add the `integrity-reactions` feature flag: ```aw features: integrity-reactions: true tools: github: min-integrity: approved ``` The compiler handles the rest — when `integrity-reactions: true` is set, it automatically: * Enables the CLI proxy (`cli-proxy: true`), which is required for reaction-based integrity decisions * Injects default endorsement reactions: `THUMBS_UP`, `HEART` * Injects default disapproval reactions: `THUMBS_DOWN`, `CONFUSED` * Uses `endorser-min-integrity: approved` (only reactions from owners, members, and collaborators count) * Uses `disapproval-integrity: none` (a disapproval reaction demotes content to `none`) These defaults mean that when a trusted member (owner, member, or collaborator) adds a or reaction to an issue or comment, the item’s integrity is promoted to `approved` — making it visible to agents using `min-integrity: approved`. Conversely, a or reaction from a trusted member demotes the item to `none`. See the [Integrity Filtering Reference](/gh-aw/reference/integrity/) for complete configuration details. ## Scaling Strategies [Section titled “Scaling Strategies”](#scaling-strategies) ### Token Budget Awareness [Section titled “Token Budget Awareness”](#token-budget-awareness) Integrity filtering directly reduces token consumption: items filtered by the gateway never appear in the agent’s context window. On a busy public repository, `min-integrity: approved` on downstream agents can reduce context size dramatically compared to seeing all activity. Use `gh aw logs --format markdown --count 20` to track token trends over time. The cross-run report surfaces cost spikes, anomalous token usage, and per-run breakdowns so you can detect regressions before they accumulate. ### Rate Limiting [Section titled “Rate Limiting”](#rate-limiting) The `user-rate-limit` frontmatter key caps how many times a workflow can run in a sliding window, preventing a flood of incoming issues from exhausting compute or inference budget: ```aw user-rate-limit: max-runs-per-window: 5 window: 60 ``` See [Rate Limiting Controls](/gh-aw/reference/rate-limiting-controls/) for full options. ### Pre-Activation Association Skips [Section titled “Pre-Activation Association Skips”](#pre-activation-association-skips) For maintainer-operated moderation and triage workflows, you can skip runs early for specific event/author-association combinations using `on.skip-author-associations`: ```aw on: issue_comment: types: [created] skip-author-associations: issue_comment: [owner, member, collaborator] ``` This compiles into a pre-activation job-level `if` guard (using event-specific payload fields such as `github.event.comment.author_association`, `github.event.issue.author_association`, and `github.event.pull_request.author_association`), so matching runs are skipped before agent execution starts. ### Concurrency Controls [Section titled “Concurrency Controls”](#concurrency-controls) Workflows automatically use dual concurrency control (per-workflow and per-engine). For repo-assist, you may want higher concurrency so multiple issues are triaged in parallel rather than queued: ```aw concurrency: max-parallel: 3 ``` ### Scoping Repository Access [Section titled “Scoping Repository Access”](#scoping-repository-access) `allowed-repos` prevents cross-repository reads that aren’t necessary for the workflow’s task: ```aw tools: github: allowed-repos: "myorg/*" min-integrity: approved ``` This is useful in monorepo or multi-repo setups where the agent should only read from the organization’s own repos. ## Debugging Failed Workflows [Section titled “Debugging Failed Workflows”](#debugging-failed-workflows) ### Quick Start: AI-Assisted Debugging [Section titled “Quick Start: AI-Assisted Debugging”](#quick-start-ai-assisted-debugging) The fastest path to a root cause is to hand the failing run URL to the Copilot CLI: ```bash copilot ``` Inside the CLI: ```text /agent agentic-workflows Debug this run: https://github.com/OWNER/REPO/actions/runs/RUN_ID ``` The agent loads the `debug-agentic-workflow` prompt, audits the run, and explains what went wrong. Follow up with specific questions about blocked domains, missing tools, or safe-output failures. On GitHub.com with [agentic authoring configured](/gh-aw/guides/agentic-authoring/): ```text /agent agentic-workflows debug https://github.com/OWNER/REPO/actions/runs/RUN_ID ``` ### Manual Debugging with CLI Commands [Section titled “Manual Debugging with CLI Commands”](#manual-debugging-with-cli-commands) **Audit a specific run:** ```bash gh aw audit RUN_ID gh aw audit RUN_ID --json # machine-readable output gh aw audit RUN_ID --parse # writes log.md and firewall.md ``` The audit report covers: failure summary, tool usage, MCP server health, firewall analysis, token metrics, and missing tools. **Analyze logs across multiple runs:** ```bash gh aw logs my-workflow gh aw logs my-workflow --format markdown --count 10 gh aw logs --filtered-integrity # only runs with DIFC-filtered events ``` **Compare two runs for regressions:** ```bash gh aw audit BASELINE_ID CURRENT_ID ``` ### Common Failure Patterns [Section titled “Common Failure Patterns”](#common-failure-patterns) | Failure | Symptom / Cause | Fixes | | ---------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **Missing tool calls** | Tool not configured or wrong name. Check `missing_tools` in audit. | Add to `tools:` in frontmatter; fix any `safeoutputs-` prefix; check MCP connectivity. | | **Authentication failures** | Token permissions too narrow or API key missing. | Review `permissions:` block; ensure secrets are set; see [Auth Reference](/gh-aw/reference/auth/). | | **Integrity filtering blocking content** | Author’s association below `min-integrity`. `DIFC_FILTERED` events in audit show details. | Adjust `min-integrity`; add author to `trusted-users`; use `approval-labels`; check `gh aw logs --filtered-integrity`. | | **Safe-output validation failures** | Agent attempted undeclared GitHub action. Safe-outputs blocks anything not listed. | Review `safe-outputs:`; check `safe_outputs.jsonl` in audit artifacts; see [Safe Outputs Reference](/gh-aw/reference/safe-outputs/). | | **Token budget exhaustion** | Run hit token limit before completing. | Raise `min-integrity` to reduce context; add `cache-memory:`; simplify prompt; tighten `user-rate-limit`. | | **Network blocks** | Required domain blocked by firewall. | Check firewall section of audit; add domain to `network.allowed`; see [Network Configuration Guide](/gh-aw/guides/network-configuration/). | ### Iterative Debug Workflow [Section titled “Iterative Debug Workflow”](#iterative-debug-workflow) 1. Check the workflow run summary in the GitHub Actions UI. 2. Run `gh aw audit RUN_ID` for a structured breakdown. 3. For complex issues, use `/agent agentic-workflows` in Copilot Chat. 4. Edit the `.md` file → run `gh aw compile` to validate → trigger a new run. 5. Compare the new run against the baseline with `gh aw audit BASELINE_ID NEW_ID`. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) — Complete output type documentation and format requirements * [Integrity Filtering Reference](/gh-aw/reference/integrity/) — Complete `min-integrity` and policy configuration * [Rate Limiting Controls](/gh-aw/reference/rate-limiting-controls/) — Preventing runaway workflows * [Cost Management](/gh-aw/reference/cost-management/) — Token budget tracking and optimization * [Audit Commands](/gh-aw/reference/audit/) — `gh aw audit` and `gh aw logs` reference * [Debugging Workflows](/gh-aw/troubleshooting/debugging/) — Detailed debugging procedures * [Network Configuration Guide](/gh-aw/guides/network-configuration/) — Firewall and domain setup * [GitHub Tools Reference](/gh-aw/reference/github-tools/) — Full `tools.github` options # Organization Practices > Guidance for adopting, sharing, and governing GitHub Agentic Workflows across teams and repositories. Organization Practices collects guidance that matters at team and enterprise scale such as: * Safe rollout strategies before production writes are enabled * Workflow sharing across repositories and organizations * Centralized ownership models for workflow infrastructure * Platform conventions for versioning, review, and promotion ## Safe Rollout [Section titled “Safe Rollout”](#safe-rollout) [Safe Rollout](/gh-aw/practices/safe-rollout/) describes how to move from report-only or staged behavior to production writes with evidence and control. One technique inside that progression is shadow evaluation, where the workflow writes to a safe non-production target before promotion. ## Sharing Workflows [Section titled “Sharing Workflows”](#sharing-workflows) [Sharing Workflows](/gh-aw/practices/sharing-workflows/) describes how workflows can be reused across repositories and organizations. It covers imports, reusable components, and central workflow repositories. # Safe Rollout > Move from report-only or staged behavior to direct production writes with evidence and control. Safe rollout is the practice of increasing workflow autonomy in steps instead of enabling direct production writes immediately. The main question is not whether a workflow is useful, but whether it is trusted enough to act on the live system. In practice, teams usually move through a ladder: report-only first, then staged behavior, then a more realistic safe-write technique if needed, and finally direct production writes. ## Rollout Ladder [Section titled “Rollout Ladder”](#rollout-ladder) The usual progression is: 1. Start in report-only mode. 2. Enable `staged` behavior when proposed writes need to be previewed. 3. Use shadow evaluation when preview mode is not enough and the real write path needs to be exercised safely. 4. Promote the same workflow to direct production writes. `staged` and shadow evaluation are not interchangeable. Staged mode is sufficient when the question is what the workflow would do. Shadow evaluation is needed when the question is whether the real write path behaves correctly on a safe non-production target. ## When Staged Is Enough [Section titled “When Staged Is Enough”](#when-staged-is-enough) Use staged mode when the main risk is decision quality rather than operational behavior. It is usually enough when maintainers only need to review proposed actions, compare alternatives, or inspect whether the workflow’s judgment is reasonable before any write is allowed. ## When Shadow Evaluation Is Needed [Section titled “When Shadow Evaluation Is Needed”](#when-shadow-evaluation-is-needed) Use shadow evaluation when staged mode is too weak because the real write path itself needs validation. This is a good fit when: * the workflow must update real target objects to prove the behavior is correct * concurrency, deduplication, or serialization needs to be tested on a live-like surface * maintainers need to inspect the actual produced state, not only proposed intent * cross-repository writes, permissions, or dispatch boundaries need to be exercised safely Shadow evaluation is one technique inside safe rollout, not a separate top-level pattern. ## Design Rules [Section titled “Design Rules”](#design-rules) ### Production truth stays authoritative [Section titled “Production truth stays authoritative”](#production-truth-stays-authoritative) Do not let the evaluation surface become the new source of truth. Production events and later trusted human actions should remain authoritative. ### Prediction snapshots should be explicit [Section titled “Prediction snapshots should be explicit”](#prediction-snapshots-should-be-explicit) If later comparison matters, persist what the workflow predicted at decision time. Do not reconstruct predictions from logs. ### Correction evidence needs provenance [Section titled “Correction evidence needs provenance”](#correction-evidence-needs-provenance) Not every later edit should count as trustworthy truth. Record provenance such as actor type, manual versus automated source, trust status, and origin repository role. ### Evaluation surfaces should remain disposable [Section titled “Evaluation surfaces should remain disposable”](#evaluation-surfaces-should-remain-disposable) Keep the shadow target thin. It should support measurement and rollout, not become a second long-lived control plane. ## Example Shape [Section titled “Example Shape”](#example-shape) The common repository split is: * production repository: emits live events and contains authoritative later human truth * ops repository: persists predictions, collects corrections, publishes reports, and updates instructions * shadow repository: temporary non-production write target during rollout That shape is often useful, but it is still rollout guidance rather than a primary pattern. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) * [Staged Mode](/gh-aw/reference/staged-mode/) * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) # Sharing Workflows > Share, reuse, and govern workflows across repositories and organizations. Sharing workflows across an organization involves several independent layers. Each layer can be adopted independently; teams do not need all of them at once. The recommended enterprise pattern is to maintain one central `agentic-workflows` repository with versioned workflow templates and shared components. Consuming repositories then use `gh aw add` to install full workflows and `imports:` to pull in common modules. ## Sharing Layers [Section titled “Sharing Layers”](#sharing-layers) ### 1. Copy and install whole workflows [Section titled “1. Copy and install whole workflows”](#1-copy-and-install-whole-workflows) A repository can pull in a complete workflow from another repository: ```bash gh aw add acme-org/agentic-workflows/ci-doctor@v1.2.0 ``` The `source:` field is automatically added to the installed workflow’s frontmatter so the origin and version are tracked. Use `gh aw add-wizard` for interactive installation with guided prompts. Use `gh aw add` for scripted or CI-driven installation. See [Reusing Workflows](/gh-aw/guides/packaging-imports/) for the full command reference and options. ### 2. Reusable workflow components [Section titled “2. Reusable workflow components”](#2-reusable-workflow-components) Shared building blocks — tool configurations, MCP server definitions, safety policies, and prompt snippets — can be imported into any workflow: ```yaml imports: - acme-org/shared-workflows/shared/security-setup.md@v2.1.0 - acme-org/shared-workflows/shared/mcp/tavily.md@v1.0.0 ``` Remote imports are cached under `.github/aw/imports/` by commit SHA after the first fetch. This enables reproducible offline compilation and avoids redundant downloads when multiple refs point to the same commit. See [Imports Reference](/gh-aw/reference/imports/) for path formats, merge semantics, and field-specific behavior. ### 3. Parameterized templates [Section titled “3. Parameterized templates”](#3-parameterized-templates) Shared workflows that declare an `import-schema` accept runtime parameters via `uses`/`with`: ```yaml imports: - uses: acme-org/shared-workflows/shared/reviewer.md@v1 with: languages: ["go", "typescript"] severity: "high" ``` This lets a single shared component serve multiple consuming workflows with different configurations without requiring separate copies. See [Imports Reference](/gh-aw/reference/imports/#calling-a-parameterized-shared-workflow) for schema declaration and validation details. ### 4. Versioning and update flow [Section titled “4. Versioning and update flow”](#4-versioning-and-update-flow) Enterprise workflow sharing needs a clear versioning model: * **Exact release tags** (`@v1.2.0`) pin to a specific immutable release. They do not move on their own, so `gh aw update` will keep fetching that same tagged version unless you change the `source:` ref explicitly. * **Moving release refs** (`@v1`) follow the latest compatible release within that stream. These are the typical refs to use when you want `gh aw update` to pick up newer upstream releases automatically. * **Branch refs** (`@develop`) track the latest commit on a branch — useful for development integration. * **SHA pins** (`@abc123def`) provide strict reproducibility and never move without an explicit change. To pull upstream changes into an already-installed workflow: ```bash gh aw update ci-doctor # update one workflow gh aw update # update all tracked workflows ``` Updates use a 3-way merge by default to preserve local edits. Use `--no-merge` to replace the local copy with the upstream version without merging. When the recorded `source:` uses a moving major ref such as `@v1`, `gh aw update` stays within that major line unless `--major` is passed. ### 5. Private and internal sharing controls [Section titled “5. Private and internal sharing controls”](#5-private-and-internal-sharing-controls) Not all workflows are safe to share across organizations. GitHub Agentic Workflows provides controls at multiple levels: * **`private: true`** in frontmatter blocks a workflow from being installed into other repositories via `gh aw add`. Attempting to add a private workflow from another repository fails with an error. * **Repository visibility** controls which workflows are discoverable. Private repositories require access before any workflow can be fetched. * **Org-internal catalogs** can be implemented by placing workflows in a private or internal organization repository, ensuring only organization members can install them. See [Private Workflows](/gh-aw/reference/frontmatter/#private-workflows-private) for configuration details. ### 6. Import caching and lock behavior [Section titled “6. Import caching and lock behavior”](#6-import-caching-and-lock-behavior) When a workflow is compiled, remote imports are resolved and locked. The compiled `.lock.yml` file records the exact commit SHA for every remote import, making runs reproducible regardless of upstream branch movement. Imports are cached locally under `.github/aw/imports/` by commit SHA. Cached imports are used for all subsequent compilations until you explicitly update them. This means the lock file and the import cache together form the reproducibility guarantee for shared workflows. ### 7. Cross-repository execution model [Section titled “7. Cross-repository execution model”](#7-cross-repository-execution-model) Separate from sharing workflow definitions, workflows can operate across repositories at runtime: * Read files and metadata from other repositories during execution. * Check out code from target repositories for analysis or modification. * Write safe outputs to target repositories with explicit authentication and allowlists. ```yaml safe-outputs: create-issue: target-repo: "acme-org/target-repo" allowed-repos: ["acme-org/repo1", "acme-org/repo2"] ``` Cross-repository operations require appropriate GitHub token permissions and explicit `allowed-repos` declarations. See [Cross-Repository Operations](/gh-aw/reference/cross-repository/) for authentication, permissions, and safe output configuration. ## Recommended Enterprise Pattern [Section titled “Recommended Enterprise Pattern”](#recommended-enterprise-pattern) The recommended pattern for organizations sharing workflows at scale: 1. **One central `agentic-workflows` repository** holds versioned workflow templates and shared components under `workflows/` and `shared/`. 2. **Consuming repositories** use `gh aw add acme-org/agentic-workflows/@` to install complete workflows. 3. **Common modules** (MCP configurations, safety policies, shared prompts) live in `shared/` and are imported via `imports:` in consuming workflows. 4. **Version tags** on the central repository provide stable anchors for production consumers while branches support development integration. 5. **`private: true`** marks internal-only workflows that should not be exported outside the organization. This model gives platform teams centralized ownership and update control while giving consuming teams reproducibility through version pins and the ability to preserve local customizations through 3-way merge. ## Governance Questions [Section titled “Governance Questions”](#governance-questions) When workflows are shared across an organization, the important decisions are usually operational rather than technical: * Who owns the source workflow and reviews proposed changes. * How updates are tested, tagged, and promoted to consuming repositories. * Which repositories may consume or dispatch to shared workflows. * How secrets, permissions, and safe outputs are standardized across consumers. * When a consuming team may fork a workflow rather than stay on the shared version. Those decisions affect reliability more than the file format does. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Reusing Workflows](/gh-aw/guides/packaging-imports/) * [Imports Reference](/gh-aw/reference/imports/) * [Cross-Repository Operations](/gh-aw/reference/cross-repository/) * [Private Workflows](/gh-aw/reference/frontmatter/#private-workflows-private) * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) # Artifacts > Complete reference for artifact names, directory structures, and download patterns used by GitHub Agentic Workflows. GitHub Agentic Workflows upload several artifacts during workflow execution. This reference documents every artifact name, its contents, and how to access the data — especially for downstream workflows that use `gh run download` directly instead of `gh aw logs`. ## Quick Reference [Section titled “Quick Reference”](#quick-reference) | Artifact Name | Constant | Type | Description | | --------------------- | --------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent` | `constants.AgentArtifactName` | Multi-file | Unified agent job outputs (logs, safe outputs, token usage summary) | | `activation` | `constants.ActivationArtifactName` | Multi-file | Activation job output (`aw_info.json`, `prompt.txt`, rate limits) | | `firewall-audit-logs` | `constants.FirewallAuditArtifactName` | Multi-file | AWF firewall audit/observability logs (token usage, network policy, audit trail) | | `detection` | `constants.DetectionArtifactName` | Single-file | Threat detection log (`detection.log`) | | `safe-output` | `constants.SafeOutputArtifactName` | Legacy/back-compat | Historical standalone safe output artifact (`safe_output.jsonl`); in current compiled workflows this content is included in the unified `agent` artifact instead | | `agent-output` | `constants.AgentOutputArtifactName` | Legacy/back-compat | Historical standalone agent output artifact (`agent_output.json`); in current compiled workflows this content is included in the unified `agent` artifact instead | | `aw-info` | — | Single-file | Engine configuration (`aw_info.json`) | | `prompt` | — | Single-file | Generated prompt (`prompt.txt`) | | `experiment` | `constants.ExperimentArtifactName` | Multi-file | A/B experiment state (`state.json`) uploaded by the activation job when experiments are declared in the frontmatter | | `safe-outputs-items` | `constants.SafeOutputItemsArtifactName` | Single-file | Safe output items manifest | | `code-scanning-sarif` | `constants.SarifArtifactName` | Single-file | SARIF file for code scanning results | ## Artifact Sets [Section titled “Artifact Sets”](#artifact-sets) The `gh aw logs` and `gh aw audit` commands support `--artifacts` to download only specific artifact groups: | Set Name | Artifacts Downloaded | Use Case | | ------------ | --------------------- | ----------------------------------------------------------------- | | `all` | Everything | Full analysis (default) | | `agent` | `agent` | Agent logs and outputs | | `activation` | `activation` | Activation data (`aw_info.json`, `prompt.txt`) | | `firewall` | `firewall-audit-logs` | Network policy and firewall audit data | | `mcp` | `firewall-audit-logs` | MCP gateway traffic logs | | `detection` | `detection` | Threat detection output | | `experiment` | `experiment` | A/B experiment state (only present when experiments are declared) | | `github-api` | `activation`, `agent` | GitHub API rate limit logs | ```bash # Download only firewall artifacts gh aw logs --artifacts firewall # Download agent and firewall artifacts gh aw logs --artifacts agent --artifacts firewall # Download everything (default) gh aw logs ``` ## `firewall-audit-logs` [Section titled “firewall-audit-logs”](#firewall-audit-logs) The `firewall-audit-logs` artifact is uploaded by **all firewall-enabled workflows**. It contains AWF (Agent Workflow Firewall) structured audit and observability logs. > **! Important:** This artifact is **separate** from the `agent` artifact. Token usage data (`token-usage.jsonl`) lives here, not in the `agent` artifact. ### Directory Structure [Section titled “Directory Structure”](#directory-structure) ```plaintext firewall-audit-logs/ ├── api-proxy-logs/ │ └── token-usage.jsonl ← Token usage data (input/output/cache tokens per API request) ├── squid-logs/ │ └── access.log ← Network policy log (domain allow/deny decisions) ├── audit.jsonl ← Firewall audit trail (policy matches, rule evaluations) └── policy-manifest.json ← Policy configuration snapshot ``` ### Accessing Token Usage Data [Section titled “Accessing Token Usage Data”](#accessing-token-usage-data) **Recommended: Use `gh aw logs`** ```bash # Download and analyze firewall data gh aw logs --artifacts firewall # Output as JSON for scripting gh aw logs --artifacts firewall --json ``` **Direct download with `gh run download`:** ```bash # Download the firewall-audit-logs artifact gh run download -n firewall-audit-logs # Token usage data is at: cat firewall-audit-logs/api-proxy-logs/token-usage.jsonl # Network access log is at: cat firewall-audit-logs/squid-logs/access.log # Audit trail is at: cat firewall-audit-logs/audit.jsonl # Policy manifest is at: cat firewall-audit-logs/policy-manifest.json ``` ### Common Mistake [Section titled “Common Mistake”](#common-mistake) Downstream workflows sometimes download `agent-artifacts` or `agent` expecting to find `token-usage.jsonl`. This will silently return no data — the token usage file is only in the `firewall-audit-logs` artifact. ```bash # ✗ WRONG — token-usage.jsonl is NOT in the agent artifact gh run download -n agent cat agent/token-usage.jsonl # File not found! # ✓ CORRECT — download from firewall-audit-logs gh run download -n firewall-audit-logs cat firewall-audit-logs/api-proxy-logs/token-usage.jsonl ``` ### JSON Schemas [Section titled “JSON Schemas”](#json-schemas) The JSONL files in this artifact are described by versioned JSON Schemas published by [github/gh-aw-firewall](https://github.com/github/gh-aw-firewall). Each record includes a `_schema` field (for example `"audit/v0.26.0"`) so consumers can identify the record type and AWF version. | File | Schema asset | Pinned URL | | ---------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------ | | `audit.jsonl` | `audit.schema.json` | `https://github.com/github/gh-aw-firewall/releases/download//audit.schema.json` | | `api-proxy-logs/token-usage.jsonl` | `token-usage.schema.json` | `https://github.com/github/gh-aw-firewall/releases/download//token-usage.schema.json` | Use `releases/latest/download/` in place of a specific tag to track the most recent published release. Schemas are versioned by AWF release tag; consumers should match `_schema` by prefix (for example `_schema.startsWith("audit/")`) so additive changes remain non-breaking. ## `agent` [Section titled “agent”](#agent) The unified `agent` artifact contains all agent job outputs. ### Contents [Section titled “Contents”](#contents) * Agent execution logs * Safe output data (`agent_output.json`) * GitHub API rate limit logs (`github_rate_limits.jsonl`) * Token usage summary (`agent_usage.json`) — aggregated totals only; per-request data is in `firewall-audit-logs` * `otel.jsonl` — OTLP span mirror written by gh-aw’s JavaScript span exporters (only present when `observability.otlp` is configured) * `copilot-otel.jsonl` — OTLP spans emitted by Copilot CLI (only present when `observability.otlp` is configured) For OTLP configuration, runtime environment variables, and span semantics, see [OpenTelemetry](/gh-aw/reference/open-telemetry/). ## `activation` [Section titled “activation”](#activation) The `activation` artifact contains activation job outputs. ### Contents [Section titled “Contents”](#contents-1) * `aw_info.json` — Engine configuration and workflow metadata * `prompt.txt` — The generated prompt sent to the AI agent * `github_rate_limits.jsonl` — Rate limit data from the activation job ## `detection` [Section titled “detection”](#detection) The `detection` artifact contains threat detection output. ### Contents [Section titled “Contents”](#contents-2) * `detection.log` — Threat detection analysis results Legacy name: `threat-detection.log` (still supported for backward compatibility). ## `experiment` [Section titled “experiment”](#experiment) The `experiment` artifact is uploaded by the **activation job** only when the workflow frontmatter declares one or more `experiments` entries. It is not present on runs without experiments. ### Contents [Section titled “Contents”](#contents-3) * `state.json` — Cumulative per-variant invocation counters used to balance A/B assignments across runs ### Accessing experiment data [Section titled “Accessing experiment data”](#accessing-experiment-data) ```bash # Download the experiment artifact for a specific run gh aw audit --artifacts experiment # Display the A/B experiment section in the audit report gh aw audit ``` The `A/B Experiments` section of the audit report shows the variant chosen for the run and the cumulative counts: ```plaintext A/B Experiments • style = concise (cumulative: concise:5, detailed:4) ``` See [A/B Experiments](/gh-aw/practices/experiments/) for how to declare experiments in workflow frontmatter. ## Naming Compatibility [Section titled “Naming Compatibility”](#naming-compatibility) Artifact names changed between upload-artifact v4 and v5. The `gh aw logs` and `gh aw audit` commands handle both naming schemes transparently: | Old Name (pre-v5) | New Name (v5+) | File Inside | | ---------------------- | -------------- | ------------------- | | `aw_info.json` | `aw-info` | `aw_info.json` | | `safe_output.jsonl` | `safe-output` | `safe_output.jsonl` | | `agent_output.json` | `agent-output` | `agent_output.json` | | `prompt.txt` | `prompt` | `prompt.txt` | | `threat-detection.log` | `detection` | `detection.log` | Single-file artifacts are automatically flattened to root level regardless of their artifact directory name. Multi-file artifacts (`firewall-audit-logs`, `agent`, `activation`, `experiment`) retain their directory structure. ## Workflow Call Prefixes [Section titled “Workflow Call Prefixes”](#workflow-call-prefixes) When workflows are invoked via `workflow_call`, GitHub Actions prepends a short hash to artifact names (e.g., `abc123-firewall-audit-logs`). The CLI handles this automatically by matching artifact names that end with `-{base-name}`. ```bash # Both of these are recognized as the firewall artifact: # - firewall-audit-logs (direct invocation) # - abc123-firewall-audit-logs (workflow_call invocation) ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Audit Commands](/gh-aw/reference/audit/) — Download and analyze workflow run artifacts * [Cost Management](/gh-aw/reference/cost-management/) — Track token usage and inference spend * [Network](/gh-aw/reference/network/) — Firewall and domain allow/deny configuration * [Compilation Process](/gh-aw/reference/compilation-process/) — How workflows are compiled including artifact upload steps # Assign to Copilot > Programmatically assign GitHub Copilot coding agent to issues and pull requests This page describes how to programmatically assign the [GitHub Copilot coding agent](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) to issues or pull requests using the `assign-to-agent` safe output. This automates the [standard GitHub workflow for assigning issues to Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-a-pr#assigning-an-issue-to-copilot). ## When to Use [Section titled “When to Use”](#when-to-use) Use `assign-to-agent` when you need to programmatically assign Copilot coding agent to **existing** issues or PRs through workflow automation. If you’re creating new issues and want to assign Copilot coding agent immediately, use `assignees: copilot` in your [`create-issue`](/gh-aw/reference/safe-outputs/#issue-creation-create-issue) configuration instead. ## Configuration [Section titled “Configuration”](#configuration) ```yaml safe-outputs: assign-to-agent: name: "copilot" # default agent (default: "copilot") model: "claude-opus-4.6" # default AI model (default: "auto") custom-agent: "agent-id" # default custom agent ID (optional) custom-instructions: "..." # default custom instructions (optional) allowed: [copilot] # restrict to specific agents (optional) max: 1 # max assignments (default: 1) target: "triggering" # "triggering" (default), "*", or number target-repo: "owner/repo" # where the issue lives (cross-repository) pull-request-repo: "owner/repo" # where the PR should be created (may differ from issue repo) allowed-pull-request-repos: [owner/repo1, owner/repo2] # additional allowed PR repositories base-branch: "develop" # target branch for PR (default: target repo's default branch) github-token: ${{ secrets.GH_AW_AGENT_TOKEN }} # token for permissions ``` **Supported agents:** `copilot` (`copilot-swe-agent`) ## Target Issue or Pull Request [Section titled “Target Issue or Pull Request”](#target-issue-or-pull-request) The `target` parameter determines which issue or PR to assign the agent to: * `target: "triggering"` (default) - Auto-resolves from `github.event.issue.number` or `github.event.pull_request.number` * `target: "*"` - Requires explicit `issue_number` or `pull_number` in agent output * `target: "123"` - Always uses issue/PR #123 ## Cross-Repository PR Creation [Section titled “Cross-Repository PR Creation”](#cross-repository-pr-creation) Use `pull-request-repo` to create pull requests in a different repository than where the issue lives — useful when issues are tracked centrally but code lives elsewhere. The issue repository is determined by `target-repo` or defaults to the workflow’s repository. `pull-request-repo` is automatically included in the allowed list; use `allowed-pull-request-repos` for additional repositories. Use `base-branch` to target a specific branch (defaults to the target repo’s default branch). ## Assignee Filtering [Section titled “Assignee Filtering”](#assignee-filtering) When an `allowed` list is configured, existing agent assignees not in the list are removed while regular user assignees are preserved. ## Authentication [Section titled “Authentication”](#authentication) This safe output requires a fine-grained PAT to authenticate the agent assignment operation. The default `GITHUB_TOKEN` lacks the necessary permissions. ### Using a Personal Access Token (PAT) [Section titled “Using a Personal Access Token (PAT)”](#using-a-personal-access-token-pat) The required token type and permissions depend on whether you own the repository or an organization owns it. 1. **Create the PAT** with **Repository permissions**: Actions, Contents, Issues, Pull requests (all Write). * [User-owned repositories](https://github.com/settings/personal-access-tokens/new?name=GH_AW_AGENT_TOKEN\&description=GitHub+Agentic+Workflows+-+Agent+assignment\&actions=write\&contents=write\&issues=write\&pull_requests=write): Resource owner = your user account; Repository access = “Public repositories” or specific repos * [Organization-owned repositories](https://github.com/settings/personal-access-tokens/new?name=GH_AW_AGENT_TOKEN\&description=GitHub+Agentic+Workflows+-+Agent+assignment\&actions=write\&contents=write\&issues=write\&pull_requests=write): Resource owner = the organization; Repository access = specific repositories that will use the workflow 2. Add to repository secrets: ```bash gh aw secrets set GH_AW_AGENT_TOKEN --value "YOUR_AGENT_PAT" ``` ### Using a GitHub App [Section titled “Using a GitHub App”](#using-a-github-app) GitHub App tokens are not supported for Copilot assignment The Copilot assignment API only accepts fine-grained PATs — GitHub App installation tokens are rejected regardless of permissions. When `github-app:` is configured in `safe-outputs`, `assign-to-agent` falls back to: explicit `github-token:` in `assign-to-agent`, then `github-token:` at the `safe-outputs` level, then the magic secret chain (`GH_AW_AGENT_TOKEN || GH_AW_GITHUB_TOKEN || GITHUB_TOKEN`). ### Using a magic secret [Section titled “Using a magic secret”](#using-a-magic-secret) Alternatively, you can set the magic secret `GH_AW_AGENT_TOKEN` to a suitable PAT (see the above guide for creating one). This secret name is known to GitHub Agentic Workflows and does not need to be explicitly referenced in your workflow. ```bash gh aw secrets set GH_AW_AGENT_TOKEN --value "" ``` Your browser doesn't support HTML5 video. [Download Creating a fine-grained PAT for organization-owned repositories with permissions for agent assignment](/gh-aw/videos/create-pat-org-agent.mp4). Creating a fine-grained PAT for organization-owned repositories with permissions for agent assignment ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - All safe output configurations * [Authentication Reference](/gh-aw/reference/auth/) - All tokens and secrets * [IssueOps](/gh-aw/patterns/issue-ops/) - Issue-triggered workflow patterns # Auditing Workflows > Reference for the gh aw audit commands — single-run analysis, behavioral diff, and cross-run security reports. The `gh aw audit` commands download workflow run artifacts and logs, analyze MCP tool usage and network behavior, and produce structured reports suited for security reviews, debugging, and feeding to AI agents. ## `gh aw audit [...]` [Section titled “gh aw audit \ \[\...\]”](#gh-aw-audit-run-id-or-url-run-id-or-url) Audit one or more workflow runs. When a single run is provided, a detailed Markdown report is generated. When two or more runs are provided, the first is used as the base (reference) run and the remaining runs are compared against it, producing a diff report. **Arguments:** | Argument | Description | | ---------------------- | ------------------------------------------------------------------------------ | | `` | A numeric run ID, GitHub Actions run URL, job URL, or job URL with step anchor | | `[...]` | Additional run IDs or URLs to compare against the first (diff mode) | **Accepted input formats (per argument):** * Numeric run ID: `1234567890` * Run URL: `https://github.com/owner/repo/actions/runs/1234567890` * Job URL: `https://github.com/owner/repo/actions/runs/1234567890/job/9876543210` * Job URL with step: `https://github.com/owner/repo/actions/runs/1234567890/job/9876543210#step:7:1` * Short run URL: `https://github.com/owner/repo/runs/1234567890` * GitHub Enterprise URLs using the same formats above When a job URL is provided without a step anchor (single-run mode), the command extracts the output of the first failing step. When a step anchor is included, it extracts that specific step. In diff mode, job URLs and step-anchored URLs are accepted for any argument — the job/step specificity is silently normalized to the parent run ID, so it is always a run-level diff. Self-comparisons and duplicate run IDs are rejected when using diff mode. **Flags:** | Flag | Default | Description | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `-o, --output ` | `./logs` | Directory to write downloaded artifacts and report files | | `--json` | off | Output report as JSON to stdout | | `--parse` | off | Run JavaScript parsers on agent and firewall logs, writing `log.md` and `firewall.md` (single-run only) | | `--repo ` | auto | Specify repository when the run ID is not from a URL | | `--stdin` | off | Read run IDs or URLs from stdin (one per line) instead of positional arguments | | `--verbose` | off | Print detailed progress information | | `--format ` | `pretty` | Diff output format: `pretty` or `markdown` (multi-run only) | **Single-run examples:** ```bash gh aw audit 1234567890 gh aw audit https://github.com/owner/repo/actions/runs/1234567890 gh aw audit 1234567890 --parse gh aw audit 1234567890 --json gh aw audit 1234567890 -o ./audit-reports gh aw audit 1234567890 --repo owner/repo ``` **Stdin mode:** Use `--stdin` to pass run IDs or URLs from a file or pipeline. This is mutually exclusive with positional arguments. Blank lines and lines starting with `#` are ignored. When passing bare numeric IDs (without embedded repo context), `--repo owner/repo` is required. ```bash echo "1234567890" | gh aw audit --stdin echo -e "1234567890\n9876543210" | gh aw audit --stdin # diff mode: first is base cat run-ids.txt | gh aw audit --stdin cat run-ids.txt | gh aw audit --stdin --repo owner/repo # required for bare numeric IDs ``` **Multi-run diff examples:** ```bash gh aw audit 12345 12346 # Compare two runs gh aw audit 12345 12346 12347 12348 # Compare base against 3 runs gh aw audit 12345 12346 --format markdown # Markdown output for PR comments gh aw audit 12345 12346 --json # JSON for CI integration gh aw audit 12345 12346 --repo owner/repo # Specify repository ``` **Single-run report sections** (rendered in Markdown or JSON): Overview, Comparison, Task/Domain, Behavior Fingerprint, Agentic Assessments, Metrics, Key Findings, Recommendations, Observability Insights, Performance Metrics, Engine Config, Prompt Analysis, Session Analysis, Safe Output Summary, MCP Server Health, Jobs, Downloaded Files, Missing Tools, Missing Data, Noops, MCP Failures, Firewall Analysis, Policy Analysis, Redacted Domains, Errors, Warnings, Tool Usage, MCP Tool Usage, Created Items. The Metrics section includes an `ambient_context` object when available. Ambient context captures the first LLM inference footprint for the run: * `ambient_context.input_tokens` — input tokens for the first invocation * `ambient_context.cached_tokens` — cache-read tokens reused by the first invocation * `ambient_context.effective_tokens` — `input_tokens + cached_tokens` **Diff output** includes: * New and removed network domains * Domain status changes (allowed denied) * Volume changes (request count changes above a 100% threshold) * Anomaly flags (new denied domains, previously-denied domains now allowed) * MCP tool invocation changes (new/removed tools, call count and error count diffs) * Run metrics comparison (token usage, duration, turns) * Token usage breakdown: input tokens, output tokens, cache read/write tokens, effective tokens, total API requests, and cache efficiency per run * Tokens per turn: effective tokens divided by turn count for each run, with the change between runs * Tool call breakdown: per-tool call counts (new, removed, and changed tools) with max input/output sizes * Bash command breakdown: aggregated call counts and max input/output sizes for each distinct bash command invoked **Diff output behavior with multiple comparisons:** * `--json` outputs a single object for one comparison, or an array for multiple * `--format pretty` and `--format markdown` separate multiple diffs with dividers ## `gh aw logs --format ` [Section titled “gh aw logs --format \”](#gh-aw-logs---format-fmt) Generate a cross-run security and performance audit report across multiple recent workflow runs. This feature is built into the `gh aw logs` command via the `--format` flag. **Flags:** | Flag | Default | Description | | --------------------- | ------------- | ---------------------------------------------------------------------------------------------------- | | `[workflow]` | all workflows | Filter by workflow name or filename (positional argument) | | `-c, --count ` | 10 | Number of recent runs to analyze | | `--last ` | — | Alias for `--count` | | `--format ` | — | Output format: `markdown` or `pretty` (generates cross-run audit report) | | `--json` | off | Output cross-run report as JSON (when combined with `--format`) | | `--repo ` | auto | Specify repository | | `-o, --output ` | `./logs` | Directory for downloaded artifacts | | `--stdin` | off | Read run IDs or URLs from stdin (one per line) instead of run-discovery; content filters still apply | | `--verbose` | off | Print detailed progress | The report output includes an executive summary, domain inventory, metrics trends, MCP server health, and per-run breakdown. It detects cross-run anomalies such as domain access spikes, elevated MCP error rates, and connection rate changes. For each run in detailed logs JSON output, an `ambient_context` object is included when token usage data is available. It reflects only the first LLM invocation in the run (`input_tokens`, `cached_tokens`, `effective_tokens`). **`--stdin` mode:** Pass `--stdin` to supply an explicit list of run IDs or URLs instead of letting the command discover runs from the GitHub API. Date, count, and workflow-name filters are ignored; `--engine`, `--firewall`, `--safe-output`, and other content filters still apply. Blank lines and `#`-prefixed lines are ignored. Bare numeric IDs require `--repo owner/repo`. ```bash cat run-ids.txt | gh aw logs --stdin echo "1234567890" | gh aw logs --stdin --engine claude cat run-ids.txt | gh aw logs --stdin --repo owner/repo # required for bare numeric IDs ``` **Examples:** ```bash gh aw logs --format markdown gh aw logs daily-repo-status --format markdown --count 10 gh aw logs agent-task --format markdown --last 5 --json gh aw logs --format pretty gh aw logs --format markdown --repo owner/repo --count 10 ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Cost Management](/gh-aw/reference/cost-management/) — Track token usage and inference spend * [Artifacts](/gh-aw/reference/artifacts/) — Artifact names, directory structures, and token usage file locations (`token-usage.jsonl` in `firewall-audit-logs`) * [Effective Tokens Specification](/gh-aw/reference/effective-tokens-specification/) — How effective tokens are computed * [Network](/gh-aw/reference/network/) — Firewall and domain allow/deny configuration * [MCP Gateway](/gh-aw/reference/mcp-gateway/) — MCP server health and debugging * [CLI Commands](/gh-aw/setup/cli/) — Full CLI reference ## Consuming Audit Reports in Workflows [Section titled “Consuming Audit Reports in Workflows”](#consuming-audit-reports-in-workflows) When running locally, all three audit commands accept `--json` to write structured output to stdout. Pipe through `jq` to extract the fields a model needs. | Command | Use case | | ---------------------------------------- | --------------------------------------------------------- | | `gh aw audit --json` | Single run — `key_findings`, `recommendations`, `metrics` | | `gh aw logs [workflow] --last 10 --json` | Trend analysis — `per_run_breakdown`, `domain_inventory` | | `gh aw audit --json` | Before/after — `run_metrics_diff`, `firewall_diff` | Inside GitHub Actions workflows, agents access these commands through the `agentic-workflows` MCP tool rather than calling the CLI directly. ### Posting findings as a PR comment [Section titled “Posting findings as a PR comment”](#posting-findings-as-a-pr-comment) ```aw --- description: Post audit findings as a PR comment after each agent run on: workflow_run: workflows: ['my-workflow'] types: [completed] engine: copilot tools: github: toolsets: [pull_requests] agentic-workflows: permissions: contents: read actions: read pull-requests: write --- # Summarize Audit Findings Use the `agentic-workflows` MCP tool `audit` with run ID ${{ github.event.workflow_run.id }}, identify the pull request that triggered it, and post a comment summarizing key findings and blocked domains. Highlight issues with severity `high` or `critical`. If there are no findings, post a brief "no issues found" comment. ``` ### Detecting regressions with diff [Section titled “Detecting regressions with diff”](#detecting-regressions-with-diff) ```aw --- description: Detect regressions between two workflow runs on: workflow_dispatch: inputs: base_run_id: description: 'Baseline run ID' required: true current_run_id: description: 'Current run ID to compare' required: true engine: copilot tools: github: toolsets: [issues] agentic-workflows: permissions: contents: read actions: read issues: write --- # Regression Detection Use the `agentic-workflows` MCP tool `audit` with run IDs ${{ inputs.base_run_id }} and ${{ inputs.current_run_id }} to compare the two runs. Check for new blocked domains, increased MCP error rates, cost increase > 20%, or token usage increase > 50%. If regressions are found, open a GitHub issue with a table from `run_metrics_diff`, affected domains from `firewall_diff`, and affected MCP tools from `mcp_tools_diff`. ``` ### Filing issues from audit findings [Section titled “Filing issues from audit findings”](#filing-issues-from-audit-findings) ```aw --- description: File GitHub issues for high-severity audit findings on: workflow_run: workflows: ['my-workflow'] types: [completed] engine: copilot tools: github: toolsets: [issues] agentic-workflows: permissions: contents: read actions: read issues: write --- # Auto-File Issues for Critical Findings Use the `agentic-workflows` MCP tool `audit` with run ID ${{ github.event.workflow_run.id }}. Filter `key_findings` for severity `high` or `critical`. For each finding without a matching open issue, create one with the finding title, description, impact, and recommendations, labelled `audit-finding`. If no critical findings, call the `noop` safe output tool. ``` ### Weekly audit monitoring agent [Section titled “Weekly audit monitoring agent”](#weekly-audit-monitoring-agent) ```aw --- description: Weekly audit digest with trend analysis on: schedule: weekly engine: copilot tools: github: toolsets: [discussions] agentic-workflows: cache-memory: key: audit-monitoring-trends permissions: contents: read actions: read discussions: write --- # Weekly Audit Monitoring Digest 1. Use the `agentic-workflows` MCP tool `logs` with parameters `workflow: my-workflow, last: 10` and read `/tmp/gh-aw/cache-memory/audit-trends.json` as the previous baseline. 2. Detect: cost spikes (`cost_spike: true` in `per_run_breakdown`), new denied domains in `domain_inventory`, MCP servers with `error_rate > 0.10` or `unreliable: true`, and week-over-week changes in `error_trend.runs_with_errors`. 3. Create a GitHub discussion "Audit Digest — [YYYY-MM-DD]" with an executive summary, anomalies table, and MCP health table. 4. Update `/tmp/gh-aw/cache-memory/audit-trends.json` with rolling averages (cost, tokens, error count, deny rate), keeping only the last 30 days. ``` Top-level fields (`key_findings`, `recommendations`, `metrics`, `firewall_analysis`, `mcp_tool_usage`) are stable; nested sub-fields may be extended but are not removed without deprecation. Add `--parse` to populate `behavior_fingerprint` and `agentic_assessments`. Cross-run JSON can be large — extract only the slices your model needs. # Authentication > Comprehensive reference for GitHub Actions secrets, GitHub tokens and GitHub Apps in gh-aw This page describes authentication settings for GitHub Agentic Workflows. ## Which secret do I need? [Section titled “Which secret do I need?”](#which-secret-do-i-need) Configure one GitHub Actions secret per engine before running your first workflow: | Engine | Required secret | Alternative | Notes | | --------------------- | ----------------------------------------------- | --------------- | --------------------------------------------------------------------------------- | | **Copilot** (default) | [`COPILOT_GITHUB_TOKEN`](#copilot_github_token) | — | Fine-grained PAT with Copilot Requests permission | | **Claude** | [`ANTHROPIC_API_KEY`](#anthropic_api_key) | — | API key from Anthropic Console | | **Codex** | [`OPENAI_API_KEY`](#openai_api_key) | `CODEX_API_KEY` | Runtime uses `CODEX_API_KEY` if present, otherwise falls back to `OPENAI_API_KEY` | | **Gemini** | [`GEMINI_API_KEY`](#gemini_api_key) | — | API key from Google AI Studio | Most workflows will run without any additional secrets or additional authentication beyond this one engine secret. ## Additional Authentication [Section titled “Additional Authentication”](#additional-authentication) Some workflows need additional authentication. These can be tokens added as secrets and referenced in your workflow, or GitHub App can be used. Workflows using the following **read** operations from GitHub require [Additional Authentication for GitHub Tools](/gh-aw/reference/github-tools/#additional-authentication-for-github-tools), via either a secret containing a PAT or GitHub App: * **Read from multiple repositories** * **Read from projects** * **GitHub tools remote mode** Workflows using the following features of [Safe Outputs](/gh-aw/reference/safe-outputs/) require additional authentication, via either a secret containing a PAT or GitHub App: * [**Safe outputs writing cross-repo**](/gh-aw/reference/safe-outputs/#cross-repository-operations) * [**Safe outputs assigning Copilot coding agent to issues/PRs**](/gh-aw/reference/assign-to-copilot/) * [**Safe outputs updating GitHub Projects**](/gh-aw/patterns/project-ops/#project-token-authentication) * [**Safe outputs triggering CI on PRs**](/gh-aw/reference/triggering-ci/) Workflows using custom MCP tools or safe outputs may require additional authentication depending on the operations performed. ## How do I add a GitHub Actions secret to my repository? [Section titled “How do I add a GitHub Actions secret to my repository?”](#how-do-i-add-a-github-actions-secret-to-my-repository) You can add secrets manually in the GitHub UI or use the CLI for a streamlined experience. ### Adding secrets using the CLI [Section titled “Adding secrets using the CLI”](#adding-secrets-using-the-cli) ```bash gh aw secrets set COPILOT_GITHUB_TOKEN --value "YOUR_COPILOT_PAT" ``` You can also check existing secrets with: ```bash gh aw secrets bootstrap ``` If you’re working in Codespaces, use the GitHub UI method below to add secrets. ### Adding secrets using the GitHub UI [Section titled “Adding secrets using the GitHub UI”](#adding-secrets-using-the-github-ui) 1. Go to your repository on GitHub 2. Click on “Settings” → “Secrets and variables” → “Actions” 3. Click “New repository secret” and add the token name and value  ## GitHub Actions secrets for AI engines [Section titled “GitHub Actions secrets for AI engines”](#github-actions-secrets-for-ai-engines) A reference for all GitHub Actions secrets used by GitHub Agentic Workflows for AI engine authentication: ### `COPILOT_GITHUB_TOKEN` [Section titled “COPILOT\_GITHUB\_TOKEN”](#copilot_github_token) If using Copilot as your AI engine, you need a GitHub Actions Secret set to a GitHub Personal Access Token (PAT) to authenticate Copilot CLI. **Setup**: [**Create a fine-grained PAT**](https://github.com/settings/personal-access-tokens/new?name=COPILOT_GITHUB_TOKEN\&description=GitHub+Agentic+Workflows+-+Copilot+engine+authentication\&user_copilot_requests=read) (this link pre-fills the token name, description, and Copilot Requests permission). Verify the following settings before generating: 1. **Resource owner** is your **user account**, not an organization. 2. Under **Permissions → Account permissions**, **Copilot Requests** is set to **Read**. 3. Click **Generate token** and copy the token value. 4. Add the PAT to your GitHub Actions repository secrets as `COPILOT_GITHUB_TOKEN`, either by CLI or GitHub UI. ```bash gh aw secrets set COPILOT_GITHUB_TOKEN --value "" ``` **Custom endpoints**: To route Copilot CLI through a custom endpoint (e.g., a corporate proxy or GHE Cloud data residency instance), set `GITHUB_COPILOT_BASE_URL` in `engine.env`. See [Custom API Endpoints via Environment Variables](/gh-aw/reference/engines/#custom-api-endpoints-via-environment-variables) for details. `COPILOT_GITHUB_TOKEN` must still be a fine-grained PAT — GitHub Apps and OAuth tokens are not supported for this secret. **Troubleshooting**: If your workflow fails at the Copilot inference step even with the token set, verify that the token owner’s account has an active Copilot license. See [Copilot License or Inference Access Issues](/gh-aw/troubleshooting/common-issues/#copilot-license-or-inference-access-issues) for a local diagnostic step. *** ### `ANTHROPIC_API_KEY` [Section titled “ANTHROPIC\_API\_KEY”](#anthropic_api_key) If using the Claude by Anthropic engine, you need to set a GitHub Actions secret `ANTHROPIC_API_KEY` to be an API key from Anthropic. **Setup**: 1. Create an API key at 2. Add it to your repository secrets, either by CLI or GitHub UI: ```bash gh aw secrets set ANTHROPIC_API_KEY --value "YOUR_ANTHROPIC_API_KEY" ``` **Custom endpoints**: To route Claude through a custom Anthropic-compatible endpoint (e.g., an internal proxy or Azure-hosted model), set `ANTHROPIC_BASE_URL` in `engine.env` and store any additional credentials as secrets. See [Custom API Endpoints via Environment Variables](/gh-aw/reference/engines/#custom-api-endpoints-via-environment-variables) for an example. **`CLAUDE_CODE_OAUTH_TOKEN`**: `CLAUDE_CODE_OAUTH_TOKEN` is not supported by GitHub Agentic Workflows. The only supported authentication method for the Claude engine is `ANTHROPIC_API_KEY`. Provider-based OAuth authentication (such as billing through a Claude Teams or Claude Max subscription) is not supported. If you have set `CLAUDE_CODE_OAUTH_TOKEN` as a repository secret, it will be ignored — configure `ANTHROPIC_API_KEY` instead. See also [AI Engines](/gh-aw/reference/engines/#available-coding-agents) for additional configuration needed when using Claude with GitHub MCP. *** ### `OPENAI_API_KEY` [Section titled “OPENAI\_API\_KEY”](#openai_api_key) If using the Codex by OpenAI engine, you need to set a GitHub Actions secret `OPENAI_API_KEY` with an API key from OpenAI. **Setup**: 1. Create an API key at 2. Add it to your repository secrets, either by CLI or GitHub UI: ```bash gh aw secrets set OPENAI_API_KEY --value "YOUR_OPENAI_API_KEY" ``` **`CODEX_API_KEY` alternative**: Both `CODEX_API_KEY` and `OPENAI_API_KEY` are accepted. The runtime tries `CODEX_API_KEY` first. If you have already stored the key under `CODEX_API_KEY`, there is no need to add `OPENAI_API_KEY` as well. **Azure OpenAI and custom endpoints**: To use Azure OpenAI or an internal LLM router instead of the default OpenAI endpoint, set `OPENAI_BASE_URL` in `engine.env` and store the corresponding key as a GitHub Actions secret referenced from `engine.env`: ```aw engine: id: codex model: gpt-4o env: OPENAI_BASE_URL: "https://my-azure-endpoint.openai.azure.com/openai/deployments/gpt-4o" OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }} network: allowed: - github.com - my-azure-endpoint.openai.azure.com ``` `AZURE_OPENAI_API_KEY` is a GitHub Actions repository secret you configure separately with `gh aw secrets set AZURE_OPENAI_API_KEY --value ""`. Do not embed raw key values directly in the frontmatter. See also [AI Engines](/gh-aw/reference/engines/#available-coding-agents) for additional configuration needed when using Codex with GitHub MCP. *** ### `GEMINI_API_KEY` [Section titled “GEMINI\_API\_KEY”](#gemini_api_key) If using the Gemini by Google engine, you need to set a GitHub Actions secret `GEMINI_API_KEY` with an API key from Google AI Studio. **Setup**: 1. Create an API key at 2. Add it to your repository secrets, either by CLI or GitHub UI: ```bash gh aw secrets set GEMINI_API_KEY --value "YOUR_GEMINI_API_KEY" ``` See also [AI Engines](/gh-aw/reference/engines/#available-coding-agents) for additional configuration needed when using Gemini with GitHub MCP. *** ## Troubleshooting auth errors [Section titled “Troubleshooting auth errors”](#troubleshooting-auth-errors) Common authentication errors and how to resolve them: **`403 "Resource not accessible by personal access token"` (Copilot)** The PAT is missing the required permission. Use a fine-grained PAT with **Account permissions → Copilot Requests: Read**. The resource owner must be your personal account, not an organization. See [`COPILOT_GITHUB_TOKEN`](#copilot_github_token) for the setup link. **`401 Unauthorized` or `403 Forbidden` (Claude)** The `ANTHROPIC_API_KEY` secret is missing, expired, or invalid. Verify the key is active in the [Anthropic Console](https://console.anthropic.com/). Re-set the secret with `gh aw secrets set ANTHROPIC_API_KEY --value ""`. Also check that you have not accidentally set `CLAUDE_CODE_OAUTH_TOKEN` instead — it is not supported. **`401 Unauthorized` or `403 Forbidden` (Codex)** The `OPENAI_API_KEY` (or `CODEX_API_KEY`) secret is missing, expired, or has insufficient quota. Verify the key at . If using a custom endpoint, confirm `OPENAI_BASE_URL` points to a reachable host and that the host is listed under `network.allowed`. **`401 Unauthorized` (Gemini)** The `GEMINI_API_KEY` secret is missing or invalid. Generate a new key at . **Copilot license or inference access errors** If the token is correctly configured but Copilot fails at the inference step, the PAT owner’s account may lack an active Copilot subscription. See [Copilot License or Inference Access Issues](/gh-aw/troubleshooting/common-issues/#copilot-license-or-inference-access-issues) for a local diagnostic command. **`Error loading models: 400 Bad Request` (Copilot on GHES)** Copilot is not licensed at the enterprise level or the API proxy is routing incorrectly. See [Copilot Engine Prerequisites on GHES](/gh-aw/troubleshooting/common-issues/#copilot-engine-prerequisites-on-ghes) for the full checklist. *** ## Using a GitHub App for Authentication [Section titled “Using a GitHub App for Authentication”](#using-a-github-app-for-authentication) For enhanced security with short-lived tokens, you may configure a GitHub App instead of using PATs. This does not apply to `COPILOT_GITHUB_TOKEN`, which must currently be a PAT. A single GitHub App can be used for all other GitHub authentication needs in GitHub Agentic Workflows, including tool authentication and safe outputs. After creating your app, configure it in your workflow: ```yaml permissions: contents: read issues: read tools: github: toolsets: [repos, issues, pull_requests] github-app: client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} owner: "my-org" # Optional: defaults to current repo owner repositories: ["repo1", "repo2"] # Optional: defaults to current repo only ``` Make sure you set up repository variables and secrets: ```bash gh variable set APP_ID --body "123456" gh aw secrets set APP_PRIVATE_KEY --value "$(cat path/to/private-key.pem)" ``` At workflow start, a token is automatically minted with **permissions matching your job’s `permissions:` field**. The token is passed to the GitHub MCP server and automatically revoked at workflow end (even on failure). You can also use GitHub App tokens for safe outputs operations: ```yaml safe-outputs: github-app: client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} owner: "my-org" # optional: installation owner repositories: ["repo1", "repo2"] # optional: scope to specific repos create-issue: ``` When you configure `github-app:` for safe outputs, tokens are minted with permissions specific to the safe output operations being performed, rather than the broader job-level permissions. This provides enhanced security by ensuring that tokens have the minimum necessary permissions for their specific use case. For both tool authentication and safe outputs, you can scope the GitHub App token to specific repositories for enhanced security. This limits the token’s access to only the repositories it needs to interact with. * Omit `repositories` field - Current repository only (default) * `repositories: ["*"]` - Org-wide access (all repos in the installation) * `repositories: ["repo1", "repo2"]` - Specific repositories only ### Gracefully Skip Minting When Keys Are Missing (`ignore-if-missing:`) [Section titled “Gracefully Skip Minting When Keys Are Missing (ignore-if-missing:)”](#gracefully-skip-minting-when-keys-are-missing-ignore-if-missing) By default, jobs fail when `client-id` or `private-key` resolve to empty strings at runtime — for example, on fork pull requests where App secrets are unavailable. Set `ignore-if-missing: true` to skip the token mint step instead and fall back to the standard non-App token chain (`secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN`): ```yaml safe-outputs: github-app: client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} ignore-if-missing: true create-issue: ``` The same field is accepted under `tools.github.github-app:` and applies consistently to all token mint paths (safe outputs, activation, pre-activation, and checkout). Default behavior (fail when keys are empty) is unchanged when the field is omitted or `false`. *** ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Engines](/gh-aw/reference/engines/) - Engine-specific authentication * [Safe Outputs](/gh-aw/reference/safe-outputs/) - Safe output token configuration * [Tools](/gh-aw/reference/tools/) - Tool authentication and modes * [Permissions](/gh-aw/reference/permissions/) - Permission model overview # Authentication (Projects) > Reference for authenticating GitHub Projects read and write operations in gh-aw GitHub Projects operations require additional authentication because the default `GITHUB_TOKEN` is repository-scoped and cannot access the Projects GraphQL API for read or write operations. ## Why a separate token is needed [Section titled “Why a separate token is needed”](#why-a-separate-token-is-needed) The standard `GITHUB_TOKEN` provided to every GitHub Actions workflow has repository-level scope only. GitHub Projects (both user-owned and organization-owned) sit outside that scope, so any workflow step that reads project fields or writes updates must supply a token with explicit Projects permissions. This applies to: * [GitHub tools `projects` toolset](/gh-aw/reference/github-tools/#additional-authentication-for-github-tools) — reads project items and field values * [`update-project` safe output](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) — adds items and updates fields * [`create-project` safe output](/gh-aw/reference/safe-outputs/#project-creation-create-project) — creates new project boards * [`create-project-status-update` safe output](/gh-aw/reference/safe-outputs/#project-status-updates-create-project-status-update) — posts status updates ## Personal Access Tokens [Section titled “Personal Access Tokens”](#personal-access-tokens) ### User-owned projects [Section titled “User-owned projects”](#user-owned-projects) Use a [classic PAT](https://github.com/settings/tokens/new) with the following scopes: * `project` * `repo` (required if the project contains items from private repositories) ### Organization-owned projects [Section titled “Organization-owned projects”](#organization-owned-projects) Use a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new?name=GH_AW_WRITE_PROJECT_TOKEN\&description=GitHub+Agentic+Workflows+-+Projects+authentication\&contents=read\&issues=read\&pull_requests=read) with these settings: * **Resource owner**: the organization that owns the project * **Repository access**: the repositories that will run the workflow * **Repository permissions**: `Contents: Read`, and optionally `Issues: Read` / `Pull requests: Read` * **Organization permissions**: `Projects: Read and write` ## GitHub App tokens [Section titled “GitHub App tokens”](#github-app-tokens) For organization-wide standardization, a GitHub App can be used instead of PATs. The app must have **Organization projects: Read and write** permission. See [Using a GitHub App for Authentication](/gh-aw/reference/auth/#using-a-github-app-for-authentication) for setup instructions. ## Recommended secret layout [Section titled “Recommended secret layout”](#recommended-secret-layout) Use separate read and write tokens to enforce least privilege: ```bash gh aw secrets set GH_AW_READ_PROJECT_TOKEN --value "" gh aw secrets set GH_AW_WRITE_PROJECT_TOKEN --value "" ``` Reference each token in the workflow where it is needed: ```aw tools: github: mode: remote toolsets: [projects] github-token: ${{ secrets.GH_AW_READ_PROJECT_TOKEN }} safe-outputs: update-project: project-url: https://github.com/orgs/my-org/projects/1 github-token: ${{ secrets.GH_AW_WRITE_PROJECT_TOKEN }} ``` The magic secret `GH_AW_GITHUB_MCP_SERVER_TOKEN` is recognized by GitHub Agentic Workflows and does not need to be explicitly referenced in your workflow — if it is present in the repository, it is used automatically for all GitHub tools toolsets, including `projects`. ## Related documentation [Section titled “Related documentation”](#related-documentation) * [Authentication](/gh-aw/reference/auth/) — AI engine secrets and GitHub App setup * [GitHub Tools](/gh-aw/reference/github-tools/) — toolset configuration and additional authentication * [Safe Outputs](/gh-aw/reference/safe-outputs/) — write operations and token configuration * [ProjectOps pattern](/gh-aw/patterns/project-ops/) — end-to-end example with project boards # Package Manifest (aw.yml) > Reference for the aw.yml package manifest used by gh aw add and gh aw compile. Use `aw.yml` to describe an installable agentic workflow package. `gh aw add` uses this manifest when installing packages, and `gh aw compile` validates repository-root manifests before compilation. For the normative file-format definition, see the [Package Management (Spec)](/gh-aw/reference/repository-package-manifest-specification/). ## Package reference formats [Section titled “Package reference formats”](#package-reference-formats) Repository references support two forms: * `OWNER/REPO` * `OWNER/REPO/PATH/TO/PACKAGE` The package root is the folder that contains `aw.yml`. ## Fields [Section titled “Fields”](#fields) | Field | Type | Required | Notes | | ------------------ | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `manifest-version` | string | No | Current supported value: `"1"`. Defaults to `"1"` when omitted. | | `min-version` | string | No | Minimum compatible `gh aw` version in `vMAJOR.minor.patch` form, such as `v0.38.0`. | | `name` | string | Yes | Human-readable package name. Must be non-empty after trimming whitespace. | | `emoji` | string | No | Optional package emoji for display in package metadata. | | `description` | string | No | Optional package description. `gh aw add` warns when it exceeds 255 characters. | | `files` | array of strings | No | Package-root-relative paths. Agentic markdown workflows under `workflows/` or `.github/workflows/`; raw GitHub Actions YAML (`.yml`) is also accepted as direct children of `.github/workflows/`. | ## Installable workflows [Section titled “Installable workflows”](#installable-workflows) If `files` is present, valid entries become the install bundle. Two entry kinds are supported: * **Agentic workflow markdown** — paths ending in `.md` under `workflows/` or `.github/workflows/`. `gh aw add` compiles these to lock files and fetches their dependencies. * **Raw GitHub Actions YAML** — paths ending in `.yml` (but not `.lock.yml`) that are direct children of `.github/workflows/`. `gh aw add` copies these verbatim to `.github/workflows/.yml` with no frontmatter processing, no dependency fetch, and no compilation. Nested subdirectories under `.github/workflows/` and `.yml` files under `workflows/` are not accepted. If `files` is omitted, or no valid entries remain after filtering, `gh aw add` discovers installable markdown files under: * `workflows/` * `.github/workflows/` If no installable workflow files are resolved, validation fails. ## Package documentation [Section titled “Package documentation”](#package-documentation) Package documentation must be `README.md` at the package root. The manifest does not support a `docs` field. Missing `README.md` causes package validation to fail. ## Example [Section titled “Example”](#example) ```yaml manifest-version: "1" min-version: v0.38.0 name: Repo Assist emoji: description: Friendly repository automation for review and issue triage files: - workflows/review.md # agentic workflow — compiled on install - .github/workflows/nightly-review.md - .github/workflows/ci.yml # raw Actions YAML — copied verbatim ``` # Cache Memory > Guide to using cache-memory for persistent file storage across workflow runs with GitHub Actions cache. Cache memory provides persistent file storage across workflow runs via GitHub Actions cache with 7-day retention. The compiler automatically configures the cache directory, restore/save operations, and progressive fallback keys at `/tmp/gh-aw/cache-memory/` (default) or `/tmp/gh-aw/cache-memory-{id}/` (additional caches). ## Enabling Cache Memory [Section titled “Enabling Cache Memory”](#enabling-cache-memory) ```aw --- tools: cache-memory: true --- ``` Stores files at `/tmp/gh-aw/cache-memory/` using a workflow-scoped cache key. Use standard file operations to store/retrieve JSON/YAML, text files, or subdirectories. ## Advanced Configuration [Section titled “Advanced Configuration”](#advanced-configuration) ```aw --- tools: cache-memory: key: custom-memory-${{ github.repository_owner }} retention-days: 30 # 1-90 days, extends access beyond cache expiration allowed-extensions: [".json", ".txt", ".md"] # Restrict file types (default: empty/all files allowed) --- ``` Note Do not include `${{ github.run_id }}` in a user-supplied key — the compiler appends it automatically to the save key and generates stable restore-keys from the prefix. ### File Type Restrictions [Section titled “File Type Restrictions”](#file-type-restrictions) The `allowed-extensions` field restricts which file types can be written to cache-memory. By default, all file types are allowed (empty array). When specified, only files with listed extensions can be stored. ```aw --- tools: cache-memory: allowed-extensions: [".json", ".jsonl", ".txt"] # Only these extensions allowed --- ``` If files with disallowed extensions are found, the workflow will report validation failures. ## Multiple Configurations [Section titled “Multiple Configurations”](#multiple-configurations) ```aw --- tools: cache-memory: - id: default key: memory-default - id: session key: memory-session-${{ github.run_id }} - id: logs retention-days: 7 --- ``` Mounts at `/tmp/gh-aw/cache-memory/` (default) or `/tmp/gh-aw/cache-memory-{id}/`. The `id` determines the folder name; `key` defaults to a workflow-scoped prefix derived from the sanitized workflow name. ## Merging from Shared Workflows [Section titled “Merging from Shared Workflows”](#merging-from-shared-workflows) ```aw --- imports: - shared/mcp/server-memory.md tools: cache-memory: true --- ``` Merge rules: **Single→Single** (local overrides), **Single→Multiple** (local converts to array), **Multiple→Multiple** (merge by `id`, local wins). ## Behavior [Section titled “Behavior”](#behavior) GitHub Actions cache: 7-day retention, 10GB per repo, LRU eviction. Add `retention-days` to upload artifacts (1-90 days) for extended access. Caches are accessible across branches with unique per-run save keys. The compiler automatically generates a restore-keys prefix by stripping `${{ github.run_id }}` from the save key, so each run can fall back to the previous run’s cache. For `scope: repo`, an additional restore key without the workflow ID is added to allow cross-workflow cache sharing. Custom user-supplied keys auto-append `-${{ github.run_id }}` if not already present. ## Best Practices [Section titled “Best Practices”](#best-practices) Use descriptive file/directory names, hierarchical cache keys (`project-${{ github.repository_owner }}-${{ github.workflow }}`), and appropriate scope (workflow-specific default or repository/user-wide). Monitor growth within 10GB limit. ## Comparison with Repo Memory [Section titled “Comparison with Repo Memory”](#comparison-with-repo-memory) | Feature | Cache Memory | Repo Memory | | --------------- | -------------------- | ----------------- | | Storage | GitHub Actions Cache | Git Branches | | Retention | 7 days | Unlimited | | Size Limit | 10GB/repo | Repository limits | | Version Control | No | Yes | | Performance | Fast | Slower | | Best For | Temporary/sessions | Long-term/history | For unlimited retention with version control, see [Repo Memory](/gh-aw/reference/repo-memory/). ## Automatic Cleanup [Section titled “Automatic Cleanup”](#automatic-cleanup) The [agentic maintenance](/gh-aw/reference/ephemerals/#cache-memory-cleanup) workflow automatically cleans up outdated cache-memory entries on a schedule. Caches are grouped by key prefix (everything before the run ID), and only the latest entry per group is kept. Older entries are deleted to prevent unbounded storage growth. You can also trigger cleanup manually from the GitHub Actions UI by running the `Agentic Maintenance` workflow with the `clean_cache_memories` operation. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) * **Files not persisting**: Check cache key consistency and logs for restore/save messages. * **File access issues**: Create subdirectories first, verify permissions, use absolute paths. * **Cache size issues**: Track growth, clear periodically, or use time-based keys for auto-expiration. * **Cache path misconfiguration**: When the agent calls `missing_data` with `reason: "cache_memory_miss"`, the conclusion handler automatically opens a failure issue flagging a likely cache path problem. Check that the agent prompt references the correct path (`/tmp/gh-aw/cache-memory/` by default, or `/tmp/gh-aw/cache-memory-{id}/` for named caches) and that the cache key is consistent across runs. ## Integrity-Aware Caching [Section titled “Integrity-Aware Caching”](#integrity-aware-caching) When a workflow uses `tools.github.min-integrity`, cache-memory automatically applies integrity-level isolation. Cache keys include the workflow’s integrity level and a hash of the guard policy so that changing any policy field forces a cache miss. The compiler generates git-backed branching steps around the agent. Before the agent runs, it checks out the matching integrity branch and merges down from all higher-integrity branches (higher integrity always wins conflicts). After the agent runs, changes are committed to that branch. The agent itself sees only plain files — the `.git/` directory rides along transparently in the Actions cache tarball. ### Merge semantics [Section titled “Merge semantics”](#merge-semantics) | Run integrity | Sees data written by | Cannot see | | ------------- | ------------------------------------ | -------------------------------- | | `merged` | `merged` only | `approved`, `unapproved`, `none` | | `approved` | `approved` + `merged` | `unapproved`, `none` | | `unapproved` | `unapproved` + `approved` + `merged` | `none` | | `none` | all levels | — | This prevents a lower-integrity agent from poisoning data that a higher-integrity run would later read. Note Existing caches will get a cache miss on first run after upgrading to a version that includes this feature — intentional, as legacy data has no integrity provenance. ## Security [Section titled “Security”](#security) Don’t store sensitive data in cache memory. Cache memory follows repository permissions. Logs access. With [threat detection](/gh-aw/reference/threat-detection/), cache saves only after validation succeeds (restore→modify→upload artifact→validate→save). ## Examples [Section titled “Examples”](#examples) See [Grumpy Code Reviewer](https://github.com/github/gh-aw/blob/main/.github/workflows/grumpy-reviewer.md) for tracking PR review history. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Repo Memory](/gh-aw/reference/repo-memory/) - Git branch-based persistent storage with unlimited retention * [Frontmatter](/gh-aw/reference/frontmatter/) - Complete frontmatter configuration guide * [Safe Outputs](/gh-aw/reference/safe-outputs/) - Output processing and automation * [GitHub Actions Cache Documentation](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) - Official GitHub cache documentation # GitHub Repository Checkout > Configure how actions/checkout is invoked in the agent job — disable checkout, override settings, check out multiple repositories, fetch additional refs, and mark a primary target repository. The `checkout:` frontmatter field controls how `actions/checkout` is invoked in the agent job. Configure custom checkout settings, check out multiple repositories, or disable checkout entirely. By default, the agent checks out the repository where the workflow is running with a shallow fetch (`fetch-depth: 1`). If triggered by a pull request event, it also checks out the PR head ref. For most workflows, this default checkout is sufficient and no `checkout:` configuration is necessary. Use `checkout:` when you need to check out additional branches, check out multiple repositories, or to disable checkout entirely for workflows that don’t need to access code or can access code dynamically through the GitHub Tools. ## Custom Checkout Settings [Section titled “Custom Checkout Settings”](#custom-checkout-settings) You can use `checkout:` to override default checkout settings (e.g., fetch depth, sparse checkout) without needing to define a custom job: ```yaml checkout: fetch-depth: 0 # Full git history github-token: ${{ secrets.MY_TOKEN }} # Custom authentication ``` Or use GitHub App authentication: ```yaml checkout: fetch-depth: 0 github-app: client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} ``` You can also use `checkout:` to check out additional repositories alongside the main repository: ```yaml checkout: - fetch-depth: 0 - repository: owner/other-repo path: ./libs/other ref: main github-token: ${{ secrets.CROSS_REPO_PAT }} ``` ## Configuration Options [Section titled “Configuration Options”](#configuration-options) | Field | Type | Description | | ----------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `repository` | string | Repository in `owner/repo` format. Defaults to the current repository. | | `ref` | string | Branch, tag, or SHA to checkout. Defaults to the triggering ref. | | `path` | string | Path within `GITHUB_WORKSPACE` to place the checkout. Defaults to workspace root. | | `github-token` | string | Token for authentication. Use `${{ secrets.MY_TOKEN }}` syntax. | | `github-app` | object | GitHub App credentials (`client-id` or `app-id` (deprecated), `private-key`, optional `owner`, `repositories`). Mutually exclusive with `github-token`. `app` is a deprecated alias for the field name. Run `gh aw fix` to auto-migrate `app-id` to `client-id`. | | `fetch-depth` | integer | Commits to fetch. `0` = full history, `1` = shallow clone (default). | | `fetch` | string \| string\[] | Additional Git refs to fetch after checkout. See [Fetching Additional Refs](#fetching-additional-refs). | | `sparse-checkout` | string | Newline-separated patterns for sparse checkout (e.g., `.github/\nsrc/`). | | `submodules` | string/bool | Submodule handling: `"recursive"`, `"true"`, or `"false"`. | | `lfs` | boolean | Download Git LFS objects. | | `current` | boolean | Marks this checkout as the primary working repository. The agent uses this as the default target for all GitHub operations. Only one checkout may set `current: true`; the compiler rejects workflows where multiple checkouts enable it. | | `force-clean-git-credentials` | boolean | When `true`, the checkout step is generated with `persist-credentials: true` and followed by a dedicated cleanup step that scrubs both repo and submodule git credentials. Use this for submodule-heavy or sparse checkouts where the default `persist-credentials: false` post-step cleanup fails. See [Cleaning Submodule Credentials](#cleaning-submodule-credentials). | ## Fetching Additional Refs [Section titled “Fetching Additional Refs”](#fetching-additional-refs) By default, `actions/checkout` performs a shallow clone (`fetch-depth: 1`) of a single ref. For workflows that need to work with other branches — for example, a scheduled workflow that must push changes to open pull-request branches — use the `fetch:` option to retrieve additional refs after the checkout step. A dedicated git fetch step is emitted after the `actions/checkout` step. Authentication re-uses the checkout token (or falls back to `github.token`) via a transient `http.extraheader` credential — no credentials are persisted to disk, consistent with the enforced `persist-credentials: false` policy. | Value | Description | | --------------------- | -------------------------------------------------- | | `"*"` | All remote branches. | | `"refs/pulls/open/*"` | All open pull-request head refs (GH-AW shorthand). | | `"main"` | A specific branch name. | | `"feature/*"` | A glob pattern matching branch names. | ```yaml checkout: - fetch: ["*"] # fetch all branches (default checkout) fetch-depth: 0 # fetch full history to ensure we can see all commits and PR details ``` ```yaml checkout: - repository: githubnext/gh-aw-side-repo github-token: ${{ secrets.GH_AW_SIDE_REPO_PAT }} fetch: ["refs/pulls/open/*"] # fetch all open PR refs after checkout fetch-depth: 0 # fetch full history to ensure we can see all commits and PR details ``` ```yaml checkout: - repository: org/target-repo github-token: ${{ secrets.CROSS_REPO_PAT }} fetch: ["main", "feature/*"] # fetch specific branches fetch-depth: 0 # fetch full history to ensure we can see all commits and PR details ``` Note If a branch you need is not available after checkout and is not covered by a `fetch:` pattern, and you’re in a private or internal repo, then the agent cannot access its Git history except inefficiently, file by file, via the GitHub MCP. For private repositories, it will be unable to fetch or explore additional branches. If the branch is required and unavailable, configure the appropriate pattern in `fetch:` (e.g., `fetch: ["*"]` for all branches, or `fetch: ["refs/pulls/open/*"]` for PR branches) and recompile the workflow. ## Disabling Checkout (`checkout: false`) [Section titled “Disabling Checkout (checkout: false)”](#disabling-checkout-checkout-false) Set `checkout: false` to suppress the default `actions/checkout` step entirely. Use this for workflows that access repositories through MCP servers or other mechanisms that do not require a local clone: ```yaml checkout: false ``` This is equivalent to omitting the checkout step from the agent job. Custom dev-mode steps (such as “Checkout actions folder”) are unaffected. ## Marking a Primary Repository (`current: true`) [Section titled “Marking a Primary Repository (current: true)”](#marking-a-primary-repository-current-true) When a workflow running from a central repository targets a different repository, use `current: true` to tell the agent which repository to treat as its primary working target. The agent uses this as the default for all GitHub operations (creating issues, opening PRs, reading content) unless the prompt instructs otherwise. When omitted, the agent defaults to the repository where the workflow is running. ```yaml checkout: - repository: org/target-repo path: ./target github-token: ${{ secrets.CROSS_REPO_PAT }} current: true # agent's primary target ``` Caution `current: true` only annotates the agent’s system prompt to identify the target repository — it does **not** automatically change the working directory. If the agent needs to run local tools (tests, linters, build scripts) against the checked-out repository, add an explicit `cd` instruction to the prompt: ```plaintext Navigate into the folder where the target repository has been checked out into: cd ${{ github.workspace }}/target ``` Without this instruction, the agent starts in `$GITHUB_WORKSPACE` (the side repository checkout) and must infer the correct directory on its own. ## Cleaning Submodule Credentials [Section titled “Cleaning Submodule Credentials”](#cleaning-submodule-credentials) By default, generated checkout steps set `persist-credentials: false`, which causes `actions/checkout` to remove credentials in its post-step. In repositories with submodules or sparse checkouts, that post-step can fail with missing submodule URL or path errors. Set `force-clean-git-credentials: true` on a checkout target to opt into an explicit cleanup step instead. The compiler emits the checkout with `persist-credentials: true`, then injects a `Clean git credentials after checkout` step immediately after it. The cleanup removes the credential helper and `http.*.extraheader` entries from both `.git/config` and any `.git/modules/*/config`, including nested submodules. ```yaml checkout: - repository: org/monorepo-with-submodules submodules: recursive force-clean-git-credentials: true ``` ## Checkout Merging [Section titled “Checkout Merging”](#checkout-merging) Multiple `checkout:` configurations can target the same path and repository. This is useful for monorepos where different parts of the repository must be merged into the same workspace directory with different settings (e.g., sparse checkout for some paths, full checkout for others). When multiple `checkout:` entries target the same repository and path, their configurations are merged with the following rules: * **Fetch depth**: Deepest value wins (`0` = full history always takes precedence) * **Fetch refs**: Merged (union of all patterns; duplicates are removed) * **Sparse patterns**: Merged (union of all patterns) * **LFS**: OR-ed (if any config enables `lfs`, the merged configuration enables it) * **Submodules**: First non-empty value wins for each `(repository, path)`; once set, later values are ignored * **Ref/Token/App**: First-seen wins ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Cross-Repository Operations](/gh-aw/reference/cross-repository/) - Reading and writing across multiple repositories * [Authentication Reference](/gh-aw/reference/auth/) - PAT and GitHub App setup * [Multi-Repository Examples](/gh-aw/examples/multi-repo/) - Complete working examples # Command Triggers > Learn about slash command triggers and context text functionality for agentic workflows, including special @mention triggers for interactive automation. GitHub Agentic Workflows add the convenience `slash_command:` trigger to create workflows that respond to `/my-bots` in issues and comments. ```yaml on: slash_command: name: my-bot # Optional: defaults to filename without .md extension ``` You can also use shorthand formats: ```yaml on: slash_command: "my-bot" # Shorthand: string directly specifies command name ``` ```yaml on: /my-bot # Ultra-short: slash prefix automatically expands to slash_command + workflow_dispatch ``` ## Multiple Command Identifiers [Section titled “Multiple Command Identifiers”](#multiple-command-identifiers) A single workflow can respond to multiple slash command names by providing an array of command identifiers: ```yaml on: slash_command: name: ["cmd.add", "cmd.remove", "cmd.list"] ``` When triggered, the matched command is available as `needs.activation.outputs.slash_command`, allowing your workflow to determine which command was used: ```aw --- on: slash_command: name: ["summarize", "summary", "tldr"] --- # Multi-Command Handler You invoked the workflow using: `/${{ needs.activation.outputs.slash_command }}` Now analyzing the content... ``` This feature enables command aliases and grouped command handlers without workflow duplication. This automatically creates issue/PR triggers (`opened`, `edited`, `reopened`), comment triggers (`created`, `edited`), and conditional execution matching `/command-name` mentions. **Code availability:** When a command is triggered from a pull request body, PR comment, or PR review comment, the coding agent has access to both the PR branch and the default branch. The command must be the **first word** of the comment or body text to trigger the workflow. This prevents accidental triggers when the command is mentioned elsewhere in the content. You can combine `slash_command:` with other events like `workflow_dispatch` or `schedule`: ```yaml on: slash_command: name: my-bot workflow_dispatch: schedule: weekly on monday ``` ### Centralized trigger strategy [Section titled “Centralized trigger strategy”](#centralized-trigger-strategy) Set `on.slash_command.strategy: centralized` to opt a workflow into centralized slash-command routing. When enabled, the workflow compiles as `workflow_dispatch`-centric, and the compiler generates one shared `agentic_commands.yml` workflow that listens to merged slash-command events and dispatches matching target workflows with `aw_context`. ```yaml on: slash_command: name: my-bot strategy: centralized ``` **Note**: With default inline strategy, you cannot combine `slash_command` with `issues`, `issue_comment`, or `pull_request` as they would conflict. With `strategy: centralized`, non-slash events are preserved because slash matching is handled in the generated central trigger workflow. **Exception for Label-Only Events**: You CAN combine `slash_command` with `issues` or `pull_request` if those events are configured for label-only triggers (`labeled` or `unlabeled` types only). This allows workflows to respond to slash commands while also reacting to label changes. ### Combining `slash_command` with `bots:` [Section titled “Combining slash\_command with bots:”](#combining-slash_command-with-bots) Concurrency clash Combining `slash_command` with `on.bots:` produces a compile-time warning. When a bot listed in `bots:` posts a comment that begins with the slash command text (e.g., `/command-name`), the command check passes and the bot triggers the workflow — occupying the concurrency slot and potentially blocking a simultaneous manual invocation, since `cancel-in-progress` is disabled for command-trigger workflows. To ensure the workflow only runs on explicit user commands, remove the `bots:` field. ```yaml # This configuration produces a compile-time warning: on: slash_command: name: rust-review events: [pull_request, pull_request_comment] bots: - "copilot[bot]" ``` ```yaml on: slash_command: deploy issues: types: [labeled, unlabeled] # Valid: label-only triggers don't conflict ``` This pattern is useful when you want a workflow that can be triggered both manually via commands and automatically when labels change. ## Filtering Command Events [Section titled “Filtering Command Events”](#filtering-command-events) By default, command triggers listen to all comment-related events, which can create skipped runs in the Actions UI. Use the `events:` field to restrict where commands are active: ```yaml on: slash_command: name: my-bot events: [issues, issue_comment] # Only in issue bodies and issue comments ``` **Supported events:** `issues`, `issue_comment`, `pull_request`, `pull_request_comment`, `pull_request_review_comment`, `discussion`, `discussion_comment`, or `*` (all, default). Note Both `issue_comment` and `pull_request_comment` map to GitHub Actions’ `issue_comment` event with automatic filtering to distinguish between issue and PR comments. ### Example command workflow [Section titled “Example command workflow”](#example-command-workflow) Issue-only command (avoids skipped runs from PR events): ```yaml on: slash_command: name: investigate events: [issues, issue_comment] ``` PR-only command: ```yaml on: slash_command: name: code-review events: [pull_request, pull_request_comment] ``` ## Context Text [Section titled “Context Text”](#context-text) All workflows access `steps.sanitized.outputs.text`, which provides **sanitized** context: for issues and PRs, it’s `title + "\n\n" + body`; for comments and reviews, it’s the body content. ```aw # Analyze this content: "${{ steps.sanitized.outputs.text }}" ``` **Why sanitized context?** The sanitized text neutralizes @mentions and bot triggers (like `fixes #123`), protects against XML injection, filters URIs to trusted HTTPS domains, limits content size (0.5MB max, 65k lines), and strips ANSI escape sequences. **Comparison:** ```aw # RECOMMENDED: Secure sanitized context Analyze this issue: "${{ steps.sanitized.outputs.text }}" # DISCOURAGED: Raw context values (security risks) Title: "${{ github.event.issue.title }}" Body: "${{ github.event.issue.body }}" ``` ## Reactions and Status Comments [Section titled “Reactions and Status Comments”](#reactions-and-status-comments) Command workflows enable `reaction: eyes` () and `status-comment: true` by default. The reaction adds a visual indicator to triggering comments; the status comment posts a started/completed notification with a workflow run link. Customize or disable either: ```yaml on: slash_command: name: my-bot reaction: "rocket" # Override default "eyes" status-comment: false # Disable the status comment ``` To disable the reaction entirely, use `reaction: none`. See [Reactions and Status Comments](/gh-aw/reference/triggers/#reactions-reaction) for all available reactions and detailed behavior. ## Slash Commands from a Side Repository [Section titled “Slash Commands from a Side Repository”](#slash-commands-from-a-side-repository) GitHub Actions only delivers events to the repository where they occur. When workflows live in a separate side repository, events from the main repository are never delivered there. **Slash command triggers cannot be used directly in a workflow hosted in a side repository.** The recommended solution is a **bridge pattern**: a thin relay workflow in the main repository receives the slash command and forwards it to the side repository via `workflow_dispatch`. See [Triage from Side Repo](/gh-aw/examples/multi-repo/triage-from-side-repo/) for a full walkthrough with examples and trade-offs. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Frontmatter](/gh-aw/reference/frontmatter/) - All configuration options for workflows * [Workflow Structure](/gh-aw/reference/workflow-structure/) - Directory layout and organization * [CLI Commands](/gh-aw/setup/cli/) - CLI commands for workflow management * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) — Running workflows from a separate repository * [ChatOps](/gh-aw/patterns/chat-ops/) - Interactive automation with slash commands # Compilation Process > Advanced technical documentation on how GitHub Agentic Workflows compiles markdown files into GitHub Actions YAML, including job orchestration, action pinning, artifacts, and MCP integration. This guide documents the internal compilation process that transforms markdown workflow files into executable GitHub Actions YAML. Understanding this process helps when debugging workflows, optimizing performance, or contributing to the project. ## Overview [Section titled “Overview”](#overview) The `gh aw compile` command transforms a markdown workflow file into a complete GitHub Actions `.lock.yml` by embedding frontmatter and setting up runtime loading of the markdown body. The process runs five compilation phases (parsing, validation, job construction, dependency resolution, and YAML generation) described below. When the workflow runs, the markdown body is loaded at runtime — you can edit instructions without recompilation. See [Editing Workflows](/gh-aw/guides/editing-workflows/) for details. ## Compilation Phases [Section titled “Compilation Phases”](#compilation-phases) ### Phase 1: Parsing and Validation [Section titled “Phase 1: Parsing and Validation”](#phase-1-parsing-and-validation) The compiler extracts the YAML frontmatter, validates it against the workflow schema, validates expression safety (only allow-listed GitHub Actions expressions), and resolves imports. #### Import Resolution [Section titled “Import Resolution”](#import-resolution) Imports are resolved with a deterministic breadth-first traversal: starting from `imports:` in the main workflow, each file is loaded, its configurations are extracted, and any nested imports are appended to the queue. Visited files are tracked to detect cycles. | Field | Merge strategy | | ------------ | ------------------------------------------------------------------ | | Tools | Deep merge; arrays concatenated and deduplicated | | MCP servers | Imported servers override main-workflow servers with the same name | | Network | Union of allowed domains, deduplicated and sorted | | Permissions | Validation only — main must satisfy imported requirements | | Safe outputs | Main workflow overrides imported configurations per type | | Runtimes | Main workflow versions override imported versions | Processing order follows BFS: ```plaintext Main Workflow ├── import-a.md → Processed 1st │ ├── nested-1.md → Processed 3rd (after import-b) │ └── nested-2.md → Processed 4th └── import-b.md → Processed 2nd └── nested-3.md → Processed 5th ``` See [Imports Reference](/gh-aw/reference/imports/) for complete merge semantics. ### Phases 2–5: Building the Workflow [Section titled “Phases 2–5: Building the Workflow”](#phases-25-building-the-workflow) | Phase | Steps | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **2 Job Construction** | Builds specialized jobs: pre-activation (if needed), activation, agent, safe outputs, safe-jobs, and custom jobs | | **3 Dependency Resolution** | Validates job dependencies, detects circular references, computes topological order, generates Mermaid graph | | **4 Action Pinning** | Pins all actions to SHAs: check cache → GitHub API → embedded pins → add version comment (e.g., `actions/checkout@sha # v6`) | | **5 YAML Generation** | Assembles final `.lock.yml`: header with metadata, Mermaid dependency graph, alphabetical jobs, embedded original prompt | ## Job Types [Section titled “Job Types”](#job-types) The compilation process generates specialized jobs based on workflow configuration: | Job | Trigger | Purpose | Key Dependencies | | -------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------- | | **pre\_activation** | Role checks, stop-after deadlines, skip-if-match, or command triggers | Validates permissions, deadlines, and conditions before AI execution | None (runs first) | | **activation** | Always | Prepares workflow context, sanitizes event text, validates lock file freshness | `pre_activation` (if exists) | | **agent** | Always | Core job that executes AI agent with configured engine, tools, and Model Context Protocol (MCP) servers | `activation` | | **detection** | `safe-outputs.threat-detection:` configured | Scans agent output for security threats before processing | `agent` | | **Safe output jobs** | Corresponding `safe-outputs.*:` configured | Process agent output to perform GitHub API operations (create issues/PRs, add comments, upload assets, etc.) | `agent`, `detection` (if exists) | | **conclusion** | Always (if safe outputs exist) | Aggregates results and generates workflow summary | All safe output jobs | ### Agent Job Steps [Section titled “Agent Job Steps”](#agent-job-steps) The agent job runs: repository checkout and runtime setup (Node.js, Python, Go) → cache restoration → MCP container initialization → prompt generation from the markdown body → engine execution (Copilot, Claude, or Codex) → output upload as a GitHub Actions artifact → cache persistence. Key environment variables: `GH_AW_PROMPT` (prompt file), `GH_AW_SAFE_OUTPUTS` (output JSON), `GITHUB_TOKEN`. ### Safe Output Jobs [Section titled “Safe Output Jobs”](#safe-output-jobs) Every safe output job follows the same pattern: download the agent artifact, parse its JSON, execute the corresponding GitHub API operation with the right permissions, and link to related items. Available types include `create_issue`, `create_discussion`, `add_comment`, `create_pull_request`, `create_pr_review_comment`, `create_code_scanning_alert`, `add_labels`, `assign_milestone`, `update_issue`, `update_release`, `push_to_pr_branch`, `upload_assets`, `update_project`, `missing_tool`, and `noop`. ### Custom Jobs [Section titled “Custom Jobs”](#custom-jobs) Use `safe-outputs.jobs:` for custom jobs with full GitHub Actions syntax, or `jobs:` for additional workflow jobs with user-defined dependencies. See [DeterministicOps](/gh-aw/patterns/deterministic-ops/) for examples of multi-stage workflows combining deterministic computation with AI reasoning. ## Job Dependency Graphs [Section titled “Job Dependency Graphs”](#job-dependency-graphs) Jobs execute in topological order based on dependencies. Here’s a comprehensive example: ``` graph LR pre_activation["pre_activation"] activation["activation"] agent["agent"] detection["detection"] create_issue["create_issue"] add_comment["add_comment"] conclusion["conclusion"] pre_activation --> activation activation --> agent agent --> detection agent --> create_issue agent --> add_comment detection --> create_issue detection --> add_comment create_issue --> add_comment create_issue --> conclusion add_comment --> conclusion ``` **Execution flow**: Pre-activation validates permissions → Activation prepares context → Agent executes AI → Detection scans output → Safe outputs run in parallel → Add comment waits for created items → Conclusion summarizes results. Safe output jobs without cross-dependencies run concurrently; when threat detection is enabled, safe outputs depend on both agent and detection jobs. ## Why Detection, Safe Outputs, and Conclusion Are Separate Jobs [Section titled “Why Detection, Safe Outputs, and Conclusion Are Separate Jobs”](#why-detection-safe-outputs-and-conclusion-are-separate-jobs) A typical compiled workflow contains these post-agent jobs: ``` flowchart TD activation["activation
ubuntu-slim
contents: read"] --> agent["agent
ubuntu-latest
READ-ONLY permissions
concurrency group"] agent --> detection["detection
ubuntu-latest
contents: read
concurrency group
RUNS AI ENGINE"] agent --> conclusion["conclusion
ubuntu-slim
issues: write
pr: write"] detection --> safe_outputs["safe_outputs
ubuntu-slim
contents: write
issues: write
pr: write"] detection --> conclusion safe_outputs --> conclusion detection --> update_cache_memory["update_cache_memory
ubuntu-latest
contents: read"] update_cache_memory --> conclusion activation --> safe_outputs activation --> conclusion ``` These three jobs form a **sequential security pipeline** rooted in [Plan-Level Trust](/gh-aw/introduction/architecture/) — AI reasoning (read-only) is separated from write operations. They cannot be merged because GitHub Actions permissions are per-job and immutable for the duration of a job: | Job | Key Permissions | Rationale | | ----------------- | ------------------------------------------------------------- | --------------------------------------------- | | **detection** | `contents: read` | Runs AI analysis — must not have write access | | **safe\_outputs** | `contents: write`, `issues: write`, `pull-requests: write` | Executes GitHub API write operations | | **conclusion** | `issues: write`, `pull-requests: write`, `discussions: write` | Updates comments, handles failures | A combined job would hold write permissions while running threat detection, defeating least privilege and letting a compromised agent bypass the gate. Job-level isolation also enables: * **Hard gating.** The `safe_outputs` job condition `needs.detection.outputs.success == 'true'` prevents the runner from starting at all if detection fails. Step-level `if` checks within one job are weaker. * **`always()` semantics for `conclusion`.** It inspects upstream results via `needs.agent.result` to log errors and report missing tools even when writes fail. * **Right-sized runners.** Detection needs `ubuntu-latest` for AI execution; safe\_outputs and conclusion use the lightweight `ubuntu-slim`. * **Concurrency isolation.** Detection shares a concurrency group with the agent job to serialize AI execution; safe\_outputs intentionally does not, so it can run alongside other workflows’ detection phases. * **Artifact-based handoff.** The agent writes `agent_output.json`; detection emits `success`; safe\_outputs only downloads the artifact if approved. A shared filesystem in a single job would allow output tampering between phases. ## Action Pinning [Section titled “Action Pinning”](#action-pinning) All GitHub Actions are pinned to commit SHAs (e.g., `actions/checkout@b4ffde6...11 # v6`) to defend against supply chain attacks — tags can be moved, SHAs cannot. Resolution order is cache (`.github/aw/actions-lock.json`) → GitHub API → embedded pins. ### The actions-lock.json Cache [Section titled “The actions-lock.json Cache”](#the-actions-lockjson-cache) `.github/aw/actions-lock.json` caches resolved `action@version` → SHA mappings so compilation produces consistent results regardless of the available token. Resolving a tag to a SHA requires GitHub API access, which fails under restricted tokens — notably the GitHub Copilot Coding Agent (CCA) token. With the cache, CCA and similar restricted environments reuse SHAs from a prior compile run with a broader-scope token. **Commit `actions-lock.json` to version control** so every contributor and automated tool uses the same immutable pins. Refresh with `gh aw update-actions`, or delete and recompile with a permissive token to force full re-resolution. ## The gh-aw-actions Repository [Section titled “The gh-aw-actions Repository”](#the-gh-aw-actions-repository) `github/gh-aw-actions` contains the reusable actions that power compiled workflows. Every action step in a generated `.lock.yml` references it (usually by commit SHA, occasionally by a stable tag like `v0` when SHA resolution is unavailable): ```yaml uses: github/gh-aw-actions/setup@abc1234... ``` Never edit these references by hand — run `gh aw compile` or `gh aw update-actions` to regenerate them. Use `--actions-repo` (with `--action-mode action`) to compile against a fork or specific tag during development; see [Compilation Commands](#compilation-commands). ### Dependabot and gh-aw-actions [Section titled “Dependabot and gh-aw-actions”](#dependabot-and-gh-aw-actions) Dependabot may open PRs to bump `github/gh-aw-actions` to a newer SHA. **Do not merge them** — pin updates must come from `gh aw compile`, which coordinates pins across all compiled workflows from a single release. `gh aw compile` automatically inserts an ignore rule when a `github-actions` update block exists in `.github/dependabot.yml`. When enabling Dependabot from scratch, use: ```yaml updates: - package-ecosystem: github-actions directory: "/.github/workflows" ignore: - dependency-name: "github/gh-aw-actions/**" # Managed by gh aw compile. Version-locked to the gh-aw compiler; do not bump. ``` ## Artifacts Created [Section titled “Artifacts Created”](#artifacts-created) Workflows generate several artifacts during execution: | Artifact | Location | Purpose | Lifecycle | | --------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | | **agent\_output.json** | `/tmp/gh-aw/safeoutputs/` | AI agent output with structured safe output data (create\_issue, add\_comment, etc.) | Uploaded by agent job, downloaded by safe output jobs, auto-deleted after 90 days | | **agent\_usage.json** | `/tmp/gh-aw/` | Aggregated token counts: `{"input_tokens":…,"output_tokens":…,"cache_read_tokens":…,"cache_write_tokens":…}` | Bundled in the unified agent artifact when the firewall is enabled; accessible to third-party tools without parsing step summaries | | **prompt.txt** | `/tmp/gh-aw/aw-prompts/` | Generated prompt sent to AI agent (includes markdown instructions, imports, context variables) | Retained for debugging and reproduction | | **firewall-audit-logs** | See structure below | Dedicated artifact for AWF audit/observability logs (token usage, network policy, audit trail) | Uploaded by all firewall-enabled workflows; analyzed by `gh aw logs --artifacts firewall` | | **firewall-logs/** | `/tmp/gh-aw/sandbox/firewall/logs/` | Network access logs in Squid format (when `network.firewall:` enabled) | Analyzed by `gh aw logs` command | | **cache-memory/** | `/tmp/gh-aw/cache-memory/` | Persistent agent memory across runs (when `tools.cache-memory:` configured) | Restored at start, saved at end via GitHub Actions cache | | **patches/**, **sarif/**, **metadata/** | Various | Safe output data (git patches, SARIF files, metadata JSON) | Temporary, cleaned after processing | ### `firewall-audit-logs` Artifact Structure [Section titled “firewall-audit-logs Artifact Structure”](#firewall-audit-logs-artifact-structure) The `firewall-audit-logs` artifact is a dedicated multi-file artifact uploaded by all firewall-enabled workflows. It is **separate** from the unified `agent` artifact. Downstream workflows that need token usage data or firewall audit logs must download this artifact specifically. ```plaintext firewall-audit-logs/ ├── api-proxy-logs/ │ └── token-usage.jsonl ← Token usage data per request ├── squid-logs/ │ └── access.log ← Network policy log (allow/deny) ├── audit.jsonl ← Firewall audit trail └── policy-manifest.json ← Policy configuration snapshot ``` > **Tip:** Use `gh aw logs --artifacts firewall` to download and analyze firewall data instead of `gh run download` directly. The CLI handles artifact naming and backward compatibility automatically. See the [Artifacts reference](/gh-aw/reference/artifacts/) for the complete artifact naming guide. ## MCP Server Integration [Section titled “MCP Server Integration”](#mcp-server-integration) Model Context Protocol (MCP) servers provide tools to AI agents. Compilation emits `mcp-config.json` from the workflow’s tool configuration. Local servers run in Docker containers with auto-generated Dockerfiles and connect via stdio; HTTP servers connect directly with configured headers and authentication. `allowed:` restricts which tools the agent sees, and secrets inject through Dockerfile env vars (local) or config references (HTTP). At runtime, MCP containers start after runtime setup, the engine executes with tool access, then containers stop. ## Pre-Activation Job [Section titled “Pre-Activation Job”](#pre-activation-job) Pre-activation runs gating checks sequentially before any AI execution. Any failure sets `activated=false`, skipping downstream jobs and saving costs: * **Role checks** (`roles:`) — actor has admin/maintainer/write permission * **Stop-after** (`on.stop-after:`) — workflow has not passed its deadline (e.g., `+30d`, `2024-12-31`) * **Skip-if-match** (`skip-if-match:`) — no existing item matches the dedup criteria * **Command position** (`on.slash_command:`) — slash command appears in the first 3 lines ## Compilation Commands [Section titled “Compilation Commands”](#compilation-commands) | Command | Description | | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `gh aw compile` | Compile all workflows in `.github/workflows/` | | `gh aw compile my-workflow` | Compile specific workflow | | `gh aw compile --verbose` | Enable verbose output | | `gh aw compile --strict` | Enhanced security validation | | `gh aw compile --no-emit` | Validate without generating files | | `gh aw compile --actionlint --zizmor --poutine` | Run security scanners | | `gh aw compile --purge` | Remove orphaned `.lock.yml` files | | `gh aw compile --output /path/to/output` | Custom output directory | | `gh aw compile --action-mode action --actions-repo owner/repo` | Compile using a custom actions repository (requires `--action-mode action`) | | `gh aw compile --action-mode action --actions-repo owner/repo --action-tag branch-or-sha` | Compile against a specific branch or SHA in a fork | | `gh aw compile --action-tag v1.2.3` | Pin action references to a specific tag or SHA (implies release mode) | | `gh aw validate` | Validate all workflows (compile + all linters, no file output) | | `gh aw validate my-workflow` | Validate a specific workflow | | `gh aw validate --json` | Validate and output results in JSON format | | `gh aw validate --strict` | Validate with strict mode enforced | Tip Compilation is only required when changing **frontmatter configuration**. The **markdown body** (AI instructions) is loaded at runtime and can be edited without recompilation. See [Editing Workflows](/gh-aw/guides/editing-workflows/) for details. Note The `--actions-repo` flag overrides the default `github/gh-aw-actions` repository used when `--action-mode action` is set. Use it together with `--action-tag` to compile against a branch or fork during development. ## Debugging Compilation [Section titled “Debugging Compilation”](#debugging-compilation) Run `DEBUG=workflow:* gh aw compile my-workflow --verbose` to trace job creation, action pin resolution, tool configuration, and MCP setup. Inspect generated `.lock.yml` files for header comments, the Mermaid dependency graph, job structure, SHA pins, and MCP config. Common fixes: circular dependencies → review `needs:` clauses; missing action pin → add to `action_pins.json` or enable dynamic resolution; invalid MCP config → verify `command`, `args`, `env`. ## Performance [Section titled “Performance”](#performance) Simple workflows compile in \~100ms; workflows with imports in \~500ms; workflows that resolve action SHAs dynamically in \~2s. To keep compilation fast, commit `.github/aw/actions-lock.json` and minimize import depth. At runtime, safe output jobs without cross-dependencies run in parallel; enable `cache:` and `cache-memory:` for further speedups. ## Advanced Topics [Section titled “Advanced Topics”](#advanced-topics) * **Custom engines**: implement an engine that returns GitHub Actions steps and tool access, then register it with the framework. * **Schema extension**: add frontmatter fields by updating the workflow schema, rebuilding (`make build`), and wiring up parser handling. * **Workflow manifest**: imported files are tracked in lock file headers for update detection and audit trails. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Editing Workflows](/gh-aw/guides/editing-workflows/) - When to recompile vs edit directly * [Frontmatter Reference](/gh-aw/reference/frontmatter/) - All configuration options * [Tools Reference](/gh-aw/reference/tools/) - Tool configuration guide * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Output processing * [Engines Reference](/gh-aw/reference/engines/) - AI engine configuration * [Network Reference](/gh-aw/reference/network/) - Network permissions # Concurrency Control > Complete guide to concurrency control in GitHub Agentic Workflows, including agent job concurrency configuration and engine isolation. GitHub Agentic Workflows uses dual-level concurrency control to prevent resource exhaustion and ensure predictable execution: * **Per-workflow**: Limits based on workflow name and trigger context (issue, PR, branch) * **Per-engine**: Limits AI execution across all workflows via `engine.concurrency` ## Per-Workflow Concurrency [Section titled “Per-Workflow Concurrency”](#per-workflow-concurrency) Workflow-level concurrency groups include the workflow name plus context-specific identifiers: | Trigger Type | Concurrency Group | Cancel In Progress | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------- | | Issues | `gh-aw-${{ github.workflow }}-${{ issue.number }}` | No | | Pull Requests | `gh-aw-${{ github.workflow }}-${{ pr.number \|\| ref }}` | Yes (new commits cancel outdated runs) | | Push | `gh-aw-${{ github.workflow }}-${{ github.ref }}` | No | | Schedule/Other | `gh-aw-${{ github.workflow }}` | No | | Label-triggered (label trigger shorthand or label\_command) | `gh-aw-${{ github.workflow }}-${{ entity.number }}-${{ github.event.label.name }}` | Yes for PRs, No otherwise | This ensures workflows on different issues, PRs, or branches run concurrently without interference. ## Per-Engine Concurrency [Section titled “Per-Engine Concurrency”](#per-engine-concurrency) The default per-engine pattern `gh-aw-{engine-id}` ensures only one agent job runs per engine across all workflows, preventing AI resource exhaustion. The group includes only the engine ID and `gh-aw-` prefix — workflow name, issue/PR numbers, and branches are excluded. ```yaml jobs: agent: concurrency: group: "gh-aw-{engine-id}" ``` ## Custom Concurrency [Section titled “Custom Concurrency”](#custom-concurrency) Override either level independently: ```yaml --- on: push concurrency: # Workflow-level group: custom-group-${{ github.ref }} cancel-in-progress: true engine: id: copilot concurrency: # Engine-level group: "gh-aw-copilot-${{ github.workflow }}" tools: github: allowed: [list_issues] --- ``` ## Safe Outputs Job Concurrency [Section titled “Safe Outputs Job Concurrency”](#safe-outputs-job-concurrency) The `safe_outputs` job runs independently from the agent job and can process outputs concurrently across workflow runs. Use `safe-outputs.concurrency-group` to serialize access when needed: ```yaml safe-outputs: concurrency-group: "safe-outputs-${{ github.repository }}" create-issue: ``` When set, the `safe_outputs` job uses `cancel-in-progress: false` — meaning queued runs wait for the in-progress run to finish rather than being cancelled. This is useful for workflows that create issues or pull requests where duplicate operations would be undesirable. See [Safe Outputs](/gh-aw/reference/safe-outputs/#safe-outputs-job-concurrency-concurrency-group) for details. ## Queue Behavior (`queue`) [Section titled “Queue Behavior (queue)”](#queue-behavior-queue) GitHub Actions concurrency groups accept an optional `queue` field that controls how multiple pending runs in the same group are handled. The gh-aw compiler preserves this field in both top-level and per-engine concurrency blocks: | Value | Behavior | | -------------------------- | ------------------------------------------------------------------------ | | `single` (Actions default) | Only the latest pending run is kept; earlier pending runs are discarded. | | `max` | All pending runs queue and run in arrival order. | ```yaml concurrency: group: ${{ github.workflow }}-${{ github.ref }} queue: max ``` Compiler-generated concurrency groups (agent, output, and conclusion jobs) emit `queue: max` by default so back-to-back triggers run sequentially rather than being dropped. Set `features.group-concurrency-queue: false` to omit `queue` from generated groups and revert to the Actions default: ```yaml features: group-concurrency-queue: false ``` ## Conclusion Job Concurrency [Section titled “Conclusion Job Concurrency”](#conclusion-job-concurrency) The `conclusion` job — which handles reporting and post-agent cleanup — automatically receives a workflow-specific concurrency group derived from the workflow filename: ```yaml conclusion: concurrency: group: "gh-aw-conclusion-my-workflow" cancel-in-progress: false queue: max ``` This prevents conclusion jobs from colliding when multiple agents run the same workflow concurrently. The group uses `cancel-in-progress: false` so queued conclusion runs complete in order rather than being discarded, and `queue: max` preserves arrival order for queued runs (see [Queue Behavior](#queue-behavior-queue)). This concurrency group is set automatically during compilation and requires no manual configuration. When `concurrency.job-discriminator` is set, the discriminator is also appended to the conclusion job’s concurrency group, making each run’s group distinct: ```yaml concurrency: job-discriminator: ${{ github.event.issue.number || github.run_id }} ``` This generates a group like `gh-aw-conclusion-my-workflow-${{ github.event.issue.number || github.run_id }}`, preventing concurrent runs for different issues or inputs from competing for the same conclusion slot. ## Fan-Out Concurrency (`job-discriminator`) [Section titled “Fan-Out Concurrency (job-discriminator)”](#fan-out-concurrency-job-discriminator) When multiple workflow instances are dispatched concurrently with different inputs (fan-out pattern), compiler-generated job-level concurrency groups are static across all runs — causing all but the latest dispatched run to be cancelled as they compete for the same slot. Use `concurrency.job-discriminator` to append a unique expression to compiler-generated job-level concurrency groups (`agent`, `output`, and `conclusion` jobs), making each dispatched run’s group distinct: ```yaml concurrency: job-discriminator: ${{ inputs.finding_id }} ``` This generates a unique job-level concurrency group per dispatched run, preventing fan-out cancellations while preserving the per-workflow concurrency group at the workflow level. Common expressions: | Scenario | Expression | | ------------------------------------------ | ----------------------------------------------- | | Fan-out by a specific input | `${{ inputs.finding_id }}` | | Universal uniqueness (e.g. scheduled runs) | `${{ github.run_id }}` | | Dispatched or scheduled fallback | `${{ inputs.organization \|\| github.run_id }}` | Note `job-discriminator` is a gh-aw extension and is stripped from the compiled lock file. It does not appear in the generated GitHub Actions YAML. Note `job-discriminator` has no effect on workflows triggered by `workflow_dispatch`-only, `push`, or `pull_request` events, or when the engine provides an explicit job-level concurrency configuration. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Frontmatter](/gh-aw/reference/frontmatter/) - Complete frontmatter reference * [Safe Outputs](/gh-aw/reference/safe-outputs/) - Safe output processing and job configuration # Importing Copilot Agent Files > Import and reuse Copilot agent files with GitHub Agentic Workflows “Custom agents” is a term used in GitHub Copilot for specialized prompts for behaviors for specific tasks. They are markdown files stored in the `.github/agents/` directory and imported via the `imports` field. Copilot supports agent files natively, while other engines (Claude, Codex) inject the markdown body as a prompt. A typical custom agent file looks like this: .github/agents/my-agent.md ```markdown --- name: My Copilot Agent description: Specialized prompt for code review tasks --- # Agent Instructions You are a specialized code review agent. Focus on: - Code quality and best practices - Security vulnerabilities - Performance optimization ``` ## Using Copilot Agent Files from Agentic Workflows [Section titled “Using Copilot Agent Files from Agentic Workflows”](#using-copilot-agent-files-from-agentic-workflows) Import Copilot agent files in your workflow using the `imports` field. Agent files can be imported from local `.github/agents/` directories or from external repositories. ### Local Agent File Import [Section titled “Local Agent File Import”](#local-agent-file-import) Import an agent from your repository: ```yaml --- on: pull_request engine: copilot imports: - .github/agents/my-agent.md --- Review the pull request and provide feedback. ``` ### Remote Agent File Import [Section titled “Remote Agent File Import”](#remote-agent-file-import) Import an agent file from an external repository using the `owner/repo/path@ref` format: ```yaml --- on: pull_request engine: copilot imports: - acme-org/shared-agents/.github/agents/code-reviewer.md@v1.0.0 --- Perform comprehensive code review using shared agent instructions. ``` The agent instructions are merged with the workflow prompt, customizing the AI engine’s behavior for specific tasks. ## Agent File Requirements [Section titled “Agent File Requirements”](#agent-file-requirements) * **Location**: Must be in a `.github/agents/` directory (local or remote repository) * **Format**: Markdown with YAML frontmatter * **Frontmatter**: Can include `name`, `description`, `tools`, and `mcp-servers` * **One per workflow**: Only one agent file can be imported per workflow * **Caching**: Remote agent files are cached by commit SHA in `.github/aw/imports/` ## Copilot Agent File Collections [Section titled “Copilot Agent File Collections”](#copilot-agent-file-collections) Organizations can create libraries of specialized custom agent files: ```text acme-org/ai-agents/ └── .github/ └── agents/ ├── code-reviewer.md # General code review ├── security-auditor.md # Security-focused analysis ├── performance-analyst.md # Performance optimization ├── accessibility-checker.md # WCAG compliance └── documentation-writer.md # Technical documentation ``` Teams import agent files based on workflow needs: Security-focused PR review ```yaml --- on: pull_request engine: copilot imports: - acme-org/ai-agents/.github/agents/security-auditor.md@v2.0.0 - acme-org/ai-agents/.github/agents/code-reviewer.md@v1.5.0 --- # Security Review Perform comprehensive security review of this pull request. ``` ## Combining Copilot Agent Files with Other Imports [Section titled “Combining Copilot Agent Files with Other Imports”](#combining-copilot-agent-files-with-other-imports) You can mix custom agent file imports with tool configurations and shared components: ```yaml --- on: pull_request engine: copilot imports: # Import specialized custom agent file - acme-org/ai-agents/.github/agents/security-auditor.md@v2.0.0 # Import tool configurations - acme-org/workflow-library/shared/tools/github-standard.md@v1.0.0 # Import MCP servers - acme-org/workflow-library/shared/mcp/database.md@v1.0.0 # Import security policies - acme-org/workflow-library/shared/config/security-policies.md@v1.0.0 permissions: contents: read safe-outputs: create-pull-request-review-comment: max: 10 --- # Comprehensive Security Review Perform detailed security analysis using specialized agent files and tools. ``` ## Defining Copilot Sub-agents Inline [Section titled “Defining Copilot Sub-agents Inline”](#defining-copilot-sub-agents-inline) Instead of (or alongside) importing agent files from `.github/agents/`, you can define agents directly inside the workflow markdown. See [Inline Sub-Agents](/gh-aw/reference/inline-sub-agents/) for the complete syntax reference, including name constraints and frontmatter fields. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Imports Reference](/gh-aw/reference/imports/) - Complete import system documentation * [Inline Sub-Agents](/gh-aw/reference/inline-sub-agents/) - Defining Copilot sub-agents inside a workflow file * [Reusing Workflows](/gh-aw/guides/packaging-imports/) - Managing workflow imports * [Frontmatter](/gh-aw/reference/frontmatter/) - Configuration options reference # Cost Management > Understand and control the cost of running GitHub Agentic Workflows, including Actions minutes, inference billing, and strategies to reduce spend. The cost of running an agentic workflow is the sum of two components: **GitHub Actions minutes** consumed by the workflow jobs, and **inference costs** charged by the AI provider for each agent run. ## Cost Components [Section titled “Cost Components”](#cost-components) ### GitHub Actions Minutes [Section titled “GitHub Actions Minutes”](#github-actions-minutes) Every workflow job consumes Actions compute time billed at standard [GitHub Actions pricing](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions). A typical agentic workflow run includes at least two jobs: | Job | Purpose | Typical duration | | -------------------------- | ----------------------------------------------------------------------------------- | ---------------- | | Pre-activation / detection | Validates the trigger, runs membership checks, evaluates `skip-if-match` conditions | 10–30 seconds | | Agent | Runs the AI engine and executes tools | 1–15 minutes | Each job also incurs approximately 1.5 minutes of runner setup overhead on top of its execution time. ### Inference Costs [Section titled “Inference Costs”](#inference-costs) The agent job invokes an AI engine to process the prompt and call tools. Inference is billed by the provider: | Engine | Billed to | Unit | | --------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `copilot` | Account owning [`COPILOT_GITHUB_TOKEN`](/gh-aw/reference/auth/#copilot_github_token) | Premium requests (1–2 per run; see [Copilot billing](https://docs.github.com/en/copilot/about-github-copilot/subscription-plans-for-github-copilot)) | | `claude` | Anthropic account for [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key) | Tokens | | `codex` | OpenAI account for [`OPENAI_API_KEY`](/gh-aw/reference/auth/#openai_api_key) | Tokens | Note For Copilot, inference is charged to the individual account owning `COPILOT_GITHUB_TOKEN`, not the repository or organization. Use a dedicated service account to track spend per workflow. ## Monitoring Costs with `gh aw logs` [Section titled “Monitoring Costs with gh aw logs”](#monitoring-costs-with-gh-aw-logs) The `gh aw logs` command surfaces per-run metrics — elapsed duration, token usage, and estimated inference cost — before you decide what to optimize. Use `gh aw audit ` to deep-dive into a single run’s token usage, tool calls, and inference spend; its **Metrics** and **Performance Metrics** sections cover token counts, effective tokens, turn counts, and estimated cost in one place. For cost trends across multiple runs, use `gh aw logs --format markdown [workflow]` to generate a cross-run report with anomaly detection. ### View recent run durations [Section titled “View recent run durations”](#view-recent-run-durations) ```bash # Overview table for all agentic workflows (last 10 runs) gh aw logs # Narrow to a single workflow gh aw logs issue-triage-agent # Last 30 days for Copilot workflows gh aw logs --engine copilot --start-date -30d ``` The overview table includes a **Duration** column showing elapsed wall-clock time per run. Because GitHub Actions bills compute time by the minute (rounded up per job), duration is the primary indicator of Actions spend. ### Export metrics as JSON [Section titled “Export metrics as JSON”](#export-metrics-as-json) Use `--json` to get structured output suitable for scripting or trend analysis: ```bash # Write JSON to a file for further processing gh aw logs --start-date -1w --json > /tmp/logs.json # List per-run duration, tokens, and cost across all workflows gh aw logs --start-date -30d --json | \ jq '.runs[] | {workflow: .workflow_name, duration: .duration, cost: .estimated_cost}' # Total cost grouped by workflow over the past 30 days gh aw logs --start-date -30d --json | \ jq '[.runs[]] | group_by(.workflow_name) | map({workflow: .[0].workflow_name, runs: length, total_cost: (map(.estimated_cost) | add // 0)})' ``` Each run under `.runs[]` includes `duration`, `token_usage`, `estimated_cost`, `workflow_name`, and `agent`. For orchestrated workflows, the same JSON includes deterministic lineage under `.episodes[]` and `.edges[]` — see the next section. ### Interpret Episode-Level Cost [Section titled “Interpret Episode-Level Cost”](#interpret-episode-level-cost) `gh aw logs --json` emits three views of the same data: `.runs[]` (individual workflow runs), `.episodes[]` (related runs grouped into one logical execution — orchestrator, workers, `workflow_call` follow-ups, and reporting passes), and `.edges[]` (the inferred parent-child lineage). Use `.runs[]` to find which specific run was expensive; use `.episodes[]` to answer “what did this job cost end-to-end?”. For non-orchestrated workflows, an episode collapses to a single run and the two views are equivalent. Useful episode fields for cost analysis: | Field | Meaning | | ----------------------------------------- | ------------------------------------------------------------------------------- | | `total_runs` | Workflow runs in the logical execution | | `total_tokens` / `total_effective_tokens` | Raw and effective token aggregates; prefer `total_effective_tokens` for Copilot | | `total_duration` | Wall-clock duration across grouped runs | | `primary_workflow` | Main workflow label | | `resource_heavy_node_count` | Runs flagged as resource-heavy | | `blocked_request_count` | Aggregate blocked-network pressure | For Copilot runs, treat `total_estimated_cost` as a heuristic — Copilot does not expose billing-grade cost data, so `total_effective_tokens` is the more reliable proxy. Safe-output actuation also appears in both `gh aw logs --json` (run- and repo-level) and `gh aw audit ` (under `safe_output_summary`). The relevant fields — `temporary_id_map_status`, `temporary_id_mappings`, `chained_target_count`, `chained_followup_action_count`, `delegated_temp_target_count`, `closed_temp_target_count`, and their repo-level aggregates — show how often a workflow follows up on its own outputs. When `temporary_id_map_status` is `missing` or `invalid`, chain counts fall back to `0` rather than guessing from incomplete data. ```bash # Top 10 heaviest logical executions over the past 30 days by effective tokens gh aw logs --start-date -30d --json | \ jq '[.episodes[] | {episode: .episode_id, workflow: .primary_workflow, runs: .total_runs, effective_tokens: (.total_effective_tokens // 0)}] | sort_by(.effective_tokens) | reverse | .[:10]' ``` ## Trigger Frequency and Cost Risk [Section titled “Trigger Frequency and Cost Risk”](#trigger-frequency-and-cost-risk) The primary cost lever for most workflows is how often they run. Some events are inherently high-frequency: | Trigger type | Risk | Notes | | ---------------------------------------------- | --------------- | ------------------------------------------------------- | | `push` | High | Every commit to any matching branch fires the workflow | | `pull_request` | Medium–High | Fires on open, sync, re-open, label, and other subtypes | | `issues` | Medium–High | Fires on open, close, label, edit, and other subtypes | | `check_run`, `check_suite` | High | Can fire many times per push in busy repositories | | `issue_comment`, `pull_request_review_comment` | Medium | Scales with comment activity | | `schedule` | Low–Predictable | Fires at a fixed cadence; easy to budget | | `workflow_dispatch` | Low | Human-initiated; naturally rate-limited | Danger Attaching an agentic workflow to `push`, `check_run`, or `check_suite` in an active repository can generate hundreds of runs per day. Start with `schedule` or `workflow_dispatch` while evaluating cost, then move to event-based triggers with safeguards in place. ## Reducing Cost [Section titled “Reducing Cost”](#reducing-cost) ### Use Deterministic Checks to Skip the Agent [Section titled “Use Deterministic Checks to Skip the Agent”](#use-deterministic-checks-to-skip-the-agent) The most effective cost reduction is skipping the agent job entirely when it is not needed. The `skip-if-match` and `skip-if-no-match` conditions run during the low-cost pre-activation job and cancel the workflow before the agent starts: ```aw on: issues: types: [opened] skip-if-match: 'label:duplicate OR label:wont-fix' ``` ```aw on: issues: types: [labeled] skip-if-no-match: 'label:needs-triage' ``` Use these to filter out noise before incurring inference costs. See [Triggers](/gh-aw/reference/triggers/) for the full syntax. ### Choose a Cheaper Model [Section titled “Choose a Cheaper Model”](#choose-a-cheaper-model) The `engine.model` field selects the AI model. Smaller or faster models cost significantly less per token while still handling many routine tasks: ```aw engine: id: copilot model: gpt-4.1-mini ``` ```aw engine: id: claude model: claude-haiku-4-5 ``` Reserve frontier models (GPT-5, Claude Sonnet, etc.) for complex tasks. Use lighter models for triage, labeling, summarization, and other structured outputs. ### Limit Context Size [Section titled “Limit Context Size”](#limit-context-size) Inference cost scales with prompt size. Write focused prompts, avoid whole-file reads when only a few lines matter, cap result counts in tool calls, and use `imports` to compose a smaller subset of prompt sections at runtime. ### Rate Limiting and Concurrency [Section titled “Rate Limiting and Concurrency”](#rate-limiting-and-concurrency) Use `user-rate-limit` to cap how many times a user can trigger the workflow in a given window, and rely on concurrency controls to serialize runs rather than letting them pile up: ```aw user-rate-limit: max-runs-per-window: 3 window: 60 # 3 runs per hour per user ``` See [Rate Limiting Controls](/gh-aw/reference/rate-limiting-controls/) and [Concurrency](/gh-aw/reference/concurrency/) for details. ### Use Schedules for Predictable Budgets [Section titled “Use Schedules for Predictable Budgets”](#use-schedules-for-predictable-budgets) Scheduled workflows fire at a fixed cadence, making cost easy to estimate and cap: ```aw schedule: daily on weekdays ``` One scheduled run per weekday = five agent invocations per week. See [Schedule Syntax](/gh-aw/reference/schedule-syntax/) for the full fuzzy schedule syntax. ## Agentic Cost Optimization [Section titled “Agentic Cost Optimization”](#agentic-cost-optimization) The `agentic-workflows` MCP tool exposes the same operations as the CLI (`logs`, `audit`, `status`) to any workflow agent, so a scheduled meta-agent can inspect and optimize other agentic workflows automatically — fetching aggregate cost data, deep-diving into individual runs, and proposing frontmatter changes (cheaper model, tighter `skip-if-match`, lower `user-rate-limit`) via a pull request. ```aw description: Weekly Actions minutes cost report on: weekly permissions: actions: read engine: copilot tools: agentic-workflows: ``` ### What to Optimize Automatically [Section titled “What to Optimize Automatically”](#what-to-optimize-automatically) | Signal | Automatic action | | ------------------------------------------ | ------------------------------------------------------------------------ | | High token count per run | Switch to a smaller model (`gpt-4.1-mini`, `claude-haiku-4-5`) | | Frequent runs with no safe-output produced | Add or tighten `skip-if-match` | | Long queue times due to concurrency | Lower `user-rate-limit.max-runs-per-window` or add a `concurrency` group | | Workflow running too often | Change trigger to `schedule` or add `workflow_dispatch` | Note The `agentic-workflows` tool requires `actions: read` permission and is configured under the `tools:` frontmatter key. See [GH-AW as an MCP Server](/gh-aw/reference/gh-aw-as-mcp-server/) for available operations. ## Common Scenario Estimates [Section titled “Common Scenario Estimates”](#common-scenario-estimates) These are rough estimates to help with budgeting. Actual costs vary by prompt size, tool usage, model, and provider pricing. | Scenario | Frequency | Actions minutes/month | Inference/month | | ----------------------------------------------------- | --------------- | --------------------- | -------------------------------- | | Weekly digest (schedule, 1 repo) | 4×/month | \~1 min | \~4–8 premium requests (Copilot) | | Issue triage (issues opened, 20/month) | 20×/month | \~10 min | \~20–40 premium requests | | PR review on every push (busy repo, 100 pushes/month) | 100×/month | \~100 min | \~100–200 premium requests | | On-demand via slash command | User-controlled | Varies | Varies | Tip Create separate `COPILOT_GITHUB_TOKEN` service accounts per repository or team to attribute spend by workflow. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Audit Commands](/gh-aw/reference/audit/) - Single-run analysis, diff, and cross-run reporting * [Artifacts](/gh-aw/reference/artifacts/) - Artifact names, directory structures, and token usage file locations * [Effective Tokens Specification](/gh-aw/reference/effective-tokens-specification/) - How effective token counts are computed * [Triggers](/gh-aw/reference/triggers/) - Configuring workflow triggers and skip conditions * [Rate Limiting Controls](/gh-aw/reference/rate-limiting-controls/) - Preventing runaway workflows * [Concurrency](/gh-aw/reference/concurrency/) - Serializing workflow execution * [AI Engines](/gh-aw/reference/engines/) - Engine and model configuration * [Schedule Syntax](/gh-aw/reference/schedule-syntax/) - Cron schedule format * [GH-AW as an MCP Server](/gh-aw/reference/gh-aw-as-mcp-server/) - `agentic-workflows` tool for self-inspection * [FAQ](/gh-aw/reference/faq/) - Common questions including cost and billing # Cross-Repository Operations > Configure workflows to access, modify, and operate across multiple GitHub repositories using checkout, target-repo, and allowed-repos settings Cross-repository operations enable workflows to access code from multiple repositories and create resources (issues, PRs, comments) in external repositories. This page documents all declarative frontmatter features for cross-repository workflows. Cross-repository features fall into three categories: 1. **Cross-Repository Checkout** - Check out code from other repositories 2. **Cross-Repository Reading** - Read issues, pull requests and other information from other repositories 3. **Cross-Repository Safe Outputs** - Create issues, PRs, comments, and other resources in external repositories using `target-repo` and `allowed-repos` in safe outputs All require additional authentication. ## Cross-Repository Checkout (`checkout:`) [Section titled “Cross-Repository Checkout (checkout:)”](#cross-repository-checkout-checkout) The `checkout:` frontmatter field controls how `actions/checkout` is invoked in the agent job. Use it to check out one or more repositories, override fetch depth or sparse-checkout settings, fetch additional refs (e.g., all open PR branches), or disable checkout entirely with `checkout: false`. For multi-repository workflows, list multiple entries to clone several repos into the workspace. Mark the agent’s primary target with `current: true` when working from a central repository that targets a different repo. ```yaml checkout: - fetch-depth: 0 # checkout this repository with full history fetch: ["refs/pulls/open/*"] # fetch all open PR branches after checkout - repository: owner/other-repo # another repository to check out path: ./libs/other # path within workspace to check out to github-token: ${{ secrets.CROSS_REPO_PAT }} # additional auth for cross-repo access ``` See [GitHub Repository Checkout](/gh-aw/reference/checkout/) for the full configuration reference, including fetch options, sparse checkout, merging rules, and examples. ## Cross-Repository Reading [Section titled “Cross-Repository Reading”](#cross-repository-reading) The [GitHub Tools](/gh-aw/reference/github-tools/) are used to read information such as issues and pull requests from repositories. By default, these tools can access the current repository and all public repositories (if permitted by the network firewall). ### Authorizing Additional Cross-Repository Reading [Section titled “Authorizing Additional Cross-Repository Reading”](#authorizing-additional-cross-repository-reading) To read from other private repositories, you must configure additional authorization. Configure a PAT or GitHub App in your GitHub Tools configuration: ```yaml tools: github: toolsets: [repos, issues, pull_requests] github-token: ${{ secrets.CROSS_REPO_PAT }} ``` This enables operations like: * Reading files and searching code in external repositories dynamically, even if the repository is not checked out * Querying issues and pull requests from other repos * Accessing commits, releases, and workflow runs across repositories * Reading organization-level information See [Additional Authentication for GitHub Tools](/gh-aw/reference/github-tools/#additional-authentication-for-github-tools) for full details on creating a PAT, using a GitHub App, or using the magic secret `GH_AW_GITHUB_MCP_SERVER_TOKEN`. ### Restricting Cross-Repository Reading (`tools.github.allowed-repos`) [Section titled “Restricting Cross-Repository Reading (tools.github.allowed-repos)”](#restricting-cross-repository-reading-toolsgithuballowed-repos) You can also configure the GitHub Tools to be restricted in which repositories can be accessed via the GitHub tools during AI engine execution by using the `tools.github.allowed-repos` setting. This is a guardrail to prevent unintended access to repositories. The setting `tools.github.allowed-repos` specifies which repositories the agent can access through GitHub tools: * `"all"` — All repositories accessible by the configured token * `"public"` — Public repositories only * `"current"` — The repository where the workflow is running (normalized to `${{ github.repository }}` in the emitted guard policy) * `"${{ github.repository }}"` — Equivalent to `"current"`, kept for backward compatibility * Array of patterns — Specific repositories and wildcards: * `"owner/repo"` — Exact repository match * `"owner/*"` — All repositories under an owner * `"owner/prefix*"` — Repositories with a name prefix under an owner This defaults to `"all"` when omitted. Patterns must be lowercase. Wildcards are only permitted at the end of the repository name component. Use `current` in reusable or generated workflows that need to express “this repository only” without hard-coding `owner/repo`: ```yaml tools: github: toolsets: [issues, pull_requests] allowed-repos: current min-integrity: approved ``` For example: ```yaml tools: github: mode: remote toolsets: [default] allowed-repos: - "myorg/*" - "partner/shared-repo" - "myorg/api-*" min-integrity: approved ``` ## Cross-Repository Safe Outputs [Section titled “Cross-Repository Safe Outputs”](#cross-repository-safe-outputs) Most safe output types support creating resources in external repositories using `target-repo` and `allowed-repos` parameters. ### Target Repository (`safe-outputs.*.target-repo`) [Section titled “Target Repository (safe-outputs.\*.target-repo)”](#target-repository-safe-outputstarget-repo) Specify a single target repository for resource creation: ```yaml safe-outputs: github-token: ${{ secrets.CROSS_REPO_PAT }} create-issue: target-repo: "org/tracking-repo" title-prefix: "[component] " ``` Without `target-repo`, safe outputs operate on the repository where the workflow is running. ### Wildcard Target Repository (`target-repo: "*"`) [Section titled “Wildcard Target Repository (target-repo: "\*")”](#wildcard-target-repository-target-repo-) Set `target-repo: "*"` to allow the agent to dynamically target any repository at runtime. When configured, the agent receives a `repo` parameter in its tool call where it supplies the target repository in `owner/repo` format: ```yaml safe-outputs: github-token: ${{ secrets.CROSS_REPO_PAT }} create-issue: target-repo: "*" title-prefix: "[component] " ``` Use this when the target repository is not known at workflow authoring time — for example, when building a workflow that routes issues to different repositories based on labels or content. Note The following safe-output types do **not** support `target-repo: "*"`: `create-pull-request-review-comment`, `reply-to-pull-request-review-comment`, `submit-pull-request-review`, `create-agent-session`, and `manage-project-items`. Use an explicit `owner/repo` value or `allowed-repos` for these types. ### Allowed Repositories (`safe-outputs.*.allowed-repos`) [Section titled “Allowed Repositories (safe-outputs.\*.allowed-repos)”](#allowed-repositories-safe-outputsallowed-repos) Allow your agentic workflow to dynamically select from multiple repositories: ```yaml safe-outputs: github-token: ${{ secrets.CROSS_REPO_PAT }} create-issue: target-repo: "org/default-repo" allowed-repos: ["org/repo-a", "org/repo-b", "org/repo-c"] title-prefix: "[cross-repo] " ``` When `allowed-repos` is specified: * The agentic step can include a `repo` field to select which repository * Target repository (from `target-repo` or current repo) is always implicitly allowed * Creates a union of allowed destinations ### Checkout Requirement for `push-to-pull-request-branch` [Section titled “Checkout Requirement for push-to-pull-request-branch”](#checkout-requirement-for-push-to-pull-request-branch) Unlike other safe output types, `push-to-pull-request-branch` with `target-repo` requires the target repository to be **checked out into the workflow workspace** using the `checkout:` frontmatter field with a `path:` specified. Without a checkout, the agent has no local git history to create and push a patch from. See the [Scheduled Push to Pull-Request Branch](#example-scheduled-push-to-pull-request-branch) example and the [Push to PR Branch cross-repo usage](/gh-aw/reference/safe-outputs-pull-requests/#cross-repo-usage) documentation for a complete setup. ## Examples [Section titled “Examples”](#examples) ### Example: Monorepo Development [Section titled “Example: Monorepo Development”](#example-monorepo-development) This uses multiple `checkout:` entries to check out different parts of the same repository with different settings: ```aw --- on: pull_request: types: [opened, synchronize] checkout: - fetch-depth: 0 - repository: org/shared-libs path: ./libs/shared ref: main github-token: ${{ secrets.LIBS_PAT }} - repository: org/config-repo path: ./config sparse-checkout: | defaults/ overrides/ permissions: contents: read pull-requests: read --- # Cross-Repo PR Analysis Analyze this PR considering shared library compatibility and configuration standards. Check compatibility with shared libraries in `./libs/shared` and verify configuration against standards in `./config`. ``` ### Example: Hub-and-Spoke Tracking [Section titled “Example: Hub-and-Spoke Tracking”](#example-hub-and-spoke-tracking) Create issues in a central tracking repo when issues open in component repos using `target-repo` on `create-issue`. See the [MultiRepoOps pattern](/gh-aw/patterns/multi-repo-ops/) for a complete walkthrough including hub-and-spoke, upstream-to-downstream, and org-wide broadcast topologies. ### Example: Cross-Repository Analysis [Section titled “Example: Cross-Repository Analysis”](#example-cross-repository-analysis) Use `tools.github` with `github-token` to read from multiple repositories, then write results back with `add-comment` and `target-repo`. See [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) for examples. ### Example: Deterministic Multi-Repo Workflows [Section titled “Example: Deterministic Multi-Repo Workflows”](#example-deterministic-multi-repo-workflows) For direct repository access without agent involvement, use custom steps with `actions/checkout`: ```aw --- engine: id: claude steps: - name: Checkout main repo uses: actions/checkout@v6 with: path: main-repo - name: Checkout secondary repo uses: actions/checkout@v6 with: repository: org/secondary-repo token: ${{ secrets.CROSS_REPO_PAT }} path: secondary-repo permissions: contents: read --- # Compare Repositories Compare code structure between main-repo and secondary-repo. ``` This approach provides full control over checkout timing and configuration. ### Example: Scheduled Push to Pull-Request Branch [Section titled “Example: Scheduled Push to Pull-Request Branch”](#example-scheduled-push-to-pull-request-branch) A scheduled workflow that automatically pushes changes to open pull-request branches in another repository needs to fetch those branches after checkout. Without `fetch:`, only the default branch (usually `main`) is available. ```aw --- on: schedule: hourly checkout: - repository: org/target-repo github-token: ${{ secrets.GH_AW_SIDE_REPO_PAT }} fetch: ["refs/pulls/open/*"] # fetch all open PR branches after checkout current: true permissions: contents: read safe-outputs: github-token: ${{ secrets.GH_AW_SIDE_REPO_PAT }} push-to-pull-request-branch: target-repo: "org/target-repo" --- # Auto-Update PR Branches Check open pull requests in org/target-repo and apply any pending automated updates to each PR branch. ``` `fetch: ["refs/pulls/open/*"]` causes a `git fetch` step to run after `actions/checkout`, downloading all open PR head refs into the workspace. The agent can then inspect and modify those branches directly. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [GitHub Repository Checkout](/gh-aw/reference/checkout/) - Full checkout configuration reference * [MultiRepoOps Pattern](/gh-aw/patterns/multi-repo-ops/) - Cross-repository workflow pattern * [MultiRepoOps — Central Control Plane](/gh-aw/patterns/multi-repo-ops/#the-central-control-plane-pattern-org-wide-rollouts) — Central control plane pattern * [GitHub Tools Reference](/gh-aw/reference/github-tools/) - Complete GitHub Tools configuration * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe output configuration * [Authentication Reference](/gh-aw/reference/auth/) - PAT and GitHub App setup * [Multi-Repository Examples](/gh-aw/examples/multi-repo/) - Complete working examples # Copilot Agent Files support for Agentic Workflows > How to create, update, import, and debug agentic workflows using our AI agent. “Custom Agents” are added prompts that can be used with Copilot, Copilot CLI and VSCode Agent Mode to provide specialized behavior for specific tasks. In this guide, we show you how to install and use the custom agent `agentic-workflows` to create, update, import, and debug agentic workflows in your repository. ## Installing the Copilot Agent Files for Agentic Workflows [Section titled “Installing the Copilot Agent Files for Agentic Workflows”](#installing-the-copilot-agent-files-for-agentic-workflows) Follow these steps to set up your repository for agentic workflows using the custom `agentic-workflows` agent. 1. **Start your coding agent**. * Navigate to your repository on and click the “Agents” tab, or * Start [VSCode Agent Mode](https://code.visualstudio.com/docs/copilot/agents/overview), or * Start your coding agent in your repository 2. **Install the Copilot Agent Files for Agentic Workflows into your repository**. ```text Initialize this repository for GitHub Agentic Workflows using https://github.com/github/gh-aw/blob/main/install.md ``` Alternatively just run ```bash gh aw init ``` After initialization, you’ll have `.github/agents/agentic-workflows.agent.md`, a [Copilot agent file](/gh-aw/reference/glossary/#agent-files) that registers the `/agent agentic-workflows` command in Copilot Chat. ## Using the Copilot Agent Files for Agentic Workflows [Section titled “Using the Copilot Agent Files for Agentic Workflows”](#using-the-copilot-agent-files-for-agentic-workflows) Once your repository is set up for agentic workflows, you can use the `agentic-workflows` agent from VSCode or GitHub.com to perform a variety of tasks: ### Creating New Agentic Workflows [Section titled “Creating New Agentic Workflows”](#creating-new-agentic-workflows) Navigate to your repository on and click the “Agents” tab, then use this prompt: ```text # Create a new workflow /agent agentic-workflows create a workflow that triages issues ``` The agent will generate a workflow file in `.github/workflows/`, write the frontmatter and prompt, configure tools and permissions, and compile to `.lock.yml`. ### Updating Existing Workflows [Section titled “Updating Existing Workflows”](#updating-existing-workflows) Modify or improve existing workflows using natural language prompts: ```text /agent agentic-workflows update the issue-triage workflow to add web-fetch tool and improve the prompt for better accuracy ``` ### Upgrading Agentic Workflows [Section titled “Upgrading Agentic Workflows”](#upgrading-agentic-workflows) Keep workflows up-to-date with the latest `gh-aw` versions and features: ```text /agent agentic-workflows upgrade all workflows to latest version ``` ### Importing Workflows [Section titled “Importing Workflows”](#importing-workflows) Import workflows from any accessible GitHub repository: ```text /agent agentic-workflows import workflow from https://github.com/githubnext/agentics/blob/main/workflows/ci-doctor.md ``` When importing, you can specify customizations such as engine or tools: ```text /agent agentic-workflows import issue-triage from githubnext/agentics and use claude engine ``` ### Debugging Agentic Workflows [Section titled “Debugging Agentic Workflows”](#debugging-agentic-workflows) When workflows fail or behave unexpectedly, use the agentic-workflows agent to investigate and diagnose issues: ```text /agent agentic-workflows debug why is my issue-triage workflow failing? ``` For the fastest diagnosis, pass the full run URL from the GitHub Actions page: ```text /agent agentic-workflows debug https://github.com/OWNER/REPO/actions/runs/RUN_ID ``` The agent audits logs, identifies the root cause, and suggests targeted fixes. It handles permission errors, missing tools, network access issues, and safe-output problems — just describe the issue in natural language. ### Self-Contained Debugging (Without Copilot) [Section titled “Self-Contained Debugging (Without Copilot)”](#self-contained-debugging-without-copilot) If your repository is not yet set up with the `agentic-workflows` agent, or if you prefer to use a different AI assistant, use the standalone debugging prompt by sharing its URL: ```text Debug this workflow run using https://raw.githubusercontent.com/github/gh-aw/main/debug.md The failed workflow run is at https://github.com/OWNER/REPO/actions/runs/RUN_ID ``` Copy debug instructions The `debug.md` file is a self-contained prompt that works with any coding agent or AI assistant. It guides the agent to install `gh aw`, analyze the run logs, identify the root cause, and open a pull request with the fix. ## Creating Agentic Workflows with an AI Chatbot [Section titled “Creating Agentic Workflows with an AI Chatbot”](#creating-agentic-workflows-with-an-ai-chatbot) If you prefer to use an AI chatbot to author agentic workflows, use the [agentic-chat instructions](https://raw.githubusercontent.com/github/gh-aw/main/.github/aw/agentic-chat.md) with any conversational AI application. Copy agentic-chat instructions Copy the instructions into your AI chat interface, describe your workflow goal, and the assistant will generate a structured task description you can use in your workflow. It focuses on clear, actionable specifications rather than implementation details. ## Dictating Agentic Workflows [Section titled “Dictating Agentic Workflows”](#dictating-agentic-workflows) When creating agentic workflows using speech-to-text (dictation), you may encounter terminology mismatches and formatting issues common to voice recognition systems. To help correct these issues, use the [dictation instructions prompt](https://raw.githubusercontent.com/github/gh-aw/main/DICTATION.md) or Copy dictation instructions . This prompt corrects terminology (e.g., “ghaw” → “gh-aw”), removes filler words, and transforms dictated sentences into clear, imperative task descriptions. Load it into your AI assistant before or after dictating to improve accuracy. # Custom Safe Outputs > How to create custom safe outputs for third-party integrations using custom jobs and MCP servers. Custom safe outputs extend built-in GitHub operations to integrate with third-party services — Slack, Discord, Notion, Jira, databases, or any external API requiring authentication. Use them for any write operation that built-in safe outputs don’t cover. ## Quick Start [Section titled “Quick Start”](#quick-start) Here’s a minimal custom safe output that sends a Slack message: .github/workflows/shared/slack-notify.md ```yaml --- safe-outputs: jobs: slack-notify: description: "Send a message to Slack" runs-on: ubuntu-latest output: "Message sent to Slack!" inputs: message: description: "The message to send" required: true type: string steps: - name: Send Slack message env: SLACK_WEBHOOK: "${{ secrets.SLACK_WEBHOOK }}" run: | if [ -f "$GH_AW_AGENT_OUTPUT" ]; then MESSAGE=$(cat "$GH_AW_AGENT_OUTPUT" | jq -r '.items[] | select(.type == "slack_notify") | .message') # Use jq to safely escape JSON content PAYLOAD=$(jq -n --arg text "$MESSAGE" '{text: $text}') curl -X POST "$SLACK_WEBHOOK" \ -H 'Content-Type: application/json' \ -d "$PAYLOAD" else echo "No agent output found" exit 1 fi --- ``` Use it in a workflow: .github/workflows/issue-notifier.md ```aw --- on: issues: types: [opened] permissions: contents: read imports: - shared/slack-notify.md --- # Issue Notifier A new issue was opened: "${{ steps.sanitized.outputs.text }}" Summarize the issue and use the slack-notify tool to send a notification. ``` The agent can now call `slack-notify` with a message, and the custom job executes with access to the `SLACK_WEBHOOK` secret. ## Architecture [Section titled “Architecture”](#architecture) Custom safe outputs separate read and write operations: agents use read-only Model Context Protocol (MCP) servers with `allowed:` tool lists, while custom jobs handle write operations with secret access after agent completion. ```text ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Agent (AI) │────│ MCP Server │────│ External API │ │ │ │ (read-only) │ │ (GET requests) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ calls safe-job tool ▼ ┌─────────────────┐ ┌─────────────────┐ │ Custom Job │────│ External API │ │ (with secrets) │ │ (POST/PUT) │ └─────────────────┘ └─────────────────┘ ``` ## Creating a Custom Safe Output [Section titled “Creating a Custom Safe Output”](#creating-a-custom-safe-output) ### Step 1: Define the Shared Configuration [Section titled “Step 1: Define the Shared Configuration”](#step-1-define-the-shared-configuration) In a shared file, define the read-only MCP server and the custom job together: ```yaml --- mcp-servers: notion: container: "mcp/notion" env: NOTION_TOKEN: "${{ secrets.NOTION_TOKEN }}" allowed: - "search_pages" - "get_page" - "get_database" - "query_database" safe-outputs: jobs: notion-add-comment: description: "Add a comment to a Notion page" runs-on: ubuntu-latest output: "Comment added to Notion successfully!" permissions: contents: read inputs: page_id: description: "The Notion page ID to add a comment to" required: true type: string comment: description: "The comment text to add" required: true type: string steps: - name: Add comment to Notion page uses: actions/github-script@v8 env: NOTION_TOKEN: "${{ secrets.NOTION_TOKEN }}" with: script: | const fs = require('fs'); const notionToken = process.env.NOTION_TOKEN; const outputFile = process.env.GH_AW_AGENT_OUTPUT; if (!notionToken) { core.setFailed('NOTION_TOKEN secret is not configured'); return; } if (!outputFile) { core.info('No GH_AW_AGENT_OUTPUT environment variable found'); return; } // Read and parse agent output const fileContent = fs.readFileSync(outputFile, 'utf8'); const agentOutput = JSON.parse(fileContent); // Filter for notion-add-comment items (job name with dashes → underscores) const items = agentOutput.items.filter(item => item.type === 'notion_add_comment'); for (const item of items) { const pageId = item.page_id; const comment = item.comment; core.info(`Adding comment to Notion page: ${pageId}`); try { const response = await fetch('https://api.notion.com/v1/comments', { method: 'POST', headers: { 'Authorization': `Bearer ${notionToken}`, 'Notion-Version': '2022-06-28', 'Content-Type': 'application/json' }, body: JSON.stringify({ parent: { page_id: pageId }, rich_text: [{ type: 'text', text: { content: comment } }] }) }); if (!response.ok) { const errorData = await response.text(); core.setFailed(`Notion API error (${response.status}): ${errorData}`); return; } const data = await response.json(); core.info('Comment added successfully'); core.info(`Comment ID: ${data.id}`); } catch (error) { core.setFailed(`Failed to add comment: ${error.message}`); return; } } --- ``` Use `container:` for Docker servers or `command:`/`args:` for npx. List only read-only tools in `allowed`. All jobs require `description` and `inputs`. Use `output` for success messages and `actions/github-script@v8` for API calls with `core.setFailed()` error handling. ### Step 2: Use in Workflow [Section titled “Step 2: Use in Workflow”](#step-2-use-in-workflow) Import the configuration: ```aw --- on: issues: types: [opened] permissions: contents: read actions: read imports: - shared/mcp/notion.md --- # Issue Summary to Notion Analyze the issue: "${{ steps.sanitized.outputs.text }}" Search for the GitHub Issues page in Notion using the read-only Notion tools, then add a summary comment using the notion-add-comment safe-job. ``` The agent uses read-only tools to query, then calls the safe-job which executes with write permissions after completion. ## Safe Job Reference [Section titled “Safe Job Reference”](#safe-job-reference) ### Job Properties [Section titled “Job Properties”](#job-properties) | Property | Type | Required | Description | | ----------------- | --------------- | -------- | -------------------------------------------------------------------------------------- | | `description` | string | Yes | Tool description shown to the agent | | `runs-on` | string | Yes | GitHub Actions runner (e.g., `ubuntu-latest`) | | `inputs` | object | Yes | Tool parameters (see [Input Types](#input-types)) | | `steps` | array | Yes | GitHub Actions steps to execute | | `output` | string | No | Success message returned to the agent | | `needs` | string or array | No | Jobs that must complete before this job runs (see [Job Ordering](#job-ordering-needs)) | | `permissions` | object | No | GitHub token permissions for the job | | `env` | object | No | Environment variables for all steps | | `if` | string | No | Conditional execution expression | | `timeout-minutes` | number | No | Maximum job duration (GitHub Actions default: 360) | ### Job Ordering (`needs:`) [Section titled “Job Ordering (needs:)”](#job-ordering-needs) Use `needs:` to sequence a custom safe-output job relative to other jobs in the compiled workflow. Unlike manually patching `needs:` in the lock file (which gets overwritten on every recompile), `needs:` declared in the frontmatter persists across recompiles. ```yaml safe-outputs: create-issue: {} jobs: post-process: needs: safe_outputs # runs after the consolidated safe-outputs job steps: - run: echo "post-processing" ``` The compiler validates each `needs:` entry at compile time and fails with a clear error if the target does not exist. Target names with dashes are automatically normalized to underscores (e.g., `safe-outputs` → `safe_outputs`). Valid `needs:` targets for custom safe-jobs: | Target | Available when | | --------------- | ------------------------------------------------------------------------ | | `agent` | Always | | `safe_outputs` | At least one builtin handler, script, action, or user step is configured | | `detection` | Threat detection is enabled | | `upload_assets` | `upload-asset` is configured | | `unlock` | `lock-for-agent` is enabled | | `` | That job exists in `safe-outputs.jobs` | Self-dependencies and cycles between custom jobs are also caught at compile time. ### Input Types [Section titled “Input Types”](#input-types) All jobs must define `inputs`: | Type | Description | | --------- | ---------------------------------------------- | | `string` | Text input | | `boolean` | True/false (as strings: `"true"` or `"false"`) | | `choice` | Selection from predefined options | ```yaml inputs: message: description: "Message content" required: true type: string notify: description: "Send notification" required: false type: boolean default: "true" environment: description: "Target environment" required: true type: choice options: ["staging", "production"] ``` ### Environment Variables [Section titled “Environment Variables”](#environment-variables) Custom safe-output jobs have access to these environment variables: | Variable | Description | | --------------------------- | ---------------------------------------------------- | | `GH_AW_AGENT_OUTPUT` | Path to JSON file containing the agent’s output data | | `GH_AW_SAFE_OUTPUTS_STAGED` | Set to `"true"` when running in staged/preview mode | ### Accessing Agent Output [Section titled “Accessing Agent Output”](#accessing-agent-output) Custom safe-output jobs receive the agent’s data through the `GH_AW_AGENT_OUTPUT` environment variable, which contains a path to a JSON file. This file has the structure: ```json { "items": [ { "type": "job_name_with_underscores", "field1": "value1", "field2": "value2" } ] } ``` The `type` field matches your job name with dashes converted to underscores (e.g., job `webhook-notify` → type `webhook_notify`). #### Example [Section titled “Example”](#example) ```yaml steps: - name: Process output run: | if [ -f "$GH_AW_AGENT_OUTPUT" ]; then MESSAGE=$(cat "$GH_AW_AGENT_OUTPUT" | jq -r '.items[] | select(.type == "my_job") | .message') echo "Message: $MESSAGE" else echo "No agent output found" exit 1 fi ``` The `inputs:` schema serves as both the MCP tool definition visible to the agent and validation for the output fields written to `GH_AW_AGENT_OUTPUT`. ## Inline Script Handlers (`safe-outputs.scripts`) [Section titled “Inline Script Handlers (safe-outputs.scripts)”](#inline-script-handlers-safe-outputsscripts) Use `safe-outputs.scripts` to define lightweight inline JavaScript handlers that execute inside the consolidated safe-outputs job handler loop. Unlike `jobs` (which create a separate GitHub Actions job for each tool call), scripts run in-process alongside the built-in safe-output handlers — there is no extra job allocation or startup overhead. **When to use scripts vs jobs:** | | Scripts | Jobs | | --------- | -------------------------------------------------------------- | ------------------------------------ | | Execution | In-process, in the consolidated safe-outputs job | Separate GitHub Actions job | | Startup | Fast (no job scheduling) | Slower (new job per call) | | Secrets | Not directly available — use for lightweight logic | Full access to repository secrets | | Use case | Lightweight processing, logging, notifications without secrets | External API calls requiring secrets | ### Defining a Script [Section titled “Defining a Script”](#defining-a-script) Under `safe-outputs.scripts`, define each handler with a `description`, `inputs`, and `script` body: .github/workflows/my-workflow\.md ```yaml --- safe-outputs: scripts: post-slack-message: description: Post a message to a Slack channel inputs: channel: description: Slack channel name required: true type: string message: description: Message text required: true type: string script: | const targetChannel = item.channel || "#general"; const text = item.message || "(no message)"; core.info(`Posting to ${targetChannel}: ${text}`); return { success: true, channel: targetChannel }; --- ``` The agent calls `post_slack_message` (dashes normalized to underscores) and the script runs synchronously in the handler loop. ### Script Body Context [Section titled “Script Body Context”](#script-body-context) Write only the handler body — the compiler wraps it automatically. Inside the body you have access to: | Variable | Description | | ---------------------- | ----------------------------------------------------------------------------- | | `item` | Runtime message object with field values matching your `inputs` schema | | `core` | `@actions/core` for logging (`core.info()`, `core.warning()`, `core.error()`) | | `resolvedTemporaryIds` | Map of temporary object IDs resolved at runtime | Each input declared in `inputs` is also destructured into a local variable. For example, an `inputs.channel` entry is available as `item.channel`. ```javascript // Example: access inputs via item const channel = item.channel; const message = item.message; core.info(`Sending to ${channel}: ${message}`); return { sent: true }; ``` Note Script names with dashes are normalized to underscores when registered as MCP tools (e.g., `post-slack-message` becomes `post_slack_message`). The normalized name is what the agent uses to call the tool. ### Script Reference [Section titled “Script Reference”](#script-reference) | Property | Type | Required | Description | | ------------- | ------ | -------- | -------------------------------------------- | | `description` | string | Yes | Tool description shown to the agent | | `inputs` | object | Yes | Tool parameters (same schema as custom jobs) | | `script` | string | Yes | JavaScript handler body | Scripts support the same `inputs` types as custom jobs: `string`, `boolean`, and `number`. ## GitHub Action Wrappers (`safe-outputs.actions`) [Section titled “GitHub Action Wrappers (safe-outputs.actions)”](#github-action-wrappers-safe-outputsactions) Use `safe-outputs.actions` to mount any public GitHub Action as a once-callable MCP tool. At compile time, `gh aw compile` fetches the action’s `action.yml` to resolve its inputs and pins the action reference to a specific SHA. The agent can call the tool once per workflow run; the action executes inside the consolidated safe-outputs job. **When to use actions vs scripts vs jobs:** | | Actions | Scripts | Jobs | | --------- | ----------------------------------------------- | ------------------------------------------------ | --------------------------------- | | Execution | In the consolidated safe-outputs job, as a step | In-process, in the consolidated safe-outputs job | Separate GitHub Actions job | | Reuse | Any public GitHub Action | Custom inline JavaScript | Custom inline YAML job | | Secrets | Full access via `env:` | Not directly available | Full access to repository secrets | | Use case | Reuse existing marketplace actions | Lightweight logic | Complex multi-step workflows | ### Defining an Action [Section titled “Defining an Action”](#defining-an-action) Under `safe-outputs.actions`, define each action with a `uses` field (matching GitHub Actions `uses` syntax) and an optional `description` override: .github/workflows/my-workflow\.md ```yaml --- safe-outputs: actions: add-smoked-label: uses: actions-ecosystem/action-add-labels@v1 description: Add the 'smoked' label to the current pull request env: GITHUB_TOKEN: ${{ github.token }} --- ``` The agent calls `add_smoked_label` (dashes normalized to underscores). The action’s declared inputs become the tool’s parameters — values are passed as step inputs at runtime. ### Action Reference [Section titled “Action Reference”](#action-reference) | Property | Type | Required | Description | | ------------- | ------ | -------- | ---------------------------------------------------------------------------- | | `uses` | string | Yes | Action reference (`owner/repo@ref` or `./path/to/local-action`) | | `description` | string | No | Tool description shown to the agent (overrides the action’s own description) | | `env` | object | No | Additional environment variables injected into the action step | Note Action names with dashes are normalized to underscores when registered as MCP tools (e.g., `add-smoked-label` becomes `add_smoked_label`). The normalized name is what the agent uses to call the tool. Tip Action references are pinned to a SHA at compile time for reproducibility. Run `gh aw compile` again to update pinned SHAs after an upstream action release. ## Importing Custom Jobs [Section titled “Importing Custom Jobs”](#importing-custom-jobs) Define jobs in shared files under `.github/workflows/shared/` and import them: ```aw --- on: issues permissions: contents: read imports: - shared/slack-notify.md - shared/jira-integration.md --- # Issue Handler Handle the issue and notify via Slack and Jira. ``` Jobs with duplicate names cause compilation errors - rename to resolve conflicts. ## Error Handling [Section titled “Error Handling”](#error-handling) Use `core.setFailed()` for errors and validate required inputs: ```javascript if (!process.env.API_KEY) { core.setFailed('API_KEY secret is not configured'); return; } try { const response = await fetch(url); if (!response.ok) { core.setFailed(`API error (${response.status}): ${await response.text()}`); return; } core.info('Operation completed successfully'); } catch (error) { core.setFailed(`Request failed: ${error.message}`); } ``` ## Security [Section titled “Security”](#security) Store secrets in GitHub Secrets and pass via environment variables. Limit job permissions to minimum required and validate all inputs. ## Staged Mode Support [Section titled “Staged Mode Support”](#staged-mode-support) When `GH_AW_SAFE_OUTPUTS_STAGED === 'true'`, skip the real operation and display a preview using `core.summary`. See [Staged Mode](/gh-aw/reference/staged-mode/#staged-mode-for-custom-safe-output-jobs) for a complete example. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) | Issue | Solution | | ----------------------------------- | -------------------------------------------------------------------------------------- | | Job or script not appearing as tool | Ensure `inputs` and `description` are defined; verify import path; run `gh aw compile` | | Secrets not available | Check secret exists in repository settings and name matches exactly (case-sensitive) | | Job fails silently | Add `core.info()` logging and ensure `core.setFailed()` is called on errors | | Agent calls wrong tool | Make `description` specific and unique; explicitly mention job name in prompt | ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [DeterministicOps](/gh-aw/patterns/deterministic-ops/) - Mixing computation and AI reasoning * [Safe Outputs](/gh-aw/reference/safe-outputs/) - Built-in safe output types * [MCPs](/gh-aw/guides/mcps/) - Model Context Protocol setup * [Frontmatter](/gh-aw/reference/frontmatter/) - All configuration options * [Imports](/gh-aw/reference/imports/) - Sharing workflow configurations # Dependabot Manifest Generation > Automatic dependency manifest generation for tracking runtime dependencies in agentic workflows, enabling Dependabot to detect and update outdated tools. The `gh aw compile --dependabot` command scans workflows for runtime tools (`npx`, `pip install`, `go install`), generates dependency manifests (`package.json`, `requirements.txt`, `go.mod`), and configures Dependabot to monitor for updates ## Usage [Section titled “Usage”](#usage) Run `gh aw compile --dependabot` to compile all workflows and generate manifests in `.github/workflows/`. Caution Must compile **all workflows** - cannot be used with specific files or `--dir` flag. **Prerequisites**: Node.js/npm required for `package-lock.json` generation. Pip and Go manifests generate without additional tools. ## Compiler-managed `gh-aw-actions` ignore rule [Section titled “Compiler-managed gh-aw-actions ignore rule”](#compiler-managed-gh-aw-actions-ignore-rule) `gh aw compile` always reconciles the compiler-managed ignore rule for `github/gh-aw-actions/**` when your repository already has a `github-actions` update block in `.github/dependabot.yml` (this is not limited to `--dependabot` runs). * No-op if `.github/dependabot.yml` does not exist * No-op if there is no `package-ecosystem: github-actions` update block * Preserves user-defined `ignore` entries ```yaml updates: - package-ecosystem: github-actions directory: "/.github/workflows" schedule: interval: weekly ignore: - dependency-name: "github/gh-aw-actions/**" # Managed by gh aw compile. Version-locked to the gh-aw compiler; do not bump. - dependency-name: "actions/checkout" # user-defined, preserved ``` ## Generated Files [Section titled “Generated Files”](#generated-files) | Ecosystem | Manifest | Lock File | | --------- | ------------------ | ----------------------------------------------------------- | | **npm** | `package.json` | `package-lock.json` (via `npm install --package-lock-only`) | | **pip** | `requirements.txt` | - | | **Go** | `go.mod` | - | All ecosystems update `.github/dependabot.yml` with weekly update schedules. Existing configurations are preserved; only missing ecosystems are added. ## Handling Dependabot PRs [Section titled “Handling Dependabot PRs”](#handling-dependabot-prs) Caution **Never merge Dependabot PRs that only modify manifest files.** These changes are overwritten on next compilation. **Correct workflow**: Update source `.md` files, then recompile to regenerate manifests. ```bash # Find affected workflows grep -r "@playwright/test@1.41.0" .github/workflows/*.md # Edit workflow .md files (change version) # npx @playwright/test@1.41.0 → npx @playwright/test@1.42.0 # Regenerate manifests gh aw compile --dependabot # Commit (Dependabot auto-closes its PR) git add .github/workflows/ git commit -m "chore: update @playwright/test to 1.42.0" git push ``` ### Handling Transitive Dependencies (MCP Servers) [Section titled “Handling Transitive Dependencies (MCP Servers)”](#handling-transitive-dependencies-mcp-servers) When Dependabot flags transitive dependencies (e.g., `@modelcontextprotocol/sdk`, `hono` from `@sentry/mcp-server`), update the **shared MCP configuration** instead: ```bash # Locate the shared MCP config (e.g., .github/workflows/shared/mcp/sentry.md) # Update the version in the args array: # args: ["@sentry/mcp-server@0.27.0"] → args: ["@sentry/mcp-server@0.29.0"] # Regenerate manifests gh aw compile --dependabot # Regenerate package-lock.json to pick up transitive dependency updates cd .github/workflows && npm install --package-lock-only # Commit changes git add .github/workflows/ git commit -m "chore: update @sentry/mcp-server to 0.29.0" git push ``` **Why?** The compiler generates `package.json` from MCP server configurations in workflow files. Directly editing `package.json` will be overwritten on next compilation. ## AI Agent Prompt Template [Section titled “AI Agent Prompt Template”](#ai-agent-prompt-template) ```markdown A Dependabot PR updated dependencies in .github/workflows/. Fix workflow: 1. Identify which .md files reference the outdated dependency 2. Update versions in workflow files 3. Run `gh aw compile --dependabot` to regenerate manifests 4. Verify manifests match the Dependabot PR 5. Commit and push (Dependabot auto-closes) Affected PR: [link] Updated dependency: [name@version] ``` ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) | Issue | Solution | | --------------------------------- | ---------------------------------------------------------------------- | | **package-lock.json not created** | Install Node.js/npm from [nodejs.org](https://nodejs.org/) | | **Dependency not detected** | Avoid shell variables (`${TOOL}`); use literal package names | | **Dependabot not opening PRs** | Verify `.github/dependabot.yml` is valid YAML and manifest files exist | ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [CLI Commands](/gh-aw/setup/cli/#compile) - Complete compile command reference * [Compilation Process](/gh-aw/reference/compilation-process/) - How compilation works * [GitHub Dependabot Docs](https://docs.github.com/en/code-security/dependabot) - Official Dependabot guide # APM Dependencies > Install and manage APM (Agent Package Manager) packages in your agentic workflows, including skills, prompts, instructions, agents, hooks, and plugins. [APM (Agent Package Manager)](https://microsoft.github.io/apm/) manages AI agent primitives such as skills, prompts, instructions, agents, hooks, and plugins (including the Claude `plugin.json` specification). Packages can depend on other packages and APM resolves the full dependency tree. APM is configured by importing the `shared/apm.md` workflow, which creates a dedicated `apm` job that packs packages and uploads the bundle as a GitHub Actions artifact. The agent job then downloads and unpacks the bundle for deterministic startup. ## Where `shared/apm.md` comes from [Section titled “Where shared/apm.md comes from”](#where-sharedapmmd-comes-from) `shared/apm.md` is a **local workflow file** that gh-aw resolves at `.github/workflows/shared/apm.md` in your repository — it is not a remote import (the `uses:` syntax inside `imports:` is gh-aw’s local-import shape, not GitHub Actions’ `uses: owner/repo@ref`). The canonical source is maintained in [microsoft/apm](https://github.com/microsoft/apm/blob/main/.github/workflows/shared/apm.md). Add it to your repository with: ```bash gh aw add microsoft/apm/.github/workflows/shared/apm.md --dir shared ``` Running `gh aw update` will keep your vendored copy in sync with the canonical source. The `shared/apm.md` file declares a `redirect` to the `microsoft/apm` library, so any copy sourced from gh-aw will automatically follow the redirect and rewrite its `source` field to track the canonical location on the next `gh aw update` run. The canonical version pins `microsoft/apm-action@v1.5.0` and supports multi-org GitHub App authentication (`apps:[]`) and multi-bundle restore. ## Usage [Section titled “Usage”](#usage) Import `shared/apm.md` and supply the list of packages via the `packages` parameter: ```aw imports: - uses: shared/apm.md with: packages: - microsoft/apm-sample-package - github/awesome-copilot/skills/review-and-refactor - anthropics/skills/skills/frontend-design ``` ## Reproducibility and governance [Section titled “Reproducibility and governance”](#reproducibility-and-governance) APM lock files (`apm.lock`) pin every package to an exact commit SHA, so the same versions are installed on every run. Lock file diffs appear in pull requests and are reviewable before merge, giving teams and enterprises a clear audit trail and the ability to govern which agent context is in use. See the [APM governance guide](https://microsoft.github.io/apm/enterprise/governance/) for details on policy enforcement and access controls. ## Package reference formats [Section titled “Package reference formats”](#package-reference-formats) Each entry in `packages` is an APM package reference. Supported formats: | Format | Description | | ------------------------------ | ------------------------------------------------------------------------- | | `owner/repo` | Full APM package | | `owner/repo/path/to/primitive` | Individual primitive (skill, instruction, plugin, etc.) from a repository | | `owner/repo#ref` | Package pinned to a tag, branch, or commit SHA | ### Examples [Section titled “Examples”](#examples) ```aw imports: - uses: shared/apm.md with: packages: # Full APM package - microsoft/apm-sample-package # Individual primitive from any repository - github/awesome-copilot/skills/review-and-refactor # Plugin (Claude plugin.json format) - github/awesome-copilot/plugins/context-engineering # Version-pinned to a tag - microsoft/apm-sample-package#v2.0 # Version-pinned to a branch - microsoft/apm-sample-package#main ``` ## How it works [Section titled “How it works”](#how-it-works) The `shared/apm.md` import adds a dedicated `apm` job to the compiled workflow. This job runs `microsoft/apm-action` to install packages and create a bundle archive, which is uploaded as a GitHub Actions artifact. The agent job downloads and restores the bundle as pre-steps, making all skills and tools available at runtime. Packages are fetched using the cascading token fallback: `GH_AW_PLUGINS_TOKEN` → `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN`. To reproduce or debug the pack/unpack flow locally, run `apm pack` and `apm unpack` directly. See the [pack and distribute guide](https://microsoft.github.io/apm/guides/pack-distribute/) for instructions. ## Reference [Section titled “Reference”](#reference) | Resource | URL | | ---------------------------- | ---------------------------------------------------------------------------- | | APM documentation | | | APM governance guide | | | Pack and distribute guide | | | gh-aw integration (APM docs) | | | apm-action (GitHub) | | | microsoft/apm (GitHub) | | | shared/apm.md (canonical) | | # Workflow Editors > A curated list of editors for authoring and previewing agentic workflows. The following editors can be used to author, compile, and preview agentic workflows. Some are built-in tools maintained alongside gh-aw; others are community-created projects. ### Compiler Playground [Section titled “Compiler Playground”](#compiler-playground) An **experimental** interactive browser-based playground that runs the gh-aw compiler entirely in the browser using [WebAssembly](/gh-aw/reference/wasm-compilation/). It demonstrates how to use the WASM build of the compiler directly in a webpage and shows how to compile workflows in the browser using the WASM-based execution engine. *  ## Community editors [Section titled “Community editors”](#community-editors) Note Community editors are created and maintained by independent contributors. They are not officially supported by the gh-aw project. ### Agentic Prompt Generator [Section titled “Agentic Prompt Generator”](#agentic-prompt-generator) A web-based tool for generating and editing agentic workflow prompts. It provides an interactive interface to help author workflow prompts for agentic workflows. *  ### Graphical Workflow Editor [Section titled “Graphical Workflow Editor”](#graphical-workflow-editor) A visual, graphical workflow editor that provides a richer UI for editing agentic workflows. Rather than working directly with markdown and YAML, this editor focuses on a more interactive and visual editing experience. *  # Effective Tokens Specification > Formal specification defining Effective Tokens (ET), a normalized metric for measuring LLM token usage across token classes, model multipliers, and multi-agent execution graphs # Effective Tokens Specification [Section titled “Effective Tokens Specification”](#effective-tokens-specification) **Version**: 0.2.0 **Status**: Draft **Publication Date**: 2026-04-02 **Editor**: GitHub Agentic Workflows Team **This Version**: [effective-tokens-specification](/gh-aw/reference/effective-tokens-specification/) **Latest Published Version**: This document *** ## Abstract [Section titled “Abstract”](#abstract) This specification defines **Effective Tokens (ET)**, a normalized unit for measuring Large Language Model (LLM) usage across token classes, model-relative computational intensity, and multi-invocation execution graphs. ET provides a single unified metric for composite LLM workloads including multi-step pipelines, tool-augmented calls, sub-agent orchestration, and recursive inference. ## Status of This Document [Section titled “Status of This Document”](#status-of-this-document) This section describes the status of this document at the time of publication. This is a draft specification and may be updated, replaced, or made obsolete by other documents at any time. This document is governed by the GitHub Agentic Workflows project specifications process. ## Table of Contents [Section titled “Table of Contents”](#table-of-contents) 1. [Introduction](#1-introduction) 2. [Conformance](#2-conformance) 3. [Terminology](#3-terminology) 4. [Token Accounting Model](#4-token-accounting-model) 5. [Multi-Invocation Aggregation](#5-multi-invocation-aggregation) 6. [Execution Graph Requirements](#6-execution-graph-requirements) 7. [Reporting](#7-reporting) 8. [Implementation Requirements](#8-implementation-requirements) 9. [Extensibility](#9-extensibility) 10. [Compliance Testing](#10-compliance-testing) 11. [Appendices](#appendices) 12. [Model Multiplier Registry](#model-multiplier-registry) 13. [Sync Notes](#sync-notes) 14. [References](#references) 15. [Change Log](#change-log) *** ## 1. Introduction [Section titled “1. Introduction”](#1-introduction) ### 1.1 Purpose [Section titled “1.1 Purpose”](#11-purpose) Token counts reported by LLM APIs are not directly comparable: different token classes (input, cached, output, reasoning) carry different computational costs, and different models have different relative costs. Effective Tokens normalizes these variables into a single scalar that reflects true computational intensity, enabling consistent measurement and comparison across complex multi-agent systems. ### 1.2 Scope [Section titled “1.2 Scope”](#12-scope) This specification covers: * Definition of token classes and their default weights * The per-invocation ET computation formula * Aggregation across multi-invocation execution graphs * Structural requirements for invocation nodes and summary reports This specification does NOT cover: * Billing, pricing, or cost allocation * Model selection or routing strategies * Streaming or partial token reporting ### 1.3 Design Goals [Section titled “1.3 Design Goals”](#13-design-goals) An ET implementation: 1. Preserves raw token counts per invocation 2. Normalizes across token classes using disclosed weights 3. Normalizes across models using per-model multipliers 4. Supports aggregation across any number of invocations 5. Produces a single reproducible metric from identical inputs 6. Carries no dependency on billing or pricing systems *** ## 2. Conformance [Section titled “2. Conformance”](#2-conformance) ### 2.1 Conformance Classes [Section titled “2.1 Conformance Classes”](#21-conformance-classes) **Conforming implementation**: An implementation that satisfies all MUST/SHALL requirements in this specification. **Partially conforming implementation**: An implementation that satisfies core accounting requirements (Sections 4–5) but omits optional fields or extensions. ### 2.2 Requirements Notation [Section titled “2.2 Requirements Notation”](#22-requirements-notation) The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). ### 2.3 Compliance Levels [Section titled “2.3 Compliance Levels”](#23-compliance-levels) * **Level 1 – Basic**: Single-invocation ET computation (Section 4) * **Level 2 – Standard**: Multi-invocation aggregation and execution graph (Sections 5–6) * **Level 3 – Complete**: Full reporting and extensibility support (Sections 7–9) *** ## 3. Terminology [Section titled “3. Terminology”](#3-terminology) ### 3.1 Token Classes [Section titled “3.1 Token Classes”](#31-token-classes) | Class | Symbol | Description | | ------------------- | ------ | ------------------------------------------------ | | Input Tokens | I | Tokens newly processed by the model | | Cached Input Tokens | C | Tokens served via cache or prefix reuse | | Output Tokens | O | Tokens generated by the model | | Reasoning Tokens | R | Internal tokens used during inference (optional) | ### 3.2 Model Multiplier [Section titled “3.2 Model Multiplier”](#32-model-multiplier) The **Copilot Multiplier** (`m`) is a scalar representing the relative computational intensity of a model versus a defined baseline. Its value is model-specific and MUST be disclosed by the implementation. ### 3.3 Invocation [Section titled “3.3 Invocation”](#33-invocation) A single LLM request-response cycle. Each invocation produces one set of token counts and yields one ET value. ### 3.4 Sub-Agent [Section titled “3.4 Sub-Agent”](#34-sub-agent) Any invocation triggered by another LLM call or orchestration layer. Examples include tool-using agents, retrieval-augmented calls, planning/execution agents, and recursively delegated LLM calls. ### 3.5 Execution Graph [Section titled “3.5 Execution Graph”](#35-execution-graph) A directed structure representing all invocations associated with a single top-level request. The root node has no parent; sub-agents reference their triggering invocation as their parent. ### 3.6 Execution-Graph Traversal Entities [Section titled “3.6 Execution-Graph Traversal Entities”](#36-execution-graph-traversal-entities) For deterministic aggregation and reporting, implementations MUST distinguish the following traversal entities when processing an execution graph: * **Local invocation cost**: The ET computed from the current node’s own `usage.*` payload only. * **Descendant contribution**: The subtotal accumulated from child nodes and deeper descendants before the current node’s local invocation cost is added. * **Observed subtree**: A subtree whose invocation nodes have concrete usage payloads and therefore contribute measured ET rather than fallback zeros. * **Unobservable subtree**: A subtree whose invocation nodes are known to exist but whose concrete usage payloads are unavailable; these nodes remain part of traversal order even when their ET is serialized as `0`. *** ## 4. Token Accounting Model [Section titled “4. Token Accounting Model”](#4-token-accounting-model) ### 4.1 Raw Token Count [Section titled “4.1 Raw Token Count”](#41-raw-token-count) For each invocation, the raw total is: ```plaintext raw_total_tokens = I + C + O + R ``` ### 4.2 Token Class Weights [Section titled “4.2 Token Class Weights”](#42-token-class-weights) Default weights for the four token classes are: | Token Class | Symbol | Default Weight | | ------------ | --------- | -------------- | | Input | w\_in | 1.0 | | Cached Input | w\_cache | 0.1 | | Output | w\_out | 4.0 | | Reasoning | w\_reason | 4.0 | Implementations MAY override these values but MUST disclose the weights used in any reported output. ### 4.3 Base Weighted Tokens [Section titled “4.3 Base Weighted Tokens”](#43-base-weighted-tokens) Per invocation: ```plaintext effective_input_tokens = max(I - C, 0) base_weighted_tokens = (w_in × effective_input_tokens) + (w_cache × C) + (w_out × O) + (w_reason × R) ``` When providers report cached reads (`C`) as part of input tokens (`I`), implementations MUST subtract cached input from `I` before applying `w_in` to avoid double counting. To avoid ambiguity, conforming implementations MUST treat these symbols as follows: * `I`: total reported input tokens for the invocation * `C`: cached subset of that same input * `w_in` MUST be applied only to `max(I - C, 0)` (the non-cached portion) * `w_cache` MUST be applied only to `C` Implementations MUST NOT charge the cached portion twice (once via `w_in × I` and again via `w_cache × C`). ### 4.4 Effective Tokens Per Invocation [Section titled “4.4 Effective Tokens Per Invocation”](#44-effective-tokens-per-invocation) ```plaintext effective_tokens = m × base_weighted_tokens ``` *** ## 5. Multi-Invocation Aggregation [Section titled “5. Multi-Invocation Aggregation”](#5-multi-invocation-aggregation) ### 5.1 Total Effective Tokens [Section titled “5.1 Total Effective Tokens”](#51-total-effective-tokens) For a request involving N invocations: ```plaintext ET_total = Σ (m_i × base_weighted_tokens_i) ``` Each invocation MAY use a different model and multiplier. ### 5.2 Total Raw Tokens [Section titled “5.2 Total Raw Tokens”](#52-total-raw-tokens) ```plaintext raw_total_tokens = Σ (I_i + C_i + O_i + R_i) ``` ### 5.3 Invocation Count [Section titled “5.3 Invocation Count”](#53-invocation-count) ```plaintext total_invocations = N ``` This count MUST include the root call, all sub-agent calls, and all tool-triggered LLM calls. *** ## 6. Execution Graph Requirements [Section titled “6. Execution Graph Requirements”](#6-execution-graph-requirements) Implementations MUST represent multi-call workflows as a directed execution graph. ### 6.1 Node Schema [Section titled “6.1 Node Schema”](#61-node-schema) Each node (invocation) MUST conform to: ```json { "id": "string", "parent_id": "string | null", "model": { "name": "string", "copilot_multiplier": number }, "usage": { "input_tokens": number, "cached_input_tokens": number, "output_tokens": number, "reasoning_tokens": number }, "derived": { "base_weighted_tokens": number, "effective_tokens": number }, "flagged": { "code": "string", "reason": "string" } } ``` ### 6.2 Root Invocation [Section titled “6.2 Root Invocation”](#62-root-invocation) The root invocation MUST have `parent_id = null`. It represents the user-facing request that initiates the execution graph. ### 6.3 Sub-Agent Invocations [Section titled “6.3 Sub-Agent Invocations”](#63-sub-agent-invocations) Each sub-agent invocation MUST reference a valid `parent_id`. Sub-agent invocations MAY recursively spawn further invocations. For execution graphs deeper than two levels, implementations MUST aggregate descendant Effective Tokens in stable post-order: fully observed leaf descendants first, then their nearest observed ancestors, and finally the parent node’s local invocation cost. When a parent has incomplete or unobservable descendants, the implementation MUST report the partial sum accumulated from the deepest observed descendants before adding any shallower fallback estimates, and SHOULD keep the parent node flagged until all known descendants are either observed or explicitly marked unobservable. Repeated computations over the same partially observed graph MUST produce the same partial-ordering and subtotal sequence. Implementation ordering constraints for multi-invocation aggregation: 1. Traverse child subtrees in deterministic order (for example, stable sibling order by invocation ID or first-seen sequence). 2. For each subtree, aggregate fully observed deepest descendants before applying fallback estimates for unobservable nodes in that same subtree. 3. Add the current node’s local invocation ET only after all descendant contributions for that node are finalized. *** ## 7. Reporting [Section titled “7. Reporting”](#7-reporting) A conforming response MUST include a `summary` object alongside the `invocations` array: ```json { "summary": { "total_invocations": number, "raw_total_tokens": number, "base_weighted_tokens": number, "effective_tokens": number }, "invocations": [ ... ] } ``` ### 7.1 OpenTelemetry Attribute Requirements [Section titled “7.1 OpenTelemetry Attribute Requirements”](#71-opentelemetry-attribute-requirements) Implementations that emit OpenTelemetry spans or metrics for token accounting MUST use the following normative attribute keys. These keys are not optional examples — they are required names for cross-implementation interoperability. | OTel Attribute Key | Type | Description | | --------------------------- | ------- | ---------------------------------------------------------------------------------- | | `llm.token.effective_total` | integer | Total Effective Tokens for the invocation (ET as defined in §4.4) | | `llm.token.input` | integer | Raw input token count for the invocation | | `llm.token.output` | integer | Raw output token count for the invocation | | `llm.token.cached_input` | integer | Number of input tokens served from cache | | `llm.token.base_weighted` | integer | Base weighted token value before model multiplier is applied | | `llm.model.multiplier` | float | The Copilot model multiplier (`m`) applied for this invocation | | `llm.invocation.id` | string | Unique identifier for this invocation node (matches `id` field in execution graph) | **R-OTL-001**: Implementations that emit OTel attributes for effective token data MUST use `llm.token.effective_total` as the attribute key for the ET value. Implementations MUST NOT use alternative keys (e.g., `effective_tokens`, `et_total`) for this attribute. **R-OTL-002**: Implementations MUST emit `llm.token.input`, `llm.token.output`, and `llm.token.cached_input` as separate span attributes when per-class token counts are available. These three attributes MUST reflect raw (unweighted) token counts. **R-OTL-003**: Implementations MUST emit `llm.token.base_weighted` as a span attribute when the base weighted token value is computed. This attribute allows consumers to audit the weighting step independently of the model multiplier. **R-OTL-004**: When `llm.model.multiplier` is emitted, its value MUST match the multiplier used to compute `llm.token.effective_total` for the same span. Implementations MUST NOT omit `llm.model.multiplier` if `llm.token.effective_total` is present. **R-OTL-005**: All OTel attribute keys defined in this section are versioned under this specification. Implementations MUST NOT rename or reuse these keys with different semantics without a specification revision. *** ## 8. Implementation Requirements [Section titled “8. Implementation Requirements”](#8-implementation-requirements) ### 8.1 Completeness [Section titled “8.1 Completeness”](#81-completeness) All LLM calls MUST be included in the execution graph. Hidden or system-triggered calls MUST be counted. ### 8.2 Determinism [Section titled “8.2 Determinism”](#82-determinism) Given identical inputs and multipliers, ET MUST be reproducible. Implementations SHOULD NOT introduce non-deterministic factors into the computation. ### 8.3 Versioning [Section titled “8.3 Versioning”](#83-versioning) Implementations SHOULD version their token weights and model multipliers so that historical reports remain interpretable. ### 8.4 Partial Visibility [Section titled “8.4 Partial Visibility”](#84-partial-visibility) When sub-agents are not fully observable, implementations MUST still report aggregate totals. Invocation nodes with incomplete data SHOULD be flagged to indicate missing information. ### 8.5 Safeguards [Section titled “8.5 Safeguards”](#85-safeguards) Implementations must prevent unbounded ET accumulation from producing non-finite or non-interoperable outputs. **R-SAFE-001**: ET aggregation logic **MUST** detect overflow and non-finite arithmetic states (`NaN`, `+Inf`, `-Inf`) before serializing output. **R-SAFE-002**: Implementations **MUST** enforce a maximum ET ceiling of `9007199254740991` (`2^53 - 1`) for serialized numeric fields to preserve JavaScript-safe integer interoperability in cross-language pipelines. **R-SAFE-003**: When computed ET exceeds the ceiling, implementations **MUST** clamp the reported `summary.effective_tokens` value to the ceiling and **MUST** emit a warning indicating that capping occurred. **R-SAFE-003A**: When ET capping occurs, implementations **MUST** record a deterministic overflow condition using either `flagged.code = "ET_OVERFLOW"` on the affected root/subtree node or a deterministic error when no structured flag channel is available. The error/flag payload **MUST** include the ceiling value `9007199254740991` so operators can distinguish overflow from missing usage data. **R-SAFE-004**: For long multi-agent chains, implementations **SHOULD** aggregate ET in a streaming manner (incremental updates per invocation) and **SHOULD** emit an early warning when running totals exceed 80% of the ceiling. **R-SAFE-005**: For invocation nodes with incomplete usage payloads (unobservable sub-agents), implementations **MUST** serialize `usage.input_tokens`, `usage.cached_input_tokens`, `usage.output_tokens`, `usage.reasoning_tokens`, `derived.base_weighted_tokens`, and `derived.effective_tokens` as numeric zero (`0`) rather than omitting those fields. **R-SAFE-006**: For invocation nodes that are incomplete/unobservable, implementations **MUST** include a `flagged` object with schema `{ "code": "UNOBSERVABLE_INVOCATION", "reason": string }`. For fully observed invocation nodes, implementations **MAY** omit `flagged`. **R-SAFE-007**: Before ET computation begins, implementations **MUST** validate the active model multiplier registry described in [Model Multiplier Registry](#model-multiplier-registry). Registry validation **MUST** confirm that `version` and `reference_model` are non-empty strings and that the reference model has a numeric multiplier entry. **R-SAFE-008**: Every declared token class weight and model multiplier loaded from the registry **MUST** be finite numeric data. `NaN`, infinite values, strings, `null`, and negative multiplier values **MUST** be rejected before any ET output is produced. **R-SAFE-009**: If registry validation fails, implementations **MUST NOT** continue with partially parsed multiplier data. They **MUST** fail deterministically with an error that identifies the invalid registry field or model entry. **R-SAFE-010**: When a runtime override or custom multiplier map is merged with the embedded registry, implementations **MUST** apply the same validation rules to the merged result before using it for ET computation. *** ## 9. Extensibility [Section titled “9. Extensibility”](#9-extensibility) Implementations MAY: * Add new token classes (e.g., `tool_tokens`) * Add latency or compute metadata per invocation node * Support streaming or partial progress updates Extensions MUST NOT alter the core ET definition or the default weight values without disclosure. *** ## 10. Compliance Testing [Section titled “10. Compliance Testing”](#10-compliance-testing) ### 10.1 Test Suite Requirements [Section titled “10.1 Test Suite Requirements”](#101-test-suite-requirements) #### 10.1.1 Token Accounting Tests [Section titled “10.1.1 Token Accounting Tests”](#1011-token-accounting-tests) * **T-ET-001**: Single invocation with all four token classes produces correct `base_weighted_tokens` * **T-ET-002**: Single invocation ET equals `m × base_weighted_tokens` * **T-ET-003**: Zero-value token classes do not affect the result * **T-ET-004**: Custom weights are applied when default weights are overridden * **T-ET-005**: Cached/input overlap is not double counted (`w_in` applies to `max(I-C,0)`, not `I`) * **T-ET-007**: Effective input is clamped at zero when `C > I` (`max(I-C,0)`) #### 10.1.2 Aggregation Tests [Section titled “10.1.2 Aggregation Tests”](#1012-aggregation-tests) * **T-ET-010**: Multi-invocation `ET_total` equals the sum of per-invocation ET values * **T-ET-011**: `raw_total_tokens` equals the sum of all raw tokens across all invocations * **T-ET-012**: `total_invocations` count includes root, sub-agents, and tool-triggered calls #### 10.1.3 Aggregation with Zero-ET Leaf Nodes [Section titled “10.1.3 Aggregation with Zero-ET Leaf Nodes”](#1013-aggregation-with-zero-et-leaf-nodes) * **T-ET-006**: Multi-invocation aggregation where one or more leaf invocation nodes have all token class values set to zero (simulating tool calls that produce no tokens, such as no-op tool invocations or tool calls whose usage data is unavailable). The implementation MUST: 1. Include the zero-ET invocation node in `total_invocations` count. 2. Contribute `0` to `ET_total` from that node (rather than omitting it). 3. Represent the node in the execution graph with all `usage.*` fields set to `0` and `derived.effective_tokens = 0`. 4. Not emit a warning or error solely because a leaf node has zero effective tokens. #### 10.1.4 Execution Graph Tests [Section titled “10.1.4 Execution Graph Tests”](#1014-execution-graph-tests) * **T-ET-020**: Root node has `parent_id = null` * **T-ET-021**: All sub-agent nodes reference a valid `parent_id` * **T-ET-022**: Node schema includes all required fields * **T-ET-032**: Deep (3+ level) execution graphs aggregate ET in deterministic post-order and keep partial subtotals stable under partial observability #### 10.1.5 Reporting Tests [Section titled “10.1.5 Reporting Tests”](#1015-reporting-tests) * **T-ET-030**: Summary object is present in all conforming responses * **T-ET-031**: Summary values are consistent with per-invocation data ### 10.2 Compliance Checklist [Section titled “10.2 Compliance Checklist”](#102-compliance-checklist) #### 10.2.1 Compliance Test Count Summary [Section titled “10.2.1 Compliance Test Count Summary”](#1021-compliance-test-count-summary) | Category | Count | | ------------------- | ----- | | Total tests defined | 16 | | Required tests | 16 | | Optional tests | 0 | Count method: unique `T-ET-*` IDs in §10.1 (`001–005`, `006`, `007`, `010–012`, `020–022`, `030–032`). | Requirement | Test ID | Level | Status | | ----------------------------------- | ---------------------- | ----- | ----------- | | Per-invocation base weighted tokens | T-ET-001–005, T-ET-007 | 1 | Implemented | | Per-invocation ET computation | T-ET-002 | 1 | Implemented | | Multi-invocation aggregation | T-ET-010–012 | 2 | Implemented | | Zero-ET leaf node aggregation | T-ET-006 | 2 | Required | | Execution graph node schema | T-ET-020–022 | 2 | Implemented | | Deep graph post-order aggregation | T-ET-032 | 2 | Required | | Summary reporting | T-ET-030–031 | 3 | Implemented | | Custom weight disclosure | T-ET-004 | 1 | Implemented | | Versioning of weights/multipliers | — | 3 | Recommended | | Partial visibility flagging | — | 2 | Recommended | *** ## Appendices [Section titled “Appendices”](#appendices) ### Appendix A: Worked Example [Section titled “Appendix A: Worked Example”](#appendix-a-worked-example) #### A.1 Scenario [Section titled “A.1 Scenario”](#a1-scenario) A request triggers three invocations: a root call, a retrieval sub-agent, and a final synthesis call. #### A.2 Input Data [Section titled “A.2 Input Data”](#a2-input-data) ```json { "invocations": [ { "id": "root", "parent_id": null, "model": { "name": "model-a", "copilot_multiplier": 2.0 }, "usage": { "input_tokens": 500, "cached_input_tokens": 200, "output_tokens": 150, "reasoning_tokens": 0 } }, { "id": "retrieval", "parent_id": "root", "model": { "name": "model-b", "copilot_multiplier": 1.0 }, "usage": { "input_tokens": 300, "cached_input_tokens": 0, "output_tokens": 100, "reasoning_tokens": 0 } }, { "id": "synthesis", "parent_id": "root", "model": { "name": "model-a", "copilot_multiplier": 2.0 }, "usage": { "input_tokens": 200, "cached_input_tokens": 100, "output_tokens": 250, "reasoning_tokens": 0 } } ] } ``` #### A.3 Computation [Section titled “A.3 Computation”](#a3-computation) ```plaintext root: base = (1.0 × max(500-200,0)) + (0.1 × 200) + (4.0 × 150) = 300 + 20 + 600 = 920 ET = 2.0 × 920 = 1840 retrieval: base = (1.0 × 300) + (4.0 × 100) = 300 + 400 = 700 ET = 1.0 × 700 = 700 synthesis: base = (1.0 × max(200-100,0)) + (0.1 × 100) + (4.0 × 250) = 100 + 10 + 1000 = 1110 ET = 2.0 × 1110 = 2220 ``` #### A.4 Output [Section titled “A.4 Output”](#a4-output) ```json { "summary": { "total_invocations": 3, "raw_total_tokens": 1800, "base_weighted_tokens": 2730, "effective_tokens": 4760 } } ``` #### A.5 Input vs Cached Conformance Test Vectors [Section titled “A.5 Input vs Cached Conformance Test Vectors”](#a5-input-vs-cached-conformance-test-vectors) These vectors are normative examples for overlap handling and are intended to be asserted by conformance tests. | Test ID | Inputs `(I,O,C,R)` | Base computation (default weights) | Expected `base_weighted_tokens` | | -------- | ------------------ | ------------------------------------- | ------------------------------: | | T-ET-005 | `(100, 0, 80, 0)` | `1.0×max(100-80,0) + 0.1×80 = 20 + 8` | 28 | | T-ET-007 | `(50, 0, 80, 0)` | `1.0×max(50-80,0) + 0.1×80 = 0 + 8` | 8 | #### A.6 Partial Observability Examples [Section titled “A.6 Partial Observability Examples”](#a6-partial-observability-examples) When some descendant invocations are unobservable, implementations still report deterministic partial totals and preserve stable ordering. **Example A (deep graph with one unobservable leaf):** ```text root ├─ planner │ ├─ retrieval (observed ET=120) │ │ └─ shard-1 (observed ET=60) │ └─ shard-2 (unobservable fallback ET=25) └─ synthesis (observed ET=40) ``` Deterministic post-order subtotal sequence: 1. `shard-1` → 60 2. `retrieval` local ET (120) → subtotal 180 3. `shard-2` fallback ET (25) → subtotal 205 4. `planner` local ET → subtotal 5. `synthesis` local ET → subtotal 6. `root` local ET → final total **Example B (all descendants unobservable):** If all descendants of a node are unobservable, that node MUST still be included with `derived.effective_tokens = 0` and `flagged.code = "UNOBSERVABLE_INVOCATION"` until concrete usage is observed. ### Appendix B: Core Formula Reference [Section titled “Appendix B: Core Formula Reference”](#appendix-b-core-formula-reference) ```plaintext ET_total = Σ [ m_i × (w_in × max(I_i - C_i, 0) + w_cache × C_i + w_out × O_i + w_reason × R_i) ] ``` With default weights: ```plaintext ET_total = Σ [ m_i × (max(I_i - C_i, 0) + 0.1 C_i + 4 O_i + 4 R_i) ] ``` ### Appendix C: Security Considerations [Section titled “Appendix C: Security Considerations”](#appendix-c-security-considerations) ET values are derived from token usage metadata. Implementations SHOULD treat per-invocation token data as potentially sensitive since usage patterns may reveal information about system prompts, model configurations, or user behavior. Aggregate ET values suitable for observability dashboards SHOULD be separated from detailed per-invocation data in access-controlled reporting systems. *** ## Model Multiplier Registry [Section titled “Model Multiplier Registry”](#model-multiplier-registry) ### Registry Purpose [Section titled “Registry Purpose”](#registry-purpose) The **Copilot Multiplier** (`m`) used in the ET formula is a per-model scalar that represents each model’s computational cost relative to the reference model. To ensure reproducibility and transparency, multiplier values MUST be sourced from a disclosed, versioned registry. ### Normative Registry Source [Section titled “Normative Registry Source”](#normative-registry-source) The authoritative registry for `copilot_multiplier` values in this implementation is the file: ```plaintext pkg/cli/data/model_multipliers.json ``` This file is embedded at compile time into the `gh-aw` binary using a Go `//go:embed` directive in `pkg/cli/effective_tokens.go`. The registry format is: ```json { "version": "string", "description": "string", "reference_model": "string", "token_class_weights": { "input": number, "cached_input": number, "output": number, "reasoning": number, "cache_write": number }, "multipliers": { "": number } } ``` ### Registry Requirements [Section titled “Registry Requirements”](#registry-requirements) **R-REG-001**: The registry MUST declare a `version` field that changes whenever any multiplier value is added, removed, or modified. **R-REG-002**: The registry MUST declare a `reference_model` field identifying the baseline model whose multiplier equals 1.0. All other multipliers are relative to this baseline. **R-REG-003**: The registry MUST include `token_class_weights` for all four standard token classes: `input`, `cached_input`, `output`, and `reasoning`. A conforming implementation MUST use these weights as the default values for Section 4.2. **R-REG-004**: Implementations MUST embed or bundle the registry at build time. Runtime fetching of multiplier values from an external source requires disclosure in reported output. **R-REG-005**: When a model name is not present in the registry, implementations MUST treat the multiplier as `1.0` and SHOULD emit a warning noting that the model is unrecognized. **R-REG-006**: Custom multipliers supplied by the caller (e.g., via API or configuration) MUST be merged with registry multipliers. Custom values take precedence and MUST be disclosed in any report that uses them. **R-REG-007**: The registry MUST NOT contain placeholder values such as `TBD`, `null`, or empty strings for any model multiplier entry. Each declared model key MUST map to a numeric multiplier value. **R-REG-008**: When adding support for a new model, maintainers MUST register the model in `pkg/cli/data/model_multipliers.json` with a concrete numeric multiplier before release. If calibration is incomplete, the model MUST be omitted from the registry and the implementation fallback behavior in R-REG-005 applies. **R-REG-009**: When a model is scheduled for removal from the registry, it MUST remain in `pkg/cli/data/model_multipliers.json` with a `deprecated` marker in a comment or companion metadata field for at least one minor version before it is deleted. Implementations SHOULD emit a warning when a `deprecated` model is encountered at runtime, advising callers to migrate to a supported model. A model entry MUST NOT be silently removed between consecutive minor versions; removal without the one-version deprecation notice is a breaking change and MUST be accompanied by a major version bump of the registry `version` field. ### Registry Versioning [Section titled “Registry Versioning”](#registry-versioning) The `version` field in `model_multipliers.json` corresponds to the registry schema version, not the gh-aw binary version. Implementations SHOULD include the registry version in all ET summary reports to enable historical reconstruction. *** ## Sync Notes [Section titled “Sync Notes”](#sync-notes) The Effective Tokens registry is maintained in `pkg/cli/data/model_multipliers.json` and loaded by `pkg/cli/effective_tokens.go`. To keep specification and implementation synchronized: 1. Update this specification’s registry requirements when adding, removing, or re-scaling model multipliers. 2. Update `pkg/cli/data/model_multipliers.json` in the same change. 3. When deprecating a model, add a `deprecated` comment alongside the entry and keep it in the registry for at least one minor version before removal (R-REG-009). Update the registry `version` field on removal. 4. Verify loading and fallback behavior in `pkg/cli/effective_tokens_test.go` (`TestModelMultipliersJSONEmbedded`, `TestResolveEffectiveWeightsDefault`, and inventory checks). 5. Run `make build` so the embedded registry is rebuilt into the `gh-aw` binary. 6. Re-run registry validation coverage after any registry edit so malformed multiplier entries fail before ET computation paths are exercised. Conforming releases SHOULD include a test assertion for newly added model multipliers to ensure implementation-registry parity. *** ## References [Section titled “References”](#references) ### Normative References [Section titled “Normative References”](#normative-references) * **\[RFC 2119]** Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. ### Informative References [Section titled “Informative References”](#informative-references) * **\[OPENAI-USAGE]** OpenAI API Reference — Usage Objects. * **\[ANTHROPIC-USAGE]** Anthropic API Reference — Token Usage. *** ## Change Log [Section titled “Change Log”](#change-log) ### Version 0.3.0 (Draft) [Section titled “Version 0.3.0 (Draft)”](#version-030-draft) * **Added**: Model Multiplier Registry section with normative requirements R-REG-001 through R-REG-009 * **Added**: R-REG-009: model deprecation/sunset lifecycle norm (models must carry a `deprecated` marker for one minor version before removal) * **Added**: Compliance test skeleton file `pkg/cli/effective_tokens_compliance_test.go` with Go test stubs for T-ET-001..T-ET-031 * **Added**: T-ET-032 requirement for deterministic post-order aggregation in deep (3+ level) partially observed execution graphs * **Updated**: Compliance checklist §10.2 status column from “Required” to “Implemented” for all test IDs T-ET-001–T-ET-031 (all tests now implemented and passing) * **Audit (Appendix C — Security)**: Verified Appendix C requirements against `pkg/cli/effective_tokens.go` and `pkg/cli/data/model_multipliers.json`. Findings: * *Sensitive usage patterns* (Appendix C §1): Per-invocation token data is not exposed directly by the CLI; only aggregate `TotalEffectiveTokens` is surfaced in the audit output. Access control is delegated to GitHub repository permissions. **No gaps found.** * *Aggregate vs. detailed data separation* (Appendix C §2): The `TokenUsageSummary.ByModel` map contains per-model breakdowns but is only logged at DEBUG level, not included in default CLI output. **No gaps found.** * *Registry exposure*: The embedded `model_multipliers.json` contains only multiplier coefficients, not secrets or PII. **No gaps found.** * *Follow-up*: The spec does not address token data leakage via OTEL attributes. This is tracked as a separate concern (see §7.3 of the Experiments Specification for precedent). ### Version 0.2.0 (Draft) [Section titled “Version 0.2.0 (Draft)”](#version-020-draft) * Adopted W3C-style specification format * Added conformance levels (Basic, Standard, Complete) * Added compliance testing section with test IDs * Added Appendix C: Security Considerations * Clarified partial visibility requirements ### Version 0.1.0 (Draft) [Section titled “Version 0.1.0 (Draft)”](#version-010-draft) * Initial definition of Effective Tokens metric * Defined four token classes and default weights * Defined per-invocation and multi-invocation formulas * Defined execution graph node schema *** *Copyright 2026 GitHub Agentic Workflows Team. All rights reserved.* # AI Engines (aka Coding Agents) > Complete guide to AI engines (coding agents) usable with GitHub Agentic Workflows, including Copilot, Claude, Codex, Gemini, Crush, OpenCode, and Pi with their specific configuration options. GitHub Agentic Workflows use [AI Engines](/gh-aw/reference/glossary/#engine) (normally a coding agent) to interpret and execute natural language instructions. ## Available Coding Agents [Section titled “Available Coding Agents”](#available-coding-agents) Set `engine:` in your workflow frontmatter and configure the corresponding secret: | Engine | `engine:` value | Required Secret | | ------------------------------------------------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) (default) | `copilot` | [COPILOT\_GITHUB\_TOKEN](/gh-aw/reference/auth/#copilot_github_token) | | [Claude by Anthropic (Claude Code)](https://www.anthropic.com/index/claude) | `claude` | [ANTHROPIC\_API\_KEY](/gh-aw/reference/auth/#anthropic_api_key) | | [OpenAI Codex](https://openai.com/blog/openai-codex) | `codex` | [OPENAI\_API\_KEY](/gh-aw/reference/auth/#openai_api_key) | | [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) | `gemini` | [GEMINI\_API\_KEY](/gh-aw/reference/auth/#gemini_api_key) | | [Crush](https://github.com/charmbracelet/crush) (experimental) | `crush` | [COPILOT\_GITHUB\_TOKEN](/gh-aw/reference/auth/#copilot_github_token) | | [OpenCode](https://opencode.ai) (experimental) | `opencode` | [COPILOT\_GITHUB\_TOKEN](/gh-aw/reference/auth/#copilot_github_token) | | [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (experimental) | `pi` | [COPILOT\_GITHUB\_TOKEN](/gh-aw/reference/auth/#copilot_github_token) (default); switches to provider-specific secret when `model:` uses `provider/model` format | Copilot CLI is the default — `engine:` can be omitted when using Copilot. See the linked authentication docs for secret setup instructions. ## Which engine should I choose? [Section titled “Which engine should I choose?”](#which-engine-should-i-choose) Choose the engine that best matches your needs and existing AI account: Copilot supports the broadest gh-aw feature set, including custom agents and autopilot-style continuations; Claude offers stronger control over turn limits (`max-turns`) for long reasoning sessions; and Gemini or Codex fit well when those models are already part of existing tooling or budget decisions. You can switch later by changing only `engine:` and the corresponding secret. ## Engine Feature Comparison [Section titled “Engine Feature Comparison”](#engine-feature-comparison) Not all features are available across all engines. The table below summarizes per-engine support for commonly used workflow options: | Feature | Copilot | Claude | Codex | Gemini | Crush | OpenCode | Pi | | ---------------------------------------- | :-----: | :-----: | :--------: | :-----: | :-----: | :------: | :-----: | | `max-runs` (AWF invocation cap) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | `max-turns` | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | | `max-continuations` | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | `tools.web-fetch` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | `tools.web-search` | via MCP | via MCP | ✓ (opt-in) | via MCP | via MCP | via MCP | via MCP | | `engine.agent` (custom agent file) | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | `engine.api-target` (custom endpoint) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | `engine.bare` (disable context loading) | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | | `engine.harness` (custom harness script) | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | Tools allowlist | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ | **Notes:** * `max-runs` is a top-level frontmatter field that maps to `apiProxy.maxRuns` and is supported by all engines. * `max-runs` defaults to `500` and `max-effective-tokens` defaults to `25000000` when omitted. * `max-turns` limits the number of AI chat iterations per run (Claude only). * `max-continuations` enables autopilot mode with multiple consecutive runs (Copilot only). * `web-search` for Codex is disabled by default; add `tools: web-search:` to enable it. Other engines use a third-party MCP server — see [Using Web Search](/gh-aw/reference/web-search/). * `engine.agent` references a `.github/agents/` file for custom Copilot agent behavior. See [Copilot Custom Configuration](#copilot-custom-configuration). * `engine.bare` disables automatic context loading (memory files, custom instructions). See [Bare Mode](#bare-mode-bare) below. * `engine.harness` allows replacing the built-in Copilot harness script. See [Custom Harness Script](#custom-harness-script-harness) below. ## Extended Coding Agent Configuration [Section titled “Extended Coding Agent Configuration”](#extended-coding-agent-configuration) Workflows can specify extended configuration for the coding agent: ```yaml engine: id: copilot version: latest # defaults to latest model: gpt-5 # example override; omit to use engine default command: /usr/local/bin/copilot # custom executable path args: ["--add-dir", "/workspace"] # custom CLI arguments agent: agent-id # custom agent file identifier api-target: api.acme.ghe.com # custom API endpoint hostname (GHEC/GHES) ``` ### Pinning a Specific Engine Version [Section titled “Pinning a Specific Engine Version”](#pinning-a-specific-engine-version) By default, workflows install the latest available version of each engine CLI. To pin to a specific version, set `version` to the desired release: | Engine | `id` | Example `version` | | ------------------ | ---------- | ----------------- | | GitHub Copilot CLI | `copilot` | `"0.0.422"` | | Claude Code | `claude` | `"2.1.70"` | | Codex | `codex` | `"0.111.0"` | | Gemini CLI | `gemini` | `"0.31.0"` | | Crush | `crush` | `"1.2.14"` | | OpenCode | `opencode` | `"0.1.0"` | | Pi | `pi` | `"0.72.1"` | ```yaml engine: id: copilot version: "0.0.422" ``` Pinning is useful when you need reproducible builds or want to avoid breakage from a new CLI release while testing. Remember to update the pinned version periodically to pick up bug fixes and new features. `version` also accepts a GitHub Actions expression string, enabling `workflow_call` reusable workflows to parameterize the engine version via caller inputs. Expressions are passed injection-safely through an environment variable rather than direct shell interpolation: ```yaml on: workflow_call: inputs: engine-version: type: string default: latest --- engine: id: copilot version: ${{ inputs.engine-version }} ``` ### Copilot Custom Configuration [Section titled “Copilot Custom Configuration”](#copilot-custom-configuration) Use `agent` to reference a custom agent file in `.github/agents/` (omit the `.agent.md` extension): ```yaml engine: id: copilot agent: technical-doc-writer # .github/agents/technical-doc-writer.agent.md ``` See [Copilot Agent Files](/gh-aw/reference/copilot-custom-agents/) for details. ### Engine Environment Variables [Section titled “Engine Environment Variables”](#engine-environment-variables) All engines support custom environment variables through the `env` field: ```yaml engine: id: copilot env: DEBUG_MODE: "true" AWS_REGION: us-west-2 CUSTOM_API_ENDPOINT: https://api.example.com ``` Environment variables can also be defined at workflow, job, step, and other scopes. See [Environment Variables](/gh-aw/reference/environment-variables/) for complete documentation on precedence and all 13 env scopes. ### Enterprise API Endpoint (`api-target`) [Section titled “Enterprise API Endpoint (api-target)”](#enterprise-api-endpoint-api-target) The `api-target` field specifies a custom API endpoint hostname for the agentic engine. Use this when running workflows against GitHub Enterprise Cloud (GHEC), GitHub Enterprise Server (GHES), or any custom AI endpoint. For a complete setup and debugging walkthrough for GHE Cloud with data residency, see [Debugging GHE Cloud with Data Residency](/gh-aw/troubleshooting/debug-ghe/). The value must be a hostname only — no protocol or path (e.g., `api.acme.ghe.com`, not `https://api.acme.ghe.com/v1`). The field works with any engine. **GHEC example** — specify your tenant-specific Copilot endpoint: ```yaml engine: id: copilot api-target: api.acme.ghe.com network: allowed: - defaults - acme.ghe.com - api.acme.ghe.com ``` **GHES example** — use the enterprise Copilot endpoint: ```yaml engine: id: copilot api-target: api.enterprise.githubcopilot.com network: allowed: - defaults - github.company.com - api.enterprise.githubcopilot.com ``` The specified hostname must also be listed in `network.allowed` for the firewall to permit outbound requests. #### Custom API Endpoints via Environment Variables [Section titled “Custom API Endpoints via Environment Variables”](#custom-api-endpoints-via-environment-variables) Set a base URL environment variable in `engine.env` to route API calls to an internal LLM router, Azure OpenAI deployment, or corporate proxy. AWF automatically extracts the hostname and applies it to the API proxy. The target domain must also appear in `network.allowed`. | Engine | Environment variable | | ---------------- | ------------------------- | | `codex`, `crush` | `OPENAI_BASE_URL` | | `claude` | `ANTHROPIC_BASE_URL` | | `copilot` | `GITHUB_COPILOT_BASE_URL` | | `gemini` | `GEMINI_API_BASE_URL` | ```yaml engine: id: codex model: gpt-4o env: OPENAI_BASE_URL: "https://llm-router.internal.example.com/v1" OPENAI_API_KEY: ${{ secrets.LLM_ROUTER_KEY }} network: allowed: - github.com - llm-router.internal.example.com ``` `GITHUB_COPILOT_BASE_URL` is a fallback — if both it and `engine.api-target` are set, `engine.api-target` takes precedence. Crush uses OpenAI-compatible API format; its `model` field uses `provider/model` format (e.g., `openai/gpt-4o`). ### Copilot Bring Your Own Key (BYOK) Mode [Section titled “Copilot Bring Your Own Key (BYOK) Mode”](#copilot-bring-your-own-key-byok-mode) The Copilot engine supports routing requests to an external LLM provider instead of GitHub’s default routing. This is useful when you want to use a different model or provider (e.g., OpenAI, Anthropic, Azure OpenAI, or a local Ollama/vLLM instance) while still using the Copilot CLI tooling. Set `COPILOT_PROVIDER_BASE_URL` in `engine.env` to activate BYOK mode. The credential variables `COPILOT_PROVIDER_BASE_URL`, `COPILOT_PROVIDER_API_KEY`, and `COPILOT_PROVIDER_BEARER_TOKEN` are explicitly allowed to carry `${{ secrets.* }}` references in `engine.env` under strict mode — they are not leaked to the agent container. Other `COPILOT_PROVIDER_*` variables hold non-sensitive configuration and can be set as plain strings. | Variable | Required | Description | | ------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- | | `COPILOT_PROVIDER_BASE_URL` | ✓ for BYOK | Base URL of the external provider (e.g. `https://api.openai.com/v1`) | | `COPILOT_MODEL` | ✓ for BYOK | Model to use (e.g. `claude-sonnet-4`, `gpt-4o`); required by most providers | | `COPILOT_PROVIDER_API_KEY` | Optional | API key for cloud providers (OpenAI, Anthropic, etc.); not needed for local providers | | `COPILOT_PROVIDER_BEARER_TOKEN` | Optional | Bearer token alternative to `COPILOT_PROVIDER_API_KEY`; takes precedence when set | | `COPILOT_PROVIDER_TYPE` | Optional | Provider format: `openai` (default), `azure`, or `anthropic` | | `COPILOT_PROVIDER_WIRE_API` | Optional | Wire API variant: `completions` (default) or `responses` (for GPT-5 series) | | `COPILOT_PROVIDER_MODEL_ID` | Optional | Model ID sent on the wire when it differs from `COPILOT_MODEL` (e.g. an Azure deployment name) | | `COPILOT_PROVIDER_WIRE_MODEL` | Optional | Alternative to `COPILOT_PROVIDER_MODEL_ID` for overriding the wire model | | `COPILOT_PROVIDER_MAX_PROMPT_TOKENS` | Optional | Override the maximum prompt token limit (otherwise resolved from model catalog) | | `COPILOT_PROVIDER_MAX_OUTPUT_TOKENS` | Optional | Override the maximum output token limit | **Example: OpenAI-compatible provider** ```yaml engine: id: copilot env: # REQUIRED — activates BYOK mode COPILOT_PROVIDER_BASE_URL: ${{ secrets.PROVIDER_BASE_URL }} # REQUIRED — a model must be specified for most external providers COPILOT_MODEL: claude-sonnet-4 # OPTIONAL — API key for cloud providers; not needed for local providers COPILOT_PROVIDER_API_KEY: ${{ secrets.PROVIDER_API_KEY }} # OPTIONAL — set to "anthropic" or "azure" if needed (default: "openai") # COPILOT_PROVIDER_TYPE: anthropic network: allowed: - defaults - your-provider-domain.example.com ``` **Example: Anthropic provider** ```yaml engine: id: copilot env: COPILOT_PROVIDER_BASE_URL: ${{ secrets.ANTHROPIC_BASE_URL }} COPILOT_MODEL: claude-sonnet-4 COPILOT_PROVIDER_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} COPILOT_PROVIDER_TYPE: anthropic ``` Note `COPILOT_PROVIDER_BASE_URL`, `COPILOT_PROVIDER_API_KEY`, and `COPILOT_PROVIDER_BEARER_TOKEN` are recognized as engine credentials and are allowed to carry `${{ secrets.* }}` references in `engine.env` without triggering the strict-mode “secrets in env” warning. Other `COPILOT_PROVIDER_*` variables (type, model, token limits) hold non-sensitive configuration and can be set as plain strings. They may also use `${{ secrets.* }}` syntax if you prefer to keep them private, but this is not required. Note Credentials passed via `COPILOT_PROVIDER_*` variables are kept out of the agent container. Only the dummy API key that activates the Agentic Workflow Firewall (AWF) BYOK detection path is visible to the agent process; the real credential is isolated in the AWF API proxy sidecar. See the [AWF sandbox architecture](/gh-aw/reference/sandbox/) for details. ### Engine Command-Line Arguments [Section titled “Engine Command-Line Arguments”](#engine-command-line-arguments) All engines support custom command-line arguments through the `args` field, injected before the prompt: ```yaml engine: id: copilot args: ["--add-dir", "/workspace", "--verbose"] ``` Arguments are added in order and placed before the `--prompt` flag. Consult the specific engine’s CLI documentation for available flags. ### Custom Engine Command [Section titled “Custom Engine Command”](#custom-engine-command) Override the default engine executable using the `command` field. Useful for testing pre-release versions, custom builds, or non-standard installations. Installation steps are automatically skipped. ```yaml engine: id: copilot command: /usr/local/bin/copilot-dev # absolute path args: ["--verbose"] ``` ### Custom Harness Script (`harness`) [Section titled “Custom Harness Script (harness)”](#custom-harness-script-harness) The `harness` field lets you replace the built-in Node.js harness wrapper that the Copilot engine uses to launch the CLI. Use this when you need to customize startup behavior, inject pre/post hooks, or test an alternative harness implementation. ```yaml engine: id: copilot harness: custom_copilot_harness.cjs ``` The value must be a bare filename — no directory separators, no `..`, and no shell metacharacters. It must end with `.js`, `.cjs`, or `.mjs`. When `harness` is set, AWF automatically ensures Node 24 is available in the runner environment. Note `engine.harness` is currently only applied during Copilot engine execution. Setting it on other engines has no effect. **Validation rules:** | Rule | Valid example | Invalid example | | -------------------------------------- | ---------------- | -------------------- | | Bare filename only | `my_harness.cjs` | `subdir/harness.cjs` | | No path traversal | `harness.mjs` | `../harness.cjs` | | Must start with `[A-Za-z0-9_]` | `harness.js` | `-harness.cjs` | | Must end with `.js`, `.cjs`, or `.mjs` | `wrapper.cjs` | `harness.sh` | ### Bare Mode (`bare`) [Section titled “Bare Mode (bare)”](#bare-mode-bare) Set `engine.bare: true` to disable automatic loading of context and custom instructions by the engine. Use this when the workflow prompt is fully self-contained and you want to prevent the engine from reading memory files, AGENTS.md, or built-in system prompts that would otherwise be loaded automatically. ```yaml engine: id: claude bare: true ``` The underlying mechanism is engine-specific: | Engine | Effect | | ------- | ----------------------------------------------------------------------------------------------------- | | Copilot | Passes `--no-custom-instructions` — suppresses `.github/AGENTS.md` and user-level custom instructions | | Claude | Passes `--bare` — suppresses CLAUDE.md memory files | | Codex | Passes `--no-system-prompt` — suppresses the default system prompt | | Gemini | Sets `GEMINI_SYSTEM_MD=/dev/null` — overrides the built-in system prompt with an empty file | Defaults to `false`. ### Custom Token Weights (`token-weights`) [Section titled “Custom Token Weights (token-weights)”](#custom-token-weights-token-weights) Override the built-in token cost multipliers used when computing [Effective Tokens](/gh-aw/reference/effective-tokens-specification/). Useful when your workflow uses a custom model not in the built-in list, or when you want to adjust the relative cost ratios for your use case. ```yaml engine: id: claude token-weights: multipliers: my-custom-model: 2.5 # 2.5x the cost of claude-sonnet-4.5 experimental-llm: 0.8 # Override an existing model's multiplier token-class-weights: output: 6.0 # Override output token weight (default: 4.0) cached-input: 0.05 # Override cached input weight (default: 0.1) ``` `multipliers` is a map of model names to numeric multipliers relative to `claude-sonnet-4.5` (= 1.0). Keys are case-insensitive and support prefix matching. `token-class-weights` overrides the per-class weights applied before the model multiplier; the defaults are `input: 1.0`, `cached-input: 0.1`, `output: 4.0`, `reasoning: 4.0`, `cache-write: 1.0`. Custom weights are embedded in the compiled workflow YAML and read by `gh aw logs` and `gh aw audit` when analyzing runs. ## Timeout Configuration [Section titled “Timeout Configuration”](#timeout-configuration) Repositories with long build or test cycles require careful timeout tuning at multiple levels. This section documents the timeout knobs available for each engine. ### Job-Level Timeout (`timeout-minutes`) [Section titled “Job-Level Timeout (timeout-minutes)”](#job-level-timeout-timeout-minutes) `timeout-minutes` sets the maximum wall-clock time for the entire agent job. This is the primary knob for repositories with long build times. The default is 20 minutes. ```yaml timeout-minutes: 60 # allow up to 60 minutes for the agent job ``` See [Long Build Times](/gh-aw/reference/sandbox/#long-build-times) in the Sandbox reference for recommended values and concrete examples, including a 30-minute C++ workflow. ### Per-Tool-Call Timeout (`tools.timeout`) [Section titled “Per-Tool-Call Timeout (tools.timeout)”](#per-tool-call-timeout-toolstimeout) `tools.timeout` limits how long any single tool invocation may run, in seconds. Useful when individual `bash` commands (builds, test suites) take longer than an engine’s default: ```yaml tools: timeout: 300 # 5 minutes per tool call ``` | Engine | Default tool timeout | | ------- | -------------------------------------- | | Copilot | not enforced by gh-aw (engine-managed) | | Claude | 60 s | | Codex | 120 s | | Gemini | not enforced by gh-aw (engine-managed) | | Crush | not enforced by gh-aw (engine-managed) | See [Tool Timeout Configuration](/gh-aw/reference/tools/#tool-timeout-configuration) for full documentation including `tools.startup-timeout`. ### Per-Engine Timeout Controls [Section titled “Per-Engine Timeout Controls”](#per-engine-timeout-controls) #### Copilot [Section titled “Copilot”](#copilot) Copilot does not expose a per-turn wall-clock time limit directly. Use `max-continuations` to control how many sequential agent runs are allowed in autopilot mode, and `timeout-minutes` for the overall job budget: ```yaml engine: id: copilot max-continuations: 3 # up to 3 consecutive autopilot runs timeout-minutes: 60 ``` #### Claude [Section titled “Claude”](#claude) Claude supports `max-turns` to cap the number of AI iterations per run. Set it together with `tools.timeout` to control both breadth (number of turns) and depth (time per tool call): ```yaml engine: id: claude max-turns: 20 # maximum number of agentic iterations tools: timeout: 600 # 10 minutes per bash/tool call timeout-minutes: 60 ``` The `CLAUDE_CODE_MAX_TURNS` environment variable is a Claude Code CLI equivalent of `max-turns`. When `max-turns` is set in frontmatter, gh-aw passes it to the Claude CLI automatically — you do not need to set this env var separately. #### Codex, Gemini, and Crush [Section titled “Codex, Gemini, and Crush”](#codex-gemini-and-crush) These engines do not support `max-turns` or `max-continuations`. Use `timeout-minutes` and `tools.timeout` to bound execution: ```yaml tools: timeout: 300 timeout-minutes: 60 ``` ### Summary Table [Section titled “Summary Table”](#summary-table) | Timeout knob | Copilot | Claude | Codex | Gemini | Crush | OpenCode | Notes | | ----------------------- | :-----: | :----: | :---: | :----: | :---: | :------: | ----------------------------------- | | `timeout-minutes` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | Job-level wall clock | | `tools.timeout` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | Per tool-call limit (seconds) | | `tools.startup-timeout` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | MCP server startup limit | | `max-turns` | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | Iteration budget (Claude only) | | `max-continuations` | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | Autopilot run budget (Copilot only) | ## Claude Tool Enforcement Security Model [Section titled “Claude Tool Enforcement Security Model”](#claude-tool-enforcement-security-model) Claude Code uses one of two permission modes at runtime, and which mode is selected determines whether the declared `tools:` allowlist is enforced: ### `acceptEdits` mode (default) [Section titled “acceptEdits mode (default)”](#acceptedits-mode-default) By default, gh-aw starts Claude Code with `--permission-mode acceptEdits`. In this mode, Claude honors the `--allowed-tools` flag. The workflow’s declared `tools:` and `mcp-servers: allowed:` configuration is compiled into an explicit allowlist and passed to the Claude CLI. Only the tools listed there are accessible to the agent. ### `bypassPermissions` mode (unrestricted bash) [Section titled “bypassPermissions mode (unrestricted bash)”](#bypasspermissions-mode-unrestricted-bash) When the workflow grants unrestricted bash access — `bash: "*"`, `bash: [":*"]`, or `bash: null` — gh-aw switches to `--permission-mode bypassPermissions`. **In this mode, Claude Code silently ignores `--allowed-tools`.** Every tool exposed by the MCP gateway is reachable regardless of the workflow’s declared tool configuration. Caution Do not rely on `tools:` or `mcp-servers: allowed:` for security guarantees when unrestricted bash is granted. In `bypassPermissions` mode, the agent can already run arbitrary shell commands, so `--allowed-tools` provides no meaningful additional boundary. ### Gateway-side enforcement [Section titled “Gateway-side enforcement”](#gateway-side-enforcement) The **MCP gateway’s `allowed:` filter is the sole effective tool boundary in `bypassPermissions` mode** (and a second layer of enforcement in `acceptEdits` mode). gh-aw compiles the `allowed:` list from each `mcp-servers:` entry into the gateway configuration before the agent starts. The gateway enforces this list server-side, regardless of what the agent requests. ```yaml mcp-servers: notion: container: "mcp/notion" allowed: ["search_pages", "get_page"] # enforced at gateway level ``` ### Summary [Section titled “Summary”](#summary) | Workflow config | Permission mode | `--allowed-tools` enforced? | Gateway `allowed:` enforced? | | ------------------------------------------- | ------------------- | :-------------------------: | :--------------------------: | | No unrestricted bash | `acceptEdits` | ✓ Yes | ✓ Yes | | `bash: "*"` / `bash: [":*"]` / `bash: null` | `bypassPermissions` | ✗ No | ✓ Yes | For workflows that must restrict which MCP tools are accessible, always specify `allowed:` on each `mcp-servers:` entry. This applies regardless of whether unrestricted bash is used. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Frontmatter](/gh-aw/reference/frontmatter/) - Complete configuration reference * [Tools](/gh-aw/reference/tools/) - Available tools and MCP servers * [Security Guide](/gh-aw/introduction/architecture/) - Security considerations for AI engines * [MCPs](/gh-aw/guides/mcps/) - Model Context Protocol setup and configuration * [Long Build Times](/gh-aw/reference/sandbox/#long-build-times) - Timeout tuning for large repositories * [Self-Hosted Runners](/gh-aw/guides/self-hosted-runners/) - Fast hardware for long-running workflows # Enterprise Configuration > Configure GitHub Agentic Workflows for GitHub Enterprise Server (GHES) and GitHub Enterprise Cloud (GHEC), including artifact compatibility and CLI setup. # Enterprise Configuration [Section titled “Enterprise Configuration”](#enterprise-configuration) This page covers configuration options specific to GitHub Enterprise Server (GHES) and GitHub Enterprise Cloud (GHEC) deployments. ## GitHub Enterprise Server (GHES) Compatibility [Section titled “GitHub Enterprise Server (GHES) Compatibility”](#github-enterprise-server-ghes-compatibility) ### Artifact Compatibility Mode [Section titled “Artifact Compatibility Mode”](#artifact-compatibility-mode) GHES instances running versions that predate `@actions/artifact` v2.0.0 support cannot use `actions/upload-artifact@v4+` or `actions/download-artifact@v4+`. Attempting to run compiled workflows on these instances produces a `GHESNotSupportedError`. gh-aw includes a GHES compatibility mode that instructs the compiler to emit `upload-artifact@v3.2.2` and `download-artifact@v3.1.0` instead of the latest v4+ versions. #### Enable via `aw.json` (recommended) [Section titled “Enable via aw.json (recommended)”](#enable-via-awjson-recommended) Set `ghes: true` in `.github/workflows/aw.json` to apply GHES compatibility to every workflow compiled in the repository: ```json { "ghes": true } ``` #### Auto-detection with `gh aw init` [Section titled “Auto-detection with gh aw init”](#auto-detection-with-gh-aw-init) Running `gh aw init` inside a GHES repository automatically detects the deployment and writes `ghes: true` to `.github/workflows/aw.json`. No manual configuration is required. #### Enable via CLI flag [Section titled “Enable via CLI flag”](#enable-via-cli-flag) Pass `--ghes` to `gh aw compile` for a one-off compilation without modifying `aw.json`: ```bash gh aw compile --ghes my-workflow.md ``` Note The `--ghes` flag only affects the current compilation. Use `aw.json` to apply GHES compatibility permanently across all workflows in the repository. ## GitHub Enterprise Server CLI Setup [Section titled “GitHub Enterprise Server CLI Setup”](#github-enterprise-server-cli-setup) For `gh` CLI configuration, host authentication, and `GH_HOST` setup on GHES, see [GitHub Enterprise Server Support](/gh-aw/setup/cli/#github-enterprise-server-support) in the CLI reference. ## Copilot Engine on GHES [Section titled “Copilot Engine on GHES”](#copilot-engine-on-ghes) For Copilot-specific prerequisites, licensing requirements, and firewall configuration on GHES, see [Copilot Engine Prerequisites on GHES](/gh-aw/troubleshooting/common-issues/#copilot-engine-prerequisites-on-ghes). # Environment Variables > Reference for all environment variables in GitHub Agentic Workflows — CLI configuration, model overrides, guard policy fallbacks, and workflow-level scope precedence Environment variables in GitHub Agentic Workflows can be defined at multiple scopes, each serving a specific purpose in the workflow lifecycle. Variables defined at more specific scopes override those at more general scopes, following GitHub Actions conventions while adding AWF-specific contexts. ## Environment Variable Scopes [Section titled “Environment Variable Scopes”](#environment-variable-scopes) GitHub Agentic Workflows supports environment variables in 13 distinct contexts: | Scope | Syntax | Context | Typical Use | | ----------------------- | ------------------------------ | ------------------------------------ | ------------------------- | | **Workflow-level** | `env:` | All jobs | Shared configuration | | **Job-level** | `jobs..env` | All steps in job | Job-specific config | | **Step-level** | `steps[*].env` | Single step | Step-specific config | | **Engine** | `engine.env` | AI engine | Engine secrets, timeouts | | **Container** | `container.env` | Container runtime | Container settings | | **Services** | `services..env` | Service containers | Database credentials | | **Sandbox Agent** | `sandbox.agent.env` | Sandbox runtime | Sandbox configuration | | **Sandbox MCP** | `sandbox.mcp.env` | Model Context Protocol (MCP) gateway | MCP debugging | | **MCP Tools** | `tools..env` | MCP server process | MCP server secrets | | **MCP Scripts** | `mcp-scripts..env` | MCP script execution | Tool-specific tokens | | **Safe Outputs Global** | `safe-outputs.env` | All safe-output jobs | Shared safe-output config | | **Safe Outputs Job** | `safe-outputs.jobs..env` | Specific safe-output job | Job-specific config | | **GitHub Actions Step** | `githubActionsStep.env` | Pre-defined steps | Step configuration | ### Example Configurations [Section titled “Example Configurations”](#example-configurations) **Workflow-level shared configuration:** ```yaml --- env: NODE_ENV: production API_ENDPOINT: https://api.example.com --- ``` **Job-specific overrides:** ```yaml --- jobs: validation: env: VALIDATION_MODE: strict steps: - run: npm run build env: BUILD_ENV: production # Overrides job and workflow levels --- ``` **AWF-specific contexts:** ```yaml --- # Engine configuration engine: id: copilot env: OPENAI_API_KEY: ${{ secrets.CUSTOM_KEY }} # MCP server with secrets tools: database: command: npx args: ["-y", "mcp-server-postgres"] env: DATABASE_URL: ${{ secrets.DATABASE_URL }} # Safe outputs with custom PAT safe-outputs: create-issue: env: GITHUB_TOKEN: ${{ secrets.CUSTOM_PAT }} --- ``` ## Agent Step Summary (`GITHUB_STEP_SUMMARY`) [Section titled “Agent Step Summary (GITHUB\_STEP\_SUMMARY)”](#agent-step-summary-github_step_summary) Agents can write markdown content to the `$GITHUB_STEP_SUMMARY` environment variable to publish a formatted summary visible in the GitHub Actions run view. Inside the AWF sandbox, `$GITHUB_STEP_SUMMARY` is redirected to a file at `/tmp/gh-aw/agent-step-summary.md`. After agent execution completes, the framework automatically appends the contents of that file to the real GitHub step summary. Secret redaction runs before the content is published. Note The first 2000 characters of the summary are appended. If the content is longer, a `[truncated: ...]` notice is included. Write your most important content first. Example: an agent writing a brief analysis result to the step summary: ```bash echo "## Analysis complete" >> "$GITHUB_STEP_SUMMARY" echo "Found 3 issues across 12 files." >> "$GITHUB_STEP_SUMMARY" ``` The output appears in the **Summary** tab of the GitHub Actions workflow run. ## System-Injected Runtime Variables [Section titled “System-Injected Runtime Variables”](#system-injected-runtime-variables) GitHub Agentic Workflows automatically injects the following environment variables into every agentic engine execution step (both the main agent run and the threat detection run). These variables are read-only from the agent’s perspective and are useful for writing workflows or agents that need to detect their execution context. | Variable | Value | Description | | --------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GITHUB_AW` | `"true"` | Present in every gh-aw engine execution step. Agents can check for this variable to confirm they are running inside a GitHub Agentic Workflow. | | `GH_AW_PHASE` | `"agent"` or `"detection"` | Identifies which execution phase is active. `"agent"` for the main run; `"detection"` for the threat-detection safety check run that precedes the main run. | | `GH_AW_VERSION` | e.g. `"0.40.1"` | The gh-aw compiler version that generated the workflow. Useful for conditional logic that depends on a minimum feature version. | These variables appear alongside other `GH_AW_*` context variables in the compiled workflow: ```yaml env: GITHUB_AW: "true" GH_AW_PHASE: agent # or "detection" GH_AW_VERSION: "0.40.1" GH_AW_PROMPT: /tmp/gh-aw/aw-prompts/prompt.txt ``` Note These variables are injected by the compiler and cannot be overridden by user-defined `env:` blocks in the workflow frontmatter. ## CLI Configuration Variables [Section titled “CLI Configuration Variables”](#cli-configuration-variables) These variables configure the `gh aw` CLI tool. Set them in your local shell environment or as repository/organization variables in GitHub Actions. | Variable | Default | Description | | -------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DEBUG` | disabled | npm-style namespace debug logging. `DEBUG=*` enables all output; `DEBUG=cli:*,workflow:*` selects specific namespaces. Exclusions are supported: `DEBUG=*,-workflow:test`. Also activated when `ACTIONS_RUNNER_DEBUG=true`. | | `DEBUG_COLORS` | `1` (enabled) | Set to `0` to disable ANSI colors in debug output. Colors are automatically disabled when output is not a TTY. | | `ACCESSIBLE` | empty | Any non-empty value enables accessibility mode, which disables spinners and animations. Also enabled when `TERM=dumb` or `NO_COLOR` is set. | | `NO_COLOR` | empty | Any non-empty value disables colored output and enables accessibility mode. Follows the [no-color.org](https://no-color.org/) standard. | | `GH_AW_ACTION_MODE` | auto-detected | Overrides how JavaScript is embedded in compiled workflows. Valid values: `dev`, `release`, `script`, `action`. When unset, the CLI auto-detects the appropriate mode. | | `GH_AW_FEATURES` | empty | Comma-separated list of experimental feature flags to enable globally. Values in workflow `features:` frontmatter take precedence over this variable. | | `GH_AW_MAX_CONCURRENT_DOWNLOADS` | `10` | Maximum number of parallel log and artifact downloads for `gh aw logs`. Valid range: `1`–`100`. | | `GH_AW_MCP_SERVER` | unset | When set, disables the automatic update check. Set automatically when `gh aw` runs as an MCP server subprocess — no manual configuration needed. | **Enabling debug logging:** ```bash # All namespaces DEBUG=* gh aw compile # Specific namespaces DEBUG=cli:*,workflow:* gh aw compile # Without colors DEBUG_COLORS=0 DEBUG=* gh aw compile ``` *** ## Model Override Variables [Section titled “Model Override Variables”](#model-override-variables) These variables override the default AI model used for agent runs and threat detection. Set them as GitHub Actions repository or organization variables to apply org-wide defaults without modifying workflow frontmatter. Note The `engine.model:` field in workflow frontmatter takes precedence over these variables. ### Agent runs [Section titled “Agent runs”](#agent-runs) | Variable | Engine | | --------------------------- | ---------------- | | `GH_AW_MODEL_AGENT_COPILOT` | GitHub Copilot | | `GH_AW_MODEL_AGENT_CLAUDE` | Anthropic Claude | | `GH_AW_MODEL_AGENT_CODEX` | OpenAI Codex | | `GH_AW_MODEL_AGENT_GEMINI` | Google Gemini | | `GH_AW_MODEL_AGENT_CRUSH` | Crush | | `GH_AW_MODEL_AGENT_CUSTOM` | Custom engine | ### Detection runs [Section titled “Detection runs”](#detection-runs) | Variable | Engine | | ------------------------------- | ---------------- | | `GH_AW_MODEL_DETECTION_COPILOT` | GitHub Copilot | | `GH_AW_MODEL_DETECTION_CLAUDE` | Anthropic Claude | | `GH_AW_MODEL_DETECTION_CODEX` | OpenAI Codex | | `GH_AW_MODEL_DETECTION_GEMINI` | Google Gemini | | `GH_AW_MODEL_DETECTION_CRUSH` | Crush | Set a model override as an organization variable: ```bash gh variable set GH_AW_MODEL_AGENT_COPILOT --org my-org --body "gpt-5" ``` See [Engines](/gh-aw/reference/engines/) for available engine identifiers and model configuration options. *** ## Guard Policy Fallback Variables [Section titled “Guard Policy Fallback Variables”](#guard-policy-fallback-variables) These variables provide fallback values for guard policy fields when the corresponding `tools.github.*` configuration is absent from workflow frontmatter. Set them as GitHub Actions organization or repository variables to enforce a consistent policy across all workflows. Note Explicit `tools.github.*` values in workflow frontmatter always take precedence over these variables. | Variable | Frontmatter field | Format | Description | | ------------------------------ | ------------------------------ | --------------------------------------- | ------------------------------------------------------------------------- | | `GH_AW_GITHUB_BLOCKED_USERS` | `tools.github.blocked-users` | Comma- or newline-separated usernames | GitHub usernames blocked from triggering agent runs | | `GH_AW_GITHUB_APPROVAL_LABELS` | `tools.github.approval-labels` | Comma- or newline-separated label names | Labels that promote content to “approved” integrity for guard checks | | `GH_AW_GITHUB_TRUSTED_USERS` | `tools.github.trusted-users` | Comma- or newline-separated usernames | GitHub usernames elevated to “approved” integrity, bypassing guard checks | Set an org-wide blocked user list: ```bash gh variable set GH_AW_GITHUB_BLOCKED_USERS --org my-org --body "bot-account1,bot-account2" ``` See [Tools Reference](/gh-aw/reference/tools/) for complete guard policy documentation. *** ## Precedence Rules [Section titled “Precedence Rules”](#precedence-rules) Environment variables follow a **most-specific-wins** model, consistent with GitHub Actions. Variables at more specific scopes completely override variables with the same name at less specific scopes. ### General Precedence (Highest to Lowest) [Section titled “General Precedence (Highest to Lowest)”](#general-precedence-highest-to-lowest) 1. **Step-level** (`steps[*].env`, `githubActionsStep.env`) 2. **Job-level** (`jobs..env`) 3. **Workflow-level** (`env:`) ### Safe Outputs Precedence [Section titled “Safe Outputs Precedence”](#safe-outputs-precedence) 1. **Job-specific** (`safe-outputs.jobs..env`) 2. **Global** (`safe-outputs.env`) 3. **Workflow-level** (`env:`) ### Context-Specific Scopes [Section titled “Context-Specific Scopes”](#context-specific-scopes) These scopes are independent and operate in different contexts: `engine.env`, `container.env`, `services..env`, `sandbox.agent.env`, `sandbox.mcp.env`, `tools..env`, `mcp-scripts..env`. ### Override Example [Section titled “Override Example”](#override-example) ```yaml --- env: API_KEY: default-key DEBUG: "false" jobs: test: env: API_KEY: test-key # Overrides workflow-level EXTRA: "value" steps: - run: | # API_KEY = "test-key" (job-level override) # DEBUG = "false" (workflow-level inherited) # EXTRA = "value" (job-level) --- ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Frontmatter Reference](/gh-aw/reference/frontmatter/) - Complete frontmatter configuration * [Safe Outputs](/gh-aw/reference/safe-outputs/) - Safe output environment configuration * [Sandbox](/gh-aw/reference/sandbox/) - Sandbox environment variables * [Tools](/gh-aw/reference/tools/) - MCP tool configuration and guard policies * [MCP Scripts](/gh-aw/reference/mcp-scripts/) - MCP script tool configuration * [Engines](/gh-aw/reference/engines/) - AI engine configuration and model selection * [GitHub Actions Environment Variables](https://docs.github.com/en/actions/learn-github-actions/variables) - GitHub Actions documentation # Ephemerals > Features for automatically expiring workflow resources and reducing noise in your repositories GitHub Agentic Workflows includes several “ephemeral” features that automatically expire resources and reduce noise in your repositories. They control costs by stopping scheduled workflows at deadlines, auto-close issues and discussions, hide older comments, and isolate automation via the [side repository pattern](/gh-aw/patterns/multi-repo-ops/#the-side-repository-pattern-isolated-automation). ## Expiration Features [Section titled “Expiration Features”](#expiration-features) ### Workflow Stop-After [Section titled “Workflow Stop-After”](#workflow-stop-after) Automatically disable workflow triggering after a deadline to control costs and prevent indefinite execution. ```yaml on: weekly on monday stop-after: "+25h" # 25 hours from compilation time ``` **Accepted formats**: * **Absolute dates**: `YYYY-MM-DD`, `MM/DD/YYYY`, `DD/MM/YYYY`, `January 2 2006`, `1st June 2025`, ISO 8601 * **Relative deltas**: `+7d`, `+25h`, `+1d12h30m` (calculated from compilation time) The minimum granularity is hours - minute-only units (e.g., `+30m`) are not allowed. Recompiling the workflow resets the stop time. At the deadline, new runs are prevented while existing runs complete. The stop time persists through recompilation; use `gh aw compile --refresh-stop-time` to reset it. Common uses: trial periods, experimental features, orchestrated initiatives, and cost-controlled schedules. See [Triggers Reference](/gh-aw/reference/triggers/#stop-after-configuration-stop-after) for complete documentation. ### Safe Output Expiration [Section titled “Safe Output Expiration”](#safe-output-expiration) Auto-close issues, discussions, and pull requests after a specified time period. This generates a maintenance workflow that runs automatically at appropriate intervals. #### Issue Expiration [Section titled “Issue Expiration”](#issue-expiration) ```yaml safe-outputs: create-issue: expires: 7 # Auto-close after 7 days labels: [automation, agentic] ``` #### Discussion Expiration [Section titled “Discussion Expiration”](#discussion-expiration) ```yaml safe-outputs: create-discussion: expires: 3 # Auto-close after 3 days as "OUTDATED" category: "general" ``` #### Pull Request Expiration [Section titled “Pull Request Expiration”](#pull-request-expiration) ```yaml safe-outputs: create-pull-request: expires: 14 # Auto-close after 14 days (same-repo only) draft: true ``` **Supported formats**: * **Integer**: Number of days (e.g., `7` = 7 days) * **Relative time**: `2h`, `7d`, `2w`, `1m`, `1y` Hours less than 24 are treated as 1 day minimum for expiration calculation. **Maintenance workflow frequency**: The generated `agentics-maintenance.yml` workflow runs at the minimum required frequency based on the shortest expiration time across all workflows: | Shortest Expiration | Maintenance Frequency | | ------------------- | --------------------- | | 1 day or less | Every 2 hours | | 2 days | Every 6 hours | | 3-4 days | Every 12 hours | | 5+ days | Daily | **Expiration markers**: The system adds a visible checkbox line with an XML comment to the body of created items: ```markdown - [x] expires on Jan 14, 2026, 3:30 PM UTC ``` The maintenance workflow searches for items with this expiration format (checked checkbox with the XML comment) and automatically closes them with appropriate comments and resolution reasons. Users can uncheck the checkbox to prevent automatic expiration. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) for complete documentation. ### Cache-Memory Cleanup [Section titled “Cache-Memory Cleanup”](#cache-memory-cleanup) The maintenance workflow automatically cleans up outdated [cache-memory](/gh-aw/reference/cache-memory/) entries on every scheduled run. Cache keys follow the pattern `memory-{workflow}-{run-id}`, and the cleanup job groups caches by workflow prefix, keeps the latest run ID per group, and deletes older entries. This prevents cache storage from growing unboundedly as workflows run repeatedly. The cleanup includes rate-limit awareness — it pauses early if the GitHub API rate limit is running low — and produces a job summary table showing how many caches were found, kept, and deleted. You can also trigger cleanup manually using the `clean_cache_memories` operation (see [Manual maintenance operations](#manual-maintenance-operations) below). ### Manual Maintenance Operations [Section titled “Manual Maintenance Operations”](#manual-maintenance-operations) The generated `agentics-maintenance.yml` workflow supports manual bulk operations via `workflow_dispatch`. Admin or maintainer users can trigger operations from the GitHub Actions UI or the CLI. All operations are restricted to admin and maintainer roles and are not available on forks. Available operations: | Operation | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------ | | `disable` | Disable all agentic workflows in the repository | | `enable` | Re-enable all agentic workflows in the repository | | `update` | Recompile workflows and create a PR if files changed | | `upgrade` | Upgrade agentic workflows to the latest version and create a PR if files changed | | `safe_outputs` | Replay safe outputs from a specific workflow run (requires a run URL or run ID) | | `create_labels` | Create any repository labels referenced in safe-outputs that do not yet exist | | `clean_cache_memories` | Clean up outdated cache-memory entries (same as the automated scheduled cleanup) | | `validate` | Run full workflow validation with all linters and file an issue if findings are detected | | `activity_report` | Generate a repository activity report for the last 24 hours, week, and month, and create an issue with the results | | `forecast` | Run a workflow token-usage forecast and create an issue with the JSON results | **Details for select operations:** * **`update` / `upgrade`**: Runs `gh aw update` or `gh aw upgrade`, stages changed files, and opens a pull request for review. After merging, recompile lock files with `gh aw compile`. See [Upgrading Agentic Workflows](/gh-aw/guides/upgrading/) for the manual upgrade process. * **`safe_outputs`**: Replays safe output processing from a previous workflow run. Provide a run URL or numeric run ID in the `run_url` input field. Useful when safe outputs were not applied correctly on the original run. * **`create_labels`**: Runs `gh aw compile --json --no-emit`, collects all unique label names across workflows, and creates missing ones with deterministic pastel colors. Requires `issues: write` permission. * **`validate`**: Runs `gh aw compile --validate --no-emit --zizmor --actionlint --poutine --verbose`. If errors or warnings are found, creates or updates a GitHub issue titled `[aw] workflow validation findings` with the full output. * **`activity_report`**: Runs `gh aw logs --format markdown` for the last 24 hours, 7 days, and 30 days (up to 1000 runs each), then creates an issue titled `[aw] agentic status report` with all three time-range sections as collapsible `

` blocks. Downloaded logs are cached under `./.cache/gh-aw/activity-report-logs`. The job has a 2-hour timeout and skips the 30-day query when the GitHub API is rate-limited. * **`forecast`**: Runs `gh aw forecast --repo --json`, writes the output to `./.cache/gh-aw/forecast/report.json`, then creates an issue titled `[aw] workflow forecast report` with the JSON payload embedded in a fenced block. ### Maintenance Configuration [Section titled “Maintenance Configuration”](#maintenance-configuration) You can customize the maintenance workflow runner or disable maintenance entirely using the `aw.json` configuration file at `.github/workflows/aw.json`. **Customize the runner:** ```json { "maintenance": { "runs_on": "ubuntu-latest", "action_failure_issue_expires": 72 } } ``` The `runs_on` field accepts a single string or an array of strings for multi-label runners (e.g., `["self-hosted", "linux"]`). The default runner is `ubuntu-slim`. The `action_failure_issue_expires` field controls expiration (in hours) for failure issues opened by the conclusion job (including grouped parent issues when `group-reports: true`). The default is `168` (7 days). See [Self-Hosted Runners](/gh-aw/guides/self-hosted-runners/#configuring-the-maintenance-workflow-runner) for more details. **Disable maintenance entirely:** ```json { "maintenance": false } ``` When maintenance is disabled, the compiler deletes any existing `agentics-maintenance.yml` file and emits a warning for workflows that use the `expires` field, since expiration depends on the maintenance workflow to run. Caution Disabling maintenance prevents automatic expiration of issues, discussions, and pull requests. Any `expires` configuration in your workflows will become a no-op until maintenance is re-enabled. ### Close Older Issues [Section titled “Close Older Issues”](#close-older-issues) Automatically close older issues with the same workflow-id marker when creating new ones. This keeps your issues focused on the latest information. ```yaml safe-outputs: create-issue: close-older-issues: true # Close previous reports ``` When a new issue is created, up to 10 older issues with the same workflow-id marker are closed as “not planned” with a comment linking to the new issue. Requires `GH_AW_WORKFLOW_ID` to be set and appropriate repository permissions. Ideal for weekly reports and recurring analyses where only the latest result matters. ## Noise Reduction Features [Section titled “Noise Reduction Features”](#noise-reduction-features) ### Hide Older Comments [Section titled “Hide Older Comments”](#hide-older-comments) Minimize previous comments from the same workflow before posting new ones. Useful for status update workflows where only the latest information matters. ```yaml safe-outputs: add-comment: hide-older-comments: true allowed-reasons: [outdated] # Optional: restrict hiding reasons ``` Before posting, the system finds and minimizes previous comments from the same workflow (identified by `GITHUB_WORKFLOW`). Comments are hidden, not deleted. Use `allowed-reasons` to restrict which minimization reason is applied: `spam`, `abuse`, `off_topic`, `outdated` (default), `resolved`, or `low_quality`. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#hide-older-comments) for complete documentation. ### Side Repository Pattern [Section titled “Side Repository Pattern”](#side-repository-pattern) Run agentic workflows from a separate “side” repository that targets your main codebase. This isolates AI-generated issues, comments, and workflow runs from your main repository, keeping automation infrastructure separate from production code. See [MultiRepoOps — Side Repository](/gh-aw/patterns/multi-repo-ops/#the-side-repository-pattern-isolated-automation) for complete setup and usage documentation. ### Text Sanitization [Section titled “Text Sanitization”](#text-sanitization) Control which GitHub repository references (`#123`, `owner/repo#456`) are allowed in workflow output text. When configured, references to unlisted repositories are escaped with backticks to prevent GitHub from creating timeline items. ```yaml safe-outputs: allowed-github-references: [] # Escape all references create-issue: target-repo: "my-org/main-repo" ``` See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) for complete documentation. ### Use Discussions Instead of Issues [Section titled “Use Discussions Instead of Issues”](#use-discussions-instead-of-issues) For ephemeral content, use discussions instead of issues. They have lower search weight and don’t clutter project boards, making them ideal for recurring reports and status updates. ```yaml safe-outputs: create-discussion: category: "Status Updates" expires: 14 # Close after 2 weeks close-older-discussions: true # Replace previous reports ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Triggers Reference](/gh-aw/reference/triggers/) - Complete trigger configuration including `stop-after` * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - All safe output types and expiration options * [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) — Complete setup for side repository operations # Frequently Asked Questions > Answers to common questions about GitHub Agentic Workflows, including security, costs, privacy, and configuration. Note GitHub Agentic Workflows is in early development and may change significantly. Using automated agentic workflows requires careful attention to security considerations and careful human supervision, and even then things can still go wrong. Use it with caution, and at your own risk. ## Determinism [Section titled “Determinism”](#determinism) ### I like deterministic CI/CD. Isn’t this non-deterministic? [Section titled “I like deterministic CI/CD. Isn’t this non-deterministic?”](#i-like-deterministic-cicd-isnt-this-non-deterministic) Agentic workflows are **100% additive** to your existing CI/CD - they don’t replace your deterministic build, test, or release pipelines. Think of it as **Continuous AI** alongside Continuous Integration and Continuous Deployment: a new automation layer running in GitHub Actions where security, permissions, and repository context already exist. Your deterministic pipelines stay unchanged. Agentic workflows handle tasks where exact reproducibility doesn’t matter - triaging issues, drafting documentation, researching dependencies, or proposing code improvements for human review. ## Capabilities [Section titled “Capabilities”](#capabilities) ### What’s the difference between agentic workflows and regular GitHub Actions workflows? [Section titled “What’s the difference between agentic workflows and regular GitHub Actions workflows?”](#whats-the-difference-between-agentic-workflows-and-regular-github-actions-workflows) Agentic workflows use AI to interpret natural language instructions in markdown instead of complex YAML. The AI engine can call pre-approved tools to perform tasks while running with read-only default permissions, safe outputs, and sandboxed execution. ### What’s the difference between agentic workflows and just running a coding agent in GitHub Actions? [Section titled “What’s the difference between agentic workflows and just running a coding agent in GitHub Actions?”](#whats-the-difference-between-agentic-workflows-and-just-running-a-coding-agent-in-github-actions) While you could install and run a coding agent directly in a standard GitHub Actions workflow, agentic workflows provide a structured framework with simpler markdown format, built-in security controls, pre-defined tools for GitHub operations, and easy switching between AI engines. ### Can agentic workflows write code and create pull requests? [Section titled “Can agentic workflows write code and create pull requests?”](#can-agentic-workflows-write-code-and-create-pull-requests) Yes! Agentic workflows can create pull requests using the `create-pull-request` safe output. This allows the workflow to propose code changes, documentation updates, or other modifications as pull requests for human review and merging. Some organizations may completely disable the creation of pull requests from GitHub Actions. In such cases, workflows can still generate diffs or suggestions in issues or comments for manual application. ### Can agentic workflows do more than code? [Section titled “Can agentic workflows do more than code?”](#can-agentic-workflows-do-more-than-code) Yes! Agentic workflows can analyze repositories, generate reports, triage issues, research information, create documentation, and coordinate work. The AI interprets natural language instructions and uses available [tools](/gh-aw/reference/tools/) to accomplish tasks. ### Can agentic workflows mix regular GitHub Actions steps with AI agentic steps? [Section titled “Can agentic workflows mix regular GitHub Actions steps with AI agentic steps?”](#can-agentic-workflows-mix-regular-github-actions-steps-with-ai-agentic-steps) Yes! Agentic workflows can include both AI agentic steps and traditional GitHub Actions steps. You can add custom steps before the agentic job using the [`steps:` configuration](/gh-aw/reference/steps-jobs/#custom-steps-steps). Additionally, [custom safe output jobs](/gh-aw/reference/safe-outputs/#custom-safe-output-jobs-jobs) can be used as consumers of agentic outputs. [MCP Scripts](/gh-aw/reference/mcp-scripts/) allow you to pass data between traditional steps and the AI agent with added checking. ### Can agentic workflows read other repositories? [Section titled “Can agentic workflows read other repositories?”](#can-agentic-workflows-read-other-repositories) Not by default, but yes with proper configuration. Cross-repository access requires: 1. A **Personal Access Token (PAT)** with access to target repositories 2. Configuring the token in your workflow See [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/) for coordinating across repositories, including running workflows from a separate side repository. ### Can I use agentic workflows in private repositories? [Section titled “Can I use agentic workflows in private repositories?”](#can-i-use-agentic-workflows-in-private-repositories) Yes, and in many cases we recommend it. Private repositories are ideal for proprietary code, creating a “sidecar” repository with limited access, testing workflows, and organization-internal automation. See [MultiRepoOps — Side Repository](/gh-aw/patterns/multi-repo-ops/#the-side-repository-pattern-isolated-automation) for patterns using private repositories. ### Can I edit workflows directly on GitHub.com without recompiling? [Section titled “Can I edit workflows directly on GitHub.com without recompiling?”](#can-i-edit-workflows-directly-on-githubcom-without-recompiling) Yes! The **markdown body** (AI instructions) is loaded at runtime and can be edited directly on GitHub.com or in any editor. Changes take effect on the next workflow run without recompilation. However, **frontmatter configuration** (tools, permissions, triggers, network rules) is embedded in the compiled workflow and requires recompilation when changed. Run `gh aw compile my-workflow` after editing frontmatter. See [Editing Workflows](/gh-aw/guides/editing-workflows/) for complete guidance on when recompilation is needed. ### Can workflows trigger other workflows? [Section titled “Can workflows trigger other workflows?”](#can-workflows-trigger-other-workflows) Yes, using the `dispatch-workflow` safe output: ```yaml safe-outputs: dispatch-workflow: max: 1 ``` This allows your workflow to trigger up to 1 other workflows with custom inputs. See [Safe Outputs](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow) for details. ### Can I trigger an agentic workflow from an external system like Jira? [Section titled “Can I trigger an agentic workflow from an external system like Jira?”](#can-i-trigger-an-agentic-workflow-from-an-external-system-like-jira) Yes. GitHub Actions cannot listen to external events directly, but any external system that can make an HTTP request can trigger a workflow via the [`repository_dispatch`](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#repository_dispatch) API. The two-step setup: **1. Add a `repository_dispatch` trigger to your workflow frontmatter:** ```yaml on: repository_dispatch: types: [jira-issue-created] ``` Access the caller’s payload in your workflow markdown via `${{ github.event.client_payload.* }}`. **2. Send a `POST` request to the GitHub dispatch API from the external system:** ```http POST https://api.github.com/repos///dispatches Authorization: Bearer Content-Type: application/json { "event_type": "jira-issue-created", "client_payload": { "issue_key": "PROJ-123", "summary": "Fix the thing" } } ``` For Jira specifically, use **Project → Automation → Issue created → Send web request** pointing at the dispatch API. Any system with webhook or outbound HTTP support—including Jira, PagerDuty, Slack, or a custom API—can trigger workflows this way. The `repository_dispatch` token must have `repo` scope (classic PAT) or `contents: write` permission. Store it in the external system’s secret or credential store (e.g., Jira Automation secret text, a CI/CD vault), scoped to the single target repository. See [Repository Dispatch Trigger](/gh-aw/reference/triggers/#repository-dispatch-trigger-repository_dispatch) for the full trigger reference. To control which branch the agent commits to based on content in the Jira issue, see [Can the agent use an existing branch specified at runtime?](#can-the-agent-use-an-existing-branch-specified-at-runtime-eg-from-a-jira-issue) ### Can I use MCP servers with agentic workflows? [Section titled “Can I use MCP servers with agentic workflows?”](#can-i-use-mcp-servers-with-agentic-workflows) Yes! [Model Context Protocol (MCP)](/gh-aw/reference/glossary/#mcp-model-context-protocol) servers extend workflow capabilities with custom tools and integrations. Configure them in your frontmatter: ```yaml tools: mcp-servers: my-server: image: "ghcr.io/org/my-mcp-server:latest" network: allowed: ["api.example.com"] ``` See [Using MCPs](/gh-aw/guides/mcps/) for configuration guides. ### If my agent can use a skill, can agentic workflows use it too? [Section titled “If my agent can use a skill, can agentic workflows use it too?”](#if-my-agent-can-use-a-skill-can-agentic-workflows-use-it-too) Usually, yes. If your agent can do it, agentic workflows can usually do it too, and that applies to skills as well. For reusable packaging, start with [imports](/gh-aw/reference/imports/) and [APM (Agent Package Manager)](https://microsoft.github.io/apm/). Imports are a good fit for sharing workflow-level configuration and prompts, while APM is the recommended way to package and distribute skills and other agent primitives. See [APM Dependencies](/gh-aw/reference/dependencies/) for the gh-aw integration. ### The `plugins:` or `dependencies:` field I was using is gone - how do I install agent plugins now? [Section titled “The plugins: or dependencies: field I was using is gone - how do I install agent plugins now?”](#the-plugins-or-dependencies-field-i-was-using-is-gone---how-do-i-install-agent-plugins-now) The `plugins:` and `dependencies:` frontmatter fields have been removed in favour of the import-based approach backed by [Microsoft APM (Agent Package Manager)](https://microsoft.github.io/apm/). APM provides cross-agent support for all agent primitives – skills, prompts, instructions, hooks, and plugins (including the Copilot `plugin.json` format and the Claude `plugin.json` format). Use `imports: - uses: shared/apm.md` with the `packages:` parameter to install plugins: ```yaml imports: - uses: shared/apm.md with: packages: - microsoft/apm-sample-package - github/awesome-copilot/skills/review-and-refactor ``` See [APM Dependencies](/gh-aw/reference/dependencies/) for full configuration options. ### Can I use Claude plugins with APM? [Section titled “Can I use Claude plugins with APM?”](#can-i-use-claude-plugins-with-apm) Yes! APM supports Claude plugins in the `plugin.json` format. When `engine: claude` is set, APM automatically infers the engine target and unpacks only Claude-compatible primitives. See [APM Dependencies](/gh-aw/reference/dependencies/) for details. ### Can workflows be broken up into shareable components? [Section titled “Can workflows be broken up into shareable components?”](#can-workflows-be-broken-up-into-shareable-components) Workflows can import shared configurations and components: ```yaml imports: - shared/github-tools.md - githubnext/agentics/shared/common-tools.md ``` This enables reusable tool configurations, network settings, and permissions across workflows. See [Imports](/gh-aw/reference/imports/) and [Packaging Imports](/gh-aw/guides/packaging-imports/) for details. ### Can I run workflows on a schedule? [Section titled “Can I run workflows on a schedule?”](#can-i-run-workflows-on-a-schedule) Yes, use fuzzy schedule expressions in the `on:` trigger (recommended): ```yaml on: weekly on monday # Automatically scattered to avoid load spikes ``` Or use standard cron syntax for fixed times: ```yaml on: schedule: - cron: "0 9 * * MON" # Every Monday at 9am UTC ``` See [Schedule Syntax](/gh-aw/reference/schedule-syntax/) for all supported formats. ### Can I run workflows conditionally? [Section titled “Can I run workflows conditionally?”](#can-i-run-workflows-conditionally) Yes, use the `if:` expression at the workflow level: ```yaml if: github.event_name == 'push' && github.ref == 'refs/heads/main' ``` See [Conditional Execution](/gh-aw/reference/frontmatter/#conditional-execution-if) in the Frontmatter Reference for details. ## Guardrails [Section titled “Guardrails”](#guardrails) ### Agentic workflows run in GitHub Actions. Can they access my repository secrets? [Section titled “Agentic workflows run in GitHub Actions. Can they access my repository secrets?”](#agentic-workflows-run-in-github-actions-can-they-access-my-repository-secrets) Repository secrets are not available to the agentic step by default. The AI agent runs with read-only permissions and cannot directly access your repository secrets unless explicitly configured. You should review workflows carefully, follow [GitHub Actions security guidelines](https://docs.github.com/en/actions/reference/security/secure-use), use least-privilege permissions, and inspect the compiled `.lock.yml` file. See the [Security Architecture](/gh-aw/introduction/architecture/) for details. Some MCP tools may be configured using secrets, but these are only accessible to the specific tool steps, not the AI agent itself. Minimize the use of tools equipped with highly privileged secrets. ### Agentic workflows run in GitHub Actions. Can they write to the repository? [Section titled “Agentic workflows run in GitHub Actions. Can they write to the repository?”](#agentic-workflows-run-in-github-actions-can-they-write-to-the-repository) By default, the agentic “coding agent” step of agentic workflows runs with read-only permissions. Write operations require explicit approval through [safe outputs](/gh-aw/reference/safe-outputs/) or explicit general `write` permissions (not recommended). This ensures that AI agents cannot make arbitrary changes to your repository. If safe outputs are configured, the workflow has limited, highly specific write operations that are then sanitized and executed securely. ### What sanitization is done on AI outputs before applying changes? [Section titled “What sanitization is done on AI outputs before applying changes?”](#what-sanitization-is-done-on-ai-outputs-before-applying-changes) All safe outputs from the AI agent are sanitized before being applied to your repository. Sanitization includes secret redaction, URL domain filtering, XML escaping, size limits, control character stripping, GitHub reference escaping and HTTPS enforcement. Additionally, safe outputs enforce permission separation - write operations happen in separate jobs with scoped permissions, never in the agentic job itself. See [Safe Outputs - Text Sanitization](/gh-aw/reference/safe-outputs/#text-sanitization-allowed-domains-allowed-github-references) for configuration options. ### How do I prevent workflow output from creating backlinks in referenced issues? [Section titled “How do I prevent workflow output from creating backlinks in referenced issues?”](#how-do-i-prevent-workflow-output-from-creating-backlinks-in-referenced-issues) When AI-generated content mentions issue or PR numbers (such as `#123` or `owner/repo#456`), GitHub automatically creates “mentioned in…” timeline entries in those issues. Set `allowed-github-references: []` to escape all such references before the content is posted: ```yaml safe-outputs: allowed-github-references: [] # Escape all GitHub references create-issue: ``` With an empty list, every `#N` and `owner/repo#N` reference in the output is wrapped in backticks, which prevents GitHub from resolving them as cross-references and avoids cluttering other repositories’ timelines. This is especially useful for workflows that write content about issues in a main repository from a separate sidecar repository. To allow references only from the current repository while still escaping all others: ```yaml safe-outputs: allowed-github-references: [repo] add-comment: ``` When `allowed-github-references` is not configured at all, all references are left unescaped (default behavior). See [Text Sanitization](/gh-aw/reference/safe-outputs/#text-sanitization-allowed-domains-allowed-github-references) for full configuration options. ### How are agent actions constrained — commenting, opening PRs, modifying files, and calling external tools? [Section titled “How are agent actions constrained — commenting, opening PRs, modifying files, and calling external tools?”](#how-are-agent-actions-constrained--commenting-opening-prs-modifying-files-and-calling-external-tools) gh-aw uses defense-in-depth rather than a single control. Four layers work together: **1. Read-only agent by default.** The AI agent step has read-only GitHub permissions. It cannot comment, open PRs, or push files unless you explicitly configure [safe outputs](/gh-aw/reference/safe-outputs/). **2. Safe outputs for all writes.** Commenting, creating PRs, and modifying files all go through safe outputs — separate GitHub Actions jobs with scoped write tokens. The agent produces a structured artifact; a downstream job applies the changes after sanitization (secret redaction, URL filtering, size limits). You declare which operations are permitted: ```yaml safe-outputs: add-comment: ``` **3. Threat detection before writes.** [Agentic threat detection](/gh-aw/reference/threat-detection/) runs automatically between the agent job and the safe output jobs. It scans the agent’s output for prompt injection attempts, secret leaks, and malicious code patches, blocking the write jobs if a threat is detected. **4. Network allowlist for external calls.** The [Agent Workflow Firewall](/gh-aw/reference/sandbox/) blocks all outbound network access by default. You must explicitly allow each domain an agent may reach: ```yaml network: allowed: - defaults ``` For sensitive operations, you can layer on a [GitHub Environment protection rule](/gh-aw/reference/faq/#can-i-require-external-human-approval-before-safe-outputs-are-applied) so a designated reviewer must approve before any write jobs run. ### Tell me more about guardrails [Section titled “Tell me more about guardrails”](#tell-me-more-about-guardrails) Guardrails are foundational to the design. Agentic workflows implement defense-in-depth through compilation-time validation (schema checks, expression safety, action SHA pinning), runtime isolation (sandboxed containers with network controls), permission separation (read-only defaults with [safe outputs](/gh-aw/reference/safe-outputs/) for writes), tool allowlisting, and output sanitization. See the [Security Architecture](/gh-aw/introduction/architecture/). ### Can I require external human approval before safe outputs are applied? [Section titled “Can I require external human approval before safe outputs are applied?”](#can-i-require-external-human-approval-before-safe-outputs-are-applied) Yes. The distinction here is between *guardrail validation* (does the agent output look acceptable?) and *external admission* (is this execution intent authorized to proceed?). gh-aw addresses both. The safe outputs architecture already enforces permission separation: the agent job runs read-only and never holds write credentials; it only produces a structured artifact. Separate jobs, with scoped write tokens, apply the changes. This boundary is real — a compromised agent cannot directly write to GitHub. For a fail-closed **external admission gate** before sensitive operations like deployments or credential use, apply **[GitHub Environment protection rules](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment#required-reviewers)** to a [custom safe output job](/gh-aw/reference/custom-safe-outputs/). The job pauses until a designated reviewer outside the workflow system explicitly approves. No approval means no execution. ```yaml jobs: approval-gate: runs-on: ubuntu-latest needs: detection # waits for automated threat scanning to complete environment: production-deploy # configure required reviewers in Settings → Environments steps: - name: Approved run: echo "Execution approved by reviewer" safe-outputs: needs: [approval-gate] # built-in safe_outputs job waits for manual approval ``` This approval is enforced by GitHub’s infrastructure, not by workflow logic the agent could influence. Threat detection still runs before the gate, so the reviewer sees output that has already passed automated scanning. Note that the *policy* — which environments require approval, what safe outputs are configured — is defined by whoever controls the repository. The admission decision for each run can be external; the admission policy itself is internal to repository owners. **Fully off-platform admission control** If your threat model requires an authority completely outside GitHub’s control plane — such as an external policy engine, a PAM/PIM system, or a compliance approval workflow — call that system from your gate job before it proceeds: ```yaml jobs: external-admission: runs-on: ubuntu-latest needs: [agent, detection] # waits for agent output and threat scanning to complete environment: production-deploy # optional: also adds GitHub-native reviewer gate steps: - name: Request admission from external authority run: | curl --fail -X POST https://YOUR_POLICY_ENGINE/v1/admit \ -H "Authorization: Bearer $POLICY_TOKEN" \ -d '{"workflow_run": "${{ github.run_id }}"}' env: POLICY_TOKEN: ${{ secrets.POLICY_TOKEN }} safe-outputs: needs: [external-admission] # write jobs don't run until external admission is granted ``` If the external call fails or is denied, the safe output jobs never run. This places the final admission decision in a system entirely independent of GitHub. ### How is my code and data processed? [Section titled “How is my code and data processed?”](#how-is-my-code-and-data-processed) By default, your workflow is run on GitHub Actions, like any other GitHub Actions workflow, and as one if its jobs it invokes your nominated [AI Engine (coding agent)](/gh-aw/reference/engines/), run in a container. This engine may in turn make tool calls and MCP calls. When using the default **GitHub Copilot CLI**, the workflow is processed by the `copilot` CLI tool which uses GitHub Copilot’s services and related AI models. The specifics depend on your engine choice: * **GitHub Copilot CLI**: See [GitHub Copilot documentation](https://docs.github.com/en/copilot) for details. * **Claude/Codex**: Uses respective providers’ APIs with their data handling policies. See the [Security Architecture](/gh-aw/introduction/architecture/) for details on the execution and data flow. ### Does the underlying AI engine run in a sandbox? [Section titled “Does the underlying AI engine run in a sandbox?”](#does-the-underlying-ai-engine-run-in-a-sandbox) Yes, the [AI engine](/gh-aw/reference/engines/) runs in a containerized sandbox with network egress control via the [Agent Workflow Firewall](/gh-aw/reference/sandbox/), container isolation, GitHub Actions resource constraints, and limited filesystem access to workspace and temporary directories. The sandbox container runs inside a GitHub Actions VM for additional isolation. See [Sandbox Configuration](/gh-aw/reference/sandbox/). ### Can an agentic workflow use outbound network requests? [Section titled “Can an agentic workflow use outbound network requests?”](#can-an-agentic-workflow-use-outbound-network-requests) Yes, but network access is restricted by the [Agent Workflow Firewall](/gh-aw/reference/sandbox/). You must explicitly declare which domains the workflow can access: ```yaml network: allowed: - defaults # Basic infrastructure - python # Python/PyPI ecosystem - "api.example.com" # Custom domain ``` See [Network Permissions](/gh-aw/reference/network/) for complete configuration options. ### How does integrity filtering protect my workflow? [Section titled “How does integrity filtering protect my workflow?”](#how-does-integrity-filtering-protect-my-workflow) [Integrity filtering](/gh-aw/reference/integrity/) controls which GitHub content the agent can see, filtering by **author trust** and **merge status**. The MCP gateway silently removes content below the configured `min-integrity` threshold before the AI engine sees it. For **public repositories**, `min-integrity: approved` is automatically applied at runtime — restricting content to owners, members, and collaborators — even without additional authentication. For triage or spam-detection workflows that need to process content from all users, set `min-integrity: none` explicitly: ```yaml tools: github: min-integrity: none ``` See [Integrity Filtering](/gh-aw/reference/integrity/) for available levels, user blocking, and approval labels. ## Configuration & Setup [Section titled “Configuration & Setup”](#configuration--setup) ### Why do slash-command workflows show many “started then skipped” runs on comments? [Section titled “Why do slash-command workflows show many “started then skipped” runs on comments?”](#why-do-slash-command-workflows-show-many-started-then-skipped-runs-on-comments) This is expected behavior. A `slash_command` is compiled into multiple GitHub event listeners (issue/PR bodies, issue comments, PR comments, and review comments, depending on `events:`). GitHub first dispatches the event, then the activation logic checks whether the comment starts with a matching command (for example `/refresh`). If it does not match, the run exits early and appears as a quick skipped/no-op run in Actions. To reduce this noise, narrow the trigger scope with `events:` so the workflow only listens where you actually use commands, and use [LabelOps](/gh-aw/patterns/label-ops/) for command-style operations that should not activate on every comment. LabelOps (`label_command`) triggers only when a specific label is applied, which produces fewer incidental runs than broad comment listeners. ```yaml on: slash_command: name: refresh events: [pull_request_comment] # only listen to PR comments label_command: name: refresh events: [pull_request] # optional low-noise label trigger ``` ### What is a workflow lock file? [Section titled “What is a workflow lock file?”](#what-is-a-workflow-lock-file) A **workflow lock file** (`.lock.yml`) is the compiled GitHub Actions workflow generated from your `.md` file by `gh aw compile`. It contains SHA-pinned actions, resolved imports, configured permissions, and all guardrail hardening - inspect it to see exactly what will run, with no hidden configuration. Both files should be committed to version control: * **`.md` file**: Your source - edit the prompt body freely; changes take effect at the next run without recompiling * **`.lock.yml` file**: The compiled workflow GitHub Actions actually runs; must be regenerated after any frontmatter changes (permissions, tools, triggers) ### What is the actions-lock.json file? [Section titled “What is the actions-lock.json file?”](#what-is-the-actions-lockjson-file) The `.github/aw/actions-lock.json` file is a cache of resolved `action@version` → ref mappings. During compilation, the compiler **tries** to pin each action reference to an immutable commit SHA for security. Resolving a version tag to a SHA requires querying the GitHub API (scanning releases), which can fail when the available token has limited permissions — for example, when compiling via GitHub Copilot Coding Agent (CCA) where the token may not have access to external repositories. In those cases, the compiler may fall back to leaving a stable version tag ref (such as `@v0`) instead of a SHA. The cache avoids this problem: if a ref (typically a SHA) was previously resolved (using a user PAT or a GitHub Actions token with broader access), the result is stored in `actions-lock.json` and reused on subsequent compilations, regardless of the current token’s capabilities. Without this cache, compilation is unstable — it succeeds with a permissive token but fails when token access is restricted. Commit `actions-lock.json` to version control so that all contributors and automated tools (including CCA) use consistent action refs (SHAs or version tags) without needing to re-resolve them. Refresh the cache periodically with `gh aw update-actions`, or delete it and recompile to force a full re-resolution when you have an appropriate token. See [Action Pinning](/gh-aw/reference/compilation-process/#action-pinning) for details. ### What is `github/gh-aw-actions`? [Section titled “What is github/gh-aw-actions?”](#what-is-githubgh-aw-actions) `github/gh-aw-actions` is the GitHub Actions repository containing all reusable actions that power compiled agentic workflows. Compiled `.lock.yml` files reference these actions as `github/gh-aw-actions/setup@` (where `` is usually a commit SHA, but may be a stable version tag such as `v0`). These references are managed entirely by `gh aw compile` — never edit them manually. See [The gh-aw-actions Repository](/gh-aw/reference/compilation-process/#the-gh-aw-actions-repository) for details. ### Why is Dependabot opening PRs to update `github/gh-aw-actions`? [Section titled “Why is Dependabot opening PRs to update github/gh-aw-actions?”](#why-is-dependabot-opening-prs-to-update-githubgh-aw-actions) Dependabot scans `.lock.yml` files for action references and treats `github/gh-aw-actions` pins as regular dependencies to update. **Do not merge these PRs.** Action pins in compiled workflows should only be updated by running `gh aw compile` or `gh aw update-actions`. Suppress these PRs by adding an `ignore` entry in `.github/dependabot.yml`: ```yaml updates: - package-ecosystem: github-actions directory: "/.github/workflows" ignore: - dependency-name: "github/gh-aw-actions/**" # Managed by gh aw compile. Version-locked to the gh-aw compiler; do not bump. ``` See [Dependabot and gh-aw-actions](/gh-aw/reference/compilation-process/#dependabot-and-gh-aw-actions) for more details. ### How does `gh aw upgrade` resolve action versions when no GitHub Releases exist? [Section titled “How does gh aw upgrade resolve action versions when no GitHub Releases exist?”](#how-does-gh-aw-upgrade-resolve-action-versions-when-no-github-releases-exist) `gh aw upgrade` (and `gh aw update-actions`) resolves the latest version of each referenced action using a two-step process: 1. **GitHub Releases API** — queries `/repos/{owner}/{repo}/releases` via the `gh` CLI. If releases are found, the highest compatible semantic version is selected. 2. **Git tag fallback** — if the Releases API returns an empty list (which happens when a repository publishes tags without creating GitHub Releases), the command automatically falls back to scanning tags via `git ls-remote`. This fallback is **safe to ignore** — tags are a valid source for version pinning. Only if *both* sources return no results does the upgrade produce a warning that cannot be resolved automatically. > **Note:** `github/gh-aw-actions` intentionally publishes only tags (not GitHub Releases). The `gh aw upgrade` warning `github/gh-aw-actions/setup: no releases found` that appeared in earlier versions was caused by this two-step logic not falling back to tags. It has been fixed — the tag fallback now runs automatically. ### Why do I need a token or key? [Section titled “Why do I need a token or key?”](#why-do-i-need-a-token-or-key) When using **GitHub Copilot CLI**, a Personal Access Token (PAT) with “Copilot Requests” permission authenticates and associates automation work with your GitHub account. This ensures usage tracking against your subscription, appropriate AI permissions, and auditable actions. In the future, this may support organization-level association. See [Authentication](/gh-aw/reference/auth/). ### Can I use `CLAUDE_CODE_OAUTH_TOKEN` with the Claude engine? [Section titled “Can I use CLAUDE\_CODE\_OAUTH\_TOKEN with the Claude engine?”](#can-i-use-claude_code_oauth_token-with-the-claude-engine) No. `CLAUDE_CODE_OAUTH_TOKEN` is not supported by GitHub Agentic Workflows. The only supported authentication method for the Claude engine is [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key), which must be configured as a GitHub Actions secret. Provider-based OAuth authentication for Claude (such as billing through a Claude Teams subscription) is not supported. See [Authentication](/gh-aw/reference/auth/) and [AI Engines](/gh-aw/reference/engines/#available-coding-agents) for setup instructions. ### What hidden runtime dependencies does this have? [Section titled “What hidden runtime dependencies does this have?”](#what-hidden-runtime-dependencies-does-this-have) The executing agentic workflow uses your nominated coding agent (defaulting to GitHub Copilot CLI), a GitHub Actions VM with NodeJS, pinned Actions from [github/gh-aw](https://github.com/github/gh-aw) releases, and an Agent Workflow Firewall container for network control (optional but default). The exact YAML workflow can be inspected in the compiled `.lock.yml` file - there’s no hidden configuration. ### Why are macOS runners not supported? [Section titled “Why are macOS runners not supported?”](#why-are-macos-runners-not-supported) macOS runners (`macos-*`) are not currently supported in agentic workflows. Agentic workflows rely on containers to build a secure execution sandbox - specifically the [Agent Workflow Firewall](/gh-aw/reference/sandbox/) that provides network egress control and process isolation. GitHub-hosted macOS runners do not support container jobs, which is a hard requirement for this security architecture. Use `ubuntu-latest` (the default) or another Linux-based runner instead. For tasks that genuinely require macOS-specific tooling, consider running those steps in a regular GitHub Actions job that coordinates with your agentic workflow. ### Can I use agentic workflows on GitHub Enterprise Server (GHES)? [Section titled “Can I use agentic workflows on GitHub Enterprise Server (GHES)?”](#can-i-use-agentic-workflows-on-github-enterprise-server-ghes) Yes, but you may need to enable GHES compatibility mode to avoid artifact errors. GHES instances that predate `@actions/artifact` v2.0.0 support cannot run `actions/upload-artifact@v4+` or `actions/download-artifact@v4+`. On those instances, compiled workflows fail with a `GHESNotSupportedError` because the compiler emits v4+ artifact actions by default. Enable GHES compatibility mode so the compiler emits `upload-artifact@v3.2.2` and `download-artifact@v3.1.0` instead: **`aw.json` (recommended — applies to all workflows in the repository):** ```json { "ghes": true } ``` **`--ghes` flag (one-off compilation):** ```bash gh aw compile --ghes my-workflow.md ``` Running `gh aw init` inside a GHES repository automatically detects the deployment and writes `ghes: true` to `.github/workflows/aw.json` for you. For `gh` CLI host setup and Copilot prerequisites on GHES, see [Enterprise Configuration](/gh-aw/reference/enterprise-configuration/). ### I’m not using a supported AI Engine (coding agent). What should I do? [Section titled “I’m not using a supported AI Engine (coding agent). What should I do?”](#im-not-using-a-supported-ai-engine-coding-agent-what-should-i-do) If you want to use a coding agent that isn’t currently supported (Copilot, Claude, Codex, Gemini, or Crush), you can contribute support to the [gh-aw repository](https://github.com/github/gh-aw), or open an issue describing your use case. See [AI Engines](/gh-aw/reference/engines/). ### Can I test workflows without affecting my repository? [Section titled “Can I test workflows without affecting my repository?”](#can-i-test-workflows-without-affecting-my-repository) Yes! Use [TrialOps](/gh-aw/experimental/trial-ops/) to test workflows in isolated trial repositories. This lets you validate behavior and iterate on prompts without creating real issues, PRs, or comments in your actual repository. ### Where can I find help with common issues? [Section titled “Where can I find help with common issues?”](#where-can-i-find-help-with-common-issues) See [Common Issues](/gh-aw/troubleshooting/common-issues/) for detailed troubleshooting guidance including workflow failures, debugging strategies, permission issues, and network problems. ### Why is my create-discussion workflow failing? [Section titled “Why is my create-discussion workflow failing?”](#why-is-my-create-discussion-workflow-failing) Ensure discussions are enabled (**Settings → Features → Discussions**) and the workflow has `discussions: write` permission. For category matching failures, verify spelling (case-insensitive) and use lowercase slugs (e.g., `general`, `announcements`) rather than display names. Use `fallback-to-issue: true` (the default) to automatically create an issue if discussions aren’t available. See [Discussion Creation](/gh-aw/reference/safe-outputs/#discussion-creation-create-discussion) for details. ### How do I turn off discussions in add-comment? [Section titled “How do I turn off discussions in add-comment?”](#how-do-i-turn-off-discussions-in-add-comment) By default, `add-comment` requests `discussions: write` permission. If your GitHub App lacks the Discussions permission (which can cause 422 errors during token generation), set `discussions: false`: ```yaml safe-outputs: add-comment: discussions: false # exclude discussions:write permission ``` This removes the `discussions: write` permission requirement. Discussion targeting itself remains automatic — `discussions: false` only controls the permission scope, not which events trigger the workflow. Similarly, you can opt out of `issues: write` or `pull-requests: write` using `issues: false` or `pull-requests: false`. ### Why is my create-pull-request workflow failing with “GitHub Actions is not permitted to create or approve pull requests”? [Section titled “Why is my create-pull-request workflow failing with “GitHub Actions is not permitted to create or approve pull requests”?”](#why-is-my-create-pull-request-workflow-failing-with-github-actions-is-not-permitted-to-create-or-approve-pull-requests) Some organizations block PR creation by GitHub Actions via **Settings → Actions → General → Workflow permissions**. If you can’t enable it, use one of these alternatives: **Automatic issue fallback (default)** — `fallback-as-issue: true` is the default; when PR creation is blocked an issue with the branch link is created instead. Requires `contents: write`, `pull-requests: write`, and `issues: write`. **Assign to Copilot** — create an issue assigned to `copilot` for automated implementation: ```yaml safe-outputs: create-issue: assignees: [copilot] labels: [automation, enhancement] ``` **Disable fallback** — set `fallback-as-issue: false` to skip the issue fallback and only attempt PR creation. Requires only `contents: write` and `pull-requests: write`, but the workflow will fail if PR creation is blocked. See [Pull Request Creation](/gh-aw/reference/safe-outputs/#pull-request-creation-create-pull-request) for details. ### Why don’t pull requests created by agentic workflows trigger my CI checks? [Section titled “Why don’t pull requests created by agentic workflows trigger my CI checks?”](#why-dont-pull-requests-created-by-agentic-workflows-trigger-my-ci-checks) This is expected GitHub Actions security behavior. Pull requests created using the default `GITHUB_TOKEN` or by the GitHub Actions bot user **do not trigger workflow runs** on `pull_request`, `pull_request_target`, or `push` events. This is a [GitHub Actions security feature](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow) designed to prevent accidental recursive workflow execution. The easy way to fix this problem is to set a secret `GH_AW_CI_TRIGGER_TOKEN` with a Personal Access Token (PAT) with ‘Contents: Read & Write’ permission to your repo. See [Triggering CI](/gh-aw/reference/triggering-ci/) for more details on how to configure workflows to run CI checks on PRs created by agentic workflows. ### How do I suppress the “Generated by…” text in workflow outputs? [Section titled “How do I suppress the “Generated by…” text in workflow outputs?”](#how-do-i-suppress-the-generated-by-text-in-workflow-outputs) When workflows create or update issues, pull requests, discussions, or post comments, they append a `> Generated by [Workflow Name](run_url) for issue #N` attribution line. Use `footer: false` to hide this visible text while preserving the hidden XML markers used for search and tracking. **Hide footers globally** (all safe output types): ```yaml safe-outputs: footer: false add-comment: create-issue: title-prefix: "[ai] " ``` **Hide footers for specific output types only:** ```yaml safe-outputs: footer: false # hide for all by default create-pull-request: footer: true # override: show footer for PRs only ``` Even with `footer: false`, the hidden `` XML marker is still included in the content for searchability - you can search GitHub for `"gh-aw-workflow-id: my-workflow" in:body` to find all items created by a workflow. See [Footer Control](/gh-aw/reference/footers/) for complete documentation including per-handler overrides and PR review footer options. ### My workflow fails with “Runtime import file not found” when used in a repository ruleset [Section titled “My workflow fails with “Runtime import file not found” when used in a repository ruleset”](#my-workflow-fails-with-runtime-import-file-not-found-when-used-in-a-repository-ruleset) This happens because workflows configured as required status checks run in a restricted context without access to the repository file system, so runtime imports cannot be resolved. The fix is to enable `inlined-imports: true` in your workflow frontmatter so the compiler bundles all imported content into the compiled `.lock.yml` at compile time. See [Self-Contained Lock Files](/gh-aw/reference/imports/#self-contained-lock-files-inlined-imports-true) for the full details. ### My cross-organization `workflow_call` fails with a repository checkout error [Section titled “My cross-organization workflow\_call fails with a repository checkout error”](#my-cross-organization-workflow_call-fails-with-a-repository-checkout-error) When a trigger file in one organization calls an agentic workflow in a **different organization**, the activation job attempts to check out the platform repo’s `.github` folder using the caller’s `GITHUB_TOKEN`. That token is scoped to the caller’s organization and cannot access a private repository in another organization, producing an error such as: ```plaintext fatal: repository 'https://github.com/other-org/platform-repo/' not found ``` The fix is to enable `inlined-imports: true` on the **platform workflow** (the callee). This embeds all imported content into the compiled `.lock.yml` at compile time, eliminating the cross-organization checkout entirely: ```yaml --- on: workflow_call: engine: copilot inlined-imports: true imports: - shared/common-tools.md --- ``` See [Self-Contained Lock Files](/gh-aw/reference/imports/#self-contained-lock-files-inlined-imports-true) for the full details. ### My workflow checkout is very slow because my repository is a large monorepo. How can I speed it up? [Section titled “My workflow checkout is very slow because my repository is a large monorepo. How can I speed it up?”](#my-workflow-checkout-is-very-slow-because-my-repository-is-a-large-monorepo-how-can-i-speed-it-up) Use **sparse checkout** to only fetch the parts of the repository that your workflow actually needs. This can reduce checkout time from tens of minutes to seconds for large monorepos. Configure `sparse-checkout` in your workflow frontmatter using the `checkout:` field: ```yaml checkout: sparse-checkout: | node/my-package .github ``` This generates a checkout step that only downloads the specified paths, dramatically reducing clone size and time. For cases where you need multiple parts of a monorepo with different settings, you can combine checkouts: ```yaml checkout: - sparse-checkout: | node/my-package .github - repository: org/shared-libs path: ./libs/shared sparse-checkout: | defaults/ ``` The `sparse-checkout` field accepts newline-separated path patterns compatible with `actions/checkout`. See [GitHub Repository Checkout](/gh-aw/reference/checkout/#configuration-options) for the full list of checkout configuration options. ## Workflow Design [Section titled “Workflow Design”](#workflow-design) ### Should I focus on one workflow, or write many different ones? [Section titled “Should I focus on one workflow, or write many different ones?”](#should-i-focus-on-one-workflow-or-write-many-different-ones) One workflow is simpler to maintain and good for learning, while multiple workflows provide better separation of concerns, different triggers and permissions per task, and clearer audit trails. Start with one or two workflows, then expand as you understand the patterns. See [Peli’s Agent Factory](/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/) for examples. ### Should I create agentic workflows by hand editing or using AI? [Section titled “Should I create agentic workflows by hand editing or using AI?”](#should-i-create-agentic-workflows-by-hand-editing-or-using-ai) Either approach works well. AI-assisted authoring using `/agent agentic-workflows create` in GitHub Copilot Chat provides interactive guidance with automatic best practices, while manual editing gives full control and is essential for advanced customizations. See [Creating Workflows](/gh-aw/setup/creating-workflows/) for AI-assisted approach, or [Reference documentation](/gh-aw/reference/frontmatter/) for manual configuration. ### Can the agent use an existing branch specified at runtime (e.g., from a Jira issue)? [Section titled “Can the agent use an existing branch specified at runtime (e.g., from a Jira issue)?”](#can-the-agent-use-an-existing-branch-specified-at-runtime-eg-from-a-jira-issue) The `create-pull-request` safe output always creates a new branch, but you can control its name and make it reuse an existing remote branch. Set these two fields in your workflow frontmatter: ```yaml safe-outputs: create-pull-request: preserve-branch-name: true # omit random salt suffix from agent-specified name recreate-ref: true # force-reset remote branch if it already exists ``` With `preserve-branch-name: true`, the agent’s branch name (e.g., `feature/abc-123-my-change`) is used as-is instead of having a random hex suffix appended. With `recreate-ref: true`, if that branch already exists remotely, it is force-reset to the agent’s current HEAD rather than falling back to creating an issue. To pass the branch name from a Jira issue body (or any issue body), instruct the agent in your workflow’s markdown: ```markdown Read the issue body and extract the branch name from the line starting with "Use existing branch:". Use that name when calling `create_pull_request`. ``` The agent reads the triggering issue body as part of its context, so no extra integration is needed when the branch name is embedded there. For richer Jira data (status, custom fields), use a [custom safe output](/gh-aw/reference/custom-safe-outputs/) or Jira MCP server. Note `recreate-ref` requires `preserve-branch-name: true` to take effect. The agent always starts from the configured base branch — it doesn’t literally check out the named branch before making changes. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/) for full configuration details. ### You use ‘agent’ and ‘agentic workflow’ interchangeably. Are they the same thing? [Section titled “You use ‘agent’ and ‘agentic workflow’ interchangeably. Are they the same thing?”](#you-use-agent-and-agentic-workflow-interchangeably-are-they-the-same-thing) Yes, for the purpose of this technology. An **“agent”** is an agentic workflow in a repository - an AI-powered automation that can reason, make decisions, and take actions. We use **“agentic workflow”** as it’s plainer and emphasizes the workflow nature of the automation, but the terms are synonymous in this context. ### How do I forward agent and detection artifacts to a third-party server after the workflow finishes? [Section titled “How do I forward agent and detection artifacts to a third-party server after the workflow finishes?”](#how-do-i-forward-agent-and-detection-artifacts-to-a-third-party-server-after-the-workflow-finishes) Add a custom job with `needs: [conclusion]` in the frontmatter `jobs:` block. The `conclusion` job is the last auto-generated job to run, so depending on it guarantees both the `agent` and `detection` artifacts are fully uploaded before your job starts. ```yaml jobs: forward-artifacts: needs: [conclusion] if: always() runs-on: ubuntu-latest steps: - uses: actions/download-artifact@v4 with: name: agent path: artifacts/agent - uses: actions/download-artifact@v4 with: name: detection path: artifacts/detection continue-on-error: true - name: Upload to third-party server env: INGEST_TOKEN: ${{ secrets.INGEST_TOKEN }} run: | tar -czf artifacts.tar.gz artifacts/ curl --fail --retry 3 -X POST https://ingest.example.com/artifacts \ -H "Authorization: ******" \ -F "file=@artifacts.tar.gz" \ -F "run_id=${{ github.run_id }}" ``` `if: always()` ensures the job runs even when the agent or safe-output jobs fail. The `detection` artifact is only present when [threat detection](/gh-aw/reference/threat-detection/) is enabled; `continue-on-error: true` on that step makes the job continue when the artifact doesn’t exist. See [Artifacts](/gh-aw/reference/artifacts/) for a full list of artifact names and their contents. ## Costs & Usage [Section titled “Costs & Usage”](#costs--usage) ### Who pays for the use of AI? [Section titled “Who pays for the use of AI?”](#who-pays-for-the-use-of-ai) This depends on the AI engine (coding agent) you use: * **GitHub Copilot CLI** (default): Usage is currently associated with the individual GitHub account of the user supplying the [`COPILOT_GITHUB_TOKEN`](/gh-aw/reference/auth/#copilot_github_token), and is drawn from the monthly quota of premium requests for that account. See [GitHub Copilot billing](https://docs.github.com/en/copilot/about-github-copilot/subscription-plans-for-github-copilot). * **Claude**: Usage is billed to the Anthropic account associated with [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key) Actions secret in the repository. * **Codex**: Usage is billed to your OpenAI account associated with [`OPENAI_API_KEY`](/gh-aw/reference/auth/#openai_api_key) Actions secret in the repository. ### What’s the approximate cost per workflow run? [Section titled “What’s the approximate cost per workflow run?”](#whats-the-approximate-cost-per-workflow-run) Costs vary depending on workflow complexity, AI model, and execution time. GitHub Copilot CLI uses 1-2 premium requests per workflow execution with agentic processing. Track usage with `gh aw logs` for runs and metrics, `gh aw audit ` for detailed token usage and costs, or check your AI provider’s usage portal. Consider creating separate PAT/API keys per repository for tracking. Reduce costs by optimizing prompts, using smaller models, limiting tool calls, reducing run frequency, and caching results. ### Are GitHub Actions minutes charged in addition to AI costs? [Section titled “Are GitHub Actions minutes charged in addition to AI costs?”](#are-github-actions-minutes-charged-in-addition-to-ai-costs) Yes. Every agentic workflow run is a GitHub Actions workflow run, so it consumes Actions minutes alongside AI inference. These are billed separately: * **Actions minutes**: Standard GitHub Actions billing applies — free for public repos, metered for private repos based on your plan. Set a [spending limit](https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions) at the org level to cap Actions spend. * **AI inference**: Billed through your AI engine account (see [Who pays for the use of AI?](#who-pays-for-the-use-of-ai)). ### How do retries and agent loops affect costs? [Section titled “How do retries and agent loops affect costs?”](#how-do-retries-and-agent-loops-affect-costs) gh-aw has no automatic retry mechanism — each workflow trigger produces exactly one run. However, you can control reasoning depth and autopilot continuation, which directly affects how many tokens and how much wall-clock time (Actions minutes) a run consumes: * `max-turns` (Claude only) — limits the number of AI chat iterations per run * `max-continuations` (Copilot only) — enables autopilot mode with multiple consecutive triggered runs ```yaml engine: id: claude max-turns: 5 # limit reasoning depth per run ``` Keep these values low for cost-sensitive workflows. For scheduled workflows, run frequency is the primary cost lever — an hourly schedule at 1–2 premium requests per run adds up quickly across many repositories. ### How do I control spend and set budgets? [Section titled “How do I control spend and set budgets?”](#how-do-i-control-spend-and-set-budgets) Spend controls live at the provider level, not inside gh-aw: * **Actions minutes**: Set an org spending limit in GitHub Billing settings. * **Claude / Codex / Gemini**: Configure spend limits in the Anthropic Console or OpenAI platform. These apply at the API key or project level. * **Copilot**: Usage is quota-based (premium requests per month) rather than dollar-metered, so the natural cap is the plan’s monthly request quota. For per-repository cost tracking, use a dedicated API key per repository so provider dashboards show usage broken down by key. You can also use `gh aw audit ` for per-run token and cost detail, and `gh aw logs` for run history and aggregate metrics. ### Can I change the model being used, e.g., use a cheaper or more advanced one? [Section titled “Can I change the model being used, e.g., use a cheaper or more advanced one?”](#can-i-change-the-model-being-used-eg-use-a-cheaper-or-more-advanced-one) Yes! You can configure the model in your workflow frontmatter: ```yaml engine: id: copilot model: gpt-5 # or claude-sonnet-4 ``` Or switch to a different engine entirely: ```yaml engine: claude ``` See [AI Engines](/gh-aw/reference/engines/) for all configuration options. # Feature Flags > Enable experimental or optional compiler and runtime behaviors in GitHub Agentic Workflows using the features: frontmatter field The `features:` frontmatter field enables experimental or optional compiler and runtime behaviors as key-value pairs. ```yaml features: my-experimental-feature: true action-mode: "script" ``` ## Action Mode (`features.action-mode`) [Section titled “Action Mode (features.action-mode)”](#action-mode-featuresaction-mode) Controls how the workflow compiler generates custom action references in compiled workflows. Can be set to `"dev"`, `"release"`, `"action"`, or `"script"`. ```yaml features: action-mode: "script" ``` **Available modes:** * **`dev`** (default): References custom actions using local paths (e.g., `uses: ./actions/setup`). Best for development and testing workflows in the gh-aw repository. * **`release`**: References custom actions using SHA-pinned remote paths within `github/gh-aw` (e.g., `uses: github/gh-aw/actions/setup@sha`). Used for production workflows with version pinning. * **`action`**: References custom actions from the `github/gh-aw-actions` external repository at the same release version (e.g., `uses: github/gh-aw-actions/setup@sha`). Uses SHA pinning when available, with a version-tag fallback. Use this when deploying workflows from the `github/gh-aw-actions` distribution repository. * **`script`**: Generates direct shell script calls instead of using GitHub Actions `uses:` syntax. The compiler: 1. Checks out the `github/gh-aw` repository’s `actions` folder to `/tmp/gh-aw/actions-source` 2. Runs the setup script directly: `bash /tmp/gh-aw/actions-source/actions/setup/setup.sh` 3. Uses shallow clone (`depth: 1`) for efficiency **When to use script mode:** * Testing custom action scripts during development * Debugging action installation issues * Environments where local action references are not available * Advanced debugging scenarios requiring direct script execution **Example:** ```yaml --- name: Debug Workflow on: workflow_dispatch features: action-mode: "script" permissions: contents: read --- Debug workflow using script mode for custom actions. ``` **Note:** The `action-mode` can also be overridden via the CLI flag `--action-mode` or the environment variable `GH_AW_ACTION_MODE`. The precedence is: CLI flag > feature flag > environment variable > auto-detection. ## Copilot BYOK Mode (Default for `engine: copilot`) [Section titled “Copilot BYOK Mode (Default for engine: copilot)”](#copilot-byok-mode-default-for-engine-copilot) Copilot offline Bring Your Own Key (BYOK) behavior is now the default for `engine: copilot`, bundling four behaviors: 1. Injecting a dummy `COPILOT_API_KEY` to trigger the AWF BYOK runtime path. 2. Implicitly enabling `cli-proxy`. 3. Forcing the Copilot CLI to install at `latest` (ignoring any pinned `engine.version`). 4. Setting `COPILOT_MODEL` to `${{ vars.GH_AW_MODEL_AGENT_COPILOT || 'claude-sonnet-4.6' }}` — Copilot BYOK providers require a non-empty model, so the compiler provides `claude-sonnet-4.6` as the fallback when `GH_AW_MODEL_AGENT_COPILOT` is not set. No feature flag is required. To use a different model, set the `GH_AW_MODEL_AGENT_COPILOT` repository variable. The compiled workflow uses `${{ vars.GH_AW_MODEL_AGENT_COPILOT || 'claude-sonnet-4.6' }}` for `COPILOT_MODEL`. Caution `features.byok-copilot` is deprecated and no longer needed. Existing workflows may still include it, but it has no effect. For Copilot BYOK setup and policy details, see [Using your LLM provider API keys with Copilot](https://docs.github.com/en/copilot/how-tos/administer-copilot/manage-for-enterprise/use-your-own-api-keys). Note Copilot BYOK defaults apply only to `engine: copilot` workflows. Other engines are unchanged. ## AWF Failure Diagnostics (`features.awf-diagnostic-logs`) [Section titled “AWF Failure Diagnostics (features.awf-diagnostic-logs)”](#awf-failure-diagnostics-featuresawf-diagnostic-logs) Enables AWF Docker operational diagnostics collection on failure by adding `--diagnostic-logs` to AWF runtime arguments. When enabled, AWF includes failure diagnostics under the `diagnostics/` subdirectory in the `firewall-audit-logs` artifact (for example, container logs, exit codes, mount metadata, and sanitized compose configuration). ```yaml features: awf-diagnostic-logs: true ``` ## Reaction-based Trust Signals (`features.integrity-reactions`) [Section titled “Reaction-based Trust Signals (features.integrity-reactions)”](#reaction-based-trust-signals-featuresintegrity-reactions) Enables maintainers to promote or demote content past the integrity filter using GitHub reactions (, , , ), without adding labels or modifying issue state. Available from gh-aw v0.68.2. ```yaml features: integrity-reactions: true ``` When set, the compiler automatically enables the CLI proxy (required to identify reaction authors) and injects default endorsement and disapproval reaction configuration. Only the `features.integrity-reactions` flag is required — the reaction fields under `tools.github` (`endorsement-reactions`, `disapproval-reactions`, `endorser-min-integrity`, `disapproval-integrity`) are optional overrides. See [Promoting and demoting items via reactions](/gh-aw/reference/integrity/#promoting-and-demoting-items-via-reactions) in the Integrity Filtering Reference for complete configuration details. ## DIFC Proxy (`tools.github.integrity-proxy`) [Section titled “DIFC Proxy (tools.github.integrity-proxy)”](#difc-proxy-toolsgithubintegrity-proxy) Controls DIFC (Data Integrity and Flow Control) proxy injection. When `tools.github.min-integrity` is configured, the compiler inserts proxy steps around the agent that enforce integrity-level isolation at the network boundary. The proxy is **enabled by default** — set `integrity-proxy: false` to opt out. ```yaml tools: github: min-integrity: approved # integrity-proxy: false # uncomment to disable proxy injection ``` Without `min-integrity`, `integrity-proxy` has no effect. When both are configured, the proxy enforces network-boundary integrity filtering in addition to the MCP gateway-level filtering. Set `integrity-proxy: false` when you only need gateway-level filtering. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Frontmatter Reference](/gh-aw/reference/frontmatter/) — Complete frontmatter field reference * [AI Engines](/gh-aw/reference/engines/) — Engine configuration including Copilot BYOK * [Integrity Filtering](/gh-aw/reference/integrity/) — Integrity levels, reactions, and DIFC proxy * [Network Permissions](/gh-aw/reference/network/) — Network access configuration # Footer Control > Learn how to control AI-generated footers in safe output operations and customize footer messages for GitHub issues, pull requests, discussions, and releases. Control whether AI-generated footers are added to created and updated GitHub items (issues, pull requests, discussions, releases). Footers provide attribution and links to workflow runs, but you may want to omit them for cleaner content or when using custom branding. ## Global Footer Control [Section titled “Global Footer Control”](#global-footer-control) Set `footer: false` at the safe-outputs level to hide footers for all output types: ```yaml safe-outputs: footer: false # hide footers globally create-issue: title-prefix: "[ai] " create-pull-request: title-prefix: "[ai] " ``` When `footer: false` is set, visible attribution text is omitted from item bodies but hidden XML markers remain for searchability: * `` — for search and tracking * `` — for issue/discussion tracking Applies to all output types: create-issue, create-pull-request, create-discussion, update-issue, update-pull-request, update-discussion, and update-release. ### Searching for Workflow-Created Items [Section titled “Searching for Workflow-Created Items”](#searching-for-workflow-created-items) Use the `gh-aw-workflow-id` marker (the workflow filename without `.md`) to find items in GitHub search: ```plaintext repo:owner/repo is:issue is:open "gh-aw-workflow-id: daily-team-status" in:body repo:owner/repo "gh-aw-workflow-id: bot-responder" in:comments ``` Combine with `is:open`, `created:>2024-01-01`, or `org:your-org` filters. See [GitHub advanced search](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests). ## Per-Handler Footer Control [Section titled “Per-Handler Footer Control”](#per-handler-footer-control) Override the global setting for specific output types by setting `footer` at the handler level: ```yaml safe-outputs: footer: false # global default: no footers create-issue: title-prefix: "[issue] " # inherits footer: false create-pull-request: title-prefix: "[pr] " footer: true # override: show footer for PRs only ``` Individual handler settings always take precedence over the global setting. ## PR Review Footer Control [Section titled “PR Review Footer Control”](#pr-review-footer-control) For PR reviews (`submit-pull-request-review`), the `footer` field supports conditional control over when the footer is added to the review body: ```yaml safe-outputs: create-pull-request-review-comment: submit-pull-request-review: footer: "if-body" # conditional footer based on review body ``` The `footer` field accepts `"always"` (default), `"none"`, or `"if-body"` (footer only when the review has body text). Booleans are accepted: `true` → `"always"`, `false` → `"none"`. Use `"if-body"` for clean approval reviews — approvals without body text appear without a footer, while reviews with comments include it. ## Backward Compatibility [Section titled “Backward Compatibility”](#backward-compatibility) The default value for `footer` is `true`. To hide footers, explicitly set `footer: false`. ## Customizing Footer Messages [Section titled “Customizing Footer Messages”](#customizing-footer-messages) Instead of hiding footers entirely, you can customize the footer message text using the `messages.footer` template. This allows you to maintain attribution while using custom branding: ```yaml safe-outputs: messages: footer: "> Powered by [{workflow_name}]({agentic_workflow_url})" create-issue: title-prefix: "[bot] " ``` The `messages.footer` template supports variables like `{workflow_name}`, `{agentic_workflow_url}`, `{run_url}`, `{triggering_number}`, `{effective_tokens_suffix}`, and more. `{agentic_workflow_url}` links directly to the agentic workflow file view for the run (equivalent to `{run_url}/agentic_workflow`), while `{run_url}` links to the plain Actions run page. `{effective_tokens_suffix}` is a pre-formatted, always-safe suffix (e.g. `" · ● 1.2K"` or `""`) that you can place directly before `{history_link}` — the same `●` format the default footer uses. See [Custom Messages](/gh-aw/reference/safe-outputs/#custom-messages-messages) for complete documentation on message templates and available variables. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Safe Outputs](/gh-aw/reference/safe-outputs/) - Complete safe outputs reference * [Custom Messages](/gh-aw/reference/safe-outputs/#custom-messages-messages) - Message templates and variables * [Frontmatter](/gh-aw/reference/frontmatter/) - All configuration options for workflows # Forecast Command Specification > Formal W3C-style specification for the gh aw forecast command — Monte Carlo token-usage projection, episode analysis, workflow discovery, and output formats for GitHub Agentic Workflows # Forecast Command Specification [Section titled “Forecast Command Specification”](#forecast-command-specification) **Version**: 0.1.0\ **Status**: Experimental Draft\ **Latest Version**: [forecast-specification](/gh-aw/reference/forecast-specification/)\ **Editor**: GitHub Agentic Workflows Team > ! **Experimental**: This specification describes a feature that is under active development. The command interface, output schema, and algorithmic parameters are subject to change without notice. Do not depend on this interface in production workflows. *** ## Abstract [Section titled “Abstract”](#abstract) This specification defines the `gh aw forecast` command for the GitHub Agentic Workflows (gh-aw) project. The command performs historical sampling of completed agentic workflow runs and applies a Monte Carlo simulation engine to project future Effective Token (ET) consumption over a configurable time horizon. The specification covers workflow discovery (local and remote modes), data sampling via the GitHub Actions API, the Poisson–bootstrap Monte Carlo projection algorithm, episode-level analysis, and both console-table and machine-readable JSON output formats. Implementations conforming to this specification provide operators with probabilistic token-consumption forecasts suitable for capacity planning, cost estimation, and budget governance. *** ## Status of This Document [Section titled “Status of This Document”](#status-of-this-document) This section describes the status of this document at the time of publication. This is an **Experimental Draft** specification and may be updated, replaced, or made obsolete by other documents at any time. The feature it describes is experimental and not yet subject to the stability guarantees that apply to other gh-aw commands. This document is governed by the GitHub Agentic Workflows project specifications process. Feedback should be filed as GitHub issues against the `github/gh-aw` repository. *** ## Table of Contents [Section titled “Table of Contents”](#table-of-contents) 1. [Introduction](#1-introduction) 2. [Conformance](#2-conformance) 3. [Terminology](#3-terminology) 4. [Command Interface](#4-command-interface) 5. [Workflow Discovery](#5-workflow-discovery) 6. [Data Sampling](#6-data-sampling) 7. [Monte Carlo Projection Engine](#7-monte-carlo-projection-engine) 8. [Episode Analysis](#8-episode-analysis) 9. [Output Formats](#9-output-formats) 10. [Error Handling](#10-error-handling) 11. [Implementation Requirements](#11-implementation-requirements) 12. [Compliance Testing](#12-compliance-testing) 13. [Sync Notes](#13-sync-notes) 14. [Appendices](#14-appendices) 15. [References](#15-references) 16. [Change Log](#16-change-log) *** ## 1. Introduction [Section titled “1. Introduction”](#1-introduction) ### 1.1 Purpose [Section titled “1.1 Purpose”](#11-purpose) The `gh aw forecast` command addresses the operational need to predict future Large Language Model (LLM) token expenditure for agentic workflows managed by gh-aw. Token consumption is a primary cost driver for agentic systems; the ability to project future usage from historical observations enables: * **Capacity Planning**: Anticipating token demand before budget thresholds are reached. * **Cost Governance**: Providing P10/P50/P90 confidence intervals for financial planning. * **Workflow Comparison**: Ranking workflows by projected token cost across a shared time period. * **Experiment Evaluation**: Measuring the token impact of A/B experiment variants. The command combines empirical bootstrapping of historical token observations with a Poisson-distributed run-count model to produce statistically sound projections without requiring parametric distribution assumptions on token usage. ### 1.2 Scope [Section titled “1.2 Scope”](#12-scope) This specification covers: * Command-line interface: flags, positional arguments, and invocation modes * Workflow discovery in local (`.github/workflows/`) and remote (`--repo`) modes * Historical run sampling and per-run metric derivation * The Monte Carlo simulation algorithm producing P10, P50, P90 percentile estimates * Episode grouping and episode-level metric computation * Console table output format * Machine-readable JSON output schema (`--json`) * Error conditions and graceful-degradation behavior This specification does NOT cover: * The Effective Tokens (ET) computation algorithm (defined in the [Effective Tokens Specification](/gh-aw/reference/effective-tokens-specification/)) * The `aw_info.json` artifact schema * A/B experiment frontmatter schema (defined in the [A/B Experiments Specification](/gh-aw/practices/experiments-specification/)) * Billing, pricing, or financial modeling beyond token projections * Streaming or real-time token consumption reporting ### 1.3 Design Goals [Section titled “1.3 Design Goals”](#13-design-goals) A conforming `gh aw forecast` implementation MUST be designed for: * **Empirical Accuracy**: Projections derived from observed historical data rather than assumed distributions. * **Probabilistic Reporting**: P10/P50/P90 uncertainty bounds communicated to callers. * **Graceful Degradation**: Missing data (no runs, no artifacts, no frontmatter) MUST produce partial results rather than failures. * **Dual Modes**: Both local-repository and remote-repository operation without requiring a checkout. * **Interoperability**: JSON output schema stable enough for machine consumption by downstream tooling. *** ## 2. Conformance [Section titled “2. Conformance”](#2-conformance) ### 2.1 Conformance Classes [Section titled “2.1 Conformance Classes”](#21-conformance-classes) A **conforming forecast implementation** is one that satisfies all MUST, REQUIRED, and SHALL requirements in this specification. A **partially conforming forecast implementation** is one that satisfies all MUST requirements in Sections 4, 5, 6, and 7 but MAY lack support for optional features such as episode analysis (Section 8), experiment variant reporting, or verbose diagnostics. ### 2.2 Requirements Notation [Section titled “2.2 Requirements Notation”](#22-requirements-notation) The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). ### 2.3 Compliance Levels [Section titled “2.3 Compliance Levels”](#23-compliance-levels) Implementations MUST support: * **Level 1 (Required)**: Command invocation, workflow discovery, historical data sampling, and Monte Carlo projection with console output. * **Level 2 (Standard)**: JSON output (`--json`), episode analysis, remote-repository mode (`--repo`), and experiment variant reporting. * **Level 3 (Complete)**: All optional features including `--verbose` diagnostics, concurrency limit reporting, and frontmatter metadata enrichment. *** ## 3. Terminology [Section titled “3. Terminology”](#3-terminology) ### 3.1 Effective Tokens (ET) [Section titled “3.1 Effective Tokens (ET)”](#31-effective-tokens-et) A normalized unit of LLM token consumption defined in the [Effective Tokens Specification](/gh-aw/reference/effective-tokens-specification/). ET accounts for token class weights and model multipliers to produce a single comparable scalar across heterogeneous LLM invocations. ### 3.2 Workflow Run [Section titled “3.2 Workflow Run”](#32-workflow-run) A single execution of a GitHub Actions workflow. A run has a unique numeric run ID, an event type, a status (`completed`, `in_progress`, `queued`), a conclusion (`success`, `failure`, `cancelled`, etc.), and a head commit SHA. ### 3.3 Historical Window [Section titled “3.3 Historical Window”](#33-historical-window) The time interval `[now − days, now]` used to bound the set of completed runs eligible for sampling. Controlled by the `--days` flag. ### 3.4 Sample [Section titled “3.4 Sample”](#34-sample) The subset of completed workflow runs within the historical window selected for metric derivation. The maximum sample size per workflow is controlled by the `--sample` flag. ### 3.5 Monte Carlo Trial [Section titled “3.5 Monte Carlo Trial”](#35-monte-carlo-trial) A single independent simulation that draws stochastic values for run count, per-run token usage, and per-run success, combining them to produce one projected Effective Token total for the projection period. ### 3.6 Projection Period [Section titled “3.6 Projection Period”](#36-projection-period) The future time interval for which token consumption is projected. Controlled by the `--period` flag; either one calendar week (`week`) or one calendar month (`month`). ### 3.7 Observed Runs Per Period [Section titled “3.7 Observed Runs Per Period”](#37-observed-runs-per-period) The rate of workflow runs observed in the historical window, extrapolated to the projection period length: ```plaintext observed_runs_per_period = (sampled_run_count / history_days) × period_days ``` Where `period_days` is 7 for `week` and 30 for `month`. ### 3.8 Episode [Section titled “3.8 Episode”](#38-episode) A logical grouping of one or more workflow runs that collectively represent a single task attempt. Episodes are identified by grouping runs sharing the same `headSha` and `headBranch`, or by `workflow_dispatch`/`workflow_call` linkage where available. ### 3.9 Yield [Section titled “3.9 Yield”](#39-yield) The effective throughput rate: the expected number of successful runs per projection period, computed as the product of the observed run frequency and the historical success rate: ```plaintext yield = observed_runs_per_period × success_rate ``` Where `success_rate = successful_run_count / total_sampled_run_count`. ### 3.10 Bootstrap Resampling [Section titled “3.10 Bootstrap Resampling”](#310-bootstrap-resampling) An empirical resampling technique where individual observations are drawn with replacement from the observed sample. Used in Section 7 to model per-run token usage without parametric distribution assumptions. ### 3.11 Lock File [Section titled “3.11 Lock File”](#311-lock-file) A `.lock.yml` file located in `.github/workflows/` that declares a compiled agentic workflow and its associated metadata. Lock files are the authoritative source of workflow identifiers in local mode. *** ## 4. Command Interface [Section titled “4. Command Interface”](#4-command-interface) ### 4.1 Synopsis [Section titled “4.1 Synopsis”](#41-synopsis) ```plaintext gh aw forecast [workflow_id...] [flags] ``` ### 4.2 Positional Arguments [Section titled “4.2 Positional Arguments”](#42-positional-arguments) | Argument | Type | Required | Description | | ------------- | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `workflow_id` | string (repeatable) | No | Zero or more workflow identifiers to forecast. If omitted, all discovered agentic workflows are forecasted. | Workflow identifiers MUST be matched case-insensitively against: 1. The workflow display name 2. The workflow file-path basename (without extension) If a provided `workflow_id` does not match any discovered workflow, the implementation MUST emit an error message identifying the unmatched identifier and MUST exit with a non-zero status code. ### 4.3 Flags [Section titled “4.3 Flags”](#43-flags) | Flag | Type | Default | Description | | ----------- | ------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--days` | int | `30` | Length of the historical sampling window in days. Permitted values: `7`, `30`. | | `--period` | string | `"month"` | Projection period length. Permitted values: `"week"`, `"month"`. | | `--sample` | int | `100` | Maximum number of completed runs to sample per workflow. MUST be ≥ 1. | | `--max-age` | int | `90` | Maximum age in days for historical runs eligible for sampling. Implementations SHOULD discard runs older than this bound unless the caller overrides it. MUST be ≥ 1. | | `--repo` | string | (none) | Target a repository other than the current working directory, in `owner/repo` format. Enables remote mode. | | `--json` | bool | `false` | Emit machine-readable JSON output instead of console tables. | | `--verbose` | bool | `false` | Emit verbose diagnostic output to stderr during processing. | ### 4.4 Flag Validation [Section titled “4.4 Flag Validation”](#44-flag-validation) Implementations MUST validate all flag values before beginning any API calls or file system operations: * **R-CLI-001**: If `--days` is not one of `{7, 30}`, the implementation MUST exit with a non-zero status and an error message specifying the permitted values. * **R-CLI-002**: If `--period` is not one of `{"week", "month"}`, the implementation MUST exit with a non-zero status and an error message specifying the permitted values. * **R-CLI-003**: If `--sample` is less than 1, the implementation MUST exit with a non-zero status. * **R-CLI-004**: If `--repo` is provided, it MUST match the pattern `owner/repo` (two non-empty components separated by `/`). An invalid format MUST produce a non-zero exit with a descriptive error. * **R-CLI-005**: If `--max-age` is provided and is less than 1, the implementation MUST exit with a non-zero status and a descriptive error. ### 4.5 Exit Codes [Section titled “4.5 Exit Codes”](#45-exit-codes) | Code | Meaning | | ---- | ---------------------------------------------------- | | `0` | Forecast completed successfully. | | `1` | Usage error (invalid flags, unmatched workflow IDs). | | `2` | GitHub API authentication failure. | | `3` | No workflows discovered. | ### 4.6 Example Invocations [Section titled “4.6 Example Invocations”](#46-example-invocations) ```sh # Forecast all agentic workflows in the current repository for the next month gh aw forecast # Forecast two specific workflows and compare gh aw forecast ci-doctor daily-planner # Use a 7-day window and project over the next week gh aw forecast --period week --days 7 # Emit machine-readable JSON gh aw forecast --json # Forecast workflows in a remote repository gh aw forecast --repo owner/repo # Forecast a specific workflow in a remote repository gh aw forecast --repo owner/repo ci-doctor # Ignore historical runs older than 90 days (default) gh aw forecast --max-age 90 ``` *** ## 5. Workflow Discovery [Section titled “5. Workflow Discovery”](#5-workflow-discovery) ### 5.1 Modes [Section titled “5.1 Modes”](#51-modes) The forecast command operates in one of two discovery modes, determined by the presence of the `--repo` flag: * **Local Mode**: `--repo` is absent; workflows are discovered from the current repository’s `.github/workflows/` directory. * **Remote Mode**: `--repo` is present; workflows are discovered via the GitHub Actions API. ### 5.2 Local Mode Discovery [Section titled “5.2 Local Mode Discovery”](#52-local-mode-discovery) In local mode, the implementation MUST: 1. **R-DISC-001**: Enumerate all files matching `*.lock.yml` within `.github/workflows/` of the current working repository. 2. **R-DISC-002**: Parse each lock file to extract the workflow identifier and display name. 3. **R-DISC-003**: If the `.github/workflows/` directory does not exist or contains no lock files, the implementation MUST emit an informational message and exit with code `3`. The implementation MAY additionally read frontmatter metadata from corresponding workflow source files to enrich per-workflow records with: * Active trigger types (`active_triggers`) * Concurrency configuration (`concurrency_limit`) * A/B experiment variant declarations (`experiment_variants`) Frontmatter enrichment is OPTIONAL; absence of a corresponding source file MUST NOT prevent discovery or projection of the workflow. ### 5.3 Remote Mode Discovery [Section titled “5.3 Remote Mode Discovery”](#53-remote-mode-discovery) In remote mode (when `--repo owner/repo` is specified), the implementation MUST: 1. **R-DISC-010**: Call the GitHub Actions API (`GET /repos/{owner}/{repo}/actions/workflows`) to enumerate workflows in the target repository. If workflow discovery hits a primary or secondary GitHub API rate limit, the implementation SHOULD back off and retry before failing. 2. **R-DISC-011**: Filter the returned workflows to those identified as agentic (e.g., by inspecting file-path conventions, labels, or other implementation-defined heuristics). 3. **R-DISC-012**: Match any caller-supplied `workflow_id` positional arguments against workflow display names and file-path basenames using case-insensitive string comparison. 4. **R-DISC-013**: If rate-limit exhaustion occurs after at least one caller-supplied workflow identifier can still be attempted, the implementation MUST continue with that subset as a partial result set and MUST emit a warning identifying the degraded discovery mode. 5. **R-DISC-014**: Implementations MUST tolerate workflow discovery race conditions where a workflow is renamed, disabled, or deleted after enumeration but before run sampling. The affected workflow MUST be reported as a per-workflow partial failure without aborting the overall forecast. Remote workflow discovery race-condition mitigation: * Capture a stable snapshot of discovered workflow IDs from the initial listing call. * During per-workflow run sampling, treat HTTP 404/410 for a previously listed workflow as a recoverable per-workflow partial failure. * Emit a warning that identifies the workflow and the race condition class (renamed, removed, or inaccessible at sample time). In remote mode, frontmatter metadata (triggers, concurrency, experiment variants) is UNAVAILABLE because the workflow source files are not accessible. The implementation MUST degrade gracefully: fields that depend on frontmatter MUST be omitted from output or reported as their zero/empty values rather than causing an error. ### 5.4 Workflow ID Matching [Section titled “5.4 Workflow ID Matching”](#54-workflow-id-matching) Workflow ID matching MUST be case-insensitive. A caller-supplied identifier matches a discovered workflow if and only if it equals (ignoring case) either: * The workflow’s display name, OR * The basename of the workflow’s file path (without file extension) Matching MUST be performed after discovery is complete; partial prefix matches are NOT sufficient for conformance. *** ## 6. Data Sampling [Section titled “6. Data Sampling”](#6-data-sampling) ### 6.1 Sampling Procedure [Section titled “6.1 Sampling Procedure”](#61-sampling-procedure) For each discovered workflow (or each workflow in the filtered set), the implementation MUST perform the following sampling procedure: 1. **R-SAMP-001**: Query completed workflow runs within the historical window using the equivalent of `gh run list --workflow --status completed --limit --created >=`. 2. **R-SAMP-002**: Limit the returned run set to at most `--sample` runs. 3. **R-SAMP-003**: Implementations SHOULD discard historical runs older than 90 days by default, even when a broader sampling window is requested, and SHOULD expose this bound through a `--max-age` flag so operators can opt in to older samples when needed. 4. **R-SAMP-004**: For each run in the sample, derive the per-run metrics defined in Section 6.2. 5. **R-SAMP-005**: Record the count of runs with a successful conclusion separately from the total sampled count. If the historical window yields zero completed runs for a workflow, the implementation MUST: * **R-SAMP-006**: Return `nil` (or a sentinel empty result) for that workflow’s Monte Carlo projection. * **R-SAMP-007**: Include the workflow in output with `sampled_runs: 0` and all projection fields set to zero. * **R-SAMP-008**: SHOULD emit a warning indicating that no historical data is available for the workflow. ### 6.2 Per-Run Metric Derivation [Section titled “6.2 Per-Run Metric Derivation”](#62-per-run-metric-derivation) For each sampled run, the implementation MUST derive: | Metric | Source | Description | | ------------------ | ------------------------ | ----------------------------------------------------------------------- | | `effective_tokens` | `aw_info.json` artifact | Total ET for this run as defined in the Effective Tokens Specification. | | `duration_seconds` | Run start/end timestamps | Wall-clock duration of the run in seconds. | | `success` | Run conclusion field | `true` if conclusion is `"success"`, `false` otherwise. | #### 6.2.1 Effective Token Retrieval [Section titled “6.2.1 Effective Token Retrieval”](#621-effective-token-retrieval) Effective token counts are obtained from locally-cached run summaries when available. The `gh aw logs` command stores a `run_summary.json` file for each processed run under `{output_dir}/run-{run_id}/`. During forecasting the implementation: * **R-SAMP-010**: MUST attempt to load the cached `run_summary.json` for each sampled run using the default logs output directory (`.github/aw/logs`). * **R-SAMP-011**: MUST extract the `TotalEffectiveTokens` field from the cached `TokenUsage` summary when present. * **R-SAMP-012**: If no cached summary exists or the ET field is zero, the run’s ET contribution MUST be treated as zero and the run MUST still be counted in `sampled_runs`. The implementation SHOULD log a debug-level warning. This lightweight approach avoids re-downloading artifacts while still providing accurate ET observations for runs that have already been processed locally by `gh aw logs`. #### 6.2.2 Duration Derivation [Section titled “6.2.2 Duration Derivation”](#622-duration-derivation) Duration MUST be computed as: ```plaintext duration_seconds = run.updated_at − run.started_at ``` Both timestamps MUST be sourced from the GitHub Actions API run object. If either timestamp is zero or unavailable, the run’s duration contribution SHOULD be treated as zero. ### 6.3 Observed Rate Computation [Section titled “6.3 Observed Rate Computation”](#63-observed-rate-computation) After sampling, the implementation MUST compute: ```plaintext observed_runs_per_period = (sampled_run_count / history_days) × period_days ``` Where: * `history_days` is the value of `--days` * `period_days` is `7` for `"week"` and `30` for `"month"` *** ## 7. Monte Carlo Projection Engine [Section titled “7. Monte Carlo Projection Engine”](#7-monte-carlo-projection-engine) ### 7.1 Overview [Section titled “7.1 Overview”](#71-overview) The Monte Carlo engine runs **10,000 independent simulation trials** per workflow to produce a probability distribution over projected Effective Token consumption in the next projection period. The engine models three independent sources of uncertainty per trial. Implementations MUST use exactly 10,000 trials. The trial count is a normative requirement to ensure consistency of P10/P50/P90 estimates across implementations. ### 7.2 Uncertainty Sources [Section titled “7.2 Uncertainty Sources”](#72-uncertainty-sources) Each trial draws independently from three stochastic components: #### 7.2.1 Run Count (Poisson Model) [Section titled “7.2.1 Run Count (Poisson Model)”](#721-run-count-poisson-model) The number of runs in the projection period is modeled as a Poisson random variable with rate parameter: ```plaintext λ = observed_runs_per_period ``` The implementation MUST use: * **Knuth’s exact algorithm** when `λ ≤ 15`: ```plaintext L ← e^(−λ) k ← 0; p ← 1 repeat: k ← k + 1 p ← p × Uniform(0, 1) until p ≤ L return k − 1 ``` * **Normal approximation** when `λ > 15`: ```plaintext k ← round(Normal(μ=λ, σ=sqrt(λ))) k ← max(0, k) ``` * **R-MC-001**: For `λ = 0`, the implementation MUST return a projected token total of 0 for that trial without invoking either algorithm. * **R-FC-060**: Implementations MUST use `λ = 15` as the crossover threshold: Knuth’s exact algorithm for `λ ≤ 15`, and Normal approximation only for `λ > 15`. Implementations MUST NOT raise this threshold above 15 without a specification revision, because the documented error and comparability assumptions are calibrated to this crossover. * **R-MC-002**: `λ` MUST be derived from `observed_runs_per_period` using the formula in §3.7 and MUST be reused unchanged for every trial of the same workflow forecast. Implementations MUST NOT recalculate or modify `λ` within a single forecast run. * **R-MC-003**: `λ` MUST be treated as a real-valued rate parameter. Implementations MUST NOT round, floor, or ceil `λ` before selecting the Poisson branch or before drawing the projected run count. * **R-MC-004**: If the computed `λ` is negative, `NaN`, or otherwise non-finite, implementations MUST replace it with `0`, emit a warning, and continue in the same zero-projection mode required by **R-MC-001**. #### 7.2.2 Per-Run Token Usage (Bootstrap Resampling) [Section titled “7.2.2 Per-Run Token Usage (Bootstrap Resampling)”](#722-per-run-token-usage-bootstrap-resampling) Token usage per run is modeled empirically using bootstrap resampling: * **R-MC-010**: For each run in a trial, the implementation MUST draw one observation uniformly at random **with replacement** from the set of historical ET observations in the sample. * **R-MC-011**: If the sample contains zero ET observations (all runs had missing artifacts), the per-run token draw MUST return 0. This non-parametric approach preserves the empirical distribution of token usage, including multi-modal distributions and heavy tails, without imposing a parametric form. #### 7.2.3 Per-Run Success (Bernoulli Model) [Section titled “7.2.3 Per-Run Success (Bernoulli Model)”](#723-per-run-success-bernoulli-model) Whether a given run in the trial succeeds is modeled as a Bernoulli draw: ```plaintext P(success) = success_rate = successful_run_count / total_sampled_run_count ``` * **R-MC-020**: Each run in a trial MUST independently draw from `Bernoulli(success_rate)`. * **R-MC-021**: Only successful runs contribute their token draw to the trial’s projected total. Failed runs contribute zero tokens to the projection. * **R-MC-022**: If `total_sampled_run_count = 0`, `success_rate` MUST be treated as 0. The implementation MUST return a zero projection for all trials. ### 7.3 Trial Aggregation [Section titled “7.3 Trial Aggregation”](#73-trial-aggregation) For a given trial with `k` drawn runs: ```plaintext trial_tokens = Σ_{i=1}^{k} (success_i × token_draw_i) ``` Where: * `success_i` is `1` if the Bernoulli draw for run `i` succeeds, `0` otherwise * `token_draw_i` is the bootstrapped ET observation for run `i` ### 7.4 Output Statistics [Section titled “7.4 Output Statistics”](#74-output-statistics) After completing all 10,000 trials, the implementation MUST compute and report: | Statistic | Definition | | --------------------------------- | ----------------------------------------------------------- | | `mean_projected_effective_tokens` | Arithmetic mean of all trial totals | | `std_dev_effective_tokens` | Population or sample standard deviation of all trial totals | | `p10_projected_effective_tokens` | 10th percentile of trial totals (lower bound of 80% CI) | | `p50_projected_effective_tokens` | 50th percentile of trial totals (median projection) | | `p90_projected_effective_tokens` | 90th percentile of trial totals (upper bound of 80% CI) | Percentile computation MUST use the nearest-rank method or an equivalent method that produces results consistent with a 10,000-element sorted array. The `projected_effective_tokens` top-level field MUST equal `p50_projected_effective_tokens`. ### 7.5 Nil Projection Condition [Section titled “7.5 Nil Projection Condition”](#75-nil-projection-condition) If no historical runs are available for a workflow, the implementation MUST return a nil (empty/zero) projection for that workflow. Nil projections MUST be represented in JSON output as zero values for all numeric Monte Carlo fields. The implementation MUST NOT run trials when the sample is empty. ### 7.6 Minimum Sample Size for Percentile Validity [Section titled “7.6 Minimum Sample Size for Percentile Validity”](#76-minimum-sample-size-for-percentile-validity) The P10 and P90 estimates produced by the Monte Carlo engine are only statistically reliable when the bootstrap sample contains a sufficient number of distinct ET observations. * **R-MC-030**: Implementations SHOULD require a minimum of **10** ET observations (i.e., runs with non-zero `effective_tokens`) before treating P10 and P90 as reliable estimates. When `n < 10`, implementations SHOULD emit a warning to stderr indicating that the confidence interval may be unreliable due to insufficient sample size. *Rationale: Bootstrap resampling with fewer than 10 observations produces percentile estimates that are highly sensitive to individual outliers. With n < 10, the P10 and P90 bounds collapse toward the single minimum and maximum observations, making the 80% confidence interval misleadingly precise. The threshold of 10 is consistent with standard statistical practice for non-parametric bootstrapping.* * **R-MC-031**: Implementations MUST still run the Monte Carlo simulation and return P10/P50/P90 values even when `n < 10`. The simulation MUST NOT be suppressed solely on the basis of sample size; the warning in **R-MC-030** is advisory only. * **R-MC-032**: When `n = 0` (no ET observations in the sample), the **Nil Projection Condition** in §7.5 applies and the simulation MUST NOT run. This is a separate condition from the low-sample warning. *** ## 8. Episode Analysis [Section titled “8. Episode Analysis”](#8-episode-analysis) ### 8.1 Purpose [Section titled “8.1 Purpose”](#81-purpose) An **episode** is a logical grouping of one or more workflow runs that collectively represent a single task attempt. Episode analysis computes per-episode metrics to reveal how many runs, on average, are required to complete a task successfully. ### 8.2 Episode Construction [Section titled “8.2 Episode Construction”](#82-episode-construction) The implementation MUST group sampled runs into episodes using the `buildEpisodeData` and `classifyEpisode` engine: * **R-EP-001**: Runs sharing the same `headSha` and `headBranch` MUST be grouped into the same episode. * **R-EP-002**: Runs linked by `workflow_dispatch` or `workflow_call` relationships (reconstructed from cached run summaries) SHOULD be merged into the triggering run’s episode. #### 8.2.1 Limitations in Forecast Context [Section titled “8.2.1 Limitations in Forecast Context”](#821-limitations-in-forecast-context) During forecasting, full artifact data may not be available for all sampled runs. When cached summary data is unavailable: * **R-EP-010**: `workflow_dispatch`/`workflow_call` linkage MUST be omitted from episode construction. * **R-EP-011**: The resulting `sampled_episodes` count MUST be treated as a **lower-bound estimate**. Implementations MUST communicate this limitation in output (e.g., via a note in console output or a boolean `episode_count_is_lower_bound` field in JSON). For orchestrator workflows that primarily receive `workflow_call` triggers, the episode count underestimate may be significant. Implementations SHOULD emit a warning when the dominant trigger type is `workflow_call` or `workflow_dispatch`. ### 8.3 Episode Metrics [Section titled “8.3 Episode Metrics”](#83-episode-metrics) For each workflow, the implementation MUST compute: | Metric | Definition | | ---------------------------------- | --------------------------------------------------- | | `sampled_episodes` | Count of distinct episodes identified in the sample | | `runs_per_episode` | `sampled_run_count / sampled_episodes` | | `avg_effective_tokens_per_episode` | Mean ET summed across all runs within each episode | | `observed_episodes_per_period` | `(sampled_episodes / history_days) × period_days` | ### 8.4 Episode Table Display [Section titled “8.4 Episode Table Display”](#84-episode-table-display) The implementation MUST display the episode analysis table in console output when any workflow in the result set has `runs_per_episode > 1.0`. The table SHOULD be omitted when all workflows have `runs_per_episode = 1.0` (one run per episode is the baseline and adds no additional information). *** ## 9. Output Formats [Section titled “9. Output Formats”](#9-output-formats) ### 9.1 Console Table Output [Section titled “9.1 Console Table Output”](#91-console-table-output) When `--json` is not specified, the implementation MUST render a formatted console table to stderr with the following columns: | Column | Description | | ------------------ | -------------------------------------------------------------------------------------------------------------- | | `Workflow` | Workflow display name or identifier | | `Sampled Runs` | Count of completed runs included in the sample | | `Success Rate` | Fraction of sampled runs concluding with `success`, formatted as a percentage; `N/A` when no runs were sampled | | `Yield/Period` | Effective throughput rate (`success_rate × observed_runs_per_period`) formatted to one decimal place | | `Avg ET` | `avg_effective_tokens` formatted as K/M abbreviations (e.g. `12.5K`, `1.20M`); `-` when zero | | `Proj. ET (P50)` | Median projected effective tokens from Monte Carlo (P50), formatted as K/M abbreviations | | `80% CI (P10–P90)` | Confidence interval range `p10–p90`, both formatted as K/M abbreviations | | `Triggers` | Comma-separated list of active trigger event names from frontmatter (up to 3, remainder shown as `+N`) | #### 9.1.1 Table Formatting Requirements [Section titled “9.1.1 Table Formatting Requirements”](#911-table-formatting-requirements) * **R-OUT-001**: Column widths MUST be auto-fitted to the widest value in each column. * **R-OUT-002**: ET values MUST be formatted as K/M abbreviations (e.g. `12.5K`, `1.20M`); raw integer values of zero MUST be rendered as `-`. * **R-OUT-003**: Rows MUST be sorted by Monte Carlo P50 projected effective tokens in descending order; when Monte Carlo data is unavailable, sort by `projected_effective_tokens`. * **R-OUT-004**: A workflow with zero sampled runs MUST appear in the table with `-` in projection columns and `N/A` in rate columns. * **R-OUT-005**: When episode analysis is applicable (Section 8.4), a second table with episode metrics MUST be printed below the main table, separated by a blank line. #### 9.1.2 Example Console Output [Section titled “9.1.2 Example Console Output”](#912-example-console-output) ```plaintext Workflow Sampled Runs Success Rate Yield/Period Avg ET Proj. ET (P50) 80% CI (P10–P90) Triggers ci-doctor 42 92% 35.4 12.5K 480.0K 430.0K–535.0K pull_request, workflow_dispatch daily-planner 18 89% 14.4 8.2K 131.0K 105.0K–158.0K schedule ``` ### 9.2 JSON Output Schema [Section titled “9.2 JSON Output Schema”](#92-json-output-schema) When `--json` is specified, the implementation MUST emit a single JSON object to stdout conforming to the following schema. No additional content (banners, progress indicators, or table output) MUST be emitted to stdout. Diagnostic messages MAY be emitted to stderr. #### 9.2.1 Root Object [Section titled “9.2.1 Root Object”](#921-root-object) ```json { "period": "", "as_of": "", "workflows": [ , ... ] } ``` | Field | Type | Required | Description | | ----------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- | | `period` | string | MUST | Projection period: `"week"` or `"month"`. | | `as_of` | string | MUST | ISO 8601 / RFC 3339 UTC timestamp at which the forecast was computed. | | `workflows` | array | MUST | Ordered array of per-workflow forecast objects. MUST be sorted by `projected_effective_tokens` (P50) descending. | #### 9.2.2 WorkflowForecast Object [Section titled “9.2.2 WorkflowForecast Object”](#922-workflowforecast-object) ```json { "workflow_id": "", "period": "", "sampled_runs": , "history_days": , "observed_runs_per_period": , "success_rate": , "yield": , "avg_effective_tokens": , "avg_duration_seconds": , "projected_effective_tokens": , "active_triggers": [ "", ... ], "concurrency_limit": , "monte_carlo": { }, "episode_analysis": { }, "experiment_variants": [ , ... ] } ``` | Field | Type | Required | Description | | ---------------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `workflow_id` | string | MUST | Workflow identifier as used in discovery. | | `period` | string | MUST | Mirrors the root `period` field. | | `sampled_runs` | integer | MUST | Number of runs included in the sample. | | `history_days` | integer | MUST | Value of `--days` used for this forecast. | | `observed_runs_per_period` | number | MUST | Extrapolated run rate for the projection period. | | `success_rate` | number | MUST | Fraction of sampled runs that concluded successfully, in `[0.0, 1.0]`. | | `yield` | number | MUST | Effective throughput rate: `success_rate × observed_runs_per_period`. | | `avg_effective_tokens` | number | MUST | Mean ET per sampled run. `0` when no ET data is available. | | `avg_duration_seconds` | number | MUST | Mean wall-clock duration per sampled run in seconds. | | `projected_effective_tokens` | number | MUST | P50 Monte Carlo projection. Equals `monte_carlo.p50_projected_effective_tokens`. | | `active_triggers` | array of strings | SHOULD | Trigger event types from workflow frontmatter. Empty array when frontmatter is unavailable. | | `concurrency_limit` | integer | SHOULD | Concurrency group limit from frontmatter. `0` indicates unlimited or unavailable. | | `monte_carlo` | object | MUST | Monte Carlo simulation results. See Section 9.2.3. | | `episode_analysis` | object | SHOULD | Episode analysis results. See Section 9.2.4. | | `experiment_variants` | array | MAY | A/B experiment variant breakdown. See Section 9.2.5. Empty array when frontmatter is unavailable or no experiments are configured. | #### 9.2.3 MonteCarlo Object [Section titled “9.2.3 MonteCarlo Object”](#923-montecarlo-object) ```json { "iterations": 10000, "mean_projected_effective_tokens": , "std_dev_effective_tokens": , "p10_projected_effective_tokens": , "p50_projected_effective_tokens": , "p90_projected_effective_tokens": } ``` | Field | Type | Required | Description | | --------------------------------- | ------- | -------- | ----------------------------------------- | | `iterations` | integer | MUST | Always `10000`. | | `mean_projected_effective_tokens` | number | MUST | Arithmetic mean of trial totals. | | `std_dev_effective_tokens` | number | MUST | Standard deviation of trial totals. | | `p10_projected_effective_tokens` | number | MUST | 10th percentile of trial totals. | | `p50_projected_effective_tokens` | number | MUST | 50th percentile (median) of trial totals. | | `p90_projected_effective_tokens` | number | MUST | 90th percentile of trial totals. | When `sampled_runs = 0`, all numeric fields in this object MUST be `0` and `iterations` MUST be `0`. #### 9.2.4 EpisodeAnalysis Object [Section titled “9.2.4 EpisodeAnalysis Object”](#924-episodeanalysis-object) ```json { "sampled_episodes": , "episode_count_is_lower_bound": , "runs_per_episode": , "avg_effective_tokens_per_episode": , "observed_episodes_per_period": } ``` | Field | Type | Required | Description | | ---------------------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------- | | `sampled_episodes` | integer | MUST | Distinct episode count. Lower-bound estimate when artifact linkage is unavailable. | | `episode_count_is_lower_bound` | boolean | SHOULD | `true` when episode linkage data is incomplete (for example, remote mode without artifacts); otherwise `false`. | | `runs_per_episode` | number | MUST | Mean runs per episode. | | `avg_effective_tokens_per_episode` | number | MUST | Mean ET per episode. | | `observed_episodes_per_period` | number | MUST | Extrapolated episode rate for the projection period. | #### 9.2.5 ExperimentVariant Object [Section titled “9.2.5 ExperimentVariant Object”](#925-experimentvariant-object) ```json { "experiment_name": "", "variant": "", "run_count": , "fraction": } ``` | Field | Type | Required | Description | | ----------------- | ------- | -------- | ----------------------------------------------------------------------- | | `experiment_name` | string | MUST | Name of the A/B experiment from frontmatter. | | `variant` | string | MUST | Variant identifier (e.g., `"control"`, `"treatment"`). | | `run_count` | integer | MUST | Number of sampled runs assigned to this variant. | | `fraction` | number | MUST | `run_count / sampled_runs` for this workflow; fraction in `[0.0, 1.0]`. | #### 9.2.6 Complete JSON Example [Section titled “9.2.6 Complete JSON Example”](#926-complete-json-example) ```json { "period": "month", "as_of": "2026-05-10T22:00:00Z", "workflows": [ { "workflow_id": "ci-doctor", "period": "month", "sampled_runs": 42, "history_days": 30, "observed_runs_per_period": 38.5, "success_rate": 0.92, "yield": 0.92, "avg_effective_tokens": 12500, "avg_duration_seconds": 145.3, "projected_effective_tokens": 480000, "active_triggers": ["pull_request", "workflow_dispatch"], "concurrency_limit": 0, "monte_carlo": { "iterations": 10000, "mean_projected_effective_tokens": 481250, "std_dev_effective_tokens": 32000.5, "p10_projected_effective_tokens": 430000, "p50_projected_effective_tokens": 480000, "p90_projected_effective_tokens": 535000 }, "episode_analysis": { "sampled_episodes": 40, "episode_count_is_lower_bound": true, "runs_per_episode": 1.05, "avg_effective_tokens_per_episode": 13100, "observed_episodes_per_period": 36.7 }, "experiment_variants": [ { "experiment_name": "model-selection", "variant": "control", "run_count": 21, "fraction": 0.5 }, { "experiment_name": "model-selection", "variant": "treatment", "run_count": 21, "fraction": 0.5 } ] } ] } ``` ### 9.3 Output Ordering [Section titled “9.3 Output Ordering”](#93-output-ordering) * **R-OUT-010**: In both console and JSON output, workflows MUST be ordered by `projected_effective_tokens` (P50 value) in descending order. * **R-OUT-011**: Workflows with zero projected tokens MUST appear after all workflows with non-zero projections. * **R-OUT-012**: Among workflows with equal projected tokens, the ordering SHOULD be deterministic (e.g., alphabetical by workflow ID). * **R-OUT-013**: JSON output SHOULD disclose episode lower-bound semantics by including `episode_analysis.episode_count_is_lower_bound` for each workflow. Console output SHOULD include a note when this field is `true`. *** ## 10. Error Handling [Section titled “10. Error Handling”](#10-error-handling) ### 10.1 Authentication Errors [Section titled “10.1 Authentication Errors”](#101-authentication-errors) If the GitHub API returns an authentication error (HTTP 401 or 403): * **R-ERR-001**: The implementation MUST emit a descriptive error message to stderr indicating the authentication failure and guidance on re-authenticating with `gh auth login`. * **R-ERR-002**: The implementation MUST exit with code `2`. ### 10.2 API Rate Limiting [Section titled “10.2 API Rate Limiting”](#102-api-rate-limiting) If the GitHub API returns a rate-limit response (HTTP 429 or a `X-RateLimit-Remaining: 0` header): * **R-ERR-010**: The implementation SHOULD retry the request after the period indicated by the `X-RateLimit-Reset` header. * **R-ERR-011**: The implementation MUST emit a warning to stderr when entering a rate-limit wait state. * **R-ERR-012**: If retry is not feasible, the implementation MUST exit with a non-zero status and a message indicating the rate limit condition. ### 10.3 Partial Failures [Section titled “10.3 Partial Failures”](#103-partial-failures) When one or more workflows in the discovery set encounter individual errors (e.g., artifact download failure, API timeout for a specific workflow): * **R-ERR-020**: The implementation MUST continue processing the remaining workflows rather than aborting the entire forecast. * **R-ERR-021**: Workflows that encountered individual errors MUST appear in output with `sampled_runs: 0` and all projection fields zeroed. * **R-ERR-022**: The implementation MUST emit a warning to stderr for each workflow that encountered an individual error. ### 10.4 No Workflows Discovered [Section titled “10.4 No Workflows Discovered”](#104-no-workflows-discovered) If workflow discovery yields zero workflows: * **R-ERR-030**: The implementation MUST emit a message to stderr indicating that no agentic workflows were found and describing the discovery mode used. * **R-ERR-031**: The implementation MUST exit with code `3`. ### 10.5 Verbose Diagnostics [Section titled “10.5 Verbose Diagnostics”](#105-verbose-diagnostics) When `--verbose` is specified, the implementation SHOULD emit the following additional diagnostic information to stderr: * The list of discovered workflows and their identifiers * The number of runs fetched per workflow * The number of runs with valid ET data versus missing artifacts * The computed `λ` (Poisson rate) for each workflow * Timing information for API calls and simulation execution ### 10.6 Safeguards for API Rate-Limit During Sampling [Section titled “10.6 Safeguards for API Rate-Limit During Sampling”](#106-safeguards-for-api-rate-limit-during-sampling) When the GitHub API returns HTTP 429 or HTTP 403 (with a `X-RateLimit-Remaining: 0` header) during `gh api` sampling calls (i.e., while fetching run lists or artifact data for individual workflows): * **R-ERR-040**: The implementation MUST apply an exponential-backoff retry strategy: the first retry MUST wait at least the number of seconds indicated by the `Retry-After` or `X-RateLimit-Reset` header (whichever is present and non-zero). If neither header is present, the implementation MUST wait at least 60 seconds before the first retry attempt. * **R-ERR-041**: The implementation MUST retry the failed request at least once before treating the workflow as a partial failure. Implementations SHOULD retry up to 3 times with increasing backoff intervals. * **R-ERR-042**: The implementation MUST emit a warning to stderr before each backoff wait period, including the workflow identifier, the HTTP status code received, and the estimated wait duration. * **R-ERR-043**: If all retry attempts are exhausted and the request still fails, the implementation SHOULD fall back to partial-result mode: the affected workflow MUST be included in output with `sampled_runs: 0` and all projection fields set to zero, consistent with **R-ERR-021**. The implementation MUST NOT abort the entire forecast run due to a single workflow’s rate-limit failure. * **R-ERR-044**: When operating in partial-result mode due to rate-limit exhaustion, the implementation SHOULD include a `rate_limit_skipped` boolean field set to `true` in the workflow’s JSON output entry so that callers can distinguish rate-limit-induced zero projections from genuine zero-activity workflows. This field is an **additive optional extension** first defined in Section 10.6; callers MUST treat its absence as equivalent to `false` (per §11.5 / **R-IMPL-041**, unknown fields in JSON output MUST be treated as ignorable). *** ## 11. Implementation Requirements [Section titled “11. Implementation Requirements”](#11-implementation-requirements) ### 11.1 Randomness [Section titled “11.1 Randomness”](#111-randomness) * **R-IMPL-001**: The Monte Carlo engine MUST use a cryptographically seeded pseudorandom number generator (PRNG). Implementations MUST NOT use a fixed seed unless in test mode. * **R-IMPL-002**: The PRNG MUST be seeded independently per forecast invocation to ensure different results on repeated calls. ### 11.2 Performance [Section titled “11.2 Performance”](#112-performance) * **R-IMPL-010**: The 10,000-trial simulation for a single workflow MUST complete within 500 milliseconds on a single CPU core with a sample size of 100 runs. * **R-IMPL-011**: Multiple workflows SHOULD be forecasted concurrently where the runtime environment supports parallelism. * **R-IMPL-012**: API calls for data sampling SHOULD be made concurrently across workflows, subject to GitHub API rate limit constraints. ### 11.3 Deterministic Output [Section titled “11.3 Deterministic Output”](#113-deterministic-output) * **R-IMPL-020**: Given a fixed sample and fixed PRNG seed (in test mode), the Monte Carlo output MUST be reproducible. This requirement applies to test and validation scenarios only; production invocations MUST use random seeds (R-IMPL-001). ### 11.4 Numeric Precision [Section titled “11.4 Numeric Precision”](#114-numeric-precision) * **R-IMPL-030**: All intermediate ET computations MUST use 64-bit floating-point arithmetic (IEEE 754 double precision). * **R-IMPL-031**: JSON serialization of numeric fields MUST NOT produce non-finite values (`NaN`, `+Inf`, `-Inf`). If a computation produces a non-finite value, it MUST be replaced with `0` and a warning MUST be emitted. * **R-IMPL-032**: Implementations MUST NOT round projected ET values in intermediate computations; rounding for display purposes MUST occur only at serialization time. ### 11.5 Experimental Status Behavior [Section titled “11.5 Experimental Status Behavior”](#115-experimental-status-behavior) Because the forecast command is marked **Experimental**: * **R-IMPL-040**: The implementation MUST emit a warning to stderr on every invocation indicating the experimental status of the command unless `--json` is specified (JSON callers are assumed to be automated pipelines that handle warnings separately). * **R-IMPL-041**: The JSON output schema MAY have new fields added in minor versions without notice. Callers MUST treat unknown fields as ignorable. *** ## 12. Compliance Testing [Section titled “12. Compliance Testing”](#12-compliance-testing) ### 12.1 Test Suite Requirements [Section titled “12.1 Test Suite Requirements”](#121-test-suite-requirements) Test fixtures for the compliance tests are located in `specs/forecast-compliance-fixtures/`. See `specs/forecast-compliance-fixtures/README.md` for instructions on running the test suite and adding new fixtures. #### 12.1.1 Command Interface Tests [Section titled “12.1.1 Command Interface Tests”](#1211-command-interface-tests) * **T-FC-001**: Invocation with invalid `--days` value exits non-zero with descriptive error. * **T-FC-002**: Invocation with invalid `--period` value exits non-zero with descriptive error. * **T-FC-003**: Invocation with `--sample < 1` exits non-zero. * **T-FC-004**: Invocation with invalid `--repo` format exits non-zero. * **T-FC-005**: Unmatched `workflow_id` positional argument exits non-zero with identification of the unmatched value. #### 12.1.2 Workflow Discovery Tests [Section titled “12.1.2 Workflow Discovery Tests”](#1212-workflow-discovery-tests) * **T-FC-010**: Local mode: discovers workflows from `.github/workflows/*.lock.yml`. * **T-FC-011**: Local mode: no lock files found exits with code `3`. * **T-FC-012**: Remote mode: calls GitHub Actions API and matches workflow IDs case-insensitively. * **T-FC-013**: Remote mode: missing frontmatter fields default to zero/empty without error. * **T-FC-030**: Remote mode: on GitHub API rate-limit exhaustion during workflow discovery, the implementation backs off and emits a warning before continuing with caller-supplied workflow IDs as partial results. #### 12.1.3 Data Sampling Tests [Section titled “12.1.3 Data Sampling Tests”](#1213-data-sampling-tests) * **T-FC-020**: Sampling respects `--sample` limit. * **T-FC-021**: Sampling respects `--days` historical window cutoff. * **T-FC-022**: Run with missing `aw_info.json` artifact contributes zero ET and is still counted in `sampled_runs`. * **T-FC-023**: Workflow with zero sampled runs produces nil projection with zero fields. #### 12.1.4 Monte Carlo Engine Tests [Section titled “12.1.4 Monte Carlo Engine Tests”](#1214-monte-carlo-engine-tests) * **T-FC-031**: With `λ ≤ 15`, Knuth’s algorithm is used for Poisson draw (verifiable by seeded PRNG in test mode). * **T-FC-032**: With `λ > 15`, Normal approximation is used; drawn value is non-negative. * **T-FC-033**: With `λ = 0`, projected tokens is exactly `0` for all trials. * **T-FC-034**: Bootstrap resampling draws with replacement from historical ET observations. * **T-FC-035**: Only successful Bernoulli draws contribute ET to the trial total. * **T-FC-036**: 10,000 trials are executed per workflow. * **T-FC-037**: P10 ≤ P50 ≤ P90 for all non-zero projections. * **T-FC-038**: `projected_effective_tokens` equals `p50_projected_effective_tokens`. * **T-FC-039**: Boundary crossover: `λ = 15` uses Knuth’s exact branch. * **T-FC-040**: Boundary crossover: `λ > 15` uses Normal approximation branch. #### 12.1.5 Episode Analysis Tests [Section titled “12.1.5 Episode Analysis Tests”](#1215-episode-analysis-tests) * **T-FC-041**: Runs sharing `headSha` and `headBranch` are grouped into the same episode. * **T-FC-042**: `runs_per_episode` equals `sampled_run_count / sampled_episodes`. * **T-FC-043**: Episode table is printed in console output when any workflow has `runs_per_episode > 1`. * **T-FC-044**: Episode table is suppressed when all workflows have `runs_per_episode = 1.0`. #### 12.1.6 Output Format Tests [Section titled “12.1.6 Output Format Tests”](#1216-output-format-tests) * **T-FC-050**: Console output contains all required columns. * **T-FC-051**: JSON output is valid JSON conforming to the schema in Section 9.2. * **T-FC-052**: JSON `as_of` field is a valid RFC 3339 UTC timestamp. * **T-FC-053**: JSON `workflows` array is sorted by `projected_effective_tokens` descending. * **T-FC-054**: No stdout output (other than JSON) when `--json` is specified. * **T-FC-055**: Experimental warning emitted to stderr unless `--json` is specified. ### 12.2 Compliance Checklist [Section titled “12.2 Compliance Checklist”](#122-compliance-checklist) | Requirement | Test ID | Level | Status | | ------------------------------------------------------- | ------------ | ----- | -------- | | Flag validation | T-FC-001–005 | 1 | Required | | Local workflow discovery | T-FC-010–011 | 1 | Required | | Remote workflow discovery | T-FC-012–013 | 2 | Required | | Remote discovery rate-limit backoff and partial results | T-FC-030 | 2 | Required | | Data sampling with limit and window | T-FC-020–021 | 1 | Required | | Missing artifact graceful handling | T-FC-022 | 1 | Required | | Nil projection for empty sample | T-FC-023 | 1 | Required | | Knuth Poisson algorithm (λ ≤ 15) | T-FC-031 | 1 | Required | | Normal approximation (λ > 15) | T-FC-032 | 1 | Required | | Zero-λ projection | T-FC-033 | 1 | Required | | Bootstrap resampling | T-FC-034 | 1 | Required | | Bernoulli success filtering | T-FC-035 | 1 | Required | | 10,000 trial count | T-FC-036 | 1 | Required | | Percentile ordering | T-FC-037 | 1 | Required | | P50 field consistency | T-FC-038 | 1 | Required | | λ crossover threshold enforcement | T-FC-039–040 | 1 | Required | | Episode grouping | T-FC-041–042 | 2 | Required | | Episode table display logic | T-FC-043–044 | 2 | Required | | Console output columns | T-FC-050 | 1 | Required | | JSON schema conformance | T-FC-051–054 | 2 | Required | | Experimental status warning | T-FC-055 | 1 | Required | *** ## 13. Sync Notes [Section titled “13. Sync Notes”](#13-sync-notes) This section maps normative forecast requirements to implementation files. | Normative Area | Implementation File(s) | | ------------------------------------------------------------------------- | ---------------------------------------------------- | | Monte Carlo engine (Poisson/Bootstrap/Bernoulli) | `pkg/cli/forecast_montecarlo.go` | | Forecast command orchestration and output fields | `pkg/cli/forecast.go`, `pkg/cli/forecast_command.go` | | Workflow discovery, rate-limit backoff, and run sampling | `pkg/cli/forecast.go` | | Forecast compliance tests (including rate-limit backoff and λ thresholds) | `pkg/cli/forecast_montecarlo_test.go` | Sync procedure: 1. Update this specification when changing projection algorithms or thresholds. 2. Update corresponding Go implementation/tests in the files above in the same change. 3. Re-run forecast tests to verify normative parity. Sync follow-up tasks: * Add an implementation-level assertion that verbose diagnostics and JSON output are derived from the same `λ` value used by the Monte Carlo engine. * Expand forecast fixtures to cover invalid/non-finite `λ` derivation paths and zero-projection fallback behavior. * Re-review Appendix B whenever the Poisson branch threshold or `observed_runs_per_period` calculation changes. *** ## 14. Appendices [Section titled “14. Appendices”](#14-appendices) ### Appendix A: Worked Example [Section titled “Appendix A: Worked Example”](#appendix-a-worked-example) #### A.1 Scenario [Section titled “A.1 Scenario”](#a1-scenario) A workflow named `ci-doctor` has the following historical sample over 30 days: * 42 completed runs * 5 runs missing `aw_info.json` (treated as 0 ET) * ET observations (for the 37 runs with artifacts): range from 8,000 to 18,000, mean ≈ 12,500 * 38 successful runs (yield = 38/42 ≈ 0.905) * Projection period: `month` (30 days) #### A.2 Observed Rate [Section titled “A.2 Observed Rate”](#a2-observed-rate) ```plaintext observed_runs_per_period = (42 / 30) × 30 = 42.0 λ = 42.0 ``` Since λ > 15, Normal approximation is used: `Normal(μ=42, σ=√42 ≈ 6.48)`. #### A.3 Single Trial [Section titled “A.3 Single Trial”](#a3-single-trial) Draw `k ~ round(Normal(42, 6.48)) = 44` (example). For each of the 44 runs: 1. Draw success: `Bernoulli(0.905)` → say 40 succeed. 2. For each of the 40 successful runs, draw one ET observation from the 37-item historical pool (bootstrap). 3. Sum the 40 ET draws. One trial might yield: 40 × 12,200 (average draw) ≈ 488,000 ET. #### A.4 After 10,000 Trials [Section titled “A.4 After 10,000 Trials”](#a4-after-10000-trials) Sorted trial totals (example summary): ```plaintext P10 ≈ 415,000 (10th percentile — lower bound of 80% CI) P50 ≈ 479,000 (median — headline projection) P90 ≈ 545,000 (90th percentile — upper bound of 80% CI) mean ≈ 481,000 std_dev ≈ 40,000 ``` ### Appendix B: Poisson Algorithm Selection Rationale [Section titled “Appendix B: Poisson Algorithm Selection Rationale”](#appendix-b-poisson-algorithm-selection-rationale) Knuth’s exact Poisson algorithm is used for small λ (≤ 15) because it produces exact integer draws from the Poisson distribution without bias. For large λ, the Poisson distribution converges to a Normal distribution (`N(λ, λ)`), making the Normal approximation computationally efficient and sufficiently accurate. The threshold of λ = 15 is chosen as the crossover point where Normal approximation error is below 1% for the tails relevant to P10/P90 computation. This fixed crossover is mandated by **R-FC-060** and MUST NOT be changed without a specification revision. ### Appendix C: Bootstrap Resampling Rationale [Section titled “Appendix C: Bootstrap Resampling Rationale”](#appendix-c-bootstrap-resampling-rationale) Traditional projection models assume a parametric distribution (e.g., log-normal) for per-run token usage. Agentic workflow token usage is frequently multi-modal (e.g., simple tasks versus complex multi-step tasks) and exhibits heavy tails due to recursive sub-agent chains. Bootstrap resampling avoids distributional misspecification by directly sampling from the empirical distribution, preserving these characteristics faithfully. The tradeoff is that projections are bounded by observed extremes; extrapolation beyond observed maximum ET requires explicit assumption and is out of scope for this specification. ### Appendix D: Episode Count Lower-Bound Semantics [Section titled “Appendix D: Episode Count Lower-Bound Semantics”](#appendix-d-episode-count-lower-bound-semantics) For orchestrator workflows that primarily use `workflow_call` or `workflow_dispatch` triggers, episodes are initiated by calls from another workflow rather than directly by GitHub events. These cross-workflow links are embedded in `aw_info.json` artifacts and are unavailable during forecasting when artifacts cannot be retrieved. As a result, each received `workflow_call` is counted as a separate episode, causing the episode count to overcount episodes and undercount the linkage. This means `runs_per_episode` may appear closer to `1.0` than its true value. Callers MUST treat `sampled_episodes` as a lower-bound estimate in this scenario and SHOULD note this limitation in any capacity planning documents. ### Appendix E: Workflow Discovery Race Conditions [Section titled “Appendix E: Workflow Discovery Race Conditions”](#appendix-e-workflow-discovery-race-conditions) Remote discovery is inherently eventually consistent. Between the workflow listing call and subsequent run/artifact sampling calls, any workflow may be renamed, disabled, or deleted. Conforming implementations SHOULD: 1. Use workflow IDs from the listing response as the stable key for subsequent requests. 2. Treat per-workflow 404/410 responses as recoverable partial failures. 3. Continue processing unaffected workflows and emit a warning for each raced workflow. ### Appendix F: Safeguards [Section titled “Appendix F: Safeguards”](#appendix-f-safeguards) #### F.1 Threat Model [Section titled “F.1 Threat Model”](#f1-threat-model) * **Credential scope abuse**: Over-scoped credentials could allow unauthorized repository access. * **Artifact privacy leakage**: `aw_info.json` artifacts may contain operationally sensitive ET metadata and prompt-adjacent context. * **Rate-limit abuse**: Aggressive polling or unrestricted retries can amplify API pressure and trigger organizational throttling. #### F.2 Required Mitigations [Section titled “F.2 Required Mitigations”](#f2-required-mitigations) * **Credential scope**: The forecast command accesses the GitHub Actions API using `gh` CLI credentials. Token permissions MUST include only the minimum required scope (`actions:read` for target repositories). * **Artifact privacy**: Implementations MUST NOT log raw artifact payloads at default verbosity and SHOULD redact prompt-adjacent fields in diagnostic output. * **Rate-limit abuse controls**: Implementations MUST implement bounded retry/backoff behavior and MUST stop retrying when the retry budget is exhausted. * **Remote repository access**: When `--repo` targets a repository the caller does not own, the caller MUST have explicit read access. Implementations MUST NOT bypass repository access controls. * **JSON output handling**: The JSON schema can expose model and usage topology; operators SHOULD treat it as internal data and apply least-privilege access controls. #### F.3 Residual Risk [Section titled “F.3 Residual Risk”](#f3-residual-risk) Even with these safeguards, operators with valid read access can still infer workload intensity from forecast outputs. This residual risk is accepted and MUST be managed through repository visibility and access-governance controls. *** ## 15. References [Section titled “15. References”](#15-references) ### Normative References [Section titled “Normative References”](#normative-references) * **\[RFC 2119]** Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. * **\[RFC 3339]** Klyne, G. and Newman, C., “Date and Time on the Internet: Timestamps”, RFC 3339, July 2002. * **\[ET-SPEC]** GitHub Agentic Workflows Team, “Effective Tokens Specification”. [effective-tokens-specification](/gh-aw/reference/effective-tokens-specification/) * **\[EXP-SPEC]** GitHub Agentic Workflows Team, “A/B Experiments Specification”. [experiments-specification](/gh-aw/practices/experiments-specification/) ### Informative References [Section titled “Informative References”](#informative-references) * **\[KNUTH-TAOCP]** Knuth, D.E., “The Art of Computer Programming, Volume 2: Seminumerical Algorithms”, 3rd edition. Section 3.4.1 (Poisson distribution generation algorithm). * **\[BOOTSTRAP]** Efron, B. and Tibshirani, R., “An Introduction to the Bootstrap”, Chapman & Hall, 1993. * **\[GH-ACTIONS-API]** GitHub, “GitHub Actions REST API Reference”. *** ## 16. Change Log [Section titled “16. Change Log”](#16-change-log) ### Version 0.1.0 (Experimental Draft) [Section titled “Version 0.1.0 (Experimental Draft)”](#version-010-experimental-draft) * Updated remote discovery requirements with workflow-race mitigation guidance (R-DISC-014) * Added optional JSON lower-bound disclosure field `episode_count_is_lower_bound` and recommendation R-OUT-013 (without reassigning existing R-OUT-010..012 semantics) * Added Appendix F safeguards format (threat model, mitigations, residual risk) * Initial specification for `gh aw forecast` command * Defined command interface: flags `--days`, `--period`, `--sample`, `--repo`, `--json`, `--verbose` * Defined local and remote workflow discovery modes * Defined data sampling procedure and per-run metric derivation * Defined Monte Carlo projection engine with Poisson + bootstrap algorithm * Defined episode analysis with lower-bound semantics for orchestrator workflows * Defined console table output format * Defined JSON output schema (Sections 9.2.1–9.2.6) * Defined error handling and exit codes * Defined compliance test suite (T-FC-001 through T-FC-055) * Added appendices: worked example, algorithm rationale, and safeguards *** *Copyright 2026 GitHub Agentic Workflows Team. All rights reserved.* # Fork Support > How GitHub Agentic Workflows behaves in forked repositories and how to allow PRs from trusted forks. GitHub Agentic Workflows has two distinct fork scenarios with different behaviors: **inbound pull requests from forks** and **running workflows inside a forked repository**. ## Running workflows in a fork [Section titled “Running workflows in a fork”](#running-workflows-in-a-fork) Agentic workflows do **not** run in forked repositories. When a workflow runs in a fork, all jobs skip automatically using the `if: ${{ !github.event.repository.fork }}` condition injected at compile time. This means: * Agent jobs are skipped — no AI execution occurs * Maintenance and self-update jobs do not run * No secrets from the upstream repository are available This is intentional. Forks lack the secrets and context required for agentic workflows to function correctly, and there is no safe way to run agents with partial configuration. Note To run agentic workflows in your own repository, fork the upstream repo and configure your own secrets — the workflows will then run in your copy of the repository, which is not a fork from GitHub Actions’ perspective. ## Inbound pull requests from forks [Section titled “Inbound pull requests from forks”](#inbound-pull-requests-from-forks) When a pull request is opened from a fork to your repository, the default behavior is to **block the workflow from running** — the `pull_request` trigger includes a repository ID check that verifies the PR head branch comes from the same repository. To allow workflows to run for PRs from trusted fork repositories, use the `forks:` field: ```aw --- on: pull_request: types: [opened, synchronize] forks: ["trusted-org/*"] --- ``` ### Fork patterns [Section titled “Fork patterns”](#fork-patterns) The `forks:` field accepts a string or a list of repository patterns: | Pattern | Matches | | -------------- | ---------------------------------------------- | | `"*"` | All forks (use with caution) | | `"owner/*"` | All forks from a specific user or organization | | `"owner/repo"` | A specific fork repository | ```aw --- on: pull_request: types: [opened, synchronize] forks: - "trusted-org/*" - "partner/specific-fork" --- ``` Caution Allowing all forks (`"*"`) means any user who forks your repository can trigger agent execution. Workflows triggered from fork PRs run with the permissions configured in the workflow — review those permissions carefully before allowing untrusted forks. # Frontmatter > Complete guide to all available frontmatter configuration options for GitHub Agentic Workflows, including triggers, permissions, AI engines, and workflow settings. The [frontmatter](/gh-aw/reference/glossary/#frontmatter) (YAML configuration section between `---` markers) of GitHub Agentic Workflows includes the triggers, permissions, AI [engines](/gh-aw/reference/glossary/#engine) (which AI model/provider to use), and workflow settings. For example: ```yaml --- on: issues: types: [opened] tools: edit: bash: ["gh issue comment"] --- ...markdown instructions... ``` ## Frontmatter Elements [Section titled “Frontmatter Elements”](#frontmatter-elements) Below is a comprehensive reference to all available frontmatter fields for GitHub Agentic Workflows. ### Description (`description:`) [Section titled “Description (description:)”](#description-description) Provides a human-readable description of the workflow rendered as a comment in the generated lock file. ```yaml description: "Workflow that analyzes pull requests and provides feedback" ``` ### Emoji (`emoji:`) [Section titled “Emoji (emoji:)”](#emoji-emoji) An optional emoji to represent the workflow visually, for example in listings and UI surfaces. ```yaml emoji: "" ``` ### Labels (`labels:`) [Section titled “Labels (labels:)”](#labels-labels) Optional array of strings for categorizing and organizing workflows. Labels are displayed in `gh aw status` command output and can be filtered using the `--label` flag. ```yaml labels: ["automation", "ci", "diagnostics"] ``` Labels help organize workflows by purpose, team, or functionality. They appear in status command table output as `[automation ci diagnostics]` and as a JSON array in `--json` mode. Filter workflows by label using `gh aw status --label automation`. ### Metadata (`metadata:`) [Section titled “Metadata (metadata:)”](#metadata-metadata) Optional key-value pairs for storing custom metadata compatible with the [GitHub Copilot custom agent spec](https://docs.github.com/en/copilot/reference/custom-agents-configuration). ```yaml metadata: author: John Doe version: 1.0.0 category: automation ``` **Constraints:** * Keys: 1-64 characters * Values: Maximum 1024 characters * Only string values are supported Metadata provides a flexible way to add descriptive information to workflows without affecting execution. ### Trigger Events (`on:`) [Section titled “Trigger Events (on:)”](#trigger-events-on) The `on:` section uses standard GitHub Actions syntax to define workflow triggers, with additional fields for security and approval controls: * Standard GitHub Actions triggers (push, pull\_request, issues, schedule, etc.) * `reaction:` - Add emoji reactions to triggering items * `status-comment:` - Post a started/completed comment with a workflow run link (automatically enabled for `slash_command` and `label_command` triggers; must be explicitly set to `true` for other trigger types). Accepts a boolean or an object with optional `issues`, `pull-requests`, and `discussions` toggle fields to selectively disable status comments for specific target types. * `stop-after:` - Automatically disable triggers after a deadline * `manual-approval:` - Require manual approval using environment protection rules * `forks:` - Configure fork filtering for pull\_request triggers * `skip-roles:` - Skip workflow execution for specific repository roles * `skip-bots:` - Skip workflow execution for specific GitHub actors * `skip-author-associations:` - Skip execution for configured event + `author_association` combinations * `roles:` - Restrict which repository roles can trigger the workflow (default: `[admin, maintainer, write]`) * `bots:` - Allow specific bot accounts to trigger the workflow * `skip-if-match:` - Skip execution when a search query has matches (supports `scope: none`; use top-level `on.github-token` / `on.github-app` for custom auth) * `skip-if-no-match:` - Skip execution when a search query has no matches (supports `scope: none`; use top-level `on.github-token` / `on.github-app` for custom auth) * `steps:` - Inject custom deterministic steps into the pre-activation job (saves one workflow job vs. multi-job pattern) * `permissions:` - Grant additional GitHub token scopes to the pre-activation job (for use with `on.steps:` API calls) * `needs:` - Add custom job dependencies that both `pre_activation` and `activation` must wait for * `github-token:` - Custom token for activation job reactions, status comments, and skip-if search queries * `github-app:` - GitHub App for minting a short-lived token used by the activation job and all skip-if search steps See [Trigger Events](/gh-aw/reference/triggers/) for complete documentation. ### Conditional Execution (`if:`) [Section titled “Conditional Execution (if:)”](#conditional-execution-if) Standard GitHub Actions `if:` syntax: ```yaml if: github.event_name == 'push' ``` ### Imports (`imports:`) [Section titled “Imports (imports:)”](#imports-imports) Share and reuse workflow components across multiple workflows. The `imports:` field in frontmatter (or `{{#import ...}}` in markdown) composes shared tools, steps, MCP servers, and prompts from other workflow files. ```yaml imports: - shared/common-tools.md - shared/mcp/tavily.md ``` See [Imports](/gh-aw/reference/imports/) for complete documentation on syntax, shared components, APM package dependencies, and composition patterns. ### Custom Steps and Jobs (`steps:`, `pre-agent-steps:`, `post-steps:`, `jobs:`) [Section titled “Custom Steps and Jobs (steps:, pre-agent-steps:, post-steps:, jobs:)”](#custom-steps-and-jobs-steps-pre-agent-steps-post-steps-jobs) Add deterministic steps before or after agentic execution, or define full custom GitHub Actions jobs that run before the agent. See [Custom Steps and Jobs](/gh-aw/reference/steps-jobs/) for complete documentation. ### Cache Configuration (`cache:`) [Section titled “Cache Configuration (cache:)”](#cache-configuration-cache) Cache configuration using standard GitHub Actions `actions/cache` syntax: Single cache: ```yaml cache: key: node-modules-${{ hashFiles('package-lock.json') }} path: node_modules restore-keys: | node-modules- ``` ### Repository Checkout (`checkout:`) [Section titled “Repository Checkout (checkout:)”](#repository-checkout-checkout) Configure how `actions/checkout` is invoked in the agent job. Override default checkout settings or check out multiple repositories for cross-repository workflows. Set `checkout: false` to disable the default repository checkout entirely — useful for workflows that access repositories through MCP servers or other mechanisms that do not require a local clone: ```yaml checkout: false ``` See [Cross-Repository Operations](/gh-aw/reference/cross-repository/) for complete documentation on checkout configuration options (including `fetch:`, `checkout: false`), merging behavior, and cross-repo examples. ### Permissions (`permissions:`) [Section titled “Permissions (permissions:)”](#permissions-permissions) The `permissions:` section uses a syntax similar to standard GitHub Actions permissions syntax to specify the GitHub read permissions relevant to the agentic (natural language) part of the execution of the workflow. See [GitHub Tools Read Permissions](/gh-aw/reference/permissions/). ### AI Engine (`engine:`) [Section titled “AI Engine (engine:)”](#ai-engine-engine) Specifies which AI engine interprets the markdown section. See [AI Engines](/gh-aw/reference/engines/) for details. ```yaml engine: copilot ``` ### Network Permissions (`network:`) [Section titled “Network Permissions (network:)”](#network-permissions-network) Controls network access using ecosystem identifiers and domain allowlists. See [Network Permissions](/gh-aw/reference/network/) for full documentation. ```yaml network: allowed: - defaults # Basic infrastructure - python # Python/PyPI ecosystem - "api.example.com" # Custom domain ``` ### Tools (`tools:`) [Section titled “Tools (tools:)”](#tools-tools) Specifies which GitHub API calls, bash commands, browser automation, and MCP servers are available to the AI agent. ```yaml tools: edit: bash: ["gh issue comment"] github: toolsets: [default] ``` See [Tools](/gh-aw/reference/tools/) for complete documentation on built-in tools, GitHub toolsets, and MCP server configuration. ### MCP Scripts (`mcp-scripts:`) [Section titled “MCP Scripts (mcp-scripts:)”](#mcp-scripts-mcp-scripts) Enables defining custom MCP tools inline using JavaScript or shell scripts. See [MCP Scripts](/gh-aw/reference/mcp-scripts/) for complete documentation on creating custom tools with controlled secret access. ### Safe Outputs (`safe-outputs:`) [Section titled “Safe Outputs (safe-outputs:)”](#safe-outputs-safe-outputs) Enables automatic issue creation, comment posting, and other safe outputs. See [Safe Outputs Processing](/gh-aw/reference/safe-outputs/). ### Run Configuration (`run-name:`, `runs-on:`, `runs-on-slim:`, `timeout-minutes:`) [Section titled “Run Configuration (run-name:, runs-on:, runs-on-slim:, timeout-minutes:)”](#run-configuration-run-name-runs-on-runs-on-slim-timeout-minutes) Standard GitHub Actions properties: ```yaml run-name: "Custom workflow run name" # Defaults to workflow name runs-on: ubuntu-latest # Defaults to ubuntu-latest (main job only) runs-on-slim: ubuntu-slim # Defaults to ubuntu-slim (framework jobs only) timeout-minutes: 30 # Defaults to 20 minutes ``` `runs-on` applies to the main agent job only. `runs-on-slim` applies to all framework/generated jobs (activation, safe-outputs, unlock, etc.) and defaults to `ubuntu-slim`. `safe-outputs.runs-on` takes precedence over `runs-on-slim` for safe-output jobs specifically. `timeout-minutes` accepts either an integer or a GitHub Actions expression string. This allows `workflow_call` reusable workflows to parameterize the timeout via caller inputs: ```yaml # Literal integer timeout-minutes: 30 # Expression — useful in reusable (workflow_call) workflows timeout-minutes: ${{ inputs.timeout }} ``` **Supported runners for `runs-on:`** | Runner | Status | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `ubuntu-latest` | ✓ Default. Recommended for most workflows. | | `ubuntu-24.04` / `ubuntu-22.04` | ✓ Supported. | | `ubuntu-24.04-arm` | ✓ Supported. Linux ARM64 runner. | | `macos-*` | ✗ Not supported. Docker is unavailable on macOS runners (no nested virtualization). See [FAQ](/gh-aw/reference/faq/). | | `windows-*` | ✗ Not supported. AWF requires Linux. | ### Workflow Concurrency Control (`concurrency:`) [Section titled “Workflow Concurrency Control (concurrency:)”](#workflow-concurrency-control-concurrency) Automatically generates concurrency policies for the agent job. See [Concurrency Control](/gh-aw/reference/concurrency/). ### Environment Variables (`env:`) [Section titled “Environment Variables (env:)”](#environment-variables-env) Standard GitHub Actions `env:` syntax for workflow-level environment variables: ```yaml env: CUSTOM_VAR: "value" ``` Environment variables can be defined at multiple scopes (workflow, job, step, engine, safe-outputs, etc.) with clear precedence rules. See [Environment Variables](/gh-aw/reference/environment-variables/) for complete documentation on all 13 env scopes and precedence order. Caution Do not use `${{ secrets.* }}` expressions in the workflow-level `env:` section. Environment variables defined here are passed directly to the agent container, which means secret values would be visible to the AI model. In strict mode, this is a compilation error. In non-strict mode, it emits a warning. Use engine-specific secret configuration instead of the `env:` section to pass secrets securely. ### Effective Token Budget (`max-effective-tokens:`) [Section titled “Effective Token Budget (max-effective-tokens:)”](#effective-token-budget-max-effective-tokens) Sets the AWF effective-token budget used for cost enforcement. Defaults to `25000000` when omitted. Token steering (budget-warning messages at 80%, 90%, 95%, and 99% of the budget) is enabled by default. Set to a negative value to disable both budget enforcement and token steering. ```yaml max-effective-tokens: 5000000 ``` ```yaml # Disable budget enforcement and token steering max-effective-tokens: -1 ``` ### Secrets (`secrets:`) [Section titled “Secrets (secrets:)”](#secrets-secrets) Defines secret values passed to workflow execution. Secrets are typically used to provide sensitive configuration to MCP servers or workflow components. Values must be GitHub Actions expressions that reference secrets (e.g., `${{ secrets.API_KEY }}`). ```yaml secrets: API_TOKEN: ${{ secrets.API_TOKEN }} DATABASE_URL: ${{ secrets.DB_URL }} ``` Secrets can also include descriptions for documentation: ```yaml secrets: API_TOKEN: value: ${{ secrets.API_TOKEN }} description: "API token for external service" DATABASE_URL: value: ${{ secrets.DB_URL }} description: "Production database connection string" ``` **Security best practices:** * Always use GitHub Actions secret expressions (`${{ secrets.NAME }}`) * Never commit plaintext secrets to workflow files * Use environment-specific secrets when possible (via `environment:` field) * Limit secret access to only the components that need them **Note:** For passing secrets to reusable workflows, use the `jobs..secrets` field instead. The top-level `secrets:` field is for workflow-level secret configuration. ### Environment Protection (`environment:`) [Section titled “Environment Protection (environment:)”](#environment-protection-environment) Specifies the environment for deployment protection rules and environment-specific secrets. Standard GitHub Actions syntax. ```yaml environment: production ``` See [GitHub Actions environment docs](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment). ### Container Configuration (`container:`) [Section titled “Container Configuration (container:)”](#container-configuration-container) Specifies a container to run job steps in. ```yaml container: node:18 ``` See [GitHub Actions container docs](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/run-jobs-in-a-container). ### Service Containers (`services:`) [Section titled “Service Containers (services:)”](#service-containers-services) Defines service containers that run alongside your job (databases, caches, etc.). ```yaml services: postgres: image: postgres:13 env: POSTGRES_PASSWORD: postgres ports: - 5432:5432 ``` Note The AWF agent runs inside an isolated Docker container. Service containers expose ports on the runner host, not within the agent’s network namespace. To connect to a service from the agent, use `host.docker.internal` as the hostname instead of `localhost`. For example, a Postgres service configured with port `5432:5432` is accessible at `host.docker.internal:5432`. See [GitHub Actions service docs](https://docs.github.com/en/actions/using-containerized-services). ### Observability (`observability:`) [Section titled “Observability (observability:)”](#observability-observability) Use `observability.otlp` to export distributed traces from workflow runs to an OpenTelemetry Protocol (OTLP) compatible backend. ```yaml observability: otlp: endpoint: ${{ secrets.OTLP_ENDPOINT }} headers: Authorization: ${{ secrets.OTLP_TOKEN }} X-Tenant: my-org ``` `endpoint` accepts a string, a `{url, headers}` object, or an array of endpoint objects for fan-out. `headers` accepts a map or comma-separated `key=value` string. `if-missing` supports `error` (default), `warn`, and `ignore`. For full OpenTelemetry reference details, including runtime variables, endpoint forms, span attributes, and artifact files, see [OpenTelemetry](/gh-aw/reference/open-telemetry/). ### Resources (`resources:`) [Section titled “Resources (resources:)”](#resources-resources) Declares additional workflow or action files to fetch alongside this workflow when running `gh aw add`. Use this field when the workflow depends on companion workflows or custom actions stored in the same directory. ```yaml resources: - triage-issue.md # companion workflow - label-issue.md # companion workflow - shared/helper-action.yml # supporting GitHub Action ``` Entries are relative paths from the workflow’s location in the source repository. GitHub Actions expression syntax (`${{`) is not allowed in resource paths. When a user runs `gh aw add` to install this workflow, each listed file is also downloaded and placed alongside the main workflow in the target repository. This ensures companion workflows and custom actions the main workflow depends on are available after installation. In addition to files explicitly listed in `resources:`, `gh aw add` automatically fetches workflows referenced in the [`dispatch-workflow`](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow) safe output. ### Runtimes (`runtimes:`) [Section titled “Runtimes (runtimes:)”](#runtimes-runtimes) Override default runtime versions for languages and tools used in workflows. The compiler automatically detects runtime requirements from tool configurations and workflow steps, then installs the specified versions. **Format**: Object with runtime name as key and configuration as value **Fields per runtime**: * `version`: Runtime version string (required) * `action-repo`: Custom GitHub Actions setup action (optional, overrides default) * `action-version`: Version of the setup action (optional, overrides default) **Supported runtimes**: | Runtime | Default Version | Default Setup Action | | --------- | --------------- | -------------------------- | | `node` | 24 | `actions/setup-node@v6` | | `python` | 3.12 | `actions/setup-python@v5` | | `go` | 1.25 | `actions/setup-go@v5` | | `uv` | latest | `astral-sh/setup-uv@v5` | | `bun` | 1.1 | `oven-sh/setup-bun@v2` | | `deno` | 2.x | `denoland/setup-deno@v2` | | `ruby` | 3.3 | `ruby/setup-ruby@v1` | | `java` | 21 | `actions/setup-java@v4` | | `dotnet` | 8.0 | `actions/setup-dotnet@v4` | | `elixir` | 1.17 | `erlef/setup-beam@v1` | | `haskell` | 9.10 | `haskell-actions/setup@v2` | **Examples**: Override Node.js version: ```yaml runtimes: node: version: "22" ``` Use specific Python version with custom setup action: ```yaml runtimes: python: version: "3.12" action-repo: "actions/setup-python" action-version: "v5" ``` Multiple runtime overrides: ```yaml runtimes: node: version: "20" python: version: "3.11" go: version: "1.22" ``` **Default Behavior**: If not specified, workflows use default runtime versions as defined in the system. The compiler automatically detects which runtimes are needed based on tool configurations (e.g., `bash: ["node"]`, `bash: ["python"]`) and workflow steps. **Use Cases**: * Pin specific runtime versions for reproducibility * Use preview/beta runtime versions for testing * Use custom setup actions (forks, enterprise mirrors) * Override system defaults for compatibility requirements **Note**: Runtimes from imported shared workflows are automatically merged with your workflow’s runtime configuration. ### Source Tracking (`source:`) [Section titled “Source Tracking (source:)”](#source-tracking-source) Tracks workflow origin in format `owner/repo/path@ref`. Automatically populated when using `gh aw add` to install workflows from external repositories. Optional for manually created workflows. ```yaml source: "githubnext/agentics/workflows/ci-doctor.md@v1.0.0" ``` ### Redirect (`redirect:`) [Section titled “Redirect (redirect:)”](#redirect-redirect) Specifies a new canonical location when a workflow has been moved or renamed. `gh aw add`, `gh aw add-wizard`, and `gh aw update` follow redirect chains to the resolved location for remote workflows. During add/update flows, the local `source` field is written (or rewritten) to the resolved location, and redirect loops are detected and reported as errors. ```yaml redirect: "githubnext/agentics/workflows/new-workflow-name.md@main" ``` Use `gh aw update --no-redirect` to refuse updates when the source workflow has a `redirect` field — the update fails rather than following the redirect. This is useful for auditing or when you want to explicitly control when redirects are followed. `gh aw compile` emits an informational message when a workflow has a `redirect` field configured, so the redirect is visible during local development. The `redirect` field uses the same `owner/repo/path@ref` format as `source:`. Redirect chains are followed transitively (up to a depth limit). Note The `redirect` field is set by workflow *authors* to signal that a workflow has moved. It is not typically set by end-users. If you see a redirect when running `gh aw update`, it means the upstream workflow has been relocated. ### Private Workflows (`private:`) [Section titled “Private Workflows (private:)”](#private-workflows-private) Mark a workflow as private to prevent it from being installed into other repositories via `gh aw add`. ```yaml private: true ``` When `private: true` is set, attempting to add the workflow from another repository will fail with an error: ```plaintext workflow 'owner/repo/internal-tooling' is private and cannot be added to other repositories ``` Use this field for internal tooling, sensitive automation, or workflows that depend on repository-specific context and are not intended for external reuse. The `private:` field only blocks installation via `gh aw add`. It does not affect the visibility of the workflow file itself — that is controlled by your repository’s access settings. ### Feature Flags (`features:`) [Section titled “Feature Flags (features:)”](#feature-flags-features) Enable experimental or optional compiler and runtime behaviors as key-value pairs. See [Feature Flags](/gh-aw/reference/feature-flags/) for complete documentation. ### Strict Mode (`strict:`) [Section titled “Strict Mode (strict:)”](#strict-mode-strict) Disables enhanced security validation for production workflows. ```yaml strict: false # Disable for development/testing ``` Workflows compiled with `strict: false` cannot run on public repositories. The workflow fails at runtime with an error message prompting recompilation with strict mode. See [Network Permissions - Strict Mode Validation](/gh-aw/reference/network/#strict-mode-validation) for details on network validation and [CLI Commands](/gh-aw/setup/cli/#compile) for compilation options. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) See also: [Trigger Events](/gh-aw/reference/triggers/), [AI Engines](/gh-aw/reference/engines/), [CLI Commands](/gh-aw/setup/cli/), [Workflow Structure](/gh-aw/reference/workflow-structure/), [Network Permissions](/gh-aw/reference/network/), [Feature Flags](/gh-aw/reference/feature-flags/), [Custom Steps and Jobs](/gh-aw/reference/steps-jobs/), [OpenTelemetry](/gh-aw/reference/open-telemetry/), [Command Triggers](/gh-aw/reference/command-triggers/), [MCPs](/gh-aw/guides/mcps/), [Tools](/gh-aw/reference/tools/), [Imports](/gh-aw/reference/imports/) # Frontmatter Reference > Complete JSON Schema-based reference for all GitHub Agentic Workflows frontmatter configuration options with YAML examples. This document provides a comprehensive reference for all available frontmatter configuration options in GitHub Agentic Workflows. The examples below are generated from the JSON Schema and include inline comments describing each field. Note This documentation is automatically generated from the JSON Schema. For a more user-friendly guide, see [Frontmatter](/gh-aw/reference/frontmatter/). ## Schema Description [Section titled “Schema Description”](#schema-description) JSON Schema for validating agentic workflow frontmatter configuration ## Complete Frontmatter Reference [Section titled “Complete Frontmatter Reference”](#complete-frontmatter-reference) ```yaml --- # Workflow name that appears in the GitHub Actions interface. If not specified, # defaults to the filename without extension. # (optional) name: "My Workflow" # Optional workflow description that is rendered as a comment in the generated # GitHub Actions YAML file (.lock.yml) # (optional) description: "Description of the workflow" # Optional emoji to represent the workflow visually in listings and UI surfaces. # (optional) emoji: "example-value" # Optional source reference indicating where this workflow was added from. Format: # owner/repo/path@ref (e.g., githubnext/agentics/workflows/ci-doctor.md@v1.0.0). # Rendered as a comment in the generated lock file. # (optional) source: "example-value" # Optional workflow location redirect for updates. Format: workflow spec or GitHub # URL (e.g., owner/repo/path@ref or # https://github.com/owner/repo/blob/main/path.md). When present, update follows # this location and rewrites source. # (optional) redirect: "example-value" # Optional tracker identifier to tag all created assets (issues, discussions, # comments, pull requests). Must be at least 8 characters and contain only # alphanumeric characters, hyphens, and underscores. This identifier will be # inserted in the body/description of all created assets to enable searching and # retrieving assets associated with this workflow. # (optional) tracker-id: "example-value" # Optional array of labels to categorize and organize workflows. Labels can be # used to filter workflows in status/list commands. # (optional) labels: [] # Array of strings # Optional metadata field for storing custom key-value pairs compatible with the # custom agent spec. Key names are limited to 64 characters, and values are # limited to 1024 characters. # (optional) metadata: {} # Workflow specifications to import. Supports array form (list of paths) or object # form with 'aw' (agentic workflow paths) subfield. Path resolution: (1) relative # paths (e.g., 'shared/file.md') are resolved relative to the workflow's # directory; (2) paths starting with '.github/' or '/' are resolved from the # repository root (repo-root-relative); (3) paths matching 'owner/repo/path@ref' # are fetched from GitHub at compile time (cross-repo). # (optional) # Accepted formats: # Format 1: Array of workflow specifications to import. Three path formats are # supported: relative paths ('shared/file.md'), repo-root-relative paths # ('.github/agents/my-agent.md'), and cross-repo paths ('owner/repo/path@ref'). # Any markdown files under .github/agents directory are treated as custom agent # files and only one agent file is allowed per workflow. imports: [] # Array items: undefined # Format 2: Object form of imports with 'aw' subfield for shared agentic workflow # paths. imports: # Array of shared agentic workflow specifications to import. Format: # owner/repo/path@ref or relative paths. # (optional) aw: [] # Optional list of additional workflow or action files that should be fetched # alongside this workflow when running 'gh aw add'. Entries are relative paths # (from the same directory as this workflow in the source repository) to agentic # workflow .md files or GitHub Actions .yml/.yaml files. GitHub Actions expression # syntax (${{) is not allowed in resource paths. # (optional) resources: [] # Array of Relative path to a workflow .md file or action .yml/.yaml file. Must be # a static path; GitHub Actions expression syntax (${{) is not allowed. # If true, inline all imports (including those without inputs) at compilation time # in the generated lock.yml instead of using runtime-import macros. When enabled, # the frontmatter hash covers the entire markdown body so any change to the # content will invalidate the hash. # (optional) inlined-imports: true # Workflow triggers that define when the agentic workflow should run. Supports # standard GitHub Actions trigger events plus special command triggers for # /commands (required) # Accepted formats: # Format 1: Simple trigger event name (e.g., 'push', 'issues', 'pull_request', # 'discussion', 'schedule', 'fork', 'create', 'delete', 'public', 'watch', # 'workflow_call'), schedule shorthand (e.g., 'daily', 'weekly'), or slash command # shorthand (e.g., '/my-bot' expands to slash_command + workflow_dispatch) on: "example-value" # Format 2: Complex trigger configuration with event-specific filters and options on: # Special slash command trigger for /command workflows (e.g., '/my-bot' in issue # comments). Creates conditions to match slash commands automatically. Note: Can # be combined with issues/pull_request events if those events only use 'labeled' # or 'unlabeled' types. # (optional) # Accepted formats: # Format 1: Null command configuration - defaults to using the workflow filename # (without .md extension) as the command name slash_command: null # Format 2: Command name as a string (shorthand format, e.g., 'customname' for # '/customname' triggers). Command names must not start with '/' as the slash is # automatically added when matching commands. slash_command: "example-value" # Format 3: Command configuration object with custom command name slash_command: # Name of the slash command that triggers the workflow (e.g., '/help', # '/analyze'). Used for comment-based workflow activation. # (optional) # Accepted formats: # Format 1: Single command name for slash commands (e.g., 'helper-bot' for # '/helper-bot' triggers). Command names must not start with '/' as the slash is # automatically added when matching commands. Defaults to workflow filename # without .md extension if not specified. name: "My Workflow" # Format 2: Array of command names that trigger this workflow (e.g., ['cmd.add', # 'cmd.remove'] for '/cmd.add' and '/cmd.remove' triggers). Each command name must # not start with '/'. name: [] # Array items: Command name without leading slash # Events where the command should be active. Default is all comment-related events # ('*'). Use GitHub Actions event names. # (optional) # Accepted formats: # Format 1: Single event name or '*' for all events. Use GitHub Actions event # names: 'issues', 'issue_comment', 'pull_request_comment', 'pull_request', # 'pull_request_review_comment', 'discussion', 'discussion_comment'. events: "*" # Format 2: Array of event names where the command should be active (requires at # least one). Use GitHub Actions event names. events: [] # Array items: GitHub Actions event name. # Slash command trigger compilation strategy. 'inline' (default) compiles direct # comment listeners in this workflow. 'centralized' compiles this workflow as # workflow_dispatch-centric and routes slash events via the generated central # trigger workflow. # (optional) strategy: "inline" # DEPRECATED: Use 'slash_command' instead. Special command trigger for /command # workflows (e.g., '/my-bot' in issue comments). Creates conditions to match slash # commands automatically. # (optional) # Accepted formats: # Format 1: Null command configuration - defaults to using the workflow filename # (without .md extension) as the command name command: null # Format 2: Command name as a string (shorthand format, e.g., 'customname' for # '/customname' triggers). Command names must not start with '/' as the slash is # automatically added when matching commands. command: "example-value" # Format 3: Command configuration object with custom command name command: # Name of the slash command that triggers the workflow (e.g., '/deploy', '/test'). # Used for command-based workflow activation. # (optional) # Accepted formats: # Format 1: Custom command name for slash commands (e.g., 'helper-bot' for # '/helper-bot' triggers). Command names must not start with '/' as the slash is # automatically added when matching commands. Defaults to workflow filename # without .md extension if not specified. name: "My Workflow" # Format 2: Array of command names that trigger this workflow (e.g., ['cmd.add', # 'cmd.remove'] for '/cmd.add' and '/cmd.remove' triggers). Each command name must # not start with '/'. name: [] # Array items: Command name without leading slash # Events where the command should be active. Default is all comment-related events # ('*'). Use GitHub Actions event names. # (optional) # Accepted formats: # Format 1: Single event name or '*' for all events. Use GitHub Actions event # names: 'issues', 'issue_comment', 'pull_request_comment', 'pull_request', # 'pull_request_review_comment', 'discussion', 'discussion_comment'. events: "*" # Format 2: Array of event names where the command should be active (requires at # least one). Use GitHub Actions event names. events: [] # Array items: GitHub Actions event name. # On Label Command trigger: fires when a specific label is added to an issue, pull # request, or discussion. The triggering label is automatically removed at # workflow start so it can be applied again to re-trigger. Use the 'events' field # to restrict which item types (issues, pull_request, discussion) activate the # trigger. # (optional) # Accepted formats: # Format 1: Label name as a string (shorthand format). The workflow fires when # this label is added to any supported item type (issue, pull request, or # discussion). label_command: "example-value" # Format 2: Label command configuration object with label name(s) and optional # event filtering. label_command: # Label name(s) that trigger the workflow when added to an issue, pull request, or # discussion. # (optional) # Accepted formats: # Format 1: Single label name that acts as a command (e.g., 'deploy' triggers the # workflow when the 'deploy' label is added). name: "My Workflow" # Format 2: Array of label names — any of these labels will trigger the workflow. name: [] # Array items: A label name # Alternative to 'name': label name(s) that trigger the workflow. # (optional) # Accepted formats: # Format 1: Single label name. names: "example-value" # Format 2: Array of label names — any of these labels will trigger the workflow. names: [] # Array items: A label name # Item types where the label-command trigger should be active. Default is all # supported types: issues, pull_request, discussion. # (optional) # Accepted formats: # Format 1: Single item type or '*' for all types. events: "*" # Format 2: Array of item types where the trigger is active. events: [] # Array items: Item type. # Whether to automatically remove the triggering label after the workflow starts. # Defaults to true. Set to false to keep the label on the item and skip the # label-removal step. When false, the issues:write and discussions:write # permissions required for label removal are also omitted. # (optional) remove_label: true # Label command trigger compilation strategy. 'inline' (default) compiles direct # labeled listeners in this workflow. 'decentralized' compiles this workflow as # workflow_dispatch-centric and routes labeled events via the generated # agentic_commands.yml workflow. # (optional) strategy: "inline" # Push event trigger that runs the workflow when code is pushed to the repository # (optional) push: # Branches to filter on # (optional) branches: [] # Array of strings # Branches to ignore # (optional) branches-ignore: [] # Array of strings # Paths to filter on # (optional) paths: [] # Array of strings # Paths to ignore # (optional) paths-ignore: [] # Array of strings # List of git tag names or patterns to include for push events (supports # wildcards) # (optional) tags: [] # Array of strings # List of git tag names or patterns to exclude from push events (supports # wildcards) # (optional) tags-ignore: [] # Array of strings # Pull request event trigger that runs the workflow when pull requests are # created, updated, or closed # (optional) pull_request: # Pull request event types to trigger on. Note: 'converted_to_draft' and # 'ready_for_review' represent state transitions (events) rather than states. # While technically valid to listen for both, consider if you need to handle both # transitions or just one. # (optional) types: [] # Array of strings # Branches to filter on # (optional) branches: [] # Array of strings # Branches to ignore # (optional) branches-ignore: [] # Array of strings # Paths to filter on # (optional) paths: [] # Array of strings # Paths to ignore # (optional) paths-ignore: [] # Array of strings # Filter by draft pull request state. Set to false to exclude draft PRs, true to # include only drafts, or omit to include both # (optional) draft: true # When true, allows workflow to run on pull requests from forked repositories. # Security consideration: fork PRs have limited permissions. # (optional) # Accepted formats: # Format 1: Single fork pattern (e.g., '*' for all forks, 'org/*' for org glob, # 'org/repo' for exact match) forks: "example-value" # Format 2: List of allowed fork repositories with glob support (e.g., 'org/repo', # 'org/*', '*' for all forks) forks: [] # Array items: Repository pattern with optional glob support # Array of pull request type names that trigger the workflow. Filters workflow # execution to specific PR categories. # (optional) # Accepted formats: # Format 1: Single label name to filter labeled/unlabeled events (e.g., 'bug') names: "example-value" # Format 2: List of label names to filter labeled/unlabeled events. Only applies # when 'labeled' or 'unlabeled' is in the types array names: [] # Array items: Label name # Issues event trigger that runs when repository issues are created, updated, or # managed # (optional) issues: # Types of issue events # (optional) types: [] # Array of strings # Array of issue type names that trigger the workflow. Filters workflow execution # to specific issue categories. # (optional) # Accepted formats: # Format 1: Single label name to filter labeled/unlabeled events (e.g., 'bug') names: "example-value" # Format 2: List of label names to filter labeled/unlabeled events. Only applies # when 'labeled' or 'unlabeled' is in the types array names: [] # Array items: Label name # Whether to lock the issue for the agent when the workflow runs (prevents # concurrent modifications) # (optional) lock-for-agent: true # Issue comment event trigger # (optional) issue_comment: # Types of issue comment events # (optional) types: [] # Array of strings # Whether to lock the parent issue for the agent when the workflow runs (prevents # concurrent modifications) # (optional) lock-for-agent: true # Discussion event trigger that runs the workflow when repository discussions are # created, updated, or managed # (optional) discussion: # Types of discussion events # (optional) types: [] # Array of strings # Discussion comment event trigger that runs the workflow when comments on # discussions are created, updated, or deleted # (optional) discussion_comment: # Types of discussion comment events # (optional) types: [] # Array of strings # Scheduled trigger events using fuzzy schedules or standard cron expressions. # Supports shorthand string notation (e.g., 'daily', 'daily around 2pm') or array # of schedule objects. Fuzzy schedules automatically distribute execution times to # prevent load spikes. # (optional) # Accepted formats: # Format 1: Shorthand schedule string using fuzzy or cron format. Examples: # 'daily', 'daily around 14:00', 'daily between 9:00 and 17:00', 'weekly', 'weekly # on monday', 'weekly on friday around 5pm', 'hourly', 'every 2h', 'every 10 # minutes', '0 9 * * 1'. Fuzzy schedules distribute execution times to prevent # load spikes. For fixed times, use standard cron syntax. Minimum interval is 5 # minutes. schedule: "example-value" # Format 2: Array of schedule objects with cron expressions (standard cron or # fuzzy format) schedule: [] # Array items: object # Manual workflow dispatch trigger # (optional) # Accepted formats: # Format 1: Simple workflow dispatch trigger workflow_dispatch: null # Format 2: object workflow_dispatch: # Input parameters for manual dispatch # (optional) inputs: {} # Workflow run trigger # (optional) workflow_run: # List of workflows to trigger on # (optional) workflows: [] # Array of strings # Types of workflow run events # (optional) types: [] # Array of strings # Branches to filter on # (optional) branches: [] # Array of strings # Branches to ignore # (optional) branches-ignore: [] # Array of strings # Release event trigger # (optional) release: # Types of release events # (optional) types: [] # Array of strings # Pull request review comment event trigger # (optional) pull_request_review_comment: # Types of pull request review comment events # (optional) types: [] # Array of strings # Branch protection rule event trigger that runs when branch protection rules are # changed # (optional) branch_protection_rule: # Types of branch protection rule events # (optional) types: [] # Array of strings # Check run event trigger that runs when a check run is created, rerequested, # completed, or has a requested action # (optional) check_run: # Types of check run events # (optional) types: [] # Array of strings # Check suite event trigger that runs when check suite activity occurs # (optional) check_suite: # Types of check suite events # (optional) types: [] # Array of strings # Create event trigger that runs when a Git reference (branch or tag) is created # (optional) # Accepted formats: # Format 1: Simple create event trigger create: null # Format 2: object create: {} # Delete event trigger that runs when a Git reference (branch or tag) is deleted # (optional) # Accepted formats: # Format 1: Simple delete event trigger delete: null # Format 2: object delete: {} # Deployment event trigger that runs when a deployment is created # (optional) # Accepted formats: # Format 1: Simple deployment event trigger deployment: null # Format 2: object deployment: {} # Deployment status event trigger that runs when a deployment status is updated # (optional) # Accepted formats: # Format 1: Simple deployment status event trigger deployment_status: null # Format 2: object deployment_status: # Filter to specific deployment states (compiled into if condition). Use a string # for one state or an array for multiple states. # (optional) # Accepted formats: # Format 1: string state: "error" # Format 2: array state: [] # Array items: string # Fork event trigger that runs when someone forks the repository # (optional) # Accepted formats: # Format 1: Simple fork event trigger fork: null # Format 2: object fork: {} # Gollum event trigger that runs when someone creates or updates a Wiki page # (optional) # Accepted formats: # Format 1: Simple gollum event trigger gollum: null # Format 2: object gollum: {} # Label event trigger that runs when a label is created, edited, or deleted # (optional) label: # Types of label events # (optional) types: [] # Array of strings # Merge group event trigger that runs when a pull request is added to a merge # queue # (optional) merge_group: # Types of merge group events # (optional) types: [] # Array of strings # Milestone event trigger that runs when a milestone is created, closed, opened, # edited, or deleted # (optional) milestone: # Types of milestone events # (optional) types: [] # Array of strings # Page build event trigger that runs when someone pushes to a GitHub Pages # publishing source branch # (optional) # Accepted formats: # Format 1: Simple page build event trigger page_build: null # Format 2: object page_build: {} # Public event trigger that runs when a repository changes from private to public # (optional) # Accepted formats: # Format 1: Simple public event trigger public: null # Format 2: object public: {} # Pull request target event trigger that runs in the context of the base # repository (secure for fork PRs) # (optional) pull_request_target: # List of pull request target event types to trigger on # (optional) types: [] # Array of strings # Branches to filter on # (optional) branches: [] # Array of strings # Branches to ignore # (optional) branches-ignore: [] # Array of strings # Paths to filter on # (optional) paths: [] # Array of strings # Paths to ignore # (optional) paths-ignore: [] # Array of strings # Filter by draft pull request state # (optional) draft: true # When true, allows workflow to run on pull requests from forked repositories with # write permissions. Security consideration: use cautiously as fork PRs run with # base repository permissions. # (optional) # Accepted formats: # Format 1: Single fork pattern forks: "example-value" # Format 2: List of allowed fork repositories with glob support forks: [] # Array items: string # Pull request review event trigger that runs when a pull request review is # submitted, edited, or dismissed # (optional) pull_request_review: # Types of pull request review events # (optional) types: [] # Array of strings # Registry package event trigger that runs when a package is published or updated # (optional) registry_package: # Types of registry package events # (optional) types: [] # Array of strings # Repository dispatch event trigger for custom webhook events # (optional) repository_dispatch: # Custom event types to trigger on # (optional) types: [] # Array of strings # Status event trigger that runs when the status of a Git commit changes # (optional) # Accepted formats: # Format 1: Simple status event trigger status: null # Format 2: object status: {} # Watch event trigger that runs when someone stars the repository # (optional) watch: # Types of watch events # (optional) types: [] # Array of strings # Workflow call event trigger that allows this workflow to be called by another # workflow # (optional) # Accepted formats: # Format 1: Simple workflow call event trigger workflow_call: null # Format 2: object workflow_call: # Input parameters that can be passed to the workflow when it is called # (optional) inputs: {} # Secrets that can be passed to the workflow when it is called # (optional) secrets: {} # Time when workflow should stop running. Supports multiple formats: absolute # dates (YYYY-MM-DD HH:MM:SS, June 1 2025, 1st June 2025, 06/01/2025, etc.) or # relative time deltas (+25h, +3d, +1d12h30m). Maximum values for time deltas: # 12mo, 52w, 365d, 8760h (365 days). Note: Minute unit 'm' is not allowed for # stop-after; minimum unit is hours 'h'. # (optional) stop-after: "example-value" # Conditionally skip workflow execution when a GitHub search query has matches. # Can be a string (query only, implies max=1) or an object with 'query', optional # 'max', and 'scope' fields. Use top-level on.github-token or on.github-app for # custom authentication. # (optional) # Accepted formats: # Format 1: GitHub search query string to check before running workflow (implies # max=1). If the search returns any results, the workflow will be skipped. Query # is automatically scoped to the current repository. Example: 'is:issue is:open # label:bug' skip-if-match: "example-value" # Format 2: Skip-if-match configuration object with query, maximum match count, # and optional scope. For custom authentication use the top-level on.github-token # or on.github-app fields. skip-if-match: # GitHub search query string to check before running workflow. Query is # automatically scoped to the current repository. query: "example-value" # Maximum number of items that must be matched for the workflow to be skipped. # Defaults to 1 if not specified. Supports integer or GitHub Actions expression # (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Scope for the search query. Set to 'none' to disable the automatic # 'repo:owner/repo' scoping, enabling org-wide or cross-repo queries. # (optional) scope: "none" # Conditionally skip workflow execution when a GitHub search query has no matches # (or fewer than minimum). Can be a string (query only, implies min=1) or an # object with 'query', optional 'min', and 'scope' fields. Use top-level # on.github-token or on.github-app for custom authentication. # (optional) # Accepted formats: # Format 1: GitHub search query string to check before running workflow (implies # min=1). If the search returns no results, the workflow will be skipped. Query is # automatically scoped to the current repository. Example: 'is:pr is:open # label:ready-to-deploy' skip-if-no-match: "example-value" # Format 2: Skip-if-no-match configuration object with query, minimum match count, # and optional scope. For custom authentication use the top-level on.github-token # or on.github-app fields. skip-if-no-match: # GitHub search query string to check before running workflow. Query is # automatically scoped to the current repository. query: "example-value" # Minimum number of items that must be matched for the workflow to proceed. # Defaults to 1 if not specified. # (optional) min: 1 # Scope for the search query. Set to 'none' to disable the automatic # 'repo:owner/repo' scoping, enabling org-wide or cross-repo queries. # (optional) scope: "none" # Skip workflow execution if any CI checks on the target branch are failing or # pending. Accepts true (check all) or an object to filter specific checks by name # and optionally specify a branch or allow pending checks. # (optional) # Accepted formats: # Format 1: Bare key with no value — equivalent to true. Skips workflow execution # if any CI checks on the target branch are currently failing. skip-if-check-failing: null # Format 2: Skip workflow execution if any CI checks on the target branch are # currently failing. For pull_request events, checks the base branch. For other # events, checks the current ref. skip-if-check-failing: true # Format 3: Skip-if-check-failing configuration object with optional # include/exclude filter lists, an optional branch name, and an allow-pending # flag. skip-if-check-failing: # List of check names to evaluate. When specified, only these named checks are # considered. If omitted, all checks are evaluated. # (optional) include: [] # Array of strings # List of check names to ignore. Checks in this list are not considered when # determining whether to skip the workflow. # (optional) exclude: [] # Array of strings # Branch name to check for failing CI checks. When omitted, defaults to the base # branch of a pull_request event or the current ref for other events. # (optional) branch: "example-value" # When true, pending or in-progress checks are not treated as failing. By default # (false), any check that has not yet completed is treated as failing and will # block the workflow. # (optional) allow-pending: true # Skip workflow execution for users with specific repository roles. Useful for # workflows that should only run for external contributors or specific permission # levels. # (optional) # Accepted formats: # Format 1: Single role to skip workflow for (e.g., 'admin'). If the triggering # user has this role, the workflow will be skipped. skip-roles: "example-value" # Format 2: List of roles to skip workflow for (e.g., ['admin', 'maintainer', # 'write']). If the triggering user has any of these roles, the workflow will be # skipped. skip-roles: [] # Array items: string # Skip workflow execution for specific GitHub users. Useful for preventing # workflows from running for specific accounts (e.g., bots, specific team # members). # (optional) # Accepted formats: # Format 1: Single GitHub username to skip workflow for (e.g., 'user1'). If the # triggering user matches, the workflow will be skipped. skip-bots: "example-value" # Format 2: List of GitHub usernames to skip workflow for (e.g., ['user1', # 'user2']). If the triggering user is in this list, the workflow will be skipped. skip-bots: [] # Array items: string # Skip workflow execution when an event-specific payload author_association field # (for example: github.event.comment.author_association, # github.event.issue.author_association, # github.event.pull_request.author_association) matches configured associations # for specific events. Keys are event names (for example: issue_comment, # pull_request_review_comment, issues, pull_request). Values accept a single # string or an array of strings. Association values are case-insensitive in # frontmatter. # (optional) skip-author-associations: {} # Repository access roles required to trigger agentic workflows. Defaults to # ['admin', 'maintainer', 'write'] for security. Use 'all' to allow any # authenticated user (! security consideration). # (optional) # Accepted formats: # Format 1: Single repository permission level that can trigger the workflow. Use # 'all' to allow any authenticated user (! disables permission checking entirely # - use with caution) roles: "admin" # Format 2: List of repository permission levels that can trigger the workflow. # Permission checks are automatically applied to potentially unsafe triggers. roles: [] # Array items: Repository permission level: 'admin' (full access), # 'maintainer'/'maintain' (repository management), 'write' (push access), 'triage' # (issue management), 'read' (read-only access) # Allow list of bot identifiers that can trigger the workflow even if they don't # meet the required role permissions. When the actor is in this list, the bot must # be active (installed) on the repository to trigger the workflow. # (optional) bots: [] # Array of Bot identifier/name (e.g., 'dependabot[bot]', 'renovate[bot]', # 'github-actions[bot]') # Filter workflows triggered by pull_request_target (or other labeled events) to # only fire when the triggering label matches one of these names. Generates a # job-level if: condition on the pre-activation job so unmatched label events show # as Skipped (⊘) rather than Failed (✗). # (optional) # Accepted formats: # Format 1: Single label name that must match the triggering label (e.g., # 'panel-review') labels: "example-value" # Format 2: List of label names; the workflow fires when the triggering label # matches any entry. labels: [] # Array items: undefined # Allow the bot-posted-menu / user-checks-box pattern: when a workflow posts a # checkbox-menu comment as a GitHub App bot and a human maintainer edits it to # tick a box (issue_comment:edited where actor ≠ comment.user.login), treat this # as safe and skip the confused-deputy check. When false (default), the check # applies to all issue_comment events. The Dependabot confused-deputy attack # vector (issue_comment:created) is unaffected. # (optional) allow-bot-authored-trigger-comment: true # Environment name that requires manual approval before the workflow can run. Must # match a valid environment configured in the repository settings. # (optional) manual-approval: "example-value" # AI reaction to add/remove on triggering item. Scalar form accepts one of: +1, # -1, laugh, confused, heart, hooray, rocket, eyes, none. Object form implies # enabled reactions and supports optional `issues`, `pull-requests`, and # `discussions` fields to control trigger groups independently; use `type` to # choose the reaction emoji (defaults to `eyes` when omitted). Use 'none' to # disable reactions. # (optional) # Accepted formats: # Format 1: string reaction: "+1" # Format 2: YAML parses +1 and -1 without quotes as integers. These are converted # to +1 and -1 strings respectively. reaction: 1 # Format 3: object reaction: # Reaction type. Defaults to 'eyes' when omitted. # (optional) # Accepted formats: # Format 1: string type: "+1" # Format 2: YAML parses +1 and -1 without quotes as integers. These are converted # to +1 and -1 strings respectively. type: 1 # Whether reactions are allowed for issue triggers (issues, issue_comment). # (optional) issues: true # Whether reactions are allowed for pull request triggers (pull_request, # pull_request_review_comment). # (optional) pull-requests: true # Whether reactions are allowed for discussion and discussion_comment triggers. # (optional) discussions: true # Whether to post status comments (started/completed) on the triggering item. # Boolean form enables/disables status comments globally. Object form implies # enabled status comments and supports optional `issues`, `pull-requests`, and # `discussions` fields to control trigger groups independently. Automatically # enabled for slash_command and label_command triggers when not explicitly # configured. # (optional) # Accepted formats: # Format 1: boolean status-comment: true # Format 2: object status-comment: # Whether status comments are allowed for issue triggers (issues, issue_comment). # (optional) issues: true # Whether status comments are allowed for pull request triggers (pull_request, # pull_request_review_comment). # (optional) pull-requests: true # Whether status comments are allowed for discussion and discussion_comment # triggers. # (optional) discussions: true # Custom GitHub token for pre-activation reactions, activation status comments, # and skip-if search queries. When specified, overrides the default GITHUB_TOKEN # for these operations. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # GitHub App configuration for minting a token used in pre-activation reactions, # activation status comments, and skip-if search queries. When configured, a # single GitHub App installation access token is minted and shared across all # these operations instead of using the default GITHUB_TOKEN. Can be defined in a # shared agentic workflow and inherited by importing workflows. # (optional) github-app: # Deprecated alias for client-id. GitHub App ID/client ID (e.g., '${{ vars.APP_ID # }}'). # (optional) app-id: "example-value" # GitHub App client ID (e.g., '${{ vars.APP_ID }}'). Required to mint a GitHub App # token. # (optional) client-id: "example-value" # GitHub App private key (e.g., '${{ secrets.APP_PRIVATE_KEY }}'). Required to # mint a GitHub App token. # (optional) private-key: "example-value" # If true, skip token minting when client-id/private-key resolve to empty strings # at runtime. Defaults to false. # (optional) ignore-if-missing: true # Optional owner of the GitHub App installation (defaults to current repository # owner if not specified) # (optional) owner: "example-value" # Optional list of repositories to grant access to (defaults to current repository # if not specified) # (optional) repositories: [] # Array of strings # Optional extra GitHub App-only permissions to merge into the minted token. Takes # effect for tools.github.github-app and safe-outputs.github-app; ignored in # on.github-app and the top-level github-app fallback. Use to add GitHub App-only # scopes (e.g. members, organization-administration) not expressible via standard # handler declarations. # (optional) permissions: # Permission level for repository administration (read/none; "write" is rejected # by the compiler). GitHub App-only permission for repository administration. # (optional) administration: "read" # Permission level for Codespaces (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) codespaces: "read" # Permission level for Codespaces lifecycle administration (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) codespaces-lifecycle-admin: "read" # Permission level for Codespaces metadata (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) codespaces-metadata: "read" # Permission level for user email addresses (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) email-addresses: "read" # Permission level for repository environments (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) environments: "read" # Permission level for git signing (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) git-signing: "read" # Permission level for organization members (read/none; "write" is rejected by the # compiler). Required for org team membership API calls. # (optional) members: "read" # Permission level for organization administration (read/none; "write" is rejected # by the compiler). GitHub App-only permission. # (optional) organization-administration: "read" # Permission level for organization announcement banners (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-announcement-banners: "read" # Permission level for organization Codespaces (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-codespaces: "read" # Permission level for organization Copilot (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-copilot: "read" # Permission level for organization custom org roles (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-org-roles: "read" # Permission level for organization custom properties (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-properties: "read" # Permission level for organization custom repository roles (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-repository-roles: "read" # Permission level for organization events (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-events: "read" # Permission level for organization webhooks (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-hooks: "read" # Permission level for organization members management (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-members: "read" # Permission level for organization packages (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-packages: "read" # Permission level for organization personal access token requests (read/none; # "write" is rejected by the compiler). GitHub App-only permission. # (optional) organization-personal-access-token-requests: "read" # Permission level for organization personal access tokens (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-personal-access-tokens: "read" # Permission level for organization plan (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-plan: "read" # Permission level for organization self-hosted runners (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-self-hosted-runners: "read" # Permission level for organization user blocking (read/none; "write" is rejected # by the compiler). GitHub App-only permission. # (optional) organization-user-blocking: "read" # Permission level for repository custom properties (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) repository-custom-properties: "read" # Permission level for repository webhooks (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) repository-hooks: "read" # Permission level for single file access (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) single-file: "read" # Permission level for team discussions (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) team-discussions: "read" # Permission level for Dependabot vulnerability alerts (read/none; "write" is # rejected by the compiler). Also available as a GITHUB_TOKEN scope. When used # with a GitHub App, forwarded as permission-vulnerability-alerts input. # (optional) vulnerability-alerts: "read" # Permission level for GitHub Actions workflow files (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) workflows: "read" # Explicit additional custom workflow jobs that pre_activation and activation # should depend on. # (optional) needs: [] # Array of strings # Steps to inject into the pre-activation job. These steps run after all built-in # checks (membership, stop-time, skip-if, etc.) and their results are exposed as # pre-activation outputs. Use 'id' on steps to reference their results via # needs.pre_activation.outputs._result. # (optional) steps: [] # Array items: # Optional name for the step # (optional) name: "My Workflow" # Optional step ID. When set, the step result is exposed as # needs.pre_activation.outputs._result # (optional) id: "example-value" # Shell command to run # (optional) run: "example-value" # Action to use (e.g., 'actions/checkout@v4') # (optional) uses: "example-value" # Input parameters for the action # (optional) with: {} # Environment variables for the step # (optional) env: {} # Conditional expression for the step # (optional) if: "example-value" # Whether to continue if the step fails # (optional) continue-on-error: true # Additional permissions for the pre-activation job. Use to declare extra scopes # required by on.steps (e.g., issues: read for GitHub API calls in steps). # (optional) # Map of permission scope to level # (optional) permissions: # (optional) actions: "read" # (optional) checks: "read" # (optional) contents: "read" # (optional) deployments: "read" # (optional) discussions: "read" # (optional) issues: "read" # (optional) packages: "read" # (optional) pages: "read" # (optional) pull-requests: "read" # (optional) repository-projects: "read" # (optional) security-events: "read" # (optional) statuses: "read" # When set to false, disables the frontmatter hash check step in the activation # job. Default is true (check is enabled). Useful when the workflow source files # are managed outside the default GitHub repo context (e.g. cross-repo org # rulesets) and the stale check is not needed. # (optional) stale-check: true # GitHub token permissions for the workflow. Controls what the GITHUB_TOKEN can # access during execution. Use the principle of least privilege - only grant the # minimum permissions needed. # (optional) # Accepted formats: # Format 1: Simple permissions string: 'read-all' (all read permissions) or # 'write-all' (all write permissions) permissions: "read-all" # Format 2: Detailed permissions object with granular control over specific GitHub # API scopes permissions: # Permission for GitHub Actions workflows and runs (read: view workflows, write: # manage workflows, none: no access) # (optional) actions: "read" # Permission for artifact attestations (read: view attestations, write: create # attestations, none: no access) # (optional) attestations: "read" # Permission for repository checks and status checks (read: view checks, write: # create/update checks, none: no access) # (optional) checks: "read" # Permission for repository contents (read: view files, write: modify # files/branches, none: no access) # (optional) contents: "read" # Permission for repository deployments (read: view deployments, write: # create/update deployments, none: no access) # (optional) deployments: "read" # Permission for repository discussions (read: view discussions, write: # create/update discussions, none: no access) # (optional) discussions: "read" # Permission level for OIDC token requests (write/none only - read is not # supported). Allows workflows to request JWT tokens for cloud provider # authentication. # (optional) id-token: "write" # Permission for repository issues (read: view issues, write: create/update/close # issues, none: no access) # (optional) issues: "read" # Permission for GitHub Copilot models (read: access AI models for agentic # workflows, none: no access) # (optional) models: "read" # Permission for repository metadata (read: view repository information, write: # update repository metadata, none: no access) # (optional) metadata: "read" # Permission level for GitHub Packages (read/write/none). Controls access to # publish, modify, or delete packages. # (optional) packages: "read" # Permission level for GitHub Pages (read/write/none). Controls access to deploy # and manage GitHub Pages sites. # (optional) pages: "read" # Permission level for pull requests (read/write/none). Controls access to create, # edit, review, and manage pull requests. # (optional) pull-requests: "read" # Permission level for repository projects (read/write/none). Controls access to # manage repository-level GitHub Projects boards. # (optional) repository-projects: "read" # Permission level for organization projects (read/write/none). Controls access to # manage organization-level GitHub Projects boards. # (optional) organization-projects: "read" # Permission level for security events (read/write/none). Controls access to view # and manage code scanning alerts and security findings. # (optional) security-events: "read" # Permission level for commit statuses (read/write/none). Controls access to # create and update commit status checks. # (optional) statuses: "read" # Permission level for Dependabot vulnerability alerts (read/write/none). Allows # workflows to access the Dependabot alerts API via GITHUB_TOKEN instead of # requiring a PAT or GitHub App. # (optional) vulnerability-alerts: "read" # Permission shorthand that applies read access to all permission scopes. Can be # combined with specific write permissions to override individual scopes. 'write' # is not allowed for all. # (optional) all: "read" # Custom name for workflow runs that appears in the GitHub Actions interface # (supports GitHub expressions like ${{ github.event.issue.title }}) # (optional) run-name: "example-value" # Groups together all the jobs that run in the workflow # (optional) jobs: {} # Runner type for workflow execution (GitHub Actions standard field). Supports # multiple forms: simple string for single runner label (e.g., 'ubuntu-latest'), # array for runner selection with fallbacks, or object for GitHub-hosted runner # groups with specific labels. For agentic workflows, runner selection matters # when AI workloads require specific compute resources or when using self-hosted # runners with specialized capabilities. Typically configured at the job level # instead. See # https://docs.github.com/en/actions/using-jobs/choosing-the-runner-for-a-job # (optional) # Accepted formats: # Format 1: Simple runner label string. Use for standard GitHub-hosted runners # (e.g., 'ubuntu-latest', 'windows-latest', 'macos-latest') or self-hosted runner # labels. Most common form for agentic workflows. runs-on: "example-value" # Format 2: Array of runner labels for selection with fallbacks. GitHub Actions # will use the first available runner that matches any label in the array. Useful # for high-availability setups or when multiple runner types are acceptable. runs-on: [] # Array items: string # Format 3: Runner group configuration for GitHub-hosted runners. Use this form to # target specific runner groups (e.g., larger runners with more CPU/memory) or # self-hosted runner pools with specific label requirements. Agentic workflows may # benefit from larger runners for complex AI processing tasks. runs-on: # Runner group name for self-hosted runners or GitHub-hosted runner groups # (optional) group: "example-value" # List of runner labels for self-hosted runners or GitHub-hosted runner selection # (optional) labels: [] # Array of strings # Runner for all framework/generated jobs (activation, pre-activation, # safe-outputs, unlock, APM, etc.). Provides a compile-stable override for # generated job runners without requiring a safe-outputs section. Overridden by # safe-outputs.runs-on when both are set. Defaults to 'ubuntu-slim'. Use this when # your infrastructure does not provide the default runner or when you need # consistent runner selection across all jobs. # (optional) runs-on-slim: "example-value" # Workflow timeout in minutes (GitHub Actions standard field). Defaults to 20 # minutes for agentic workflows. Has sensible defaults and can typically be # omitted. Custom runners support longer timeouts beyond the GitHub-hosted runner # limit. Supports GitHub Actions expressions (e.g. '${{ inputs.timeout }}') for # reusable workflow_call workflows. # (optional) # Accepted formats: # Format 1: integer timeout-minutes: 1 # Format 2: GitHub Actions expression that resolves to an integer (e.g. '${{ # inputs.timeout }}') timeout-minutes: "example-value" # Concurrency control to limit concurrent workflow runs (GitHub Actions standard # field). Supports two forms: simple string for basic group isolation, or object # with cancel-in-progress option for advanced control. Agentic workflows enhance # this with automatic per-engine concurrency policies (defaults to single job per # engine across all workflows) and token-based rate limiting. Default behavior: # workflows in the same group queue sequentially unless cancel-in-progress is # true. See https://docs.github.com/en/actions/using-jobs/using-concurrency # (optional) # Accepted formats: # Format 1: Simple concurrency group name to prevent multiple runs in the same # group. Use expressions like '${{ github.workflow }}' for per-workflow isolation # or '${{ github.ref }}' for per-branch isolation. Agentic workflows automatically # generate enhanced concurrency policies using 'gh-aw-{engine-id}' as the default # group to limit concurrent AI workloads across all workflows using the same # engine. concurrency: "example-value" # Format 2: Concurrency configuration object with group isolation and cancellation # control. Use object form when you need fine-grained control over whether to # cancel in-progress runs. For agentic workflows, this is useful to prevent # multiple AI agents from running simultaneously and consuming excessive resources # or API quotas. concurrency: # Concurrency group name. Workflows in the same group cannot run simultaneously. # Supports GitHub Actions expressions for dynamic group names based on branch, # workflow, or other context. # (optional) group: "example-value" # Whether to cancel in-progress workflows in the same concurrency group when a new # one starts. Default: false (queue new runs). Set to true for agentic workflows # where only the latest run matters (e.g., PR analysis that becomes stale when new # commits are pushed). # (optional) cancel-in-progress: true # Pending run queue behavior for this concurrency group. 'single' (default) allows # one pending run and replaces older pending runs. 'max' allows up to 100 pending # runs in FIFO order. # (optional) queue: "single" # Additional discriminator expression appended to compiler-generated job-level # concurrency groups (agent, output jobs). Use this when multiple workflow # instances are dispatched concurrently with different inputs (fan-out pattern) to # prevent job-level concurrency groups from colliding. For example, '${{ # inputs.finding_id }}' ensures each dispatched run gets a unique job-level group. # Supports GitHub Actions expressions. This field is stripped from the compiled # lock file (it is a gh-aw extension, not a GitHub Actions field). # (optional) job-discriminator: "example-value" # Environment variables for the workflow # (optional) # Accepted formats: # Format 1: object env: {} # Format 2: string env: "example-value" # Deprecated switch for inline sub-agent support. Inline sub-agents are enabled by # default. Setting this to false is not supported and causes a compilation error. # (optional) inline-sub-agents: true # Feature flags and configuration options for experimental or optional features in # the workflow. Each feature can be a boolean flag or a string value. The # 'action-tag' feature (string) specifies the tag or SHA to use when referencing # actions/setup in compiled workflows (for testing purposes only). # (optional) features: {} # Named model alias definitions with ordered fallback lists, resolved recursively # by AWF. Each key is an alias name (use empty string "" for the default policy). # Each value is an ordered list of vendor/modelid glob patterns or other alias # names to try in sequence. Entries defined here are merged on top of the builtin # aliases; the main workflow file always wins over imported aliases. Builtin # aliases include: sonnet, sonnet-6x, haiku, opus, gpt-5, gpt-5-mini, gpt-5-codex, # gemini-flash, gemini-pro, small, mini, large, auto, any, agent, copilot, claude, # codex, gemini. # (optional) models: {} # A/B testing experiments. Each key is an experiment name; the value is either an # array of two or more variant strings (bare-array form) or an object with a # 'variants' field plus optional metadata fields (description, metric, weight, # issue, start_date, end_date, hypothesis, secondary_metrics, guardrail_metrics, # min_samples). The reserved 'storage' key controls how experiment state is # persisted: 'repo' (default) commits state to a git branch named # 'experiments/{sanitizedWorkflowID}' (workflow ID lowercased with hyphens # removed) for durability; 'cache' uses GitHub Actions cache. At runtime the # activation job picks a variant and persists the updated counters. Use ${{ # experiments. }} in the workflow prompt to reference the selected variant. # When multiple experiments are declared, assignments are statistically balanced # using a least-used counter that round-robins across variants (or weighted when # 'weight' is provided); ties are broken randomly so no variant is systematically # favoured on the first run. # (optional) experiments: # Storage backend for experiment state. 'repo' (default) persists state to a git # branch named 'experiments/{sanitizedWorkflowID}' (workflow ID lowercased with # hyphens removed, e.g. 'my-workflow' -> 'experiments/myworkflow') for durability # across cache evictions. 'cache' uses GitHub Actions cache (legacy behaviour). # Repo storage is recommended because experiment data is valuable and more durable # than cache. # (optional) storage: "cache" # Controls whether the custom agent should disable model invocation. When set to # true, the agent will not make additional model calls. # (optional) disable-model-invocation: true # Secret values passed to workflow execution. Secrets can be defined as simple # strings (GitHub Actions expressions) or objects with 'value' and 'description' # properties. Typically used to provide secrets to MCP servers or custom engines. # Note: For passing secrets to reusable workflows, use the jobs..secrets # field instead. # (optional) secrets: {} # Environment that the job references (for protected environments and deployments) # (optional) # Accepted formats: # Format 1: Environment name as a string environment: "example-value" # Format 2: Environment object with name and optional URL environment: # The name of the environment configured in the repo name: "My Workflow" # A deployment URL # (optional) url: "example-value" # Container to run the job steps in # (optional) # Accepted formats: # Format 1: Docker image name (e.g., 'node:18', 'ubuntu:latest') container: "example-value" # Format 2: Container configuration object container: # The Docker image to use as the container image: "example-value" # Credentials for private registries # (optional) credentials: # Username for Docker registry authentication when pulling private container # images. # (optional) username: "example-value" # Password or access token for Docker registry authentication. Should use secrets # syntax: ${{ secrets.DOCKER_PASSWORD }} # (optional) password: "example-value" # Environment variables for the container # (optional) env: {} # Ports to expose on the container # (optional) ports: [] # Volumes for the container # (optional) volumes: [] # Array of strings # Additional Docker container options # (optional) options: "example-value" # Service containers for the job # (optional) services: {} # Network access control for AI engines using ecosystem identifiers and domain # allowlists. Supports wildcard patterns like '*.example.com' to match any # subdomain. Controls web fetch and search capabilities. IMPORTANT: For workflows # that build/install/test code, always include the language ecosystem identifier # alongside 'defaults' — 'defaults' alone only covers basic infrastructure, not # package registries. Key ecosystem identifiers by runtime: 'dotnet' (.NET/NuGet), # 'python' (pip/PyPI), 'node' (npm/yarn), 'go' (go modules), 'java' # (Maven/Gradle), 'ruby' (Bundler), 'rust' (Cargo), 'swift' (Swift PM). Example: a # .NET project needs network: { allowed: [defaults, dotnet] }. # (optional) # Accepted formats: # Format 1: Use default network permissions (basic infrastructure: certificates, # JSON schema, Ubuntu, etc.) network: "defaults" # Format 2: Custom network access configuration with ecosystem identifiers and # specific domains network: # List of allowed domains or ecosystem identifiers (e.g., 'defaults', 'python', # 'node', '*.example.com'). Wildcard patterns match any subdomain AND the base # domain. # (optional) allowed: [] # Array of Domain name or ecosystem identifier. Supports wildcards like # '*.example.com' (matches sub.example.com, deep.nested.example.com, and # example.com itself). Ecosystem identifiers by runtime: 'dotnet' (.NET/NuGet), # 'python' (pip/PyPI), 'node' (npm/yarn), 'go' (go modules), 'java' # (Maven/Gradle), 'ruby' (RubyGems), 'rust' (Cargo), 'swift' (Swift PM), 'php' # (Composer), 'dart' (pub.dev), 'haskell' (Hackage), 'perl' (CPAN), 'containers' # (Docker/GHCR), 'github' (GitHub domains), 'terraform' (HashiCorp), # 'linux-distros' (apt/yum), 'playwright' (browser testing), 'defaults' (basic # infrastructure). # When true and the workflow uses workflow_call, expose a network_allowed string # input on the compiled lock file. The caller-supplied value is unioned with # network.allowed at runtime, supporting ecosystem identifiers (for example # 'rust') or comma-separated domains. # (optional) allowed-input: true # List of blocked domains or ecosystem identifiers (e.g., 'python', 'node', # 'tracker.example.com'). Blocked domains take precedence over allowed domains. # (optional) blocked: [] # Array of Domain name or ecosystem identifier to block. Supports wildcards like # '*.example.com' (matches sub.example.com, deep.nested.example.com, and # example.com itself) and ecosystem names like 'python', 'node'. # Sandbox configuration for AI engines. Controls agent sandbox (AWF) and MCP # gateway. The MCP gateway is always enabled and cannot be disabled. # (optional) # Accepted formats: # Format 1: String format for sandbox type: 'default' for no sandbox, 'awf' for # Agent Workflow Firewall. Note: Legacy 'srt' and 'sandbox-runtime' values are # automatically migrated to 'awf' sandbox: "default" # Format 2: Object format for full sandbox configuration with agent and mcp # options sandbox: # Legacy sandbox type field (use agent instead). Note: Legacy 'srt' and # 'sandbox-runtime' values are automatically migrated to 'awf' # (optional) type: "default" # Agent sandbox type: 'awf' uses AWF (Agent Workflow Firewall), or false to # disable agent sandbox. Defaults to 'awf' if not specified. Note: Disabling the # agent sandbox (false) removes firewall protection but keeps the MCP gateway # enabled. # (optional) # Accepted formats: # Format 1: Set to false to disable the agent sandbox (firewall). Warning: This # removes firewall protection but keeps the MCP gateway enabled. Not allowed in # strict mode. agent: true # Format 2: Sandbox type: 'awf' for Agent Workflow Firewall agent: "awf" # Format 3: Custom sandbox runtime configuration agent: # Agent identifier (replaces 'type' field in new format): 'awf' for Agent Workflow # Firewall # (optional) id: "awf" # Legacy: Sandbox type to use (use 'id' instead) # (optional) type: "awf" # AWF version override used to install and run the matching firewall version. # (optional) version: "example-value" # Container mounts to add when using AWF. Each mount is specified using Docker # mount syntax: 'source:destination:mode' where mode can be 'ro' (read-only) or # 'rw' (read-write). Example: '/host/path:/container/path:ro' # (optional) mounts: [] # Array of Mount specification in format 'source:destination:mode' # Memory limit for the AWF container (e.g., '4g', '8g'). Passed as --memory-limit # to AWF. If not specified, AWF's default memory limit is used. # (optional) memory: "example-value" # Custom sandbox runtime configuration. Note: Network configuration is controlled # by the top-level 'network' field, not here. # (optional) config: # Filesystem access control configuration for the agent within the sandbox. # Controls read/write permissions and path restrictions. # (optional) filesystem: # List of paths to deny read access # (optional) denyRead: [] # Array of strings # List of paths to allow write access # (optional) allowWrite: [] # Array of strings # List of paths to deny write access # (optional) denyWrite: [] # Array of strings # Map of command patterns to paths that should ignore violations # (optional) ignoreViolations: {} # Enable weaker nested sandbox mode (recommended: true for Docker access) # (optional) enableWeakerNestedSandbox: true # Legacy custom Sandbox Runtime configuration (use agent.config instead). Note: # Network configuration is controlled by the top-level 'network' field, not here. # (optional) config: # Filesystem access control configuration for sandboxed workflows. Controls # read/write permissions and path restrictions for file operations. # (optional) filesystem: # Array of path patterns that deny read access in the sandboxed environment. Takes # precedence over other read permissions. # (optional) denyRead: [] # Array of strings # Array of path patterns that allow write access in the sandboxed environment. # Paths outside these patterns are read-only. # (optional) allowWrite: [] # Array of strings # Array of path patterns that deny write access in the sandboxed environment. # Takes precedence over other write permissions. # (optional) denyWrite: [] # Array of strings # When true, log sandbox violations without blocking execution. Useful for # debugging and gradual enforcement of sandbox policies. # (optional) ignoreViolations: {} # When true, allows nested sandbox processes to run with relaxed restrictions. # Required for certain containerized tools that spawn subprocesses. # (optional) enableWeakerNestedSandbox: true # MCP Gateway configuration for routing MCP server calls through a unified HTTP # gateway. Requires the 'mcp-gateway' feature flag to be enabled. Per MCP Gateway # Specification v1.0.0: Only container-based execution is supported. # (optional) mcp: # Volume mounts for the MCP gateway container. Each mount is specified using # Docker mount syntax: 'source:destination:mode' where mode can be 'ro' # (read-only) or 'rw' (read-write). Example: '/host/data:/container/data:ro' # (optional) mounts: [] # Array of Mount specification in format 'source:destination:mode' # Environment variables for MCP gateway # (optional) env: {} # Port number for the MCP gateway HTTP server (default: 8080) # (optional) port: 1 # API key for authenticating with the MCP gateway (supports ${{ secrets.* }} # syntax) # (optional) api-key: "example-value" # Gateway domain for URL generation (default: 'host.docker.internal' when agent is # enabled, 'localhost' when disabled) # (optional) domain: "localhost" # Keepalive ping interval in seconds for HTTP MCP backends. Sends periodic pings # to prevent session expiry during long-running agent tasks. Set to -1 to disable # keepalive pings. Unset or 0 uses the gateway default (1500 seconds = 25 # minutes). # (optional) keepalive-interval: 1 # Conditional execution expression # (optional) if: "example-value" # Custom workflow steps # (optional) # Accepted formats: # Format 1: object steps: {} # Format 2: array steps: [] # Array items: undefined # Custom workflow steps to run at the very beginning of the agent job, before # checkout and any other built-in steps. Use pre-steps to mint short-lived tokens # or perform any setup that must happen before the repository is checked out. Step # outputs are available via ${{ steps..outputs. }} and can be referenced # in checkout.token to avoid masked-value cross-job-boundary issues. # (optional) # Accepted formats: # Format 1: object pre-steps: {} # Format 2: array pre-steps: [] # Array items: undefined # Custom workflow steps to run immediately before AI execution, after all # initialization and setup steps in the agent job. # (optional) # Accepted formats: # Format 1: object pre-agent-steps: {} # Format 2: array pre-agent-steps: [] # Array items: undefined # Custom workflow steps to run after AI execution # (optional) # Accepted formats: # Format 1: object post-steps: {} # Format 2: array post-steps: [] # Array items: undefined # AI engine configuration that specifies which AI processor interprets and # executes the markdown content of the workflow. Defaults to 'copilot'. # (optional) # Accepted formats: # Format 1: Engine name: built-in ('claude', 'codex', 'copilot', 'gemini', # 'opencode', 'crush', 'pi') or a named catalog entry engine: "example-value" # Format 2: Extended engine configuration object with advanced options for model # selection, turn limiting, environment variables, and custom steps engine: # AI engine identifier: built-in ('claude', 'codex', 'copilot', 'gemini', # 'opencode', 'crush', 'pi') or a named catalog entry id: "example-value" # Optional version of the AI engine action (e.g., 'beta', 'stable', 20). Has # sensible defaults and can typically be omitted. Numeric values are automatically # converted to strings at runtime. GitHub Actions expressions (e.g., '${{ # inputs.engine-version }}') are accepted and compiled with injection-safe env var # handling. # (optional) version: null # Optional specific LLM model to use (e.g., 'claude-3-5-sonnet-20241022', # 'gpt-4'). Has sensible defaults and can typically be omitted. # (optional) model: "example-value" # Maximum number of chat iterations per run. Helps prevent runaway loops and # control costs. Has sensible defaults and can typically be omitted. Note: Only # supported by the claude engine. # (optional) # Accepted formats: # Format 1: Maximum number of chat iterations per run as an integer value max-turns: 1 # Format 2: Maximum number of chat iterations per run as a string value max-turns: "example-value" # Maximum number of continuations for multi-run autopilot mode. Default is 1 # (single run, no autopilot). Values greater than 1 enable --autopilot mode for # the copilot engine with --max-autopilot-continues set to this value. Note: Only # supported by the copilot engine. # (optional) max-continuations: 1 # Agent job concurrency configuration. Defaults to single job per engine across # all workflows (group: 'gh-aw-{engine-id}'). Supports full GitHub Actions # concurrency syntax. # (optional) # Accepted formats: # Format 1: Simple concurrency group name. Gets converted to GitHub Actions # concurrency format with the specified group. concurrency: "example-value" # Format 2: GitHub Actions concurrency configuration for the agent job. Controls # how many agentic workflow runs can run concurrently. concurrency: # Concurrency group identifier. Use GitHub Actions expressions like ${{ # github.workflow }} or ${{ github.ref }}. Defaults to 'gh-aw-{engine-id}' if not # specified. group: "example-value" # Whether to cancel in-progress runs of the same concurrency group. Defaults to # false for agentic workflow runs. # (optional) cancel-in-progress: true # Pending run queue behavior for this concurrency group. 'single' (default) allows # one pending run and replaces older pending runs. 'max' allows up to 100 pending # runs in FIFO order. # (optional) queue: "single" # Custom user agent string for GitHub MCP server configuration (codex engine only) # (optional) user-agent: "example-value" # Custom executable path for the AI engine CLI. When specified, the workflow will # skip the standard installation steps and use this command instead. The command # should be the full path to the executable or a command available in PATH. # (optional) command: "example-value" # Custom Node.js harness script filename for an agentic engine. This replaces the # engine's built-in harness wrapper (when the engine supports one) and must end # with .js, .cjs, or .mjs. # (optional) harness: "example-value" # Custom environment variables to pass to the AI engine, including secret # overrides (e.g., OPENAI_API_KEY: ${{ secrets.CUSTOM_KEY }}) # (optional) env: {} # Engine-level authentication configuration for AWF API proxy sidecar integration # (for example, Azure OpenAI via GitHub OIDC). Values are mapped to AWF_AUTH_* # environment variables. # (optional) auth: # Authentication type. Currently only 'github-oidc' is supported. type: "github-oidc" # OIDC audience to request from GitHub Actions for token exchange. # (optional) audience: "example-value" # Optional Azure tenant ID for token exchange. # (optional) azure-tenant-id: "example-value" # Optional Azure client ID for token exchange. # (optional) azure-client-id: "example-value" # Optional Azure OAuth scope (defaults to # https://cognitiveservices.azure.com/.default in AWF sidecar). # (optional) azure-scope: "example-value" # Optional Azure cloud name (for example, public, usgovernment, china). # (optional) azure-cloud: "example-value" # Additional TOML configuration text that will be appended to the generated # config.toml in the action (codex engine only) # (optional) config: "example-value" # Agent identifier to pass to copilot --agent flag (copilot engine only). # Specifies which custom agent to use for the workflow. # (optional) agent: "example-value" # Custom API endpoint hostname for the agentic engine. Used for GitHub Enterprise # Cloud (GHEC), GitHub Enterprise Server (GHES), or custom AI endpoints. Example: # 'api.acme.ghe.com' for GHEC, 'api.enterprise.githubcopilot.com' for GHES, or # custom endpoint hostnames. # (optional) api-target: "example-value" # Custom model token weights for effective token computation. Overrides or extends # the built-in model multipliers from model_multipliers.json. Useful for custom # models or adjusted cost ratios. # (optional) token-weights: # Per-model cost multipliers relative to the reference model (claude-sonnet-4.5 = # 1.0). Keys are model names (case-insensitive, prefix matching supported). Values # are numeric multipliers. # (optional) multipliers: {} # Per-token-class weights applied before the model multiplier. Any specified # weight overrides the corresponding default. # (optional) token-class-weights: # Weight for input tokens (default: 1.0) # (optional) input: 1 # Weight for cached input tokens (default: 0.1) # (optional) cached-input: 1 # Weight for output tokens (default: 4.0) # (optional) output: 1 # Weight for reasoning tokens (default: 4.0) # (optional) reasoning: 1 # Weight for cache write tokens (default: 1.0) # (optional) cache-write: 1 # Optional array of command-line arguments to pass to the AI engine CLI. These # arguments are injected after all other args but before the prompt. # (optional) args: [] # Array of strings # When true, disables automatic loading of context and custom instructions by the # AI engine. The engine-specific flag depends on the engine: copilot uses # --no-custom-instructions (suppresses .github/AGENTS.md and user-level custom # instructions), claude uses --bare (suppresses CLAUDE.md memory files), codex # uses --no-system-prompt (suppresses the default system prompt), gemini sets # GEMINI_SYSTEM_MD=/dev/null (overrides the built-in system prompt with an empty # one). Defaults to false. # (optional) bare: true # Engine-level MCP gateway configuration. Settings here apply to the MCP gateway # used by this engine. # (optional) mcp: # Session timeout for MCP gateway sessions as a Go duration string (e.g. "30m", # "4h", "24h"). Must be at least 5m (no upper bound). Omitted or empty uses the # effective gateway default (precedence: this field > MCP_GATEWAY_SESSION_TIMEOUT # env var > built-in default 6h). Longer timeouts benefit multi-hour workflows # such as large-scale migrations; shorter values free gateway resources sooner. # (optional) session-timeout: "example-value" # Timeout for individual MCP tool calls as a Go duration string (e.g. "30s", "2m", # "10m"). Must be between 10s and 600s inclusive. Omitted or empty uses the # gateway built-in default (60s). Use a higher value for slow MCP backends such as # full-text search over large indexes. # (optional) tool-timeout: "example-value" # Format 3: Inline engine definition: specifies a runtime adapter and optional # provider settings directly in the workflow frontmatter, without requiring a # named catalog entry engine: # Runtime adapter reference for the inline engine definition runtime: # Runtime adapter identifier (e.g. 'codex', 'claude', 'copilot', 'gemini', # 'opencode', 'crush', 'pi') id: "example-value" # Optional version of the runtime adapter (e.g. '0.105.0', 'beta') # (optional) version: null # Optional provider configuration for the inline engine definition # (optional) provider: # Provider identifier (e.g. 'openai', 'anthropic', 'github', 'google') # (optional) id: "example-value" # Optional specific LLM model to use (e.g. 'gpt-5', 'claude-3-5-sonnet-20241022') # (optional) model: "example-value" # Authentication configuration for the provider # (optional) auth: # Name of the GitHub Actions secret that contains the API key for this provider # (optional) secret: "example-value" # Authentication strategy for the provider (default: api-key when secret is set) # (optional) strategy: "api-key" # OAuth 2.0 token endpoint URL. Required when strategy is # 'oauth-client-credentials'. # (optional) token-url: "example-value" # GitHub Actions secret name that holds the OAuth client ID. Required when # strategy is 'oauth-client-credentials'. # (optional) client-id: "example-value" # GitHub Actions secret name that holds the OAuth client secret. Required when # strategy is 'oauth-client-credentials'. # (optional) client-secret: "example-value" # JSON field name in the token response that contains the access token. Defaults # to 'access_token'. # (optional) token-field: "example-value" # HTTP header name to inject the API key or token into (e.g. 'api-key', # 'x-api-key'). Required when strategy is not 'bearer'. # (optional) header-name: "example-value" # Request shaping configuration for non-standard provider URL and body # transformations # (optional) request: # URL path template with {model} and other variable placeholders (e.g. # '/openai/deployments/{model}/chat/completions') # (optional) path-template: "example-value" # Static or template query-parameter values appended to every request # (optional) query: {} # Key/value pairs injected into the JSON request body before sending # (optional) body-inject: {} # When true, disables automatic loading of context and custom instructions by the # AI engine. The engine-specific flag depends on the engine: copilot uses # --no-custom-instructions, claude uses --bare, codex uses --no-system-prompt, # gemini sets GEMINI_SYSTEM_MD=/dev/null. Defaults to false. # (optional) bare: true # Format 4: Engine definition: full declarative metadata for a named engine entry # (used in builtin engine shared workflow files such as @builtin:engines/*.md) engine: # Unique engine identifier (e.g. 'copilot', 'claude', 'codex', 'gemini', # 'opencode', 'crush', 'pi') id: "example-value" # Human-readable display name for the engine display-name: "example-value" # Human-readable description of the engine # (optional) description: "Description of the workflow" # Runtime adapter identifier. Maps to the CodingAgentEngine registered in the # engine registry. Defaults to id when omitted. # (optional) runtime-id: "example-value" # Provider metadata for the engine # (optional) provider: # Provider name (e.g. 'anthropic', 'github', 'google', 'openai') # (optional) name: "My Workflow" # Default authentication configuration for the provider # (optional) auth: # Name of the GitHub Actions secret that contains the API key # (optional) secret: "example-value" # Authentication strategy # (optional) strategy: "api-key" # OAuth 2.0 token endpoint URL # (optional) token-url: "example-value" # GitHub Actions secret name for the OAuth client ID # (optional) client-id: "example-value" # GitHub Actions secret name for the OAuth client secret # (optional) client-secret: "example-value" # JSON field name in the token response containing the access token # (optional) token-field: "example-value" # HTTP header name to inject the API key or token into # (optional) header-name: "example-value" # Request shaping configuration # (optional) request: # URL path template with variable placeholders # (optional) path-template: "example-value" # Static query parameters # (optional) query: {} # Key/value pairs injected into the JSON request body # (optional) body-inject: {} # Model selection configuration for the engine # (optional) models: # Default model identifier # (optional) default: "example-value" # List of supported model identifiers # (optional) supported: [] # Array of strings # Authentication bindings — maps logical roles (e.g. 'api-key') to GitHub Actions # secret names # (optional) auth: [] # Array items: # Logical authentication role (e.g. 'api-key', 'token') role: "example-value" # Name of the GitHub Actions secret that provides credentials for this role secret: "example-value" # Additional engine-specific options # (optional) options: {} # Format 5: MCP gateway configuration for shared workflows. Declares engine.mcp # settings (tool-timeout, session-timeout) that consumers inherit during import # without specifying an engine identifier. The engine is always inherited from the # importing workflow. engine: # Engine-level MCP gateway configuration. Settings here apply to the MCP gateway # used by this engine. mcp: # Session timeout for MCP gateway sessions as a Go duration string (e.g. "30m", # "4h", "24h"). Must be at least 5m (no upper bound). Omitted or empty uses the # effective gateway default (precedence: this field > MCP_GATEWAY_SESSION_TIMEOUT # env var > built-in default 6h). # (optional) session-timeout: "example-value" # Timeout for individual MCP tool calls as a Go duration string (e.g. "30s", "2m", # "10m"). Must be between 10s and 600s inclusive. Omitted or empty uses the # gateway built-in default (60s). Use a higher value for slow MCP backends such as # full-text search over large indexes. # (optional) tool-timeout: "example-value" # Format 6: Engine object with only a model preference (no engine.id). Allows # workflow authors to express a model-size hint (e.g. 'small', 'large') without # committing to a specific engine. The runtime selects an appropriate engine using # its default, and the model preference is applied to it. engine: # Model preference or size category (e.g. 'small', 'large', 'gpt-4.1'). Applied to # the default engine when engine.id is not specified. model: "example-value" # Explicit ET budget control for firewall cost enforcement. Defaults to 25000000 # when omitted. Set to a negative value to disable budget enforcement and token # steering. # (optional) # Accepted formats: # Format 1: Maximum effective-token (ET) budget for AWF API proxy enforcement. Use # a negative value to disable budget enforcement and token steering. max-effective-tokens: 1 # Format 2: Maximum effective-token (ET) budget as a numeric string or GitHub # Actions expression. max-effective-tokens: "example-value" # AWF invocation cap (`apiProxy.maxRuns`) applied consistently across all engines. # Defaults to 500 when omitted. # (optional) # Accepted formats: # Format 1: Maximum number of LLM invocations allowed per run. max-runs: 1 # Format 2: Maximum number of LLM invocations allowed per run as a numeric string # or GitHub Actions expression. max-runs: "example-value" # MCP server definitions # (optional) mcp-servers: {} # Tools and MCP (Model Context Protocol) servers available to the AI engine for # GitHub API access, browser automation, file editing, and more # (optional) tools: # GitHub API tools for repository operations (issues, pull requests, content # management) # (optional) # Accepted formats: # Format 1: Empty GitHub tool configuration (enables all read-only GitHub API # functions) github: null # Format 2: Boolean to explicitly enable (true) or disable (false) the GitHub MCP # server. When set to false, the GitHub MCP server is not mounted. github: true # Format 3: Simple GitHub tool configuration (enables all GitHub API functions) github: "example-value" # Format 4: GitHub tools object configuration with restricted function access github: # List of allowed GitHub API functions (e.g., 'create_issue', 'update_issue', # 'add_comment') # (optional) allowed: [] # Array of strings # GitHub access mode. Prefer 'gh-proxy' for better performance (uses # pre-authenticated gh CLI prompt guidance). Legacy MCP transport values 'local' # and 'remote' are accepted for backward compatibility and use GitHub MCP server # prompt guidance. # (optional) mode: "gh-proxy" # GitHub MCP transport type: 'local' (Docker-based, default) or 'remote' (hosted # at api.githubcopilot.com) # (optional) type: "local" # Optional version specification for the GitHub MCP server (used with 'local' # type). Can be a string (e.g., 'v1.0.0', 'latest') or number (e.g., 20, 3.11). # Numeric values are automatically converted to strings at runtime. # (optional) version: null # Optional additional arguments to append to the generated MCP server command # (used with 'local' type) # (optional) args: [] # Array of strings # Enable read-only mode to restrict GitHub MCP server to read-only operations only # (optional) read-only: true # Enable lockdown mode to limit content surfaced from public repositories (only # items authored by users with push access). Default: false # (optional) lockdown: true # Controls DIFC proxy injection for pre-agent gh CLI steps when guard policies # (min-integrity) are configured. Default: true (enabled). Set to false to disable # proxy injection and rely solely on MCP gateway-level filtering. # (optional) integrity-proxy: true # Optional custom GitHub token (e.g., '${{ secrets.CUSTOM_PAT }}'). For 'remote' # type, defaults to GH_AW_GITHUB_TOKEN if not specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # GitHub MCP server toolset name(s) to enable. Accepts a single toolset name # (string) or an array of toolset names. # (optional) # Accepted formats: # Format 1: A single GitHub MCP server toolset name (shorthand for a one-element # array) toolsets: "all" # Format 2: Array of GitHub MCP server toolset names to enable specific groups of # GitHub API functionalities toolsets: [] # Array items: undefined # Volume mounts for the containerized GitHub MCP server (format: # 'host:container:mode' where mode is 'ro' for read-only or 'rw' for read-write). # Applies to local mode only. Example: '/data:/data:ro' # (optional) mounts: [] # Array of Mount specification in format 'host:container:mode' # Guard policy: repository access configuration. Restricts which repositories the # agent can access. Use 'all' to allow all repos, 'public' for public repositories # only, '${{ github.repository }}' for the current repository, or an array of # repository patterns (e.g., 'owner/repo', 'owner/*', 'owner/prefix*'). # (optional) # Accepted formats: # Format 1: Allow access to all repositories ('all'), only public repositories # ('public'), or the current repository ('${{ github.repository }}') allowed-repos: "all" # Format 2: Allow access to specific repositories using patterns (e.g., # 'owner/repo', 'owner/*', 'owner/prefix*') allowed-repos: [] # Array items: Repository pattern in the format 'owner/repo', 'owner/*' (all repos # under owner), or 'owner/prefix*' (repos with name prefix) # Guard policy: minimum required integrity level for repository access. Restricts # the agent to users with at least the specified permission level. # (optional) min-integrity: "none" # Guard policy: GitHub usernames whose content is unconditionally blocked. Items # from these users receive 'blocked' integrity (below 'none') and are always # denied, even when 'min-integrity' is 'none'. Cannot be overridden by # 'approval-labels'. Requires 'min-integrity' to be set. Accepts an array of # usernames, a comma-separated string, a newline-separated string, or a GitHub # Actions expression (e.g. '${{ vars.BLOCKED_USERS }}'). # (optional) # Accepted formats: # Format 1: Array of GitHub usernames to block blocked-users: [] # Array items: GitHub username to block # Format 2: Comma- or newline-separated list of usernames, or a GitHub Actions # expression resolving to such a list (e.g. '${{ vars.BLOCKED_USERS }}') blocked-users: "example-value" # Guard policy: GitHub usernames whose content is elevated to 'approved' integrity # regardless of author_association. Allows specific external contributors to # bypass 'min-integrity' checks without lowering the global policy. Precedence: # blocked-users > trusted-users > approval-labels > author_association. Requires # 'min-integrity' to be set. Accepts an array of usernames, a comma-separated # string, a newline-separated string, or a GitHub Actions expression (e.g. '${{ # vars.TRUSTED_USERS }}'). # (optional) # Accepted formats: # Format 1: Array of GitHub usernames to trust trusted-users: [] # Array items: GitHub username to elevate to approved integrity # Format 2: Comma- or newline-separated list of usernames, or a GitHub Actions # expression resolving to such a list (e.g. '${{ vars.TRUSTED_USERS }}') trusted-users: "example-value" # Guard policy: GitHub label names that promote a content item's effective # integrity to 'approved' when present. Enables human-review gates where a # maintainer labels an item to allow it through. Uses max(base, approved) so it # never lowers integrity. Does not override 'blocked-users'. Requires # 'min-integrity' to be set. Accepts an array of label names, a comma-separated # string, a newline-separated string, or a GitHub Actions expression (e.g. '${{ # vars.APPROVAL_LABELS }}'). # (optional) # Accepted formats: # Format 1: Array of GitHub label names approval-labels: [] # Array items: GitHub label name # Format 2: Comma- or newline-separated list of label names, or a GitHub Actions # expression resolving to such a list (e.g. '${{ vars.APPROVAL_LABELS }}') approval-labels: "example-value" # Guard policy: GitHub reaction types that promote a content item's integrity to # 'approved' when added by maintainers. Only enforced in proxy mode (DIFC/CLI # proxy); ignored in MCP gateway mode because reaction authors cannot be # identified. Optional; defaults to ["THUMBS_UP", "HEART"] when the # integrity-reactions feature flag is enabled. Requires 'min-integrity' to be set # and MCPG >= v0.2.18. # (optional) endorsement-reactions: [] # Array of GitHub ReactionContent enum value # Guard policy: GitHub reaction types that demote content integrity when added by # maintainers. Only enforced in proxy mode (DIFC/CLI proxy); ignored in MCP # gateway mode because reaction authors cannot be identified. Optional; defaults # to ["THUMBS_DOWN", "CONFUSED"] when the integrity-reactions feature flag is # enabled. Disapproval overrides endorsement (safe default). Requires # 'min-integrity' to be set and MCPG >= v0.2.18. # (optional) disapproval-reactions: [] # Array of GitHub ReactionContent enum value # Guard policy: integrity level assigned when a disapproval reaction is present. # Optional, defaults to 'none'. Requires the 'integrity-reactions' feature flag # and MCPG >= v0.2.18. # (optional) disapproval-integrity: "none" # Guard policy: minimum integrity level required for an endorser (reactor) to # promote content. Optional, defaults to 'approved'. Requires the # 'integrity-reactions' feature flag and MCPG >= v0.2.18. # (optional) endorser-min-integrity: "unapproved" # GitHub App configuration for token minting. When configured, a GitHub App # installation access token is minted at workflow start and used instead of the # default token. This token overrides any custom github-token setting and provides # fine-grained permissions matching the agent job requirements. # (optional) github-app: # Deprecated alias for client-id. GitHub App ID/client ID (e.g., '${{ vars.APP_ID # }}'). # (optional) app-id: "example-value" # GitHub App client ID (e.g., '${{ vars.APP_ID }}'). Required to mint a GitHub App # token. # (optional) client-id: "example-value" # GitHub App private key (e.g., '${{ secrets.APP_PRIVATE_KEY }}'). Required to # mint a GitHub App token. # (optional) private-key: "example-value" # If true, skip token minting when client-id/private-key resolve to empty strings # at runtime. Defaults to false. # (optional) ignore-if-missing: true # Optional owner of the GitHub App installation (defaults to current repository # owner if not specified) # (optional) owner: "example-value" # Optional list of repositories to grant access to (defaults to current repository # if not specified) # (optional) repositories: [] # Array of strings # Optional extra GitHub App-only permissions to merge into the minted token. Takes # effect for tools.github.github-app and safe-outputs.github-app; ignored in # on.github-app and the top-level github-app fallback. Use to add GitHub App-only # scopes (e.g. members, organization-administration) not expressible via standard # handler declarations. # (optional) permissions: # Permission level for repository administration (read/none; "write" is rejected # by the compiler). GitHub App-only permission for repository administration. # (optional) administration: "read" # Permission level for Codespaces (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) codespaces: "read" # Permission level for Codespaces lifecycle administration (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) codespaces-lifecycle-admin: "read" # Permission level for Codespaces metadata (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) codespaces-metadata: "read" # Permission level for user email addresses (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) email-addresses: "read" # Permission level for repository environments (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) environments: "read" # Permission level for git signing (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) git-signing: "read" # Permission level for organization members (read/none; "write" is rejected by the # compiler). Required for org team membership API calls. # (optional) members: "read" # Permission level for organization administration (read/none; "write" is rejected # by the compiler). GitHub App-only permission. # (optional) organization-administration: "read" # Permission level for organization announcement banners (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-announcement-banners: "read" # Permission level for organization Codespaces (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-codespaces: "read" # Permission level for organization Copilot (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-copilot: "read" # Permission level for organization custom org roles (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-org-roles: "read" # Permission level for organization custom properties (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-properties: "read" # Permission level for organization custom repository roles (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-repository-roles: "read" # Permission level for organization events (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-events: "read" # Permission level for organization webhooks (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-hooks: "read" # Permission level for organization members management (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-members: "read" # Permission level for organization packages (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-packages: "read" # Permission level for organization personal access token requests (read/none; # "write" is rejected by the compiler). GitHub App-only permission. # (optional) organization-personal-access-token-requests: "read" # Permission level for organization personal access tokens (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-personal-access-tokens: "read" # Permission level for organization plan (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-plan: "read" # Permission level for organization self-hosted runners (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-self-hosted-runners: "read" # Permission level for organization user blocking (read/none; "write" is rejected # by the compiler). GitHub App-only permission. # (optional) organization-user-blocking: "read" # Permission level for repository custom properties (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) repository-custom-properties: "read" # Permission level for repository webhooks (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) repository-hooks: "read" # Permission level for single file access (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) single-file: "read" # Permission level for team discussions (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) team-discussions: "read" # Permission level for Dependabot vulnerability alerts (read/none; "write" is # rejected by the compiler). Also available as a GITHUB_TOKEN scope. When used # with a GitHub App, forwarded as permission-vulnerability-alerts input. # (optional) vulnerability-alerts: "read" # Permission level for GitHub Actions workflow files (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) workflows: "read" # Bash shell command execution tool. Supports wildcards: '*' (all commands), # 'command *' (command with any args, e.g., 'date *', 'echo *'). Default safe # commands: echo, ls, pwd, cat, head, tail, grep, wc, sort, uniq, date. # (optional) # Accepted formats: # Format 1: Enable bash tool with all shell commands allowed (security # consideration: use restricted list in production) bash: null # Format 2: Enable bash tool - true allows all commands (equivalent to ['*']), # false disables the tool bash: true # Format 3: List of allowed commands and patterns. Wildcards: '*' allows all # commands, 'command *' allows command with any args (e.g., 'date *', 'echo *'). bash: [] # Array items: Command or pattern: 'echo' (exact match), 'echo *' (command with # any args) # Web content fetching tool for downloading web pages and API responses (subject # to network permissions) # (optional) # Accepted formats: # Format 1: Enable web fetch tool with default configuration web-fetch: null # Format 2: Web fetch tool configuration object web-fetch: {} # Web search tool for performing internet searches and retrieving search results # (subject to network permissions) # (optional) # Accepted formats: # Format 1: Enable web search tool with default configuration web-search: null # Format 2: Web search tool configuration object web-search: {} # File editing tool for reading, creating, and modifying files in the repository # (optional) # Accepted formats: # Format 1: Enable edit tool edit: null # Format 2: Edit tool configuration object edit: {} # Playwright browser automation tool for web scraping, testing, and UI # interactions in containerized browsers # (optional) # Accepted formats: # Format 1: Enable Playwright tool with default settings playwright: null # Format 2: Playwright tool configuration with custom version and arguments playwright: # Optional version pin. In CLI mode (recommended): the @playwright/cli npm package # version (e.g., '0.1.11'). In MCP mode (deprecated): the Playwright browser # Docker image version (e.g., 'v1.56.1'). Omit to use the default version. # (optional) version: null # Optional additional arguments to append to the generated MCP server command (MCP # mode only) # (optional) args: [] # Array of strings # Integration mode: 'cli' (recommended) installs @playwright/cli via npm for # token-efficient CLI invocations — use playwright-cli commands in bash and # localhost to reach local servers; 'mcp' (deprecated) runs a Docker-based MCP # server. # (optional) mode: "cli" # GitHub Agentic Workflows MCP server for workflow introspection and analysis. # Provides tools for checking status, compiling workflows, downloading logs, and # auditing runs. # (optional) # Accepted formats: # Format 1: Enable agentic-workflows tool with default settings agentic-workflows: true # Format 2: Enable agentic-workflows tool with default settings (same as true) agentic-workflows: null # Cache memory MCP configuration for persistent memory storage # (optional) # Accepted formats: # Format 1: Enable cache-memory with default settings cache-memory: true # Format 2: Enable cache-memory with default settings (same as true) cache-memory: null # Format 3: Cache-memory configuration object cache-memory: # Custom cache key for memory MCP data (restore keys are auto-generated by # splitting on '-') # (optional) key: "example-value" # Optional description for the cache that will be shown in the agent prompt # (optional) description: "Description of the workflow" # Number of days to retain uploaded artifacts (1-90 days, default: repository # setting) # (optional) retention-days: 1 # If true, only restore the cache without saving it back. Uses # actions/cache/restore instead of actions/cache. No artifact upload step will be # generated. # (optional) restore-only: true # Cache restore key scope: 'workflow' (default, only restores from same workflow) # or 'repo' (restores from any workflow in the repository). Use 'repo' with # caution as it allows cross-workflow cache sharing. # (optional) scope: "workflow" # List of allowed file extensions (e.g., [".json", ".txt"]). Default: [".json", # ".jsonl", ".txt", ".md", ".csv"] # (optional) allowed-extensions: [] # Array of strings # Format 4: Array of cache-memory configurations for multiple caches cache-memory: [] # Array items: object # Comment memory configuration for managed comment persistence # (optional) # Accepted formats: # Format 1: Configuration for persisting memory in a managed issue/PR comment. # Memory is materialized to files for agent editing and synchronized back after # execution. comment-memory: # Maximum number of comment_memory updates to process (default: 1). Supports # integer or GitHub Actions expression. # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target for comment memory: 'triggering' (default), '*' (current issue/PR), or # explicit issue/PR number # (optional) target: "example-value" # Target repository in format 'owner/repo' for cross-repository memory storage. # (optional) target-repo: "example-value" # Additional repositories in format 'owner/repo' allowed for comment memory # operations. # (optional) allowed-repos: [] # Array of strings # Default memory identifier when output items omit memory_id. # (optional) memory-id: "example-value" # Controls whether AI-generated footer is added to the managed comment. Defaults # to true. # (optional) footer: true # GitHub token to use for comment-memory operations. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable (true) or disable (false) comment-memory. comment-memory: true # Format 3: Explicitly disable comment-memory comment-memory: null # Timeout in seconds for tool/MCP server operations. Applies to all tools and MCP # servers if supported by the engine. Default: 60 seconds (for both Claude and # Codex). Supports GitHub Actions expressions for reusable workflow_call # workflows. # (optional) # Accepted formats: # Format 1: integer timeout: 1 # Format 2: GitHub Actions expression (e.g. '${{ inputs.tool-timeout }}') timeout: "example-value" # Timeout in seconds for MCP server startup. Applies to MCP server initialization # if supported by the engine. Default: 120 seconds. Supports GitHub Actions # expressions for reusable workflow_call workflows. # (optional) # Accepted formats: # Format 1: integer startup-timeout: 1 # Format 2: GitHub Actions expression (e.g. '${{ inputs.startup-timeout }}') startup-timeout: "example-value" # When true, each user-facing MCP server is mounted as a standalone CLI tool on # PATH. The agent can then call MCP servers via shell commands (e.g. 'github # issue_read --method get ...'). CLI-mounted servers remain in the MCP gateway # config so their containers can start, and are removed only from the agent's # final config during convert_gateway_config_*.sh processing. Default: false. # (optional) cli-proxy: true # Repo memory configuration for git-based persistent storage # (optional) # Accepted formats: # Format 1: Enable repo-memory with default settings repo-memory: true # Format 2: Enable repo-memory with default settings (same as true) repo-memory: null # Format 3: Repo-memory configuration object repo-memory: # Branch prefix for memory storage (default: 'memory'). Must be 4-32 characters, # alphanumeric with hyphens/underscores, and cannot be 'copilot'. Branch will be # named {branch-prefix}/{id} # (optional) branch-prefix: "example-value" # Target repository for memory storage (default: current repository). Format: # owner/repo # (optional) target-repo: "example-value" # Git branch name for memory storage (default: {branch-prefix}/default or # memory/default if branch-prefix not set) # (optional) branch-name: "example-value" # Glob patterns for files to include in repository memory. Supports wildcards # (e.g., '**/*.md', 'docs/**/*.json') to filter cached files. # (optional) # Accepted formats: # Format 1: Single file glob pattern for allowed files file-glob: "example-value" # Format 2: Array of file glob patterns for allowed files file-glob: [] # Array items: string # Maximum size per file in bytes (default: 102400 = 100KB) # (optional) max-file-size: 1 # Maximum file count per commit (default: 100) # (optional) max-file-count: 1 # Maximum total patch size in bytes (default: 10240 = 10KB, max: 1048576 = 1MB). # The total size of the git diff must not exceed this value. # (optional) max-patch-size: 1 # Optional description for the memory that will be shown in the agent prompt # (optional) description: "Description of the workflow" # Create orphaned branch if it doesn't exist (default: true) # (optional) create-orphan: true # Use the GitHub Wiki git repository instead of the regular repository. When # enabled, files are stored in and read from the wiki, and the agent will be # instructed to follow GitHub Wiki markdown syntax (default: false) # (optional) wiki: true # List of allowed file extensions (e.g., [".json", ".txt"]). Default: [".json", # ".jsonl", ".txt", ".md", ".csv"] # (optional) allowed-extensions: [] # Array of strings # Format 4: Array of repo-memory configurations for multiple memory locations repo-memory: [] # Array items: object # Cache configuration for workflow (uses actions/cache syntax) # (optional) # Accepted formats: # Format 1: Single cache configuration cache: # An explicit key for restoring and saving the cache key: "example-value" # File path or directory to cache for faster workflow execution. Can be a single # path or an array of paths to cache multiple locations. # Accepted formats: # Format 1: A single path to cache path: "example-value" # Format 2: Multiple paths to cache path: [] # Array items: string # Optional list of fallback cache key patterns to use if exact cache key is not # found. Enables partial cache restoration for better performance. # (optional) # Accepted formats: # Format 1: A single restore key restore-keys: "example-value" # Format 2: Multiple restore keys restore-keys: [] # Array items: string # The chunk size used to split up large files during upload, in bytes # (optional) upload-chunk-size: 1 # Fail the workflow if cache entry is not found # (optional) fail-on-cache-miss: true # If true, only checks if cache entry exists and skips download # (optional) lookup-only: true # Optional custom name for the cache step (overrides auto-generated name) # (optional) name: "My Workflow" # Format 2: Multiple cache configurations cache: [] # Array items: object # Safe output processing configuration that automatically creates GitHub issues, # comments, and pull requests from AI workflow output without requiring write # permissions in the main job # (optional) safe-outputs: # List of allowed domains for URL redaction in safe output handlers. Supports # ecosystem identifiers (e.g., "python", "node", "default-safe-outputs") like # network.allowed. These domains are unioned with the engine defaults and # network.allowed when computing the final allowed domain set. localhost and # github.com are always included. # (optional) allowed-domains: [] # Array of strings # List of allowed repositories for GitHub references (e.g., #123 or # owner/repo#456). Use 'repo' to allow current repository. References to other # repositories will be escaped with backticks. If not specified, all references # are allowed. # (optional) allowed-github-references: [] # Array of strings # Enable AI agents to create GitHub issues from workflow output. Supports title # prefixes, automatic labeling, assignees, and cross-repository creation. Does not # require 'issues: write' permission. # (optional) # Accepted formats: # Format 1: Configuration for automatically creating GitHub issues from AI # workflow output. The main job does not need 'issues: write' permission. create-issue: # Optional prefix to add to the beginning of the issue title (e.g., '[ai] ' or # '[analysis] ') # (optional) title-prefix: "example-value" # Optional list of labels to automatically attach to created issues (e.g., # ['automation', 'ai-generated']) # (optional) labels: [] # Array of strings # Optional list of allowed labels that can be used when creating issues. If # omitted, any labels are allowed (including creating new ones). When specified, # the agent can only use labels from this list. # (optional) allowed-labels: [] # Array of strings # Optional list of issue field names that can be modified by create-issue field # updates. If omitted or empty, any issue field may be set. Use ['*'] to # explicitly allow all. # (optional) allowed-fields: [] # Array of strings # GitHub usernames to assign the created issue to. Can be a single username string # or array of usernames. Use 'copilot' to assign to GitHub Copilot. # (optional) # Accepted formats: # Format 1: Single GitHub username to assign the created issue to (e.g., 'user1' # or 'copilot'). Use 'copilot' to assign to GitHub Copilot using the @copilot # special value. assignees: "example-value" # Format 2: List of GitHub usernames to assign the created issue to (e.g., # ['user1', 'user2', 'copilot']). Use 'copilot' to assign to GitHub Copilot using # the @copilot special value. assignees: [] # Array items: string # Maximum number of issues to create (default: 1) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Title-based deduplication for create-issue. Set to true for exact title # matching, or provide a non-negative integer to deduplicate by Levenshtein edit # distance (e.g., 1 allows one-character differences). Applies within-run and # against open/recently-closed repository issues. # (optional) # Accepted formats: # Format 1: boolean deduplicate-by-title: true # Format 2: integer deduplicate-by-title: 1 # Target repository in format 'owner/repo' for cross-repository issue creation. # Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' that issues can be # created in. When specified, the agent can use a 'repo' field in the output to # specify which repository to create the issue in. The target repository (current # or target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # Time until the issue expires and should be automatically closed. Supports # integer (days), relative time format, or false to disable expiration. Minimum # duration: 2 hours. When set, a maintenance workflow will be generated. # (optional) # Accepted formats: # Format 1: Number of days until expires expires: 1 # Format 2: Relative time (e.g., '2h', '7d', '2w', '1m', '1y'); minimum 2h for # hour values expires: "example-value" # Format 3: Set to false to explicitly disable expiration expires: false # If true, group issues as sub-issues under a parent issue. The workflow ID is # used as the group identifier. Parent issues are automatically created and # managed, with a maximum of 64 sub-issues per parent. # (optional) group: true # When true, automatically close older issues with the same workflow-id marker as # 'not planned' with a comment linking to the new issue. Searches for issues # containing the workflow-id marker in their body. Maximum 10 issues will be # closed. Only runs if issue creation succeeds. # (optional) close-older-issues: true # Optional explicit deduplication key for close-older matching. When set, a `` marker is embedded in the issue body and used as # the primary key for searching and filtering older issues instead of the # workflow-id markers. This gives deterministic isolation across caller workflows # and is stable across workflow renames. The value is normalized to identifier # style (lowercase alphanumeric, dashes, underscores). # (optional) close-older-key: "example-value" # When true, if an open issue with the same close-older-key (or workflow-id marker # when no key is set) was already created today (UTC), post the new content as a # comment on that existing issue instead of creating a new one. Groups multiple # same-day runs into a single issue. Works best when combined with # close-older-issues: true. # (optional) group-by-day: true # Controls whether AI-generated footer is added to the issue. When false, the # visible footer content is omitted but XML markers (workflow-id, tracker-id, # metadata) are still included for searchability. Defaults to true. # (optional) footer: true # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable issue creation with default configuration create-issue: null # Enable creation of GitHub Copilot coding agent tasks from workflow output. # Allows workflows to spawn new agent sessions for follow-up work. # (optional) # Accepted formats: # Format 1: DEPRECATED: Use 'create-agent-session' instead. Configuration for # creating GitHub Copilot coding agent sessions from agentic workflow output using # gh agent-task CLI. The main job does not need write permissions. create-agent-task: # Base branch for the agent session pull request. Defaults to the current branch # or repository default branch. # (optional) base: "example-value" # Maximum number of agent sessions to create (default: 1) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository agent session # creation. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' that agent sessions can # be created in. When specified, the agent can use a 'repo' field in the output to # specify which repository to create the agent session in. The target repository # (current or target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable agent session creation with default configuration create-agent-task: null # Enable creation of GitHub Copilot coding agent sessions from workflow output. # Allows workflows to start interactive agent conversations. # (optional) # Accepted formats: # Format 1: Configuration for creating GitHub Copilot coding agent sessions from # agentic workflow output using gh agent-task CLI. The main job does not need # write permissions. create-agent-session: # Base branch for the agent session pull request. Defaults to the current branch # or repository default branch. # (optional) base: "example-value" # Maximum number of agent sessions to create (default: 1) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository agent session # creation. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' that agent sessions can # be created in. When specified, the agent can use a 'repo' field in the output to # specify which repository to create the agent session in. The target repository # (current or target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable agent session creation with default configuration create-agent-session: null # Enable AI agents to add items to GitHub Projects, update custom fields, and # manage project structure. Use this for organizing work into projects with status # tracking, priority management, and custom metadata. # (optional) # Accepted formats: # Format 1: Configuration for managing GitHub Projects boards. Enable agents to # add issues and pull requests to projects, update custom field values (status, # priority, effort, dates), create project fields and views. By default it is # update-only: if the project does not exist, the job fails with instructions to # create it. To allow workflows to create missing projects, explicitly opt in via # agent output field create_if_missing=true. Requires a Personal Access Token # (PAT) or GitHub App token with Projects permissions (default GITHUB_TOKEN cannot # be used). Agent output includes: project (full URL or temporary project ID like # aw_XXXXXXXXXXXX or #aw_XXXXXXXXXXXX from create_project), content_type # (issue|pull_request|draft_issue), content_number, fields, create_if_missing. For # specialized operations, agent can also provide: operation # (create_fields|create_view), field_definitions (array of field configs when # operation=create_fields), view (view config object when operation=create_view). update-project: # Maximum number of project operations to perform (default: 10). Each operation # may add a project item, or update its fields. Supports integer or GitHub Actions # expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # Target project URL for update-project operations. This is required in the # configuration for documentation purposes. Agent messages MUST explicitly include # the project field in their output - the configured value is not used as a # fallback. Must be a valid GitHub Projects v2 URL. project: "example-value" # Default repository in format 'owner/repo' for cross-repository content # resolution. When specified, the agent can use 'target_repo' in agent output to # resolve issues or PRs from this repository. Wildcards ('*') are not allowed. # Supports GitHub Actions expression syntax (e.g., '${{ vars.TARGET_REPO }}'). # (optional) # Accepted formats: # Format 1: string target-repo: "example-value" # Format 2: GitHub Actions expression that resolves to owner/repo at runtime target-repo: "example-value" # List of additional repositories in format 'owner/repo' allowed for # cross-repository content resolution via 'target_repo'. The target-repo (or # current repo) is always implicitly allowed. Supports wildcard patterns (e.g., # 'org/*', '*/repo', '*') and GitHub Actions expression syntax for individual # entries. # (optional) allowed-repos: [] # Optional array of project views to create. Each view must have a name and # layout. Views are created during project setup. # (optional) views: [] # Array items: # The name of the view (e.g., 'Sprint Board', 'Roadmap') name: "My Workflow" # The layout type of the view layout: "table" # Optional filter query for the view (e.g., 'is:issue is:open', 'label:bug') # (optional) filter: "example-value" # Optional array of field IDs that should be visible in the view (table/board # only, not applicable to roadmap) # (optional) visible-fields: [] # Optional human description for the view. Not supported by the GitHub Views API # and may be ignored. # (optional) description: "Description of the workflow" # Optional array of project custom fields to create up-front. # (optional) field-definitions: [] # Array items: # The field name to create (e.g., 'status', 'priority') name: "My Workflow" # The GitHub Projects v2 custom field type data-type: "DATE" # Options for SINGLE_SELECT fields. GitHub does not support adding options later. # (optional) options: [] # Array of strings # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable project management with default configuration (max=10) update-project: null # Enable AI agents to create new GitHub Projects for organizing and tracking work # across issues and pull requests. # (optional) # Accepted formats: # Format 1: Configuration for creating new GitHub Projects boards. Enables agents # to create new project boards with optional custom fields, views, and an initial # item. Requires a Personal Access Token (PAT) or GitHub App token with Projects # write permission (default GITHUB_TOKEN cannot be used). Agent output includes: # title (project name), owner (org/user login, uses default if omitted), # owner_type ('org' or 'user'), optional item_url (issue to add as first item), # and optional field_definitions. Returns a temporary project ID for use in # subsequent update_project operations. create-project: # Maximum number of create operations to perform (default: 1). Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # GitHub token to use for this specific output type. Must have Projects write # permission. Overrides global github-token if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # Optional default target owner (organization or user login, e.g., 'myorg' or # 'username') for the new project. If specified, the agent can omit the owner # field in the tool call and this default will be used. The agent can still # override by providing an owner in the tool call. # (optional) target-owner: "example-value" # Optional prefix for auto-generated project titles (default: 'Project'). When the # agent doesn't provide a title, the project title is auto-generated as # ': ' or ' #' based on the # issue context. # (optional) title-prefix: "example-value" # Optional array of project views to create automatically after project creation. # Each view must have a name and layout. Views are created immediately after the # project is created. # (optional) views: [] # Array items: # The name of the view (e.g., 'Sprint Board', 'Roadmap') name: "My Workflow" # The layout type of the view layout: "table" # Optional filter query for the view (e.g., 'is:issue is:open', 'label:bug') # (optional) filter: "example-value" # Optional array of field IDs that should be visible in the view (table/board # only, not applicable to roadmap) # (optional) visible-fields: [] # Optional human description for the view. Not supported by the GitHub Views API # and may be ignored. # (optional) description: "Description of the workflow" # Optional array of project custom fields to create automatically after project # creation. # (optional) field-definitions: [] # Array items: # The field name to create (e.g., 'Priority', 'Classification') name: "My Workflow" # The GitHub Projects v2 custom field type data-type: "DATE" # Options for SINGLE_SELECT fields. GitHub does not support adding options later. # (optional) options: [] # Array of strings # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable project creation with default configuration (max=1) create-project: null # Enable AI agents to post status updates to GitHub Projects for progress tracking # and stakeholder communication. # (optional) # Accepted formats: # Format 1: Configuration for posting status updates to GitHub Projects. Status # updates provide stakeholder communication about project progress, health, and # timeline. Each update appears in the project's Updates tab and creates a # historical record. Requires a Personal Access Token (PAT) or GitHub App token # with Projects read & write permission (default GITHUB_TOKEN cannot be used). # Typically used by scheduled workflows or orchestrators to post regular progress # summaries with status indicators (on-track, at-risk, off-track, complete, # inactive), dates, and progress details. create-project-status-update: # Maximum number of status updates to create (default: 1). Typically 1 per # orchestrator run. Supports integer or GitHub Actions expression (e.g. '${{ # inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. Must have Projects: Read+Write permission. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # Target project URL for status update operations. This is required in the # configuration for documentation purposes. Agent messages MUST explicitly include # the project field in their output - the configured value is not used as a # fallback. Must be a valid GitHub Projects v2 URL. project: "example-value" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable project status updates with default configuration (max=1) create-project-status-update: null # Enable AI agents to create GitHub Discussions from workflow output. Supports # categorization, labeling, and automatic closure of older discussions. Does not # require 'discussions: write' permission. # (optional) # Accepted formats: # Format 1: Configuration for creating GitHub discussions from agentic workflow # output create-discussion: # Optional prefix for the discussion title # (optional) title-prefix: "example-value" # Optional discussion category. Can be a category ID (string or numeric value), # category name, or category slug/route. If not specified, uses the first # available category. Matched first against category IDs, then against category # names, then against category slugs. Numeric values are automatically converted # to strings at runtime. # (optional) category: null # Minimum required length of the discussion body content (before footer/metadata) # in characters. If a create_discussion message body is shorter than this value, # the safe-outputs job fails. # (optional) min-body-length: 1 # Optional list of labels to attach to created discussions. Also used for matching # when close-older-discussions is enabled - discussions must have ALL specified # labels (AND logic). # (optional) labels: [] # Array of strings # Optional list of allowed labels that can be used when creating discussions. If # omitted, any labels are allowed (including creating new ones). When specified, # the agent can only use labels from this list. # (optional) allowed-labels: [] # Array of strings # Maximum number of discussions to create (default: 1) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository discussion # creation. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' that discussions can be # created in. When specified, the agent can use a 'repo' field in the output to # specify which repository to create the discussion in. The target repository # (current or target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # When true, automatically close older discussions matching the same title prefix # or labels as 'outdated' with a comment linking to the new discussion. Requires # title-prefix or labels to be set. Maximum 10 discussions will be closed. Only # runs if discussion creation succeeds. When fallback-to-issue is enabled and # discussion creation fails, older issues will be closed instead. # (optional) close-older-discussions: true # Optional explicit deduplication key for close-older matching. When set, a `` marker is embedded in the discussion body and used # as the primary key for searching and filtering older discussions instead of the # workflow-id markers. This gives deterministic isolation across caller workflows # and is stable across workflow renames. The value is normalized to identifier # style (lowercase alphanumeric, dashes, underscores). # (optional) close-older-key: "example-value" # When true (default), fallback to creating an issue if discussion creation fails # due to permissions. The fallback issue will include a note indicating it was # intended to be a discussion. If close-older-discussions is enabled, the # close-older-issues logic will be applied to the fallback issue. # (optional) fallback-to-issue: true # Controls whether AI-generated footer is added to the discussion. When false, the # visible footer content is omitted but XML markers (workflow-id, tracker-id, # metadata) are still included for searchability. Defaults to true. # (optional) footer: true # Time until the discussion expires and should be automatically closed. Supports # integer (days), relative time format like '2h' (2 hours), '7d' (7 days), '2w' (2 # weeks), '1m' (1 month), '1y' (1 year), or false to disable expiration. Minimum # duration: 2 hours. When set, a maintenance workflow will be generated. Defaults # to 7 days if not specified. # (optional) # Accepted formats: # Format 1: Number of days until expires expires: 1 # Format 2: Relative time (e.g., '2h', '7d', '2w', '1m', '1y'); minimum 2h for # hour values expires: "example-value" # Format 3: Set to false to explicitly disable expiration expires: false # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable discussion creation with default configuration create-discussion: null # Enable AI agents to close GitHub Discussions based on workflow analysis or # conditions. # (optional) # Accepted formats: # Format 1: Configuration for closing GitHub discussions with comment and # resolution from agentic workflow output close-discussion: # Only close discussions that have all of these labels # (optional) required-labels: [] # Array of strings # Only close discussions with this title prefix # (optional) required-title-prefix: "example-value" # Only close discussions in this category # (optional) required-category: "example-value" # Target for closing: 'triggering' (default, current discussion), or '*' (any # discussion with discussion_number field) # (optional) target: "example-value" # Maximum number of discussions to close (default: 1) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository operations. Takes # precedence over trial target repo settings. # (optional) target-repo: "example-value" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable discussion closing with default configuration close-discussion: null # Enable AI agents to edit and update existing GitHub Discussion content, titles, # and metadata. # (optional) # Accepted formats: # Format 1: Configuration for updating GitHub discussions from agentic workflow # output update-discussion: # Target for updates: 'triggering' (default), '*' (any discussion), or explicit # discussion number # (optional) target: "example-value" # Allow updating discussion title - presence of key indicates field can be updated # (optional) title: null # Allow updating discussion body - presence of key indicates field can be updated # (optional) body: null # Allow updating discussion labels - presence of key indicates field can be # updated # (optional) labels: null # Optional list of allowed labels. If omitted, any labels are allowed (including # creating new ones). # (optional) allowed-labels: [] # Array of strings # Maximum number of discussions to update (default: 1) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository discussion # updates. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # Controls whether AI-generated footer is added when updating the discussion body. # When false, the visible footer content is omitted. Defaults to true. Only # applies when 'body' is enabled. # (optional) footer: true # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # Format 2: Enable discussion updating with default configuration update-discussion: null # Enable AI agents to close GitHub issues based on workflow analysis, resolution # detection, or automated triage. # (optional) # Accepted formats: # Format 1: Configuration for closing GitHub issues with comment from agentic # workflow output close-issue: # Only close issues that have all of these labels # (optional) required-labels: [] # Array of strings # Only close issues with this title prefix # (optional) required-title-prefix: "example-value" # Target for closing: 'triggering' (default, current issue), or '*' (any issue # with issue_number field) # (optional) target: "example-value" # Maximum number of issues to close (default: 1) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository operations. Takes # precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' that issues can be closed # in. When specified, the agent can use a 'repo' field in the output to specify # which repository to close the issue in. The target repository (current or # target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Reason for closing the issue (default: completed) # (optional) state-reason: "completed" # Format 2: Enable issue closing with default configuration close-issue: null # Enable AI agents to close pull requests based on workflow analysis or automated # review decisions. # (optional) # Accepted formats: # Format 1: Configuration for closing GitHub pull requests without merging, with # comment from agentic workflow output close-pull-request: # Only close pull requests that have any of these labels # (optional) required-labels: [] # Array of strings # Only close pull requests with this title prefix # (optional) required-title-prefix: "example-value" # Target for closing: 'triggering' (default, current PR), or '*' (any PR with # pull_request_number field) # (optional) target: "example-value" # Maximum number of pull requests to close (default: 1) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository operations. Takes # precedence over trial target repo settings. # (optional) target-repo: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable pull request closing with default configuration close-pull-request: null # Enable AI agents to mark draft pull requests as ready for review when criteria # are met. # (optional) # Accepted formats: # Format 1: Configuration for marking draft pull requests as ready for review, # with comment from agentic workflow output mark-pull-request-as-ready-for-review: # Only mark pull requests that have any of these labels # (optional) required-labels: [] # Array of strings # Only mark pull requests with this title prefix # (optional) required-title-prefix: "example-value" # Target for marking: 'triggering' (default, current PR), or '*' (any PR with # pull_request_number field) # (optional) target: "example-value" # Maximum number of pull requests to mark as ready (default: 1) Supports integer # or GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository operations. Takes # precedence over trial target repo settings. # (optional) target-repo: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable marking pull requests as ready for review with default # configuration mark-pull-request-as-ready-for-review: null # Enable AI agents to add comments to GitHub issues, pull requests, or # discussions. Supports templating, cross-repository commenting, and automatic # mentions. # (optional) # Accepted formats: # Format 1: Configuration for automatically creating GitHub issue or pull request # comments from AI workflow output. The main job does not need write permissions. add-comment: # Maximum number of comments to create (default: 1) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target for comments: 'triggering' (default), '*' (any issue), or explicit issue # number # (optional) target: "example-value" # Target repository in format 'owner/repo' for cross-repository comments. Takes # precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' that comments can be # created in. When specified, the agent can use a 'repo' field in the output to # specify which repository to create the comment in. The target repository # (current or target-repo) is always implicitly allowed. Accepts an array or a # GitHub Actions expression resolving to a comma-separated list (e.g. '${{ # inputs[\'allowed-repos\'] }}'). # (optional) # Accepted formats: # Format 1: Array of repository slugs in 'owner/repo' format allowed-repos: [] # Array items: string # Format 2: GitHub Actions expression resolving to a comma-separated list of # repository slugs (e.g. '${{ inputs[\'allowed-repos\'] }}') allowed-repos: "example-value" # When true, minimizes/hides all previous comments from the same agentic workflow # (identified by tracker-id) before creating the new comment. Supports literal # boolean or GitHub Actions expression (e.g. '${{ inputs.hide-older-comments }}'). # Default: false. # (optional) # Accepted formats: # Format 1: boolean hide-older-comments: true # Format 2: GitHub Actions expression that resolves to a boolean at runtime hide-older-comments: "example-value" # List of allowed reasons for hiding older comments when hide-older-comments is # enabled. Default: all reasons allowed (spam, abuse, off_topic, outdated, # resolved, low_quality). # (optional) allowed-reasons: [] # Array of strings # Controls whether the workflow requests discussions:write permission for # add-comment. Default: true (includes discussions:write). Set to false if your # GitHub App lacks Discussions permission to prevent 422 errors during token # generation. # (optional) discussions: true # Controls whether the workflow requests issues:write permission for add-comment. # Default: true (includes issues:write). Set to false to disable issue commenting # permissions. # (optional) issues: true # Controls whether the workflow requests pull-requests:write permission for # add-comment. Default: true (includes pull-requests:write). Set to false to # disable pull request commenting permissions. # (optional) pull-requests: true # Controls whether AI-generated footer is added to the comment. When false, the # visible footer content is omitted but XML markers (workflow-id, metadata) are # still included for searchability. Defaults to true. # (optional) footer: true # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # Conjunctive label constraint: ALL of these labels must be present on the # issue/PR for the operation to proceed. # (optional) required-labels: [] # Array of strings # Title prefix constraint: the issue/PR title must start with this prefix for the # operation to proceed. # (optional) required-title-prefix: "example-value" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable issue comment creation with default configuration add-comment: null # Enable AI agents to create GitHub pull requests from workflow-generated code # changes, patches, or analysis results. # (optional) # Accepted formats: # Format 1: Configuration for creating GitHub pull requests from agentic workflow # output. Supports creating multiple PRs in a single run when max > 1. create-pull-request: # Maximum number of pull requests to create (default: 1). Each PR requires # distinct changes on a separate branch. Supports integer or GitHub Actions # expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Optional prefix to prepend to the pull request branch name (e.g. "signed/"). # Applied before the agent-specified or auto-generated branch name. # (optional) branch-prefix: "example-value" # Optional prefix for the pull request title # (optional) title-prefix: "example-value" # Optional list of labels to attach to the pull request. Accepts an array of label # names or a GitHub Actions expression resolving to a comma-separated list (e.g. # '${{ inputs.labels }}'). # (optional) # Accepted formats: # Format 1: Array of label names labels: [] # Array items: string # Format 2: GitHub Actions expression resolving to a comma-separated list of label # names (e.g. '${{ inputs.labels }}') labels: "example-value" # Optional list of allowed labels that can be used when creating pull requests. If # omitted, any labels are allowed (including creating new ones). When specified, # the agent can only use labels from this list. # (optional) allowed-labels: [] # Array of strings # Optional reviewer(s) to assign to the pull request. Accepts either a single # string or an array of usernames. Use 'copilot' to request a code review from # GitHub Copilot. # (optional) # Accepted formats: # Format 1: Single reviewer username to assign to the pull request. Use 'copilot' # to request a code review from GitHub Copilot using the # copilot-pull-request-reviewer[bot]. reviewers: "example-value" # Format 2: List of reviewer usernames to assign to the pull request. Use # 'copilot' to request a code review from GitHub Copilot using the # copilot-pull-request-reviewer[bot]. reviewers: [] # Array items: string # Optional team reviewer(s) to assign to the pull request. Accepts either a single # string or an array of team slugs. # (optional) # Accepted formats: # Format 1: Single team slug to assign as a reviewer to the pull request. team-reviewers: "example-value" # Format 2: List of team slugs to assign as reviewers to the pull request. team-reviewers: [] # Array items: string # Optional assignee(s) for a fallback issue created when pull request creation # cannot proceed, including protected-files fallback-to-issue and pull request # creation or push failures. Accepts either a single string or an array of # usernames. # (optional) # Accepted formats: # Format 1: Single username to assign to a fallback issue created when pull # request creation cannot proceed, including protected-files fallback-to-issue and # pull request creation or push failures. assignees: "example-value" # Format 2: List of usernames to assign to a fallback issue created when pull # request creation cannot proceed, including protected-files fallback-to-issue and # pull request creation or push failures. assignees: [] # Array items: string # Optional labels to apply to fallback issues created when pull request creation # cannot proceed. When omitted, fallback issues reuse pull request labels. A # managed label is always added for triage. # (optional) fallback-labels: [] # Array of strings # Whether to create pull request as draft (defaults to true). Accepts a boolean or # a GitHub Actions expression. # (optional) draft: null # Behavior when no changes to push: 'warn' (default - log warning but succeed), # 'error' (fail the action), or 'ignore' (silent success) # (optional) if-no-changes: "warn" # When true, allows creating a pull request without any initial changes or git # patch. This is useful for preparing a feature branch that an agent can push # changes to later. The branch will be created from the base branch without # applying any patch. Defaults to false. # (optional) allow-empty: true # Target repository in format 'owner/repo' for cross-repository pull request # creation. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' that pull requests can be # created in. When specified, the agent can use a 'repo' field in the output to # specify which repository to create the pull request in. The target repository # (current or target-repo) is always implicitly allowed. Accepts an array or a # GitHub Actions expression resolving to a comma-separated list (e.g. '${{ # inputs[\'allowed-repos\'] }}'). # (optional) # Accepted formats: # Format 1: Array of repository slugs in 'owner/repo' format allowed-repos: [] # Array items: string # Format 2: GitHub Actions expression resolving to a comma-separated list of # repository slugs (e.g. '${{ inputs[\'allowed-repos\'] }}') allowed-repos: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # Time until the pull request expires and should be automatically closed (only for # same-repo PRs without target-repo). Supports integer (days) or relative time # format. Minimum duration: 2 hours. # (optional) # Accepted formats: # Format 1: Number of days until expires expires: 1 # Format 2: Relative time (e.g., '2h', '7d', '2w', '1m', '1y'); minimum 2h for # hour values expires: "example-value" # Enable auto-merge for the pull request. When enabled, the PR will be # automatically merged once all required checks pass and required approvals are # met. Defaults to false. # (optional) auto-merge: true # Base branch for the pull request. Defaults to the workflow's branch # (github.ref_name) if not specified. Useful for cross-repository PRs targeting # non-default branches (e.g., 'vnext', 'release/v1.0'). # (optional) base-branch: "example-value" # Optional list of allowed source branch patterns (glob syntax, e.g. 'feature/*', # 'release/*'). When configured, the effective create_pull_request branch must # match one of these patterns. Accepts an array or a GitHub Actions expression # resolving to a comma-separated list (e.g. '${{ inputs[\'allowed-branches\'] # }}'). # (optional) # Accepted formats: # Format 1: Array of source branch patterns (glob syntax supported) allowed-branches: [] # Array items: string # Format 2: GitHub Actions expression resolving to a comma-separated list of # source branch patterns (e.g. '${{ inputs[\'allowed-branches\'] }}') allowed-branches: "example-value" # Optional list of allowed base branch patterns (glob syntax, e.g. 'main', # 'release/*'). When configured, the agent may provide a `base` field in # create_pull_request output to override base-branch for a single run, but only if # it matches one of these patterns. Accepts an array or a GitHub Actions # expression resolving to a comma-separated list (e.g. '${{ # inputs[\'allowed-base-branches\'] }}'). # (optional) # Accepted formats: # Format 1: Array of base branch patterns (glob syntax supported) allowed-base-branches: [] # Array items: string # Format 2: GitHub Actions expression resolving to a comma-separated list of base # branch patterns (e.g. '${{ inputs[\'allowed-base-branches\'] }}') allowed-base-branches: "example-value" # Maximum allowed size for git patches in kilobytes (KB) for create-pull-request # only. Overrides safe-outputs max-patch-size for this output type. Defaults to # 1024 KB (1 MB) when unset. # (optional) max-patch-size: 1 # Maximum allowed number of unique files in a create-pull-request patch. Overrides # safe-outputs max-patch-files for this output type. Defaults to 100 when unset. # (optional) max-patch-files: 1 # Controls whether AI-generated footer is added to the pull request. When false, # the visible footer content is omitted but XML markers (workflow-id, tracker-id, # metadata) are still included for searchability. Defaults to true. # (optional) footer: true # Controls the fallback behavior when pull request creation fails. When true # (default), an issue is created as a fallback with the patch content. When false, # no issue is created and the workflow fails with an error. Setting to false also # removes the issues:write permission requirement. # (optional) fallback-as-issue: true # When true (default), automatically appends a closing keyword ("Fixes #N") to the # PR description when the workflow is triggered from an issue and no closing # keyword is already present. This causes GitHub to auto-close the triggering # issue when the PR is merged. Set to false to prevent this behavior, e.g., for # partial-work PRs or multi-PR workflows. Accepts a boolean or a GitHub Actions # expression. # (optional) auto-close-issue: null # Token used to push an empty commit after PR creation to trigger CI events. Works # around the GITHUB_TOKEN limitation where pushes don't trigger workflow runs. # Defaults to the magic secret GH_AW_CI_TRIGGER_TOKEN if set in the repository. # Use a secret expression (e.g. '${{ secrets.CI_TOKEN }}') for a custom token, or # 'app' for GitHub App auth. # (optional) github-token-for-extra-empty-commit: "example-value" # Controls protected-file protection. String form: blocked (default), allowed, or # fallback-to-issue — or a GitHub Actions expression for reusable workflows. # Object form: { policy, exclude } to customise the protected-file set. # (optional) # Accepted formats: # Format 1: Controls protected-file protection. blocked (default): hard-block any # patch that modifies package manifests (e.g. package.json, go.mod), engine # instruction files (e.g. AGENTS.md, CLAUDE.md) or .github/ files. allowed: allow # all changes. fallback-to-issue: push the branch but create a review issue # instead of a PR, so a human can review the manifest changes before merging. protected-files: "blocked" # Format 2: GitHub Actions expression that resolves to 'blocked', 'allowed', or # 'fallback-to-issue' at runtime. Use in reusable workflow_call workflows to # parameterise the policy per caller. protected-files: "example-value" # Format 3: Object form for granular control over the protected-file set. Use the # exclude list to remove specific files from the default protection while keeping # the rest. protected-files: # (optional) # Accepted formats: # Format 1: Protection policy. blocked (default): hard-block any patch that # modifies protected files. allowed: allow all changes. fallback-to-issue: push # the branch but create a review issue instead of a PR. policy: "blocked" # Format 2: GitHub Actions expression that resolves to 'blocked', 'allowed', or # 'fallback-to-issue' at runtime. policy: "example-value" # List of filenames or path prefixes to remove from the default protected-file # set. Items are matched by basename (e.g. "AGENTS.md") or path prefix (e.g. # ".agents/"). Use this to allow the agent to modify specific files that are # otherwise blocked by default. # (optional) exclude: [] # Array of strings # Exclusive allowlist of glob patterns. When set, every file in the patch must # match at least one pattern — files outside the list are always refused, # including normal source files. This is a restriction, not an exception: setting # allowed-files: [".github/workflows/*"] blocks all other files. To allow multiple # sets of files, list all patterns explicitly. Acts independently of the # protected-files policy; both checks must pass. To modify a protected file, it # must both match allowed-files and be permitted by protected-files (e.g. # protected-files: allowed). Supports * (any characters except /) and ** (any # characters including /). # (optional) allowed-files: [] # Array of strings # When true, the random salt suffix is not appended to the agent-specified branch # name. Invalid characters are still replaced for security, and casing is always # preserved regardless of this setting. Useful when the target repository enforces # branch naming conventions (e.g. Jira keys in uppercase such as # 'bugfix/BR-329-red'). Defaults to false. # (optional) preserve-branch-name: true # When true (and preserve-branch-name is true), allows the handler to force-delete # an existing remote branch ref and recreate it from the agent's local HEAD. When # false (default), if the agent-specified branch already exists on the remote with # preserve-branch-name enabled, the handler falls back (e.g. opens an issue) # rather than overwriting the remote ref. Useful for long-lived reusable branches # whose previous PR was merged. # (optional) recreate-ref: true # List of glob patterns for files to exclude from the patch. Each pattern is # passed to `git format-patch` as a `:(exclude)` magic pathspec, so # matching files are stripped by git at generation time and will not appear in the # commit. Excluded files are also not subject to `allowed-files` or # `protected-files` checks. Supports * (any characters except /) and ** (any # characters including /). # (optional) excluded-files: [] # Array of strings # Transport format for packaging changes. "bundle" (default) uses git bundle. "am" # uses git format-patch/git am. Accepts a GitHub Actions expression for reusable # workflows. # (optional) # Accepted formats: # Format 1: Transport format for packaging changes. "bundle" (default) uses git # bundle, which preserves merge commit topology, per-commit authorship, and # merge-resolution-only content. "am" uses git format-patch/git am. patch-format: "am" # Format 2: GitHub Actions expression that resolves to 'am' or 'bundle' at # runtime. Use in reusable workflow_call workflows to parameterise the transport # format per caller. patch-format: "example-value" # When true (default), signed commits are required and pushes use GitHub's # createCommitOnBranch GraphQL mutation so GitHub signs them. Set to false to use # git push directly for repositories that do not require signed commits; this also # allows pushing merge commits that GraphQL cannot represent. # (optional) signed-commits: true # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # When true, adds workflows: write to the GitHub App token permissions. Required # when allowed-files targets .github/workflows/ paths. Requires # safe-outputs.github-app to be configured because the workflows permission is a # GitHub App-only permission and cannot be granted via GITHUB_TOKEN. # (optional) allow-workflows: true # Format 2: Enable pull request creation with default configuration create-pull-request: null # Enable AI agents to add review comments to specific lines in pull request diffs # during code review workflows. # (optional) # Accepted formats: # Format 1: Configuration for creating GitHub pull request review comments from # agentic workflow output create-pull-request-review-comment: # Maximum number of review comments to create (default: 10) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Side of the diff for comments: 'LEFT' or 'RIGHT' (default: 'RIGHT') # (optional) side: "LEFT" # Target for review comments: 'triggering' (default, only on triggering PR), '*' # (any PR, requires pull_request_number in agent output), or explicit PR number # (optional) target: "example-value" # Target repository in format 'owner/repo' for cross-repository PR review # comments. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' that PR review comments # can be created in. When specified, the agent can use a 'repo' field in the # output to specify which repository to create the review comment in. The target # repository (current or target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Format 2: Enable PR review comment creation with default configuration create-pull-request-review-comment: null # Enable AI agents to submit consolidated pull request reviews with a status # decision. Works with create-pull-request-review-comment to batch inline comments # into a single review. # (optional) # Accepted formats: # Format 1: Configuration for submitting a consolidated PR review with a status # decision (APPROVE, REQUEST_CHANGES, COMMENT). All # create-pull-request-review-comment outputs are collected and submitted as part # of this review. submit-pull-request-review: # Maximum number of reviews to submit (default: 1) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Controls when AI-generated footer is added to the review body. Accepts boolean # (true/false) or string ('always', 'none', 'if-body'). The 'if-body' mode is # useful for clean approval reviews without body text. Defaults to 'always'. # (optional) # Accepted formats: # Format 1: Controls whether AI-generated footer is added to the review body. true # maps to 'always', false maps to 'none'. footer: true # Format 2: Controls when AI-generated footer is added to the review body: # 'always' (default), 'none' (never), or 'if-body' (only when review has body # text). footer: "always" # Target PR for the review: 'triggering' (default, current PR), '*' (any PR, # requires pull_request_number in agent output), or explicit PR number (e.g. ${{ # github.event.inputs.pr_number }}). Required when workflow is not triggered by a # pull request (e.g. workflow_dispatch). # (optional) target: "example-value" # Target repository in format 'owner/repo' for cross-repository PR review # submission. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' that PR reviews can be # submitted in. When specified, the agent can use a 'repo' field in the output to # specify which repository to submit the review in. The target repository (current # or target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # Optional list of allowed review event types. If omitted, all event types # (APPROVE, COMMENT, REQUEST_CHANGES) are allowed. Use this to restrict the agent # to specific event types, e.g. [COMMENT, REQUEST_CHANGES] to prevent approvals. # (optional) allowed-events: [] # Array of strings # When true, after posting a replacement review this workflow dismisses older # REQUEST_CHANGES reviews previously posted by the same workflow on the same pull # request. This is best-effort and requires workflow markers in prior review # bodies. # (optional) supersede-older-reviews: true # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Format 2: Enable PR review submission with default configuration submit-pull-request-review: null # Enable AI agents to reply to existing review comments on pull requests. # (optional) # Accepted formats: # Format 1: Configuration for replying to existing pull request review comments reply-to-pull-request-review-comment: # Maximum number of replies to create (default: 10) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target for replies: 'triggering' (default), '*' (any PR), or explicit PR number # (optional) target: "example-value" # Target repository in format 'owner/repo' for cross-repository operations # (optional) target-repo: "example-value" # List of additional repositories that replies can target # (optional) allowed-repos: [] # Array of strings # Controls whether AI-generated footer is added to the reply body. When false, the # footer is omitted. Defaults to true. # (optional) footer: true # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Format 2: Enable with default configuration reply-to-pull-request-review-comment: null # Enable AI agents to resolve review threads on the triggering pull request after # addressing feedback. # (optional) # Accepted formats: # Format 1: Configuration for resolving review threads on pull requests. # Resolution is scoped to the triggering PR only — threads on other PRs cannot be # resolved. resolve-pull-request-review-thread: # Maximum number of review threads to resolve (default: 10) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Format 2: Enable review thread resolution with default configuration resolve-pull-request-review-thread: null # Enable AI agents to create GitHub Advanced Security code scanning alerts for # detected vulnerabilities or security issues. # (optional) # Accepted formats: # Format 1: Configuration for creating repository security advisories (SARIF # format) from agentic workflow output create-code-scanning-alert: # Maximum number of security findings to include (default: unlimited) Supports # integer or GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Driver name for SARIF tool.driver.name field (default: 'GitHub Agentic Workflows # Security Scanner') # (optional) driver: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # Target repository in format 'owner/repo' for cross-repository code scanning # alert creation. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' that code scanning alerts # can be created in. When specified, the agent can use a 'repo' field in the # output to specify which repository to create the alert in. The target repository # (current or target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable code scanning alert creation with default configuration # (unlimited findings) create-code-scanning-alert: null # Enable AI agents to create autofixes for code scanning alerts using the GitHub # REST API. # (optional) # Accepted formats: # Format 1: Configuration for creating autofixes for code scanning alerts autofix-code-scanning-alert: # Maximum number of autofixes to create (default: 10) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable code scanning autofix creation with default configuration (max: # 10) autofix-code-scanning-alert: null # Enable AI agents to add labels to GitHub issues or pull requests based on # workflow analysis or classification. # (optional) # Accepted formats: # Format 1: Null configuration allows any labels. Labels will be created if they # don't already exist in the repository. add-labels: null # Format 2: Configuration for adding labels to issues/PRs from agentic workflow # output. Labels will be created if they don't already exist in the repository. add-labels: # Optional list of allowed labels that can be added. Labels will be created if # they don't already exist in the repository. If omitted, any labels are allowed # (including creating new ones). # (optional) allowed: [] # Array of strings # Optional list of blocked label patterns (supports glob patterns like '~*', # '*[bot]'). Labels matching these patterns will be rejected. Applied before # allowed list filtering for security. # (optional) blocked: [] # Array of strings # Optional maximum number of labels to add (default: 3) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target for labels: 'triggering' (default), '*' (any issue/PR), or explicit # issue/PR number # (optional) target: "example-value" # Target repository in format 'owner/repo' for cross-repository label addition. # Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # List of additional repositories in format 'owner/repo' that labels can be added # to. When specified, the agent can use a 'repo' field in the output to specify # which repository to add labels to. The target repository (current or # target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # Conjunctive label constraint: ALL of these labels must be present on the # issue/PR for the operation to proceed. # (optional) required-labels: [] # Array of strings # Title prefix constraint: the issue/PR title must start with this prefix for the # operation to proceed. # (optional) required-title-prefix: "example-value" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Enable AI agents to remove labels from GitHub issues or pull requests. # (optional) # Accepted formats: # Format 1: Null configuration allows any labels to be removed. remove-labels: null # Format 2: Configuration for removing labels from issues/PRs from agentic # workflow output. remove-labels: # Optional list of allowed labels that can be removed. If omitted, any labels can # be removed. # (optional) allowed: [] # Array of strings # Optional list of blocked label patterns (supports glob patterns like '~*', # '*[bot]'). Labels matching these patterns will be rejected. Applied before # allowed list filtering for security. # (optional) blocked: [] # Array of strings # Optional maximum number of labels to remove (default: 3) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target for labels: 'triggering' (default), '*' (any issue/PR), or explicit # issue/PR number # (optional) target: "example-value" # Target repository in format 'owner/repo' for cross-repository label removal. # Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # List of additional repositories in format 'owner/repo' that labels can be # removed from. When specified, the agent can use a 'repo' field in the output to # specify which repository to remove labels from. The target repository (current # or target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # Conjunctive label constraint: ALL of these labels must be present on the # issue/PR for the operation to proceed. # (optional) required-labels: [] # Array of strings # Title prefix constraint: the issue/PR title must start with this prefix for the # operation to proceed. # (optional) required-title-prefix: "example-value" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Enable AI agents to request reviews from users or teams on pull requests based # on code changes or expertise matching. # (optional) # Accepted formats: # Format 1: Null configuration allows any reviewers add-reviewer: null # Format 2: Configuration for adding reviewers to pull requests from agentic # workflow output add-reviewer: # Optional list of allowed reviewer usernames. If omitted, any reviewers are # allowed. # (optional) allowed-reviewers: [] # Array of strings # Optional allowed team reviewer or list of allowed team reviewers. If omitted, # any team reviewers are allowed. # (optional) # Accepted formats: # Format 1: string allowed-team-reviewers: "example-value" # Format 2: array allowed-team-reviewers: [] # Array items: string # Optional maximum number of reviewers to add (default: 3) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target for reviewers: 'triggering' (default), '*' (any PR), or explicit PR # number # (optional) target: "example-value" # Target repository in format 'owner/repo' for cross-repository reviewer addition. # Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Enable AI agents to assign GitHub milestones to issues or pull requests based on # workflow analysis or project planning. # (optional) # Accepted formats: # Format 1: Null configuration allows assigning any milestones assign-milestone: null # Format 2: Configuration for assigning issues to milestones from agentic workflow # output assign-milestone: # Optional list of allowed milestone titles that can be assigned. If omitted, any # milestones are allowed. # (optional) allowed: [] # Array of strings # Optional maximum number of milestone assignments (default: 1) Supports integer # or GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository milestone # assignment. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Enable AI agents to assign issues or pull requests to GitHub Copilot (@copilot) # for automated handling. # (optional) # Accepted formats: # Format 1: Null configuration uses default agent (copilot) assign-to-agent: null # Format 2: Configuration for assigning GitHub Copilot coding agent to issues from # agentic workflow output assign-to-agent: # Default agent name to assign (default: 'copilot') # (optional) name: "My Workflow" # Default AI model to use for the agent (e.g., 'auto', 'claude-sonnet-4.5', # 'claude-opus-4.5', 'claude-opus-4.6', 'gpt-5.1-codex-max', 'gpt-5.2-codex'). # Defaults to 'auto' if not specified. # (optional) model: "example-value" # Default custom agent ID to use when assigning custom agents. This is used for # specialized agent configurations beyond the standard Copilot agent. # (optional) custom-agent: "example-value" # Default custom instructions to provide to the agent. These instructions will # guide the agent's behavior when working on the task. # (optional) custom-instructions: "example-value" # Optional list of allowed agent names. If specified, only these agents can be # assigned. When configured, existing agent assignees not in the list are removed # while regular user assignees are preserved. # (optional) allowed: [] # Array of strings # Optional maximum number of agent assignments (default: 1) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target issue/PR to assign agents to. Use 'triggering' (default) for the # triggering issue/PR, '*' to require explicit issue_number/pull_number, or a # specific issue/PR number. With 'triggering', auto-resolves from # github.event.issue.number or github.event.pull_request.number. # (optional) target: null # Target repository in format 'owner/repo' for cross-repository agent assignment. # Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # Target repository where the pull request should be created, in format # 'owner/repo'. If omitted, the PR will be created in the same repository as the # issue (specified by target-repo or the workflow's repository). This allows # issues and code to live in different repositories. # (optional) pull-request-repo: "example-value" # List of additional repositories that pull requests can be created in beyond # pull-request-repo. Each entry should be in 'owner/repo' format. The repository # specified by pull-request-repo is automatically allowed without needing to be # listed here. # (optional) allowed-pull-request-repos: [] # Array of strings # If true, the workflow continues gracefully when agent assignment fails (e.g., # due to missing token or insufficient permissions), logging a warning instead of # failing. Default is false. Useful for workflows that should not fail when agent # assignment is optional. # (optional) ignore-if-error: true # Base branch for pull request creation in the target repository. Defaults to the # target repo's default branch. Only relevant when pull-request-repo is # configured. # (optional) base-branch: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Enable AI agents to assign issues or pull requests to specific GitHub users # based on workflow logic or expertise matching. # (optional) # Accepted formats: # Format 1: Enable user assignment with default configuration assign-to-user: null # Format 2: Configuration for assigning users to issues from agentic workflow # output assign-to-user: # Optional list of allowed usernames. If specified, only these users can be # assigned. # (optional) allowed: [] # Array of strings # Optional list of blocked usernames or patterns (e.g., 'copilot', '*[bot]'). # Users matching these patterns cannot be assigned. Supports exact matches and # glob patterns. # (optional) blocked: [] # Array of strings # Optional maximum number of user assignments (default: 1) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target issue to assign users to. Use 'triggering' (default) for the triggering # issue, '*' to allow any issue, or a specific issue number. # (optional) target: null # Target repository in format 'owner/repo' for cross-repository user assignment. # Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # If true, unassign all current assignees before assigning new ones. Useful for # reassigning issues from one user to another (default: false). # (optional) unassign-first: true # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # List of allowed repositories in format 'owner/repo' for cross-repository user # assignment operations. Use with 'repo' field in tool calls. # (optional) allowed-repos: [] # Array of strings # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Enable AI agents to unassign users from issues or pull requests. Useful for # reassigning work or removing users from issues. # (optional) # Accepted formats: # Format 1: Enable user unassignment with default configuration unassign-from-user: null # Format 2: Configuration for removing assignees from issues in agentic workflow # output unassign-from-user: # Optional list of allowed usernames. If specified, only these users can be # unassigned. # (optional) allowed: [] # Array of strings # Optional list of blocked usernames or patterns (e.g., 'copilot', '*[bot]'). # Users matching these patterns cannot be unassigned. Supports exact matches and # glob patterns. # (optional) blocked: [] # Array of strings # Optional maximum number of unassignment operations (default: 1) Supports integer # or GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target issue to unassign users from. Use 'triggering' (default) for the # triggering issue, '*' to allow any issue, or a specific issue number. # (optional) target: null # Target repository in format 'owner/repo' for cross-repository user unassignment. # Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of allowed repositories in format 'owner/repo' for cross-repository # unassignment operations. Use with 'repo' field in tool calls. # (optional) allowed-repos: [] # Array of strings # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Enable AI agents to create hierarchical relationships between issues using # GitHub's sub-issue (tasklist) feature. # (optional) # Accepted formats: # Format 1: Enable sub-issue linking with default configuration link-sub-issue: null # Format 2: Configuration for linking issues as sub-issues from agentic workflow # output link-sub-issue: # Maximum number of sub-issue links to create (default: 5) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Optional list of labels that parent issues must have to be eligible for linking # (optional) parent-required-labels: [] # Array of strings # Optional title prefix that parent issues must have to be eligible for linking # (optional) parent-title-prefix: "example-value" # Optional list of labels that sub-issues must have to be eligible for linking # (optional) sub-required-labels: [] # Array of strings # Optional title prefix that sub-issues must have to be eligible for linking # (optional) sub-title-prefix: "example-value" # Target repository in format 'owner/repo' for cross-repository sub-issue linking. # Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Enable AI agents to edit and update existing GitHub issue content, titles, # labels, assignees, and metadata. # (optional) # Accepted formats: # Format 1: Configuration for updating GitHub issues from agentic workflow output update-issue: # Allow updating issue status (open/closed) - presence of key indicates field can # be updated # (optional) status: null # Target for updates: 'triggering' (default), '*' (any issue), or explicit issue # number # (optional) target: "example-value" # Allow updating issue title - presence of key indicates field can be updated # (optional) title: null # Allow updating issue body. Set to true to enable body updates, false to disable. # For backward compatibility, null (body:) also enables body updates. # (optional) body: null # Controls whether AI-generated footer is added when updating the issue body. When # false, the visible footer content is omitted but XML markers are still included. # Defaults to true. Only applies when 'body' is enabled. # (optional) footer: true # Maximum number of issues to update (default: 1) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository issue updates. # Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # Required prefix for issue title. Only issues with this title prefix can be # updated. # (optional) title-prefix: "example-value" # List of additional repositories in format 'owner/repo' that issues can be # updated in. When specified, the agent can use a 'repo' field in the output to # specify which repository to update the issue in. The target repository (current # or target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Format 2: Enable issue updating with default configuration update-issue: null # Enable AI agents to edit and update existing pull request content, titles, # labels, reviewers, and metadata. # (optional) # Accepted formats: # Format 1: Configuration for updating GitHub pull requests from agentic workflow # output. Both title and body updates are enabled by default. update-pull-request: # Target for updates: 'triggering' (default), '*' (any PR), or explicit PR number # (optional) target: "example-value" # Allow updating pull request title - defaults to true, set to false to disable # (optional) title: true # Allow updating pull request body - defaults to true, set to false to disable # (optional) body: true # When true, update the pull request branch with the latest base branch changes # before applying other updates. Defaults to false. # (optional) update-branch: true # Default operation for body updates: 'append' (add to end), 'prepend' (add to # start), or 'replace' (overwrite completely). Defaults to 'replace' if not # specified. # (optional) operation: "append" # Controls whether AI-generated footer is added when updating the pull request # body. When false, the visible footer content is omitted but XML markers are # still included. Defaults to true. Only applies when 'body' is enabled. # (optional) footer: true # Maximum number of pull requests to update (default: 1) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository pull request # updates. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Format 2: Enable pull request updating with default configuration (title and # body updates enabled) update-pull-request: null # Enable AI agents to merge pull requests under configured policy gates. # (optional) # Accepted formats: # Format 1: Enable pull request merge with default policy configuration merge-pull-request: null # Format 2: Configuration for controlled pull request merges. The merge is blocked # unless all configured gates pass. merge-pull-request: # Maximum number of pull request merges to perform per run (default: 1). Supports # integer or GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # List of labels that must ALL be present on the pull request before merge is # allowed. # (optional) required-labels: [] # Array of strings # Glob patterns for allowed source branch names (pull request head ref). The PR's # branch must match at least one pattern. # (optional) allowed-branches: [] # Array of strings # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, evaluate merge gates and emit preview results without executing the # merge API call. # (optional) staged: true # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Enable AI agents to push commits directly to pull request branches for automated # fixes or improvements. # (optional) # Accepted formats: # Format 1: Use default configuration (branch: 'triggering', if-no-changes: # 'warn') push-to-pull-request-branch: null # Format 2: Configuration for pushing changes to a specific branch from agentic # workflow output. Supports pushing to multiple PRs in a single run when max > 1. push-to-pull-request-branch: # Maximum number of push operations to perform (default: 1). Each push targets a # different pull request branch. Supports integer or GitHub Actions expression # (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # The branch to push changes to (defaults to 'triggering') # (optional) branch: "example-value" # Target for push operations: 'triggering' (default), '*' (any pull request), or # explicit pull request number # (optional) target: "example-value" # Required prefix for pull request title. Only pull requests with this prefix will # be accepted. # (optional) required-title-prefix: "example-value" # Required labels for pull request validation. Only pull requests with all these # labels will be accepted. Accepts an array of label names or a GitHub Actions # expression resolving to a comma-separated list of labels (e.g. '${{ # inputs[\'required-labels\'] }}'). # (optional) # Accepted formats: # Format 1: Array of label names required-labels: [] # Array items: string # Format 2: GitHub Actions expression resolving to a comma-separated list of label # names (e.g. '${{ inputs[\'required-labels\'] }}') required-labels: "example-value" # Behavior when no changes to push: 'warn' (default - log warning but succeed), # 'error' (fail the action), or 'ignore' (silent success) # (optional) if-no-changes: "warn" # When true, treat deleted/missing pull request branch errors as a skipped push # instead of a hard failure. Useful when the PR branch may be deleted before safe # outputs run. # (optional) ignore-missing-branch-failure: true # Optional suffix to append to generated commit titles (e.g., ' [skip ci]' to # prevent triggering CI on the commit) # (optional) commit-title-suffix: "example-value" # Maximum allowed size for git patches in kilobytes (KB) for # push-to-pull-request-branch only. Overrides safe-outputs max-patch-size for this # output type. Defaults to 1024 KB (1 MB) when unset. # (optional) max-patch-size: 1 # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Token used to push an empty commit after pushing changes to trigger CI events. # Works around the GITHUB_TOKEN limitation where pushes don't trigger workflow # runs. Defaults to the magic secret GH_AW_CI_TRIGGER_TOKEN if set in the # repository. Use a secret expression (e.g. '${{ secrets.CI_TOKEN }}') for a # custom token, or 'app' for GitHub App auth. # (optional) github-token-for-extra-empty-commit: "example-value" # When true (default), if pushing to the PR branch fails due to a # non-fast-forward/diverged branch, create a fallback pull request that targets # the original PR branch. Set to false to disable this behavior and avoid # requiring pull-requests: write permission. # (optional) fallback-as-pull-request: true # When true (default), signed commits are required and pushes use GitHub's # createCommitOnBranch GraphQL mutation so GitHub signs them. Set to false to use # git push directly for repositories that do not require signed commits; this also # allows pushing merge commits that GraphQL cannot represent. # (optional) signed-commits: true # Target repository in format 'owner/repo' for cross-repository push to pull # request branch. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' that push to pull request # branch can target. When specified, the agent can use a 'repo' field in the # output to specify which repository to push to. The target repository (current or # target-repo) is always implicitly allowed. Accepts an array or a GitHub Actions # expression resolving to a comma-separated list (e.g. '${{ # inputs[\'allowed-repos\'] }}'). # (optional) # Accepted formats: # Format 1: Array of repository slugs in 'owner/repo' format allowed-repos: [] # Array items: string # Format 2: GitHub Actions expression resolving to a comma-separated list of # repository slugs (e.g. '${{ inputs[\'allowed-repos\'] }}') allowed-repos: "example-value" # Controls protected-file protection. String form: blocked (default), allowed, or # fallback-to-issue — or a GitHub Actions expression for reusable workflows. # Object form: { policy, exclude } to customise the protected-file set. # (optional) # Accepted formats: # Format 1: Controls protected-file protection. blocked (default): hard-block any # patch that modifies package manifests (e.g. package.json, go.mod), engine # instruction files (e.g. AGENTS.md, CLAUDE.md) or .github/ files. allowed: allow # all changes. fallback-to-issue: create a review issue instead of pushing to the # PR branch, so a human can review the changes before applying. protected-files: "blocked" # Format 2: GitHub Actions expression that resolves to 'blocked', 'allowed', or # 'fallback-to-issue' at runtime. Use in reusable workflow_call workflows to # parameterise the policy per caller. protected-files: "example-value" # Format 3: Object form for granular control over the protected-file set. Use the # exclude list to remove specific files from the default protection while keeping # the rest. protected-files: # (optional) # Accepted formats: # Format 1: Protection policy. blocked (default): hard-block any patch that # modifies protected files. allowed: allow all changes. fallback-to-issue: create # a review issue instead of pushing. policy: "blocked" # Format 2: GitHub Actions expression that resolves to 'blocked', 'allowed', or # 'fallback-to-issue' at runtime. policy: "example-value" # List of filenames or path prefixes to remove from the default protected-file # set. Items are matched by basename (e.g. "AGENTS.md") or path prefix (e.g. # ".agents/"). Use this to allow the agent to modify specific files that are # otherwise blocked by default. # (optional) exclude: [] # Array of strings # Exclusive allowlist of glob patterns. When set, every file in the patch must # match at least one pattern — files outside the list are always refused, # including normal source files. This is a restriction, not an exception: setting # allowed-files: [".github/workflows/*"] blocks all other files. To allow multiple # sets of files, list all patterns explicitly. Acts independently of the # protected-files policy; both checks must pass. To modify a protected file, it # must both match allowed-files and be permitted by protected-files (e.g. # protected-files: allowed). Supports * (any characters except /) and ** (any # characters including /). # (optional) allowed-files: [] # Array of strings # List of glob patterns for files to exclude from the patch. Each pattern is # passed to `git format-patch` as a `:(exclude)` magic pathspec, so # matching files are stripped by git at generation time and will not appear in the # commit. Excluded files are also not subject to `allowed-files` or # `protected-files` checks. Supports * (any characters except /) and ** (any # characters including /). # (optional) excluded-files: [] # Array of strings # Transport format for packaging changes. "bundle" (default) uses git bundle. "am" # uses git format-patch/git am. Accepts a GitHub Actions expression for reusable # workflows. # (optional) # Accepted formats: # Format 1: Transport format for packaging changes. "bundle" (default) uses git # bundle, which preserves merge commit topology, per-commit authorship, and # merge-resolution-only content. "am" uses git format-patch/git am. patch-format: "am" # Format 2: GitHub Actions expression that resolves to 'am' or 'bundle' at # runtime. Use in reusable workflow_call workflows to parameterise the transport # format per caller. patch-format: "example-value" # When true, adds workflows: write to the GitHub App token permissions. Required # when allowed-files targets .github/workflows/ paths. Requires # safe-outputs.github-app to be configured because the workflows permission is a # GitHub App-only permission and cannot be granted via GITHUB_TOKEN. # (optional) allow-workflows: true # When false, skips the branch protection API pre-flight check before pushing. Set # to false to avoid requiring administration: read permission. The GitHub platform # will still enforce branch protection at push time. Default is true (check # enabled). # (optional) check-branch-protection: true # Enable AI agents to minimize (hide) comments on issues or pull requests based on # relevance, spam detection, or moderation rules. # (optional) # Accepted formats: # Format 1: Enable comment hiding with default configuration hide-comment: null # Format 2: Configuration for hiding comments on GitHub issues, pull requests, or # discussions from agentic workflow output hide-comment: # Maximum number of comments to hide (default: 5) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository in format 'owner/repo' for cross-repository comment hiding. # Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of allowed reasons for hiding comments. Default: all reasons allowed (spam, # abuse, off_topic, outdated, resolved, low_quality). # (optional) allowed-reasons: [] # Array of strings # Controls whether the workflow requests discussions:write permission for # hide-comment. Default: true (includes discussions:write). Set to false if your # GitHub App lacks Discussions permission to prevent 422 errors during token # generation. # (optional) discussions: true # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Enable AI agents to set or clear the type of GitHub issues. Use an empty string # to clear the current type. # (optional) # Accepted formats: # Format 1: Null configuration allows setting any issue type set-issue-type: null # Format 2: Configuration for setting the type of GitHub issues from agentic # workflow output set-issue-type: # Optional list of allowed issue type names (e.g. 'Bug', 'Feature'). If omitted, # any type is allowed. Empty string is always allowed to clear the type. # (optional) allowed: [] # Array of strings # Optional maximum number of set-issue-type operations (default: 5). Supports # integer or GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target for issue type: 'triggering' (default), '*' (any issue), or explicit # issue number # (optional) target: "example-value" # Target repository in format 'owner/repo' for cross-repository issue type # setting. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' where issue types can be # set. When specified, the agent can use a 'repo' field in the output to specify # which repository to target. The target repository (current or target-repo) is # always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Enable AI agents to set one issue field value by field name and value. # (optional) # Accepted formats: # Format 1: Null configuration enables set-issue-field with defaults. set-issue-field: null # Format 2: Configuration for setting one issue field value by field name and # value. set-issue-field: # Optional maximum number of set-issue-field operations (default: 5). Supports # integer or GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target for issue field updates: 'triggering' (default), '*' (any issue), or # explicit issue number # (optional) target: "example-value" # Optional list of issue field names that can be modified by set-issue-field. If # omitted or empty, any issue field may be set. Use ['*'] to explicitly allow all. # (optional) allowed-fields: [] # Array of strings # Target repository in format 'owner/repo' for cross-repository issue field # updates. Takes precedence over trial target repo settings. # (optional) target-repo: "example-value" # List of additional repositories in format 'owner/repo' where issue fields can be # updated. When specified, the agent can use a 'repo' field in the output to # specify which repository to target. The target repository (current or # target-repo) is always implicitly allowed. # (optional) allowed-repos: [] # Array of strings # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # All of these labels must be present on the target item for this operation to # proceed # (optional) required-labels: [] # Array of strings # The target item's title must start with this prefix for this operation to # proceed # (optional) required-title-prefix: "example-value" # Dispatch workflow_dispatch events to other workflows. Used by orchestrators to # delegate work to worker workflows with controlled maximum dispatch count. # (optional) # Accepted formats: # Format 1: Configuration for dispatching workflow_dispatch events to other # workflows. Orchestrators use this to delegate work to worker workflows. dispatch-workflow: # List of workflow names (without .md extension) to allow dispatching. Each # workflow must exist in .github/workflows/. workflows: [] # Array of strings # Maximum number of workflow dispatch operations per run (default: 1, max: 50) # Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # GitHub token to use for dispatching workflows. Overrides global github-token if # specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # Target repository in format 'owner/repo' for cross-repository workflow dispatch. # When specified, the workflow will be dispatched to the target repository instead # of the current one. # (optional) target-repo: "example-value" # Git ref (branch, tag, or SHA) to use when dispatching the workflow. For # workflow_call relay scenarios this is auto-injected by the compiler from # needs.activation.outputs.target_ref. Overrides the caller's GITHUB_REF. # (optional) target-ref: "example-value" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Shorthand array format: list of workflow names (without .md extension) # to allow dispatching dispatch-workflow: [] # Array items: string # Dispatch repository_dispatch events to external repositories. Each sub-key # defines a named dispatch tool with its own event_type, target repository, input # schema, and execution limits. # (optional) dispatch_repository: {} # Call reusable workflows via workflow_call fan-out. The compiler generates static # conditional jobs; the agent selects which worker to activate. Use this for # orchestrator/dispatcher patterns within the same repository. # (optional) # Accepted formats: # Format 1: Configuration for calling reusable workflows via workflow_call # fan-out. The compiler generates conditional `uses:` jobs at compile time; the # agent selects which worker to activate at runtime. call-workflow: # List of workflow names (without .md extension) to allow calling. Each workflow # must exist in .github/workflows/ and declare a workflow_call trigger. workflows: [] # Array of strings # Maximum number of workflow_call fan-out operations per run (default: 1, max: # 50). Supports integer or GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # GitHub token passed to called workflows. Overrides global github-token if # specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Shorthand array format: list of workflow names (without .md extension) # to allow calling call-workflow: [] # Array items: string # Enable AI agents to report when required MCP tools are unavailable. Used for # workflow diagnostics and tool discovery. # (optional) # Accepted formats: # Format 1: Configuration for reporting missing tools from agentic workflow output missing-tool: # Maximum number of missing tool reports (default: unlimited) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Whether to create or update GitHub issues when tools are missing (default: # true). Supports literal boolean or GitHub Actions expression (e.g. '${{ # inputs.create-issue }}'). # (optional) # Accepted formats: # Format 1: boolean create-issue: true # Format 2: GitHub Actions expression that resolves to a boolean at runtime create-issue: "example-value" # Prefix for issue titles when creating issues for missing tools (default: # '[missing tool]') # (optional) title-prefix: "example-value" # Labels to add to created issues for missing tools # (optional) labels: [] # Array of strings # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable missing tool reporting with default configuration missing-tool: null # Format 3: Explicitly disable missing tool reporting (false). Missing tool # reporting is enabled by default when safe-outputs is configured. missing-tool: true # Enable AI agents to report when required data or context is missing. Used for # workflow troubleshooting and data validation. # (optional) # Accepted formats: # Format 1: Configuration for reporting missing data required to achieve workflow # goals. Encourages AI agents to be truthful about data gaps instead of # hallucinating information. missing-data: # Maximum number of missing data reports (default: unlimited) Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Whether to create or update GitHub issues when data is missing (default: true). # Supports literal boolean or GitHub Actions expression (e.g. '${{ # inputs.create-missing-data-issue }}'). # (optional) # Accepted formats: # Format 1: boolean create-issue: true # Format 2: GitHub Actions expression that resolves to a boolean at runtime create-issue: "example-value" # Prefix for issue titles when creating issues for missing data (default: # '[missing data]') # (optional) title-prefix: "example-value" # Labels to add to created issues for missing data # (optional) labels: [] # Array of strings # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable missing data reporting with default configuration missing-data: null # Format 3: Explicitly disable missing data reporting (false). Missing data # reporting is enabled by default when safe-outputs is configured. missing-data: true # Enable AI agents to explicitly indicate no action is needed. Used for workflow # control flow and conditional logic. # (optional) # Accepted formats: # Format 1: Configuration for no-op safe output (logging only, no GitHub API # calls). Always available as a fallback to ensure human-visible artifacts. noop: # Maximum number of noop messages (default: 1) Supports integer or GitHub Actions # expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # Controls whether noop runs are reported as issue comments (default: true). Set # to false to disable posting to the no-op runs issue. # (optional) report-as-issue: true # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable noop output with default configuration (max: 1) noop: null # Format 3: Explicitly disable noop output (false). Noop is enabled by default # when safe-outputs is configured. noop: true # Enable AI agents to publish files (images, charts, reports) to an orphaned git # branch for persistent storage and web access. # (optional) # Accepted formats: # Format 1: Configuration for publishing assets to an orphaned git branch upload-asset: # Branch name (default: 'assets/${{ github.workflow }}') # (optional) branch: "example-value" # Maximum file size in KB (default: 10240 = 10MB) # (optional) max-size: 1 # Allowed file extensions (default: common non-executable types) # (optional) allowed-exts: [] # Array of strings # Maximum number of assets to upload (default: 10) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable asset publishing with default configuration upload-asset: null # Enable AI agents to upload files as run-scoped GitHub Actions artifacts. Returns # a temporary artifact ID rather than a raw download URL, keeping authorization # centralized. # (optional) # Accepted formats: # Format 1: Configuration for uploading files as run-scoped GitHub Actions # artifacts upload-artifact: # Maximum number of upload_artifact tool calls allowed per run (default: 1) # (optional) max-uploads: 1 # Artifact retention period in days (fixed; the agent cannot override this value). # Supports integer or GitHub Actions expression (e.g. '${{ inputs.retention-days # }}'). # (optional) # Accepted formats: # Format 1: integer retention-days: 1 # Format 2: string retention-days: "example-value" # Upload files directly without zip archiving (fixed; the agent cannot override # this value). Only valid for single-file uploads. Supports boolean or GitHub # Actions expression (e.g. '${{ inputs.skip-archive }}'). # (optional) # Accepted formats: # Format 1: boolean skip-archive: true # Format 2: string skip-archive: "example-value" # Maximum total upload size in bytes per slot (default: 104857600 = 100 MB) # (optional) max-size-bytes: 1 # Glob patterns restricting which paths relative to the staging directory the # model may upload # (optional) allowed-paths: [] # Array of strings # Default include/exclude glob filters applied on top of allowed-paths # (optional) filters: # Glob patterns for files to include # (optional) include: [] # Array of strings # Glob patterns for files to exclude # (optional) exclude: [] # Array of strings # Default values injected when the model omits a field # (optional) defaults: # Behaviour when no files match: 'error' (default) or 'ignore' # (optional) if-no-files: "error" # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub Actions artifact # uploads (preview mode) # (optional) staged: true # Format 2: Enable artifact uploads with default configuration upload-artifact: null # Enable AI agents to edit and update GitHub release content, including release # notes, assets, and metadata. # (optional) # Accepted formats: # Format 1: Configuration for updating GitHub release descriptions update-release: # Maximum number of releases to update (default: 1) Supports integer or GitHub # Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Target repository for cross-repo release updates (format: owner/repo). If not # specified, updates releases in the workflow's repository. # (optional) target-repo: "example-value" # Controls whether AI-generated footer is added when updating the release body. # When false, the visible footer content is omitted. Defaults to true. # (optional) footer: true # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable release updates with default configuration update-release: null # If true, emit step summary messages instead of making GitHub API calls (preview # mode) # (optional) staged: true # Environment variables to pass to safe output jobs # (optional) env: {} # GitHub token to use for safe output jobs. Typically a secret reference like ${{ # secrets.GITHUB_TOKEN }} or ${{ secrets.CUSTOM_PAT }} # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # GitHub App credentials for minting installation access tokens. When configured, # a token will be generated using the app credentials and used for all safe output # operations. # (optional) github-app: # Deprecated alias for client-id. GitHub App ID/client ID (e.g., '${{ vars.APP_ID # }}'). # (optional) app-id: "example-value" # GitHub App client ID (e.g., '${{ vars.APP_ID }}'). Required to mint a GitHub App # token. # (optional) client-id: "example-value" # GitHub App private key (e.g., '${{ secrets.APP_PRIVATE_KEY }}'). Required to # mint a GitHub App token. # (optional) private-key: "example-value" # If true, skip token minting when client-id/private-key resolve to empty strings # at runtime. Defaults to false. # (optional) ignore-if-missing: true # Optional owner of the GitHub App installation (defaults to current repository # owner if not specified) # (optional) owner: "example-value" # Optional list of repositories to grant access to (defaults to current repository # if not specified) # (optional) repositories: [] # Array of strings # Optional extra GitHub App-only permissions to merge into the minted token. Takes # effect for tools.github.github-app and safe-outputs.github-app; ignored in # on.github-app and the top-level github-app fallback. Use to add GitHub App-only # scopes (e.g. members, organization-administration) not expressible via standard # handler declarations. # (optional) permissions: # Permission level for repository administration (read/none; "write" is rejected # by the compiler). GitHub App-only permission for repository administration. # (optional) administration: "read" # Permission level for Codespaces (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) codespaces: "read" # Permission level for Codespaces lifecycle administration (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) codespaces-lifecycle-admin: "read" # Permission level for Codespaces metadata (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) codespaces-metadata: "read" # Permission level for user email addresses (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) email-addresses: "read" # Permission level for repository environments (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) environments: "read" # Permission level for git signing (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) git-signing: "read" # Permission level for organization members (read/none; "write" is rejected by the # compiler). Required for org team membership API calls. # (optional) members: "read" # Permission level for organization administration (read/none; "write" is rejected # by the compiler). GitHub App-only permission. # (optional) organization-administration: "read" # Permission level for organization announcement banners (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-announcement-banners: "read" # Permission level for organization Codespaces (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-codespaces: "read" # Permission level for organization Copilot (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-copilot: "read" # Permission level for organization custom org roles (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-org-roles: "read" # Permission level for organization custom properties (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-properties: "read" # Permission level for organization custom repository roles (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-repository-roles: "read" # Permission level for organization events (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-events: "read" # Permission level for organization webhooks (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-hooks: "read" # Permission level for organization members management (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-members: "read" # Permission level for organization packages (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-packages: "read" # Permission level for organization personal access token requests (read/none; # "write" is rejected by the compiler). GitHub App-only permission. # (optional) organization-personal-access-token-requests: "read" # Permission level for organization personal access tokens (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-personal-access-tokens: "read" # Permission level for organization plan (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-plan: "read" # Permission level for organization self-hosted runners (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-self-hosted-runners: "read" # Permission level for organization user blocking (read/none; "write" is rejected # by the compiler). GitHub App-only permission. # (optional) organization-user-blocking: "read" # Permission level for repository custom properties (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) repository-custom-properties: "read" # Permission level for repository webhooks (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) repository-hooks: "read" # Permission level for single file access (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) single-file: "read" # Permission level for team discussions (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) team-discussions: "read" # Permission level for Dependabot vulnerability alerts (read/none; "write" is # rejected by the compiler). Also available as a GITHUB_TOKEN scope. When used # with a GitHub App, forwarded as permission-vulnerability-alerts input. # (optional) vulnerability-alerts: "read" # Permission level for GitHub Actions workflow files (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) workflows: "read" # Maximum allowed size for git patches in kilobytes (KB). Defaults to 1024 KB (1 # MB). If patch exceeds this size, the job will fail. # (optional) max-patch-size: 1 # Maximum allowed number of unique files in a create-pull-request patch. Defaults # to 100. The check counts unique file paths (deduplicated across multi-commit # patches), so it reflects how many distinct files the agent is pushing in this # iteration. # (optional) max-patch-files: 1 # Enable AI agents to report detected security threats, policy violations, or # suspicious patterns for security review. # (optional) # Accepted formats: # Format 1: Enable or disable threat detection for safe outputs (defaults to true # when safe-outputs are configured) threat-detection: true # Format 2: GitHub Actions expression that resolves to a boolean at runtime, # enabling or disabling threat detection based on workflow inputs (e.g. '${{ # inputs.enable-threat-detection }}') threat-detection: "example-value" # Format 3: Threat detection configuration object threat-detection: # Whether threat detection is enabled. Accepts a boolean literal or a GitHub # Actions expression (e.g. '${{ inputs.enable-threat-detection }}'). # (optional) # Accepted formats: # Format 1: boolean enabled: true # Format 2: GitHub Actions expression that resolves to a boolean at runtime enabled: "example-value" # Additional custom prompt instructions to append to threat detection analysis # (optional) prompt: "example-value" # AI engine configuration specifically for threat detection (overrides main # workflow engine). Set to false to disable AI-based threat detection. Supports # same format as main engine field when not false. # (optional) # Accepted formats: # Format 1: Disable AI engine for threat detection (only run custom steps) engine: true # Format 2: Configuration object # Array of extra job steps to run before engine execution # (optional) steps: [] # Array of extra job steps to run after engine execution # (optional) post-steps: [] # Runner specification for the detection job. Overrides agent.runs-on for the # detection job only. Defaults to agent.runs-on. # (optional) runs-on: "example-value" # When true (default), detection failures produce warnings and allow safe outputs # to proceed with a caution notice and 'needs-review' label. When false, detection # failures block safe outputs entirely. Accepts a boolean literal or a GitHub # Actions expression. # (optional) # Accepted formats: # Format 1: boolean continue-on-error: true # Format 2: GitHub Actions expression that resolves to a boolean at runtime continue-on-error: "example-value" # Custom safe-output jobs that can be executed based on agentic workflow output. # Job names containing dashes will be automatically normalized to underscores # (e.g., 'send-notification' becomes 'send_notification'). # (optional) jobs: {} # Inline JavaScript script handlers that run inside the consolidated safe-outputs # job handler loop. Unlike 'jobs' (which create separate GitHub Actions jobs), # scripts execute in-process alongside the built-in handlers. Users write only the # body of the main function — the compiler wraps it with 'async function # main(config = {}) { ... }' and 'module.exports = { main };' automatically. # Script names containing dashes will be automatically normalized to underscores # (e.g., 'post-slack-message' becomes 'post_slack_message'). # (optional) scripts: {} # Custom message templates for safe-output footer and notification messages. # Available placeholders: {workflow_name} (workflow name), {run_url} (GitHub # Actions run URL), {triggering_number} (issue/PR/discussion number), # {workflow_source} (owner/repo/path@ref), {workflow_source_url} (GitHub URL to # source), {operation} (safe-output operation name for staged mode). # (optional) messages: # Custom footer message template for AI-generated content. Available placeholders: # {workflow_name}, {run_url}, {triggering_number}, {workflow_source}, # {workflow_source_url}. Example: '> Generated by [{workflow_name}]({run_url})' # (optional) footer: "example-value" # Custom installation instructions template appended to the footer. Available # placeholders: {workflow_source}, {workflow_source_url}. Example: '> Install: `gh # aw add {workflow_source}`' # (optional) footer-install: "example-value" # Custom footer message template for workflow recompile issues. Available # placeholders: {workflow_name}, {run_url}, {repository}. Example: '> Workflow # sync report by [{workflow_name}]({run_url}) for {repository}' # (optional) footer-workflow-recompile: "example-value" # Custom footer message template for comments on workflow recompile issues. # Available placeholders: {workflow_name}, {run_url}, {repository}. Example: '> # Update from [{workflow_name}]({run_url}) for {repository}' # (optional) footer-workflow-recompile-comment: "example-value" # Custom title template for staged mode preview. Available placeholders: # {operation}. Example: ' Preview: {operation}' # (optional) staged-title: "example-value" # Custom description template for staged mode preview. Available placeholders: # {operation}. Example: 'The following {operation} would occur if staged mode was # disabled:' # (optional) staged-description: "example-value" # Custom message template for workflow activation comment. Available placeholders: # {workflow_name}, {run_url}, {event_type}. Default: 'Agentic # [{workflow_name}]({run_url}) triggered by this {event_type}.' # (optional) run-started: "example-value" # Custom message template for successful workflow completion. Available # placeholders: {workflow_name}, {run_url}. Default: '✓ Agentic # [{workflow_name}]({run_url}) completed successfully.' # (optional) run-success: "example-value" # Custom message template for failed workflow. Available placeholders: # {workflow_name}, {run_url}, {status}. Default: '✗ Agentic # [{workflow_name}]({run_url}) {status} and wasn't able to produce a result.' # (optional) run-failure: "example-value" # Custom message template for detection job failure. Available placeholders: # {workflow_name}, {run_url}. Default: '! Security scanning failed for # [{workflow_name}]({run_url}). Review the logs for details.' # (optional) detection-failure: "example-value" # Custom footer template for agent failure tracking issues. Available # placeholders: {workflow_name}, {run_url}. Default: '> Agent failure tracked by # [{workflow_name}]({run_url})' # (optional) agent-failure-issue: "example-value" # Custom footer template for comments on agent failure tracking issues. Available # placeholders: {workflow_name}, {run_url}. Default: '> Agent failure update from # [{workflow_name}]({run_url})' # (optional) agent-failure-comment: "example-value" # Custom message template for pull request creation link appended to the # activation comment. Available placeholders: {item_number}, {item_url}. Default: # 'Pull request created: [#{item_number}]({item_url})' # (optional) pull-request-created: "example-value" # Custom message template for issue creation link appended to the activation # comment. Available placeholders: {item_number}, {item_url}. Default: 'Issue # created: [#{item_number}]({item_url})' # (optional) issue-created: "example-value" # Custom message template for commit push link appended to the activation comment. # Available placeholders: {commit_sha}, {short_sha}, {commit_url}. Default: # 'Commit pushed: [`{short_sha}`]({commit_url})' # (optional) commit-pushed: "example-value" # Custom header text prepended to every message body generated by safe outputs # (issues, comments, pull requests, discussions). Applied after any # threat-detection caution alert and before the agent-generated content. Available # placeholders: {workflow_name}, {run_url}. # (optional) body-header: "example-value" # When enabled, workflow completion notifier creates a new comment instead of # editing the activation comment. Creates an append-only timeline of workflow # runs. Default: false # (optional) append-only-comments: true # Configuration for @mention filtering in safe outputs. Controls whether and how # @mentions in AI-generated content are allowed or escaped. # (optional) # Accepted formats: # Format 1: Simple boolean mode: false = always escape mentions, true = always # allow mentions (error in strict mode) mentions: true # Format 2: Advanced configuration for @mention filtering with fine-grained # control mentions: # Allow mentions of repository team members (collaborators with any permission # level, excluding bots). Default: true # (optional) allow-team-members: true # Allow mentions inferred from event context (issue/PR authors, assignees, # commenters). Default: true # (optional) allow-context: true # List of user/bot names always allowed to be mentioned. Bots are not allowed by # default unless listed here. # (optional) allowed: [] # Array of strings # Maximum number of mentions allowed per message. Default: 50 Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Global footer control for all safe outputs. When false, omits visible # AI-generated footer content from all created/updated entities (issues, PRs, # discussions, releases) while still including XML markers for searchability. # Individual safe-output types (create-issue, update-issue, etc.) can override # this by specifying their own footer field. Defaults to true. # (optional) footer: true # When set to false or "false", disables all activation and fallback comments # entirely (run-started, run-success, run-failure, PR/issue creation links). # Supports templatable boolean values including GitHub Actions expressions (e.g. # ${{ inputs.activation-comments }}). Default: true # (optional) activation-comments: null # When true, creates a parent '[aw] Failed runs' issue that tracks all workflow # failures as sub-issues. Helps organize failure tracking but may be unnecessary # in smaller repositories. Defaults to false. # (optional) group-reports: true # When false, disables creating failure tracking issues when workflows fail. # Useful for workflows where failures are expected or handled elsewhere. Defaults # to true. # (optional) report-failure-as-issue: true # Repository to create failure tracking issues in, in the format 'owner/repo'. # Useful when the current repository has issues disabled. Defaults to the current # repository. # (optional) failure-issue-repo: "example-value" # Maximum number of bot trigger references (e.g. 'fixes #123', 'closes #456') # allowed in output before all of them are neutralized. Default: 10. Supports # integer or GitHub Actions expression (e.g. '${{ inputs.max-bot-mentions }}'). # (optional) # Accepted formats: # Format 1: integer max-bot-mentions: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max-bot-mentions: "example-value" # Override the id-token permission for the safe-outputs job. Use 'write' to # force-enable the id-token: write permission (required for OIDC authentication # with cloud providers). Use 'none' to suppress automatic detection and prevent # adding id-token: write even when vault/OIDC actions are detected in steps. By # default, the compiler auto-detects known OIDC/vault actions # (aws-actions/configure-aws-credentials, azure/login, google-github-actions/auth, # hashicorp/vault-action, cyberark/conjur-action) and adds id-token: write # automatically. # (optional) id-token: "write" # Concurrency group for the safe-outputs job. When set, the safe-outputs job will # use this concurrency group with cancel-in-progress: false. Supports GitHub # Actions expressions. # (optional) concurrency-group: "example-value" # Explicit additional custom workflow jobs that the consolidated safe_outputs job # should depend on. # (optional) needs: [] # Array of strings # Override the GitHub deployment environment for the safe-outputs job. When set, # this environment is used instead of the top-level environment: field. When not # set, the top-level environment: field is propagated automatically so that # environment-scoped secrets are accessible in the safe-outputs job. # (optional) # Accepted formats: # Format 1: Environment name as a string environment: "example-value" # Format 2: Environment object with name and optional URL environment: # The name of the environment configured in the repo name: "My Workflow" # A deployment URL # (optional) url: "example-value" # Runner specification for all safe-outputs jobs (activation, create-issue, # add-comment, etc.). Single runner label (e.g., 'ubuntu-slim', 'ubuntu-latest', # 'windows-latest', 'self-hosted'). Defaults to 'ubuntu-slim'. See # https://github.blog/changelog/2025-10-28-1-vcpu-linux-runner-now-available-in-github-actions-in-public-preview/ # (optional) runs-on: "example-value" # Custom steps to inject into all safe-output jobs. These steps run after checking # out the repository and setting up the action, and before any safe-output code # executes. # (optional) steps: [] # Custom GitHub Actions to mount as once-callable MCP tools. Each action is # resolved at compile time to derive its input schema from action.yml, and a # guarded `uses:` step is injected in the safe_outputs job. Action names # containing dashes will be automatically normalized to underscores (e.g., # 'add-smoked-label' becomes 'add_smoked_label'). # (optional) actions: {} # Enable AI agents to signal that a task could not be completed due to # infrastructure or tool failures (e.g., MCP crash, missing auth, inaccessible # repository). Activates failure handling even when the agent exits 0. # (optional) # Accepted formats: # Format 1: Configuration for report_incomplete safe output report-incomplete: # Maximum number of report_incomplete signals (default: 5). Supports integer or # GitHub Actions expression (e.g. '${{ inputs.max }}'). # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Whether to create or update GitHub issues when the task was incomplete (default: # true). Supports literal boolean or GitHub Actions expression (e.g. '${{ # inputs.create-incomplete-issue }}'). # (optional) # Accepted formats: # Format 1: boolean create-issue: true # Format 2: GitHub Actions expression that resolves to a boolean at runtime create-issue: "example-value" # Prefix for issue titles when creating issues for incomplete runs (default: # '[incomplete]') # (optional) title-prefix: "example-value" # Labels to add to created issues for incomplete runs # (optional) labels: [] # Array of strings # GitHub token to use for this specific output type. Overrides global github-token # if specified. # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # If true, emit step summary messages instead of making GitHub API calls for this # specific output type (preview mode) # (optional) staged: true # Format 2: Enable report_incomplete with default configuration report-incomplete: null # Format 3: Explicitly disable report_incomplete (false). report_incomplete is # enabled by default when safe-outputs is configured. report-incomplete: true # Configuration for secret redaction behavior in workflow outputs and artifacts # (optional) secret-masking: # Additional secret redaction steps to inject after the built-in secret redaction. # Use this to mask secrets in generated files using custom patterns. # (optional) steps: [] # Optional observability output settings for workflow runs. # (optional) observability: # OTLP (OpenTelemetry Protocol) trace export configuration. # (optional) otlp: # OTLP endpoint configuration. Accepts a plain URL string (backward-compat), a # single {url, headers} object, or an array of {url, headers} objects for # multi-endpoint concurrent fan-out. Encoded as GH_AW_OTLP_ENDPOINTS (JSON array). # (optional) # Accepted formats: # Format 1: OTLP collector endpoint URL (e.g. 'https://traces.example.com:4317'). # Supports GitHub Actions expressions such as ${{ secrets.OTLP_ENDPOINT }}. When a # static URL is provided, its hostname is automatically added to the network # firewall allowlist. endpoint: "example-value" # Format 2: A single OTLP endpoint with a URL and optional per-endpoint headers. endpoint: # OTLP collector endpoint URL (e.g. 'https://traces.example.com:4317'). Supports # GitHub Actions expressions such as ${{ secrets.OTLP_ENDPOINT }}. When a static # URL is provided, its hostname is automatically added to the network firewall # allowlist. url: "example-value" # (optional) # Accepted formats: # Format 1: Map of HTTP header names to values. Values support GitHub Actions # expressions such as ${{ secrets.TOKEN }}. headers: {} # Format 2: Deprecated: use the map form instead. Comma-separated list of # key=value HTTP headers (e.g. 'Authorization=Bearer '). Supports GitHub # Actions expressions such as ${{ secrets.OTLP_HEADERS }}. headers: "example-value" # Format 3: Multiple OTLP collector endpoints to export traces to concurrently. # Each entry has its own URL and optional per-endpoint headers. endpoint: [] # Array items: A single OTLP endpoint with a URL and optional per-endpoint # headers. # HTTP headers for the backward-compat string endpoint form. Only used when # endpoint is a plain string; object/array endpoint entries carry their own # per-endpoint headers. # (optional) # Accepted formats: # Format 1: Map of HTTP header names to values to include with every OTLP export # request. Values support GitHub Actions expressions such as ${{ secrets.TOKEN }}. # Injected as the OTEL_EXPORTER_OTLP_HEADERS environment variable. headers: {} # Format 2: Deprecated: use the map form instead. Comma-separated list of # key=value HTTP headers to include with every OTLP export request (e.g. # 'Authorization=Bearer '). Supports GitHub Actions expressions such as ${{ # secrets.OTLP_HEADERS }}. Injected as the OTEL_EXPORTER_OTLP_HEADERS environment # variable. headers: "example-value" # How to handle missing OTLP endpoint/header values at runtime (for example from # unset secrets). 'error' fails workflow startup (default), 'warn' logs a warning # and skips MCP gateway OTLP configuration, and 'ignore' skips MCP gateway OTLP # configuration without warning. This affects MCP gateway setup only; # workflow-level OTEL_* environment variables are still injected. # (optional) if-missing: "error" # Rate limiting configuration to restrict how frequently users can trigger the # workflow. Helps prevent abuse and resource exhaustion from programmatically # triggered events. # (optional) user-rate-limit: # Maximum number of workflow runs allowed per user within the time window. # Required field. Supports integer or GitHub Actions expression (e.g. '${{ # inputs.max }}'). # Accepted formats: # Format 1: integer max-runs-per-window: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max-runs-per-window: "example-value" # Time window in minutes for rate limiting. Defaults to 60 (1 hour). Maximum: 180 # (3 hours). # (optional) window: 1 # Optional list of event types to apply rate limiting to. If not specified, rate # limiting applies to all programmatically triggered events (e.g., # workflow_dispatch, issue_comment, pull_request_review). # (optional) events: [] # Array of strings # Optional list of roles that are exempt from rate limiting. Defaults to ['admin', # 'maintain', 'write'] if not specified. Users with any of these roles will not be # subject to rate limiting checks. To apply rate limiting to all users, set to an # empty array: [] # (optional) ignored-roles: [] # Array of strings # Legacy alias for 'user-rate-limit'. Prefer 'user-rate-limit' with # 'max-runs-per-window'. # (optional) rate-limit: # Legacy maximum runs key. Prefer 'max-runs-per-window'. # (optional) # Accepted formats: # Format 1: integer max-runs: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max-runs: "example-value" # Legacy maximum runs key. Prefer 'max-runs-per-window'. # (optional) # Accepted formats: # Format 1: integer max: 1 # Format 2: GitHub Actions expression that resolves to an integer at runtime max: "example-value" # Time window in minutes for rate limiting. Defaults to 60 (1 hour). Maximum: 180 # (3 hours). # (optional) window: 1 # Optional list of event types to apply rate limiting to. # (optional) events: [] # Array of strings # Optional list of roles that are exempt from rate limiting. # (optional) ignored-roles: [] # Array of strings # Enable strict mode validation for enhanced security and compliance. Strict mode # enforces: (1) Write Permissions - refuses contents:write, issues:write, # pull-requests:write; requires safe-outputs instead, (2) Network Configuration - # requires explicit network configuration with no standalone wildcard '*' in # allowed domains (patterns like '*.example.com' are allowed), (3) Action Pinning # - enforces actions pinned to commit SHAs instead of tags/branches, (4) MCP # Network - requires network configuration for custom MCP servers with containers, # (5) Deprecated Fields - refuses deprecated frontmatter fields. Can be enabled # per-workflow via 'strict: true' in frontmatter, or disabled via 'strict: false'. # CLI flag takes precedence over frontmatter (gh aw compile --strict enforces # strict mode). Defaults to true. See: # https://github.github.com/gh-aw/reference/frontmatter/#strict-mode-strict # (optional) strict: true # Mark the workflow as private, preventing it from being added to other # repositories via 'gh aw add'. A workflow with private: true is not meant to be # shared outside its repository. # (optional) private: true # Control whether the compile-agentic version update check runs in the activation # job. When true (default), the activation job downloads config.json from the # gh-aw repository and verifies the compiled version is not blocked and meets the # minimum supported version. Set to false to disable the check (not allowed in # strict mode). See: # https://github.github.com/gh-aw/reference/frontmatter/#check-for-updates # (optional) check-for-updates: true # Allow npm pre/post install scripts to execute during package installation. By # default, --ignore-scripts is added to all generated npm install commands to # prevent supply chain attacks via malicious install hooks. Setting # run-install-scripts: true disables this protection globally (all runtimes). A # supply chain security warning is emitted at compile time; in strict mode this is # an error. Per-runtime control is also available via # runtimes..run-install-scripts. See: # https://github.github.com/gh-aw/reference/frontmatter/#run-install-scripts # (optional) run-install-scripts: true # MCP Scripts configuration for defining custom lightweight MCP tools as # JavaScript, shell scripts, or Python scripts. Tools are mounted in an MCP server # and have access to secrets specified by the user. Only one of 'script' # (JavaScript), 'run' (shell), or 'py' (Python) must be specified per tool. # (optional) mcp-scripts: {} # Runtime environment version overrides. Allows customizing runtime versions # (e.g., Node.js, Python) or defining new runtimes. Runtimes from imported shared # workflows are also merged. # (optional) runtimes: {} # Checkout configuration for the agent job. Controls how actions/checkout is # invoked. Can be a single checkout configuration, an array for multiple # checkouts, or false to disable the default checkout step entirely (dev-mode # checkouts are unaffected). # (optional) # Accepted formats: # Format 1: Single checkout configuration for the default workspace checkout: # Repository to checkout in owner/repo format. Defaults to the current repository. # (optional) repository: "example-value" # Branch, tag, or SHA to checkout. Defaults to the ref that triggered the # workflow. # (optional) ref: "example-value" # Relative path within GITHUB_WORKSPACE to place the checkout. Defaults to the # workspace root. # (optional) path: "example-value" # Number of commits to fetch. 0 fetches all history. 1 (default) is a shallow # clone. When multiple configs target the same path, the deepest value is used. # (optional) fetch-depth: 1 # Enable sparse-checkout with newline-separated patterns. When multiple configs # target the same path, patterns are merged. # (optional) sparse-checkout: "example-value" # Controls submodule checkout. Use "recursive" for all submodules, "true" for # immediate submodules, or "false" to skip. # (optional) # Accepted formats: # Format 1: string submodules: "recursive" # Format 2: boolean submodules: true # Whether to download Git LFS objects. Defaults to false. # (optional) lfs: true # Deprecated: Use github-token instead. GitHub token for authentication. # Credentials are always removed after checkout (persist-credentials: false is # enforced). # (optional) token: "example-value" # GitHub token for authentication. Use ${{ secrets.MY_TOKEN }} to reference a # secret. Mutually exclusive with github-app (and deprecated app). Credentials are # always removed after checkout (persist-credentials: false is enforced). # (optional) github-token: "${{ secrets.GITHUB_TOKEN }}" # GitHub App authentication. Mints a short-lived installation access token via # actions/create-github-app-token. Mutually exclusive with github-token. # (optional) github-app: # Deprecated alias for client-id. GitHub App ID/client ID (e.g., '${{ vars.APP_ID # }}'). # (optional) app-id: "example-value" # GitHub App client ID (e.g., '${{ vars.APP_ID }}'). Required to mint a GitHub App # token. # (optional) client-id: "example-value" # GitHub App private key (e.g., '${{ secrets.APP_PRIVATE_KEY }}'). Required to # mint a GitHub App token. # (optional) private-key: "example-value" # If true, skip token minting when client-id/private-key resolve to empty strings # at runtime. Defaults to false. # (optional) ignore-if-missing: true # Optional owner of the GitHub App installation (defaults to current repository # owner if not specified) # (optional) owner: "example-value" # Optional list of repositories to grant access to (defaults to current repository # if not specified) # (optional) repositories: [] # Array of strings # Optional extra GitHub App-only permissions to merge into the minted token. Takes # effect for tools.github.github-app and safe-outputs.github-app; ignored in # on.github-app and the top-level github-app fallback. Use to add GitHub App-only # scopes (e.g. members, organization-administration) not expressible via standard # handler declarations. # (optional) permissions: # Permission level for repository administration (read/none; "write" is rejected # by the compiler). GitHub App-only permission for repository administration. # (optional) administration: "read" # Permission level for Codespaces (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) codespaces: "read" # Permission level for Codespaces lifecycle administration (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) codespaces-lifecycle-admin: "read" # Permission level for Codespaces metadata (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) codespaces-metadata: "read" # Permission level for user email addresses (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) email-addresses: "read" # Permission level for repository environments (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) environments: "read" # Permission level for git signing (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) git-signing: "read" # Permission level for organization members (read/none; "write" is rejected by the # compiler). Required for org team membership API calls. # (optional) members: "read" # Permission level for organization administration (read/none; "write" is rejected # by the compiler). GitHub App-only permission. # (optional) organization-administration: "read" # Permission level for organization announcement banners (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-announcement-banners: "read" # Permission level for organization Codespaces (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-codespaces: "read" # Permission level for organization Copilot (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-copilot: "read" # Permission level for organization custom org roles (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-org-roles: "read" # Permission level for organization custom properties (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-properties: "read" # Permission level for organization custom repository roles (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-repository-roles: "read" # Permission level for organization events (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-events: "read" # Permission level for organization webhooks (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-hooks: "read" # Permission level for organization members management (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-members: "read" # Permission level for organization packages (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-packages: "read" # Permission level for organization personal access token requests (read/none; # "write" is rejected by the compiler). GitHub App-only permission. # (optional) organization-personal-access-token-requests: "read" # Permission level for organization personal access tokens (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-personal-access-tokens: "read" # Permission level for organization plan (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-plan: "read" # Permission level for organization self-hosted runners (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-self-hosted-runners: "read" # Permission level for organization user blocking (read/none; "write" is rejected # by the compiler). GitHub App-only permission. # (optional) organization-user-blocking: "read" # Permission level for repository custom properties (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) repository-custom-properties: "read" # Permission level for repository webhooks (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) repository-hooks: "read" # Permission level for single file access (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) single-file: "read" # Permission level for team discussions (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) team-discussions: "read" # Permission level for Dependabot vulnerability alerts (read/none; "write" is # rejected by the compiler). Also available as a GITHUB_TOKEN scope. When used # with a GitHub App, forwarded as permission-vulnerability-alerts input. # (optional) vulnerability-alerts: "read" # Permission level for GitHub Actions workflow files (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) workflows: "read" # Marks this checkout as the logical current repository for the workflow. When set # to true, the AI agent will treat this repository as its primary working target. # Only one checkout may have current set to true. Useful for central-repo # workflows targeting a different repository. # (optional) current: true # Additional Git refs to fetch after the checkout. Supported values: "*" (all # branches), "refs/pulls/open/*" (all open pull-request refs), branch names (e.g. # "main"), or glob patterns (e.g. "feature/*"). # (optional) # Accepted formats: # Format 1: A single additional ref pattern to fetch after checkout. fetch: "example-value" # Format 2: Additional Git refs to fetch after checkout. A git fetch step is # emitted after the actions/checkout step. fetch: [] # Array items: string # When true, clones the repository's wiki git instead of the regular repository. # The effective repository becomes "{repository}.wiki" (e.g. "owner/repo.wiki"). # Defaults to false. # (optional) wiki: true # When true, persist credentials during checkout, then immediately run a # post-checkout cleanup step that removes credentials from root and submodule git # configs. Useful for submodule-safe cleanup behavior. # (optional) force-clean-git-credentials: true # Format 2: Multiple checkout configurations checkout: [] # Array items: undefined # Format 3: Set to false to disable the default checkout step. The agent job will # not check out any repository (dev-mode checkouts are unaffected). checkout: false # Top-level GitHub App configuration used as a fallback for all nested github-app # token minting operations (on, safe-outputs, checkout, tools.github, # dependencies). When a nested section does not define its own github-app, this # top-level configuration is used automatically. # (optional) github-app: # Deprecated alias for client-id. GitHub App ID/client ID (e.g., '${{ vars.APP_ID # }}'). # (optional) app-id: "example-value" # GitHub App client ID (e.g., '${{ vars.APP_ID }}'). Required to mint a GitHub App # token. # (optional) client-id: "example-value" # GitHub App private key (e.g., '${{ secrets.APP_PRIVATE_KEY }}'). Required to # mint a GitHub App token. # (optional) private-key: "example-value" # If true, skip token minting when client-id/private-key resolve to empty strings # at runtime. Defaults to false. # (optional) ignore-if-missing: true # Optional owner of the GitHub App installation (defaults to current repository # owner if not specified) # (optional) owner: "example-value" # Optional list of repositories to grant access to (defaults to current repository # if not specified) # (optional) repositories: [] # Array of strings # Optional extra GitHub App-only permissions to merge into the minted token. Takes # effect for tools.github.github-app and safe-outputs.github-app; ignored in # on.github-app and the top-level github-app fallback. Use to add GitHub App-only # scopes (e.g. members, organization-administration) not expressible via standard # handler declarations. # (optional) permissions: # Permission level for repository administration (read/none; "write" is rejected # by the compiler). GitHub App-only permission for repository administration. # (optional) administration: "read" # Permission level for Codespaces (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) codespaces: "read" # Permission level for Codespaces lifecycle administration (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) codespaces-lifecycle-admin: "read" # Permission level for Codespaces metadata (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) codespaces-metadata: "read" # Permission level for user email addresses (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) email-addresses: "read" # Permission level for repository environments (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) environments: "read" # Permission level for git signing (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) git-signing: "read" # Permission level for organization members (read/none; "write" is rejected by the # compiler). Required for org team membership API calls. # (optional) members: "read" # Permission level for organization administration (read/none; "write" is rejected # by the compiler). GitHub App-only permission. # (optional) organization-administration: "read" # Permission level for organization announcement banners (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-announcement-banners: "read" # Permission level for organization Codespaces (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-codespaces: "read" # Permission level for organization Copilot (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-copilot: "read" # Permission level for organization custom org roles (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-org-roles: "read" # Permission level for organization custom properties (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-properties: "read" # Permission level for organization custom repository roles (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-custom-repository-roles: "read" # Permission level for organization events (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-events: "read" # Permission level for organization webhooks (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-hooks: "read" # Permission level for organization members management (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-members: "read" # Permission level for organization packages (read/none; "write" is rejected by # the compiler). GitHub App-only permission. # (optional) organization-packages: "read" # Permission level for organization personal access token requests (read/none; # "write" is rejected by the compiler). GitHub App-only permission. # (optional) organization-personal-access-token-requests: "read" # Permission level for organization personal access tokens (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-personal-access-tokens: "read" # Permission level for organization plan (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) organization-plan: "read" # Permission level for organization self-hosted runners (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) organization-self-hosted-runners: "read" # Permission level for organization user blocking (read/none; "write" is rejected # by the compiler). GitHub App-only permission. # (optional) organization-user-blocking: "read" # Permission level for repository custom properties (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) repository-custom-properties: "read" # Permission level for repository webhooks (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) repository-hooks: "read" # Permission level for single file access (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) single-file: "read" # Permission level for team discussions (read/none; "write" is rejected by the # compiler). GitHub App-only permission. # (optional) team-discussions: "read" # Permission level for Dependabot vulnerability alerts (read/none; "write" is # rejected by the compiler). Also available as a GITHUB_TOKEN scope. When used # with a GitHub App, forwarded as permission-vulnerability-alerts input. # (optional) vulnerability-alerts: "read" # Permission level for GitHub Actions workflow files (read/none; "write" is # rejected by the compiler). GitHub App-only permission. # (optional) workflows: "read" # Schema for validating 'with' input values when this workflow is imported by # another workflow using the 'uses'/'with' syntax. Defines the expected # parameters, their types, and whether they are required. Scalar inputs are # accessible via '${{ github.aw.import-inputs. }}' expressions. Object # inputs (type: object) allow one-level deep sub-fields accessible via '${{ # github.aw.import-inputs.. }}' expressions. # (optional) import-schema: {} --- ``` ## Additional Information [Section titled “Additional Information”](#additional-information) * Fields marked with `(optional)` are not required * Fields with multiple options show all possible formats * See the [Frontmatter guide](/gh-aw/reference/frontmatter/) for detailed explanations and examples * See individual reference pages for specific topics like [Triggers](/gh-aw/reference/triggers/), [Tools](/gh-aw/reference/tools/), and [Safe Outputs](/gh-aw/reference/safe-outputs/) # Frontmatter Hash Specification > Specification for computing deterministic hashes of agentic workflow frontmatter # Frontmatter Hash Specification [Section titled “Frontmatter Hash Specification”](#frontmatter-hash-specification) **Version**: 1.0.0\ **Status**: Draft\ **Publication Date**: 2026-05-07\ **Latest Version**: [frontmatter-hash-specification](/gh-aw/reference/frontmatter-hash-specification/)\ **Editor**: GitHub Agentic Workflows Team *** This document specifies the algorithm for computing a deterministic hash of agentic workflow frontmatter, including contributions from imported workflows. ## Purpose [Section titled “Purpose”](#purpose) The frontmatter hash provides: 1. **Stale lock detection**: Identify when the compiled lock file is out of sync with the source workflow (e.g. after editing the `.md` file without recompiling) 2. **Reproducibility**: Ensure identical configurations produce identical hashes across languages (Go and JavaScript) 3. **Change detection**: Verify that workflow configuration has not changed between compilation and execution ## Conformance [Section titled “Conformance”](#conformance) ### Conformance Classes [Section titled “Conformance Classes”](#conformance-classes) * **Basic Conformance**: An implementation MUST compute a deterministic SHA-256 hash from canonicalized frontmatter input and MUST produce the same output for identical input. * **Full Conformance**: An implementation MUST satisfy Basic Conformance and MUST implement cross-language consistency checks between Go and JavaScript implementations. ### Requirements Notation [Section titled “Requirements Notation”](#requirements-notation) The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). ## Hash Algorithm [Section titled “Hash Algorithm”](#hash-algorithm) ### 1. Input Collection [Section titled “1. Input Collection”](#1-input-collection) Collect all frontmatter from the main workflow and all imported workflows in **breadth-first order** (BFS traversal): 1. **Main workflow frontmatter**: The frontmatter from the root workflow file 2. **Imported workflow frontmatter**: Frontmatter from each imported file in BFS processing order * Includes transitively imported files (imports of imports) * Agent files (`.github/agents/*.md`) only contribute markdown content, not frontmatter #### BFS Traversal and Tie-Breaking Rules [Section titled “BFS Traversal and Tie-Breaking Rules”](#bfs-traversal-and-tie-breaking-rules) The BFS traversal processes imports level by level, starting from the root workflow. When a workflow imports multiple files, they are enqueued left-to-right in the order they appear in the `imports:` list. This ordering is preserved at every level. **Diamond-import handling**: If a workflow file appears more than once in the import graph (a “diamond” dependency), the **first occurrence** in BFS order determines where that file’s frontmatter is merged; all subsequent occurrences of the same file **MUST be silently skipped**. Implementations MUST detect duplicate import paths using canonical path comparison (case-sensitive, no trailing-slash normalization) and discard duplicates without error. **Example (diamond graph)**: ```plaintext root.md → imports: [a.md, b.md] a.md → imports: [shared.md] b.md → imports: [shared.md] ``` BFS queue order: `[root.md, a.md, b.md, shared.md]`\ `shared.md` appears twice but is processed only once (after `a.md` in queue order).\ Canonical hash input order: root → a → b → shared. If the root import list were reversed to `[b.md, a.md]`, the canonical order would be `root → b → a → shared`. The first sibling encountered in BFS order always claims the shared dependency. Later duplicates are skipped. This rule ensures that the hash is deterministic regardless of which traversal path first discovers a shared dependency. ### 2. Field Selection [Section titled “2. Field Selection”](#2-field-selection) Include the following frontmatter fields in the hash computation: **Core Configuration:** * `engine` - AI engine specification * `on` - Workflow triggers * `permissions` - GitHub Actions permissions * `tracker-id` - Workflow tracker identifier **Tool and Integration:** * `tools` - Tool configurations (GitHub, Playwright, etc.) * `mcp-servers` - MCP server configurations * `network` - Network access permissions * `safe-outputs` - Safe output configurations * `mcp-scripts` - Safe input configurations **Runtime Configuration:** * `runtimes` - Runtime version specifications (Node.js, Python, etc.) * `services` - Container services * `cache` - Caching configuration **Workflow Structure:** * `steps` - Custom workflow steps * `post-steps` - Post-execution steps * `jobs` - GitHub Actions job definitions **Metadata:** * `description` - Workflow description * `labels` - Workflow labels * `bots` - Authorized bot list * `timeout-minutes` - Workflow timeout * `secret-masking` - Secret masking configuration **Import Metadata:** * `imports` - List of imported workflow paths (for traceability) * `inputs` - Input parameter definitions **Excluded Fields:** * Markdown body content (not part of frontmatter) * Comments and whitespace variations * Field ordering (normalized during processing) ### 3. Canonical JSON Serialization [Section titled “3. Canonical JSON Serialization”](#3-canonical-json-serialization) Transform the collected frontmatter into a canonical JSON representation: #### 3.1 Merge Strategy [Section titled “3.1 Merge Strategy”](#31-merge-strategy) For each workflow in BFS order: 1. Parse frontmatter into a structured object 2. Merge with accumulated frontmatter using these rules: * **Replace**: `engine`, `on`, `tracker-id`, `description`, `timeout-minutes` * **Deep merge**: `tools`, `mcp-servers`, `network`, `permissions`, `runtimes`, `cache`, `services` * **Append**: `steps`, `post-steps`, `safe-outputs`, `mcp-scripts`, `jobs` * **Union**: `labels`, `bots` (deduplicated) * **Track**: `imports` (list of all imported paths) #### 3.2 Normalization Rules [Section titled “3.2 Normalization Rules”](#32-normalization-rules) Apply these normalization rules to ensure deterministic output: 1. **Key Sorting**: Sort all object keys alphabetically at every level 2. **Array Ordering**: Preserve array order as-is (no sorting of array elements) 3. **Whitespace**: Use minimal whitespace (no pretty-printing) 4. **Number Format**: Represent numbers without exponents (e.g., `120` not `1.2e2`) 5. **Boolean Values**: Use lowercase `true` and `false` 6. **Null Handling**: Include `null` values explicitly 7. **Empty Containers**: Include empty objects `{}` and empty arrays `[]` 8. **String Escaping**: Use JSON standard escaping (quotes, backslashes, control characters) #### 3.3 Serialization Format [Section titled “3.3 Serialization Format”](#33-serialization-format) The canonical JSON includes all frontmatter fields plus version information: ```json { "bots": ["copilot"], "cache": {}, "description": "Daily audit of workflow runs", "engine": "claude", "imports": ["shared/mcp/tavily.md", "shared/jqschema.md"], "jobs": {}, "labels": ["audit", "automation"], "mcp-servers": {}, "network": {"allowed": ["api.github.com"]}, "on": {"schedule": "daily"}, "permissions": {"actions": "read", "contents": "read"}, "post-steps": [], "runtimes": {"node": {"version": "20"}}, "mcp-scripts": {}, "safe-outputs": {"create-discussion": {"category": "audits"}}, "services": {}, "steps": [], "template-expressions": ["${{ env.MY_VAR }}"], "timeout-minutes": 30, "tools": {"repo-memory": {"branch-name": "memory/audit"}}, "tracker-id": "audit-workflows-daily", "versions": { "agents": "v0.0.84", "awf": "v0.11.2", "gh-aw": "dev" } } ``` ### 4. Version Information [Section titled “4. Version Information”](#4-version-information) The hash includes version numbers to ensure hash changes when dependencies are upgraded: * **gh-aw**: The compiler version (e.g., “0.1.0” or “dev”) * **awf**: The firewall version (e.g., “v0.11.2”) * **agents**: The MCP gateway version (e.g., “v0.0.84”) This ensures that upgrading any component invalidates existing hashes. 1. **Serialize**: Convert the merged and normalized frontmatter to canonical JSON 2. **Add Versions**: Include version information for gh-aw, awf (firewall), and agents (MCP gateway) 3. **Hash**: Compute SHA-256 hash of the JSON string (UTF-8 encoded) 4. **Encode**: Represent the hash as a lowercase hexadecimal string (64 characters) **Example:** ```plaintext Input JSON: {"engine":"copilot","on":{"schedule":"daily"},"versions":{"agents":"v0.0.84","awf":"v0.11.2","gh-aw":"dev"}} SHA-256: a1b2c3d4e5f6... (64 hex characters) ``` ### 5. Cross-Language Consistency [Section titled “5. Cross-Language Consistency”](#5-cross-language-consistency) Both Go and JavaScript implementations MUST: * Use the same field selection and merging rules * Produce identical canonical JSON (byte-for-byte) * Use SHA-256 hash function * Encode output as lowercase hexadecimal **Test cases** must verify identical hashes across both implementations for: * Empty frontmatter * Single-file workflows (no imports) * Multi-level imports (2+ levels deep) * All field types (strings, numbers, booleans, arrays, objects) * Special characters and escaping * All workflows in the repository ### 5.1 Cross-Language Validation Protocol [Section titled “5.1 Cross-Language Validation Protocol”](#51-cross-language-validation-protocol) The project maintains Go and JavaScript implementations of the frontmatter hash algorithm. A conforming change to either implementation MUST follow this validation protocol: 1. Update both implementations in the same change whenever the authoritative runtime algorithm or normalization behavior changes. 2. Execute the shared cross-language test vectors so each implementation validates the other implementation’s output, not just its own fixtures. 3. Treat any byte-level mismatch in canonical JSON or final SHA-256 output as a release-blocking failure until both implementations are aligned. 4. Recompile workflow lock files only after the cross-language checks pass, so newly generated hashes reflect a synchronized algorithm. **R-XLANG-001**: The shared validation corpus **MUST** include at least one empty-frontmatter case, one single-file case, one multi-level import case, and one diamond-import case. **R-XLANG-002**: A change that alters canonical JSON generation in either language **MUST** update the shared validation corpus in the same change. **R-XLANG-003**: CI or pre-release validation **MUST** fail if Go and JavaScript produce different hashes for any corpus member. ## Implementation Notes [Section titled “Implementation Notes”](#implementation-notes) ### Go Implementation [Section titled “Go Implementation”](#go-implementation) The current Go implementation (`pkg/parser/frontmatter_hash.go`) uses a **text-based approach** that diverges from the field-selection model described in Section 2 (“Field Selection”) of this specification: * **Actual behavior**: The entire normalized frontmatter text is hashed as a single opaque string (`frontmatter-text` key in the canonical JSON), alongside a sorted list of imported file paths and their normalized texts. This means *all* frontmatter fields — including excluded ones such as comments — affect the hash value. * **Specified behavior**: The specification calls for selecting individual named fields and merging them by type (replace, deep-merge, append, union). **Implication**: The text-based approach is more conservative (any frontmatter change invalidates the hash, including whitespace-only changes after normalization) and simpler to implement cross-language. The trade-off is that it cannot support selective field exclusion without modifying the text normalization step. **Sync status** (verified 2026-05-06): The Go implementation is consistent with the JavaScript implementation in `actions/setup/js/` for the text-based approach. Both produce identical hashes for the same input. The field-selection model in Section 2 documents the *logical* intent; the text-based implementation is the authoritative runtime behavior until a future revision aligns them. **Resolution** (2026-05-08): The project officially adopts the **text-based approach** as the authoritative runtime behavior (option b). Section 2 (“Field Selection”) documents the intended logical model for future alignment, but is non-normative until a dedicated migration milestone is scheduled. No immediate changes to the Go or JavaScript implementations are required. A future v2.0.0 revision of this specification MAY align both implementations to the field-selection model if selective field exclusion becomes a concrete requirement; that revision MUST include updated cross-language test vectors and a migration guide. Until then, implementations MUST continue to use the text-based approach and MUST NOT selectively exclude fields from the hash input. * Use `crypto/sha256` for hashing (`crypto/sha256.Sum256`) * Use `hex.EncodeToString()` for hexadecimal encoding ### JavaScript Implementation [Section titled “JavaScript Implementation”](#javascript-implementation) * Uses the same text-based approach as the Go implementation * Uses Node.js `crypto.createHash('sha256')` for hashing * Uses `.digest('hex')` for hexadecimal encoding * The JavaScript cross-language test suite in `pkg/parser/frontmatter_hash_cross_language_test.go` verifies identical output between the two implementations ### Hash Storage and Verification [Section titled “Hash Storage and Verification”](#hash-storage-and-verification) 1. **Compilation**: The Go compiler computes the hash and writes it to the workflow log file 2. **Execution**: The JavaScript custom action: * Reads the hash from the log file * Recomputes the hash from the workflow file * Compares the two hashes * Creates a GitHub issue if they differ (indicating frontmatter modification) ## Safeguards [Section titled “Safeguards”](#safeguards) This section describes known risks associated with the frontmatter hash mechanism and the recommended mitigations. ### S-1: Hash Collision Risk [Section titled “S-1: Hash Collision Risk”](#s-1-hash-collision-risk) SHA-256 produces a 256-bit output, giving a collision probability of approximately 2⁻¹²⁸ for any two distinct inputs under the birthday paradox. For the expected number of compiled workflows in a repository (typically <10,000), the probability of an accidental collision is negligible and does not require mitigation at the application layer. However, implementations MUST NOT rely on the hash as a cryptographic commitment or security boundary. The hash is an integrity check for stale-lock detection only. **Mitigation**: If future use cases require stronger collision resistance (e.g., content-addressed storage), implementations SHOULD upgrade to SHA-512 or SHA3-256 and bump the specification version. ### S-2: Tamper Detection Limits [Section titled “S-2: Tamper Detection Limits”](#s-2-tamper-detection-limits) The frontmatter hash detects accidental drift between the `.md` source and the compiled `.lock.yml` file. It does **not** prevent intentional tampering. Any user with write access to the repository can modify both files simultaneously: 1. Edit the `.md` source. 2. Recompile to regenerate the `.lock.yml` with the new hash. 3. Commit both files in a single push. This bypass is by design — the hash mechanism is intended to catch *accidental* stale locks, not to enforce a security boundary. **Mitigation**: Enforce required code reviews via branch protection rules. Require signed commits for critical workflows. Use separate compilation and merge workflows with protected branches to prevent direct pushes to the default branch. ### S-3: Inclusion of Sensitive Configuration in Hash Input [Section titled “S-3: Inclusion of Sensitive Configuration in Hash Input”](#s-3-inclusion-of-sensitive-configuration-in-hash-input) The canonical JSON used for hash computation includes all frontmatter fields, some of which may encode sensitive topology information (e.g., MCP server addresses in `mcp-servers:`, secret names in `mcp-scripts:`, or branch names in `tools.repo-memory`). This information is embedded in the `.lock.yml` file at compile time and is visible to anyone who can read the repository. **Mitigation**: Treat repository visibility as the primary access control boundary. Avoid storing secret *values* in frontmatter (use GitHub Actions secrets instead). Periodically audit lock files for inadvertently committed sensitive configuration. ### S-4: Version-Bump-Forced Recompilation [Section titled “S-4: Version-Bump-Forced Recompilation”](#s-4-version-bump-forced-recompilation) The hash includes `versions.gh-aw`, `versions.awf`, and `versions.agents`. Upgrading any of these components will invalidate all existing hashes, triggering stale-lock warnings on all workflows until they are recompiled. In a repository with many workflows, this can create a noisy wave of false-positive stale-lock issues. **Mitigation**: Coordinate component upgrades with a bulk `make recompile` step. Automate recompilation in the upgrade PR so that lock files are always fresh after a version bump. ### S-5: Cross-Language Hash Divergence [Section titled “S-5: Cross-Language Hash Divergence”](#s-5-cross-language-hash-divergence) The Go and JavaScript implementations must produce byte-for-byte identical canonical JSON. Any divergence in key sorting, number representation, or null/undefined handling between the two implementations will cause the JavaScript runtime to report a false stale-lock mismatch for every workflow run. **Mitigation**: Maintain a shared test-vector file (at minimum: empty frontmatter, single-field workflow, multi-level imports, all field types). Run cross-language hash tests in CI. Any change to the serialization algorithm in either language MUST be accompanied by updated test vectors verified against both implementations. ### S-6: Maximum Frontmatter Input Size [Section titled “S-6: Maximum Frontmatter Input Size”](#s-6-maximum-frontmatter-input-size) Very large frontmatter payloads can cause excessive memory use and hash-computation latency during compilation and runtime verification. This can degrade CI reliability and increase stale-lock false positives due to timeout or resource pressure. **Mitigation**: Implementations SHOULD enforce a maximum cumulative frontmatter input size and MUST fail deterministically with a descriptive error when the limit is exceeded. A limit of 1 MiB for the combined normalized frontmatter input is RECOMMENDED unless repository-specific requirements justify a higher bound. *** ## Sync Notes [Section titled “Sync Notes”](#sync-notes) This section maps the frontmatter hash specification to the source files that implement it. Use this mapping to verify that specification changes are reflected in both implementations. | Component | File(s) | | --------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Go hash computation | `pkg/parser/frontmatter_hash.go` (`computeFrontmatterHashTextBased`, `computeFrontmatterHashTextBasedWithReader`) | | JavaScript hash computation | `actions/setup/js/frontmatter_hash.cjs` | | Cross-language test | `pkg/parser/frontmatter_hash_cross_language_test.go` | | Text normalization | `pkg/parser/frontmatter_hash.go` (`normalizeFrontmatterText`) | | Import processing | `pkg/parser/frontmatter_hash.go` (`processImportsTextBased`) | **After any change to the hash algorithm:** 1. Update the Go implementation in `pkg/parser/frontmatter_hash.go` 2. Update the JavaScript implementation in `actions/setup/js/frontmatter_hash.cjs` 3. Run the cross-language test: `go test ./pkg/parser/ -run TestFrontmatterHash` 4. Run `make recompile` to regenerate all lock files with fresh hashes 5. Verify cross-language consistency for the test cases listed in Section 5 6. Verify BFS diamond-import tie-breaking remains deterministic: when the same imported file is reachable through multiple import paths at the same depth, the canonical traversal MUST prefer first-seen path order and MUST NOT duplicate imported content in hash input. **Runtime behavior**: text-based approach is authoritative (see Implementation Notes § Resolution). **Resolution log (2026-05-08, authoritative)**: Text-based canonicalization is the resolved, runtime-authoritative algorithm. Section 2 field-selection remains future-state design intent only until an explicit migration milestone is approved. **Sync verification (2026-05-12)**: SPDD review reconfirmed that the 2026-05-08 text-based resolution remains in force. *** ## Security Considerations [Section titled “Security Considerations”](#security-considerations) * The hash is **not cryptographically secure** for authentication (no HMAC/signing) * The hash is designed to **detect stale lock files** — it catches cases where the frontmatter has changed since the lock file was last compiled * The hash **does not guarantee tamper protection**: anyone with write access to the repository can modify both the `.md` source and the `.lock.yml` file together, bypassing detection * Always validate workflow sources through proper code review processes ## Versioning [Section titled “Versioning”](#versioning) This is version 1.0 of the frontmatter hash specification. Future versions may: * Add additional fields * Change normalization rules * Use different hash algorithms Version changes will be documented and backward compatibility maintained where possible. ### Future Versions (v2.0.0 Planning) [Section titled “Future Versions (v2.0.0 Planning)”](#future-versions-v200-planning) Per the **Resolution (2026-05-08)** in Implementation Notes, the text-based algorithm remains authoritative until a dedicated migration milestone is approved. Tracking issue: [#31983](https://github.com/github/gh-aw/issues/31983) The project **MUST NOT** schedule a v2.0.0 migration to the field-selection model until all of the following tracked tasks are complete: * [ ] Confirm and document a selective field-exclusion use case in [#31983](https://github.com/github/gh-aw/issues/31983). * [ ] Draft a migration guide in [#31983](https://github.com/github/gh-aw/issues/31983), including lock-file invalidation and recompilation steps. * [ ] Write candidate v2.0.0 cross-language test vectors in [#31983](https://github.com/github/gh-aw/issues/31983) and verify they pass in CI. * [ ] Approve a rollout plan in [#31983](https://github.com/github/gh-aw/issues/31983), including backward-compatibility impact analysis. Until these prerequisites are met, implementations **MUST** continue using the text-based algorithm and **MUST NOT** selectively exclude frontmatter fields from hash input. ## Appendix A: Cross-Language Test Vectors (Text-Based Algorithm) [Section titled “Appendix A: Cross-Language Test Vectors (Text-Based Algorithm)”](#appendix-a-cross-language-test-vectors-text-based-algorithm) The following vectors are normative for the current authoritative text-based algorithm. Validation status: Each vector hash is verified to match in both implementations via automated cross-language tests in CI. ### FH-TV-001 [Section titled “FH-TV-001”](#fh-tv-001) Expected hash: `4c8309afbcf816cd80c0824dce2b50047834b29e14b34b96953e88ae81048c46` This vector represents an intentionally empty frontmatter block (`---` followed immediately by `---`) rather than a file with no frontmatter delimiter. These are treated as different input forms for conformance testing and MUST be validated independently; this vector defines only the explicit-empty-block form. ```yaml --- --- # Empty Workflow ``` ### FH-TV-002 [Section titled “FH-TV-002”](#fh-tv-002) Expected hash: `b9def9907e3328e2e03e8c47c315723df39788f251627313b1a984bb61b9cbce` ```yaml --- engine: copilot description: Test workflow on: schedule: daily --- # Test Workflow ``` ### FH-TV-003 [Section titled “FH-TV-003”](#fh-tv-003) Expected hash: `8c63a05ef42cbfaff9be87a06257282cb4dcb952f71481d9d65ec3037003dbe8` ```yaml --- engine: claude description: Complex workflow tracker-id: complex-test timeout-minutes: 30 on: schedule: daily workflow_dispatch: true permissions: contents: read actions: read tools: playwright: version: v1.41.0 labels: - test - complex bots: - copilot --- # Complex Workflow ``` ### FH-TV-004 [Section titled “FH-TV-004”](#fh-tv-004) Expected hash: `701dc12776a417c6ce4c82b16d1fcc9de343130efb554fda27a701386b17d134` This vector validates deterministic hash input when frontmatter includes agent file imports. It also exercises BFS diamond-import tie-breaking where multiple import branches reference the same transitive file. ```yaml --- engine: copilot imports: - ./agents/router.agent.md - ./agents/summarizer.agent.md --- # Import-based Workflow ``` # Fuzzy Schedule Time Syntax Specification > Formal specification for the fuzzy schedule time syntax following W3C conventions **Version**: 1.2.0 **Status**: Draft Specification\ **Latest Version**: [fuzzy-schedule-specification](/gh-aw/reference/fuzzy-schedule-specification/)\ **Editor**: GitHub Agentic Workflows Team *** ## Abstract [Section titled “Abstract”](#abstract) This specification defines the Fuzzy Schedule Time Syntax, a human-friendly scheduling language for GitHub Agentic Workflows that automatically distributes workflow execution times to prevent server load spikes. The syntax supports daily, hourly, weekly, and interval-based schedules with optional time constraints and timezone conversions. The specification includes a deterministic scattering algorithm that uses hash functions to assign consistent execution times to workflows based on their identifiers, ensuring predictable behavior across multiple compilations while distributing load across an organization’s infrastructure. ## Status of This Document [Section titled “Status of This Document”](#status-of-this-document) This section describes the status of this document at the time of publication. This is a draft specification and may be updated, replaced, or made obsolete by other documents at any time. This document is governed by the GitHub Agentic Workflows project specifications process. ## Table of Contents [Section titled “Table of Contents”](#table-of-contents) 1. [Introduction](#1-introduction) 2. [Conformance](#2-conformance) 3. [Core Syntax](#3-core-syntax) 4. [Time Specifications](#4-time-specifications) 5. [Timezone Support](#5-timezone-support) 6. [Scattering Algorithm](#6-scattering-algorithm) 7. [Cron Expression Generation](#7-cron-expression-generation) 8. [Safeguards](#8-safeguards) 9. [Error Handling](#9-error-handling) 10. [Compliance Testing](#10-compliance-testing) 11. [Sync Notes](#11-sync-notes) 12. [Calendar Output Schema](#12-calendar-output-schema) *** ## 1. Introduction [Section titled “1. Introduction”](#1-introduction) ### 1.1 Purpose [Section titled “1.1 Purpose”](#11-purpose) The Fuzzy Schedule Time Syntax addresses the problem of server load spikes that occur when multiple workflows execute simultaneously using fixed-time schedules. Traditional cron expressions require explicit time specifications, leading developers to commonly use convenient times (e.g., midnight, on-the-hour) that create load concentration. This specification defines a natural language syntax that automatically distributes execution times while preserving schedule semantics. ### 1.2 Scope [Section titled “1.2 Scope”](#12-scope) This specification covers: * Natural language schedule expressions for daily, hourly, weekly, and interval-based schedules * Time constraint syntax using `around` and `between` modifiers * Timezone conversion syntax for local-to-UTC time translation * Deterministic scattering algorithm for execution time distribution * Cron expression generation from fuzzy syntax * Validation requirements and error handling This specification does NOT cover: * Standard cron expression syntax (handled by GitHub Actions) * Monthly or yearly schedule patterns * Dynamic schedule adjustment based on load metrics * Schedule conflict resolution between workflows ### 1.3 Design Goals [Section titled “1.3 Design Goals”](#13-design-goals) This specification prioritizes: 1. **Human readability**: Natural language expressions that clearly communicate intent 2. **Load distribution**: Automatic scattering prevents simultaneous workflow execution 3. **Determinism**: Same workflow identifier always produces same execution time 4. **Predictability**: Execution times remain consistent across recompilations 5. **Timezone awareness**: Support for local time specifications with UTC conversion *** ## 2. Conformance [Section titled “2. Conformance”](#2-conformance) ### 2.1 Conformance Classes [Section titled “2.1 Conformance Classes”](#21-conformance-classes) A **conforming implementation** is a parser that satisfies all MUST, MUST NOT, REQUIRED, SHALL, and SHALL NOT requirements in this specification. A **conforming fuzzy schedule expression** is a schedule string that conforms to the syntax grammar defined in Section 3 and produces a valid fuzzy cron placeholder. A **conforming scattering implementation** is an implementation that satisfies all scattering algorithm requirements in Section 6. ### 2.2 Requirements Notation [Section titled “2.2 Requirements Notation”](#22-requirements-notation) The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). ### 2.3 Compliance Levels [Section titled “2.3 Compliance Levels”](#23-compliance-levels) **Level 1 (Basic)**: Supports daily and weekly schedules without time constraints **Level 2 (Standard)**: Adds support for time constraints (`around`, `between`) and hourly schedules **Level 3 (Complete)**: Includes timezone conversion, interval schedules, and bi-weekly/tri-weekly patterns *** ## 3. Core Syntax [Section titled “3. Core Syntax”](#3-core-syntax) ### 3.1 Grammar Definition [Section titled “3.1 Grammar Definition”](#31-grammar-definition) A fuzzy schedule expression MUST conform to the following ABNF grammar: ```text fuzzy-schedule = daily-schedule / hourly-schedule / weekly-schedule / interval-schedule daily-schedule = "daily" [time-constraint] weekly-schedule = "weekly" ["on" weekday] [time-constraint] hourly-schedule = "hourly" / ("every" hour-interval) interval-schedule = "every" (minute-interval / hour-interval / day-interval / week-interval) time-constraint = around-constraint / between-constraint around-constraint = "around" time-spec between-constraint = "between" time-spec "and" time-spec time-spec = (hour-24 ":" minute) [utc-offset] / (hour-12 am-pm) [utc-offset] / time-keyword [utc-offset] time-keyword = "midnight" / "noon" am-pm = "am" / "pm" utc-offset = "utc" ("+" / "-") (hours / hours ":" minutes) weekday = "sunday" / "monday" / "tuesday" / "wednesday" / "thursday" / "friday" / "saturday" hour-24 = 1*2DIGIT ; 0-23 hour-12 = 1*2DIGIT ; 1-12 minute = 2DIGIT ; 00-59 hours = 1*2DIGIT minutes = 2DIGIT minute-interval = 1*DIGIT ("m" / "minutes" / "minute") hour-interval = 1*DIGIT ("h" / "hours" / "hour") day-interval = 1*DIGIT ("d" / "days" / "day") week-interval = 1*DIGIT ("w" / "weeks" / "week") ``` ### 3.2 Daily Schedules [Section titled “3.2 Daily Schedules”](#32-daily-schedules) #### 3.2.1 Basic Daily Schedule [Section titled “3.2.1 Basic Daily Schedule”](#321-basic-daily-schedule) A basic daily schedule expression SHALL take the form: ```yaml daily ``` An implementation MUST generate a fuzzy cron placeholder: `FUZZY:DAILY * * *` The execution time SHALL be deterministically scattered across all 24 hours and 60 minutes of the day. #### 3.2.2 Daily Around Time [Section titled “3.2.2 Daily Around Time”](#322-daily-around-time) A daily around schedule expression SHALL take the form: ```yaml daily around ``` An implementation MUST generate a fuzzy cron placeholder: `FUZZY:DAILY_AROUND:HH:MM * * *` The execution time SHALL be scattered within a ±60 minute window around the specified time. **Example**: ```yaml daily around 14:00 # Generates: FUZZY:DAILY_AROUND:14:0 * * * # Scatters within window: 13:00 to 15:00 ``` #### 3.2.3 Daily Between Times [Section titled “3.2.3 Daily Between Times”](#323-daily-between-times) A daily between schedule expression SHALL take the form: ```yaml daily between and ``` An implementation MUST generate a fuzzy cron placeholder: `FUZZY:DAILY_BETWEEN:START_H:START_M:END_H:END_M * * *` The execution time SHALL be scattered uniformly within the specified time range, including handling of midnight-crossing ranges. **Example**: ```yaml daily between 9:00 and 17:00 # Generates: FUZZY:DAILY_BETWEEN:9:0:17:0 * * * # Scatters within window: 09:00 to 17:00 daily between 22:00 and 02:00 # Generates: FUZZY:DAILY_BETWEEN:22:0:2:0 * * * # Scatters within window: 22:00 to 02:00 (crossing midnight) ``` ### 3.3 Weekly Schedules [Section titled “3.3 Weekly Schedules”](#33-weekly-schedules) #### 3.3.1 Basic Weekly Schedule [Section titled “3.3.1 Basic Weekly Schedule”](#331-basic-weekly-schedule) A basic weekly schedule expression SHALL take the form: ```yaml weekly ``` An implementation MUST generate a fuzzy cron placeholder: `FUZZY:WEEKLY * * *` The execution SHALL be scattered across all seven days of the week and all hours/minutes of each day. #### 3.3.2 Weekly with Day Specification [Section titled “3.3.2 Weekly with Day Specification”](#332-weekly-with-day-specification) A weekly day schedule expression SHALL take the form: ```yaml weekly on ``` An implementation MUST generate a fuzzy cron placeholder: `FUZZY:WEEKLY:DOW * * DOW` **Example**: ```yaml weekly on monday # Generates: FUZZY:WEEKLY:1 * * 1 # Scatters across all hours on Monday ``` #### 3.3.3 Weekly with Time Constraints [Section titled “3.3.3 Weekly with Time Constraints”](#333-weekly-with-time-constraints) A weekly schedule MAY include time constraints using `around` or `between`: ```yaml weekly on around weekly on between and ``` **Example**: ```yaml weekly on friday around 17:00 # Generates: FUZZY:WEEKLY:5:AROUND:17:0 * * 5 # Scatters Friday 16:00-18:00 ``` ### 3.4 Hourly Schedules [Section titled “3.4 Hourly Schedules”](#34-hourly-schedules) #### 3.4.1 Basic Hourly Schedule [Section titled “3.4.1 Basic Hourly Schedule”](#341-basic-hourly-schedule) A basic hourly schedule expression SHALL take the form: ```yaml hourly ``` An implementation MUST generate a fuzzy cron placeholder: `FUZZY:HOURLY * * *` The minute offset SHALL be scattered across 0-59 minutes but remain consistent for each hour. **Example**: ```yaml hourly # Generates: FUZZY:HOURLY * * * # Might scatter to: 43 * * * * (runs at minute 43 every hour) ``` #### 3.4.2 Hour Interval Schedules [Section titled “3.4.2 Hour Interval Schedules”](#342-hour-interval-schedules) An hour interval schedule expression SHALL take the form: ```yaml every h every hours every hour ``` Where `` MUST be a positive integer. An implementation MUST generate a fuzzy cron placeholder: `FUZZY:HOURLY: * * *` Valid hour intervals SHOULD be: 1, 2, 3, 4, 6, 8, 12 (factors of 24 for even distribution). **Example**: ```yaml every 2h # Generates: FUZZY:HOURLY:2 * * * # Might scatter to: 53 */2 * * * (runs at minute 53 every 2 hours) ``` ### 3.5 Special Period Schedules [Section titled “3.5 Special Period Schedules”](#35-special-period-schedules) #### 3.5.1 Bi-weekly Schedule [Section titled “3.5.1 Bi-weekly Schedule”](#351-bi-weekly-schedule) A bi-weekly schedule expression SHALL take the form: ```yaml bi-weekly ``` An implementation MUST generate a fuzzy cron placeholder: `FUZZY:BI-WEEKLY * * *` The schedule SHALL execute once every 14 days with scattered time. #### 3.5.2 Tri-weekly Schedule [Section titled “3.5.2 Tri-weekly Schedule”](#352-tri-weekly-schedule) A tri-weekly schedule expression SHALL take the form: ```yaml tri-weekly ``` An implementation MUST generate a fuzzy cron placeholder: `FUZZY:TRI-WEEKLY * * *` The schedule SHALL execute once every 21 days with scattered time. ### 3.6 Interval Schedules [Section titled “3.6 Interval Schedules”](#36-interval-schedules) An interval schedule expression SHALL take the form: ```yaml every ``` Where: * `` MUST be a positive integer * `` MUST be one of: `minutes`, `minute`, `m`, `hours`, `hour`, `h`, `days`, `day`, `d`, `weeks`, `week`, `w` An implementation MUST generate appropriate cron expressions based on the unit: * Minutes: `*/N * * * *` (minimum N=5 per GitHub Actions constraint) * Hours: `FUZZY:HOURLY:N * * *` (scattered minute) * Days: `0 0 */N * *` (fixed midnight) * Weeks: `0 0 */N*7 * *` (fixed Sunday midnight) **Example**: ```yaml every 5 minutes # Generates: */5 * * * * every 6h # Generates: FUZZY:HOURLY:6 * * * every 2 days # Generates: 0 0 */2 * * ``` ### 3.7 Error Norms for Invalid Schedule Expressions [Section titled “3.7 Error Norms for Invalid Schedule Expressions”](#37-error-norms-for-invalid-schedule-expressions) The following table specifies normative behavior (MUST/SHALL requirements) for malformed or unrecognizable fuzzy schedule expressions encountered during compilation. These norms apply at parse time (when the compiler processes the workflow frontmatter) and at test time (when the compliance test suite exercises the parser with invalid inputs). | # | Error Condition | Input Example | MUST/SHALL Behavior | Error Code | | ---- | ----------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | E-01 | Unknown schedule keyword (not one of `daily`, `weekly`, `hourly`, `bi-weekly`, `tri-weekly`, `every`) | `monthly` | Implementation MUST reject with a descriptive error naming the unrecognized keyword and listing valid keywords | `UNKNOWN_KEYWORD` | | E-02 | Out-of-range hour in 24-hour format | `daily around 25:00` | Implementation MUST reject; the error message MUST state the valid hour range (0–23) and the offending value | `HOUR_OUT_OF_RANGE` | | E-03 | Out-of-range minute | `daily around 14:65` | Implementation MUST reject; the error message MUST state the valid minute range (0–59) and the offending value | `MINUTE_OUT_OF_RANGE` | | E-04 | `around` keyword with no time specification | `daily around` | Implementation MUST reject; the error message MUST include an example of correct `around` usage | `MISSING_TIME_SPEC` | | E-05 | `between` keyword with only one time argument | `daily between 9:00` | Implementation MUST reject; the error message MUST state that `between` requires both a start and an end time connected by `and` | `INCOMPLETE_RANGE` | | E-06 | `between` range where start equals end | `daily between 14:00 and 14:00` | Implementation MUST reject; a zero-duration window cannot scatter execution times | `ZERO_DURATION_RANGE` | | E-07 | Unknown weekday in `weekly on ` | `weekly on mondey` | Implementation MUST reject with a did-you-mean suggestion when the input differs from a valid weekday by one character | `UNKNOWN_WEEKDAY` | | E-08 | Invalid interval unit | `every 5 fortnights` | Implementation MUST reject; the error message MUST list valid units (`minutes`, `hours`, `days`, `weeks` and their abbreviations) | `UNKNOWN_UNIT` | | E-09 | Interval value below minimum allowed by GitHub Actions | `every 2 minutes` | Implementation MUST reject; the error message MUST state the minimum permitted interval (5 minutes for the `minutes` unit) and the GitHub Actions constraint source | `INTERVAL_TOO_SMALL` | | E-10 | Non-integer interval value | `every 1.5 hours` | Implementation MUST reject; fractional interval values are not supported | `NON_INTEGER_INTERVAL` | **Normative notes**: * All error messages MUST be directed to the user’s console (stderr) and MUST be human-readable. * Implementations MUST NOT silently fall back to a default schedule when the input is invalid; all errors in rows E-01 through E-10 MUST cause compilation to fail with a non-zero exit code. * Implementations SHOULD NOT attempt automatic correction of the schedule expression. Actionable correction guidance in the error message is preferred over silent fixup. *** ## 4. Time Specifications [Section titled “4. Time Specifications”](#4-time-specifications) ### 4.1 Time Format Requirements [Section titled “4.1 Time Format Requirements”](#41-time-format-requirements) An implementation MUST support the following time formats: #### 4.1.1 24-Hour Format [Section titled “4.1.1 24-Hour Format”](#411-24-hour-format) The 24-hour format SHALL use the pattern `HH:MM`: * Hours MUST be in range 0-23 * Minutes MUST be in range 0-59 * Leading zeros MAY be omitted for hours * Minutes MUST use two digits with leading zero if necessary **Valid examples**: `00:00`, `9:30`, `14:00`, `23:59` #### 4.1.2 12-Hour Format [Section titled “4.1.2 12-Hour Format”](#412-12-hour-format) The 12-hour format SHALL use the pattern `H[H]am` or `H[H]pm`: * Hours MUST be in range 1-12 * AM/PM indicator MUST be lowercase `am` or `pm` * Minutes MAY be omitted (defaults to :00) * Colon and minutes MAY be included (e.g., `3:30pm`) **Valid examples**: `1am`, `12pm`, `11pm`, `9am`, `3:30pm` **Conversion rules**: * `12am` converts to 00:00 (midnight) * `12pm` converts to 12:00 (noon) * `1am-11am` converts to 01:00-11:00 * `1pm-11pm` converts to 13:00-23:00 #### 4.1.3 Time Keywords [Section titled “4.1.3 Time Keywords”](#413-time-keywords) An implementation MUST support the following time keywords: * `midnight`: Represents 00:00 (start of day) * `noon`: Represents 12:00 (middle of day) Keywords MUST be case-insensitive. ### 4.2 Time Range Requirements [Section titled “4.2 Time Range Requirements”](#42-time-range-requirements) #### 4.2.1 Window Specification [Section titled “4.2.1 Window Specification”](#421-window-specification) When using `around `, the implementation MUST use a ±60 minute window centered on the specified time. The window MUST handle day boundaries correctly: * `around 00:30` creates window: 23:30 (previous day) to 01:30 * `around 23:30` creates window: 22:30 to 00:30 (next day) #### 4.2.2 Range Specification [Section titled “4.2.2 Range Specification”](#422-range-specification) When using `between and `, the implementation MUST: 1. Accept ranges within a single day (e.g., `9:00` to `17:00`) 2. Accept ranges crossing midnight (e.g., `22:00` to `02:00`) 3. Calculate range size correctly for midnight-crossing ranges 4. Distribute scattered times uniformly within the range For midnight-crossing ranges where start > end: * Range size = (24\*60 - start\_minutes) + end\_minutes **Example**: ```yaml between 22:00 and 02:00 # Range: 22:00, 22:01, ..., 23:59, 00:00, ..., 02:00 # Duration: 4 hours (240 minutes) ``` *** ## 5. Timezone Support [Section titled “5. Timezone Support”](#5-timezone-support) ### 5.1 UTC Offset Syntax [Section titled “5.1 UTC Offset Syntax”](#51-utc-offset-syntax) An implementation MUST support UTC offset specifications using the format: ```text utc-offset = "utc" ("+" / "-") offset-value offset-value = hours / hours ":" minutes ``` Where: * `hours` MAY be 1 or 2 digits * `minutes` MUST be 2 digits when specified * Offset MUST be in range UTC-12:00 to UTC+14:00 **Valid examples**: `utc+9`, `utc-5`, `utc+05:30`, `utc-08:00` ### 5.2 Timezone Conversion [Section titled “5.2 Timezone Conversion”](#52-timezone-conversion) #### 5.2.1 Conversion Algorithm [Section titled “5.2.1 Conversion Algorithm”](#521-conversion-algorithm) When a UTC offset is specified, the implementation MUST: 1. Parse the local time value 2. Parse the UTC offset value (in minutes) 3. Subtract the offset from the local time to get UTC time 4. Handle day wrapping correctly **Formula**: `UTC_time = local_time - offset` **Example**: ```plaintext local_time = 14:00 (2 PM) offset = +9 hours (JST) UTC_time = 14:00 - 9:00 = 05:00 (5 AM UTC) ``` #### 5.2.2 Day Boundary Handling [Section titled “5.2.2 Day Boundary Handling”](#522-day-boundary-handling) The implementation MUST handle day boundaries when converting times: * Negative results MUST wrap to previous day (add 24 hours) * Results ≥24:00 MUST wrap to next day (subtract 24 hours) * Wrap operations MUST preserve minute precision **Example**: ```plaintext local_time = 02:00 (2 AM) offset = +9 hours UTC_time = 02:00 - 9:00 = -7:00 → 17:00 (previous day) ``` ### 5.3 Common Timezone Abbreviations [Section titled “5.3 Common Timezone Abbreviations”](#53-common-timezone-abbreviations) An implementation SHOULD recognize common timezone abbreviations: | Abbreviation | UTC Offset | Notes | | ------------ | ---------- | --------------------- | | PST | UTC-8 | Pacific Standard Time | | PDT | UTC-7 | Pacific Daylight Time | | EST | UTC-5 | Eastern Standard Time | | EDT | UTC-4 | Eastern Daylight Time | | JST | UTC+9 | Japan Standard Time | | IST | UTC+5:30 | India Standard Time | Implementations MAY issue warnings for ambiguous abbreviations (e.g., “PT” could be PST or PDT). DST transition behavior: * Abbreviation-based schedules MUST resolve to their explicit UTC offset at parse time (`PST=-08:00`, `PDT=-07:00`, etc.) and MUST NOT infer locale-specific daylight-saving transitions dynamically. * During DST spring-forward and fall-back transitions, schedule scattering MUST remain stable for the same canonical UTC offset input and workflow identifier. * Implementations SHOULD emit an informational warning when ambiguous abbreviations are used near DST transition dates so operators can switch to explicit `utc±HH[:MM]` notation. *** ## 6. Scattering Algorithm [Section titled “6. Scattering Algorithm”](#6-scattering-algorithm) ### 6.1 Algorithm Purpose [Section titled “6.1 Algorithm Purpose”](#61-algorithm-purpose) The scattering algorithm MUST provide: 1. **Determinism**: Same workflow identifier produces same scattered time 2. **Distribution**: Scattered times distribute evenly across the allowed range 3. **Stability**: Scattered times remain constant across recompilations 4. **Uniqueness**: Different workflow identifiers produce different scattered times The scattering algorithm uses the following formal input entities: | Entity | Type | Constraints | Description | | --------------------- | ----------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `workflow_identifier` | string | MUST be non-empty; SHOULD use `owner/repo/path/to/workflow.md` format | Canonical identifier hashed for deterministic scatter selection | | `schedule_string` | string | MUST match a supported fuzzy placeholder form (`FUZZY:*`) | Parsed schedule expression that determines algorithm branch | | `seed` | unsigned 32-bit integer | MUST be derived deterministically from `workflow_identifier` using the configured hash function | Hash-derived seed used for modulo operations | | `window_minutes` | integer | MUST be positive; MUST NOT exceed 1440 | Candidate-minute search window for around/between scattering | ### 6.2 Hash Function Requirements [Section titled “6.2 Hash Function Requirements”](#62-hash-function-requirements) #### 6.2.1 Hash Algorithm Selection [Section titled “6.2.1 Hash Algorithm Selection”](#621-hash-algorithm-selection) An implementation MUST use a hash function that satisfies the following requirements: 1. **Determinism**: The hash function MUST produce the same output for the same input across all platforms and executions 2. **Distribution**: The hash function SHOULD produce uniformly distributed outputs across the hash space 3. **Stability**: The hash function MUST NOT change behavior across different versions of the implementation 4. **Integer output**: The hash function MUST produce an integer output suitable for modulo operations **R-HASH-001**: For a fixed `workflow_identifier` and canonical fuzzy schedule expression, implementations MUST preserve hash-derived scatter output across minor version upgrades. Any planned change that would alter hash output for existing identifiers MUST be treated as a breaking change and documented with migration guidance. An implementation SHOULD use the FNV-1a (Fowler-Noll-Vo) 32-bit hash algorithm as a reference implementation: ```plaintext hash = FNV_offset_basis for each byte in input: hash = hash XOR byte hash = hash * FNV_prime return hash Where: FNV_offset_basis = 2166136261 (0x811c9dc5) FNV_prime = 16777619 (0x01000193) ``` Other suitable hash functions MAY be used, such as MurmurHash, xxHash, or CityHash, provided they meet the above requirements. #### 6.2.2 Workflow Identifier Format [Section titled “6.2.2 Workflow Identifier Format”](#622-workflow-identifier-format) The workflow identifier used for hashing MUST be constructed as: ```plaintext workflow_identifier = repository_slug + "/" + workflow_file_path ``` Where: * `repository_slug` is the format `owner/repo` * `workflow_file_path` is the relative path from repository root **Example**: `github/gh-aw/.github/workflows/daily-report.md` This format ensures workflows with the same filename in different repositories receive different execution times. ### 6.3 Scattering Ranges [Section titled “6.3 Scattering Ranges”](#63-scattering-ranges) #### 6.3.1 Daily Schedule Scattering [Section titled “6.3.1 Daily Schedule Scattering”](#631-daily-schedule-scattering) For `FUZZY:DAILY * * *` and `FUZZY:DAILY_WEEKDAYS * * *`, an implementation MUST use the **weighted daily time slot pool** to select execution time: 1. Construct a weighted pool of (hour, minute) time slots using three preference tiers: * **BEST** (weight 3): hours 02–05 UTC, odd minutes `{7, 13, 23, 37, 43, 53}` → 72 slots * **GOOD** (weight 2): hours 10–12 UTC, minutes `[5, 54]` → 300 slots * **OK** (weight 1): hours 19–23 UTC, minutes `[5, 54]` → 250 slots * Total pool size: 622 slots 2. Select slot: `index = hash(workflow_identifier) % pool_size` 3. Extract `(hour, minute)` from the selected slot 4. Generate cron: ` * * *` (or `* * 1-5` for weekday variant) The pool is pre-computed once. Because each tier appears proportionally in the pool, a randomly selected slot is 3× more likely to land in the BEST window than in the OK window. **Example**: ```plaintext pool_size = 622 hash("github/gh-aw/workflow.md") % 622 = 84 slot[84] = (hour=2, minute=23) # BEST tier cron = "23 2 * * *" (2:23 AM UTC) ``` #### 6.3.2 Daily Around Scattering [Section titled “6.3.2 Daily Around Scattering”](#632-daily-around-scattering) For `FUZZY:DAILY_AROUND:HH:MM * * *`: 1. Calculate target time in minutes: `target_minutes = HH * 60 + MM` 2. Define window: `[-60, +59]` minutes from target 3. Calculate hash modulo 120 (window size) 4. Calculate offset: `offset = hash_result - 60` 5. Calculate scattered time: `scattered_minutes = target_minutes + offset` 6. Handle day wrapping (keep within 0-1439) 7. Convert to hour and minute **Example**: ```plaintext target = 14:00 (840 minutes) hash % 120 = 73 offset = 73 - 60 = 13 scattered = 840 + 13 = 853 minutes hour = 853 / 60 = 14 minute = 853 % 60 = 13 cron = "13 14 * * *" (2:13 PM, within 13:00-15:00 window) ``` #### 6.3.3 Daily Between Scattering [Section titled “6.3.3 Daily Between Scattering”](#633-daily-between-scattering) For `FUZZY:DAILY_BETWEEN:START_H:START_M:END_H:END_M * * *`: 1. Calculate start and end times in minutes 2. Calculate range size (handling midnight crossing) 3. Calculate hash modulo range\_size 4. Add hash\_result to start\_minutes 5. Handle day wrapping 6. Convert to hour and minute **For midnight-crossing ranges** (start > end): ```plaintext range_size = (24 * 60 - start_minutes) + end_minutes ``` **Example**: ```plaintext range = 9:00 to 17:00 start_minutes = 540, end_minutes = 1020 range_size = 1020 - 540 = 480 minutes (8 hours) hash % 480 = 217 scattered = 540 + 217 = 757 minutes hour = 757 / 60 = 12 minute = 757 % 60 = 37 cron = "37 12 * * *" (12:37 PM) ``` #### 6.3.4 Hourly Schedule Scattering [Section titled “6.3.4 Hourly Schedule Scattering”](#634-hourly-schedule-scattering) For `FUZZY:HOURLY * * *`: 1. Calculate hash modulo 60 2. Use result as minute offset 3. Generate cron: ` * * * *` **Example**: ```plaintext hash % 60 = 43 cron = "43 * * * *" (runs at minute 43 every hour) ``` For `FUZZY:HOURLY:N * * *`: 1. Calculate hash modulo 60 2. Use result as minute offset 3. Generate cron: ` */N * * *` **Example**: ```plaintext interval = 2 hours hash % 60 = 53 cron = "53 */2 * * *" (runs at minute 53 every 2 hours) ``` #### 6.3.5 Weekly Schedule Scattering [Section titled “6.3.5 Weekly Schedule Scattering”](#635-weekly-schedule-scattering) For `FUZZY:WEEKLY * * *` and `FUZZY:WEEKLY:DOW * * *`: 1. Select day-of-week: `weekday = hash(workflow_identifier) % 7` (0=Sunday, 6=Saturday)\ For `FUZZY:WEEKLY:DOW`, the day is fixed from the expression instead. 2. Select time from the **weighted daily time slot pool** (Section 6.3.1) 3. Generate cron: ` * * ` Both patterns use the same weighted pool as the daily schedule, ensuring execution times prefer the BEST/GOOD/OK tiers rather than distributing flatly across the full day. **Example**: ```plaintext weekly on monday day = 1 (Monday) pool selection → (hour=2, minute=23) # BEST tier cron = "23 2 * * 1" (Monday 2:23 AM UTC) ``` #### 6.3.6 Bi-weekly and Tri-weekly Scattering [Section titled “6.3.6 Bi-weekly and Tri-weekly Scattering”](#636-bi-weekly-and-tri-weekly-scattering) For `FUZZY:BI-WEEKLY * * *` and `FUZZY:TRI-WEEKLY * * *`: 1. Select time from the **weighted daily time slot pool** (Section 6.3.1) 2. Generate cron: ` */14 * *` (bi-weekly) or ` */21 * *` (tri-weekly) Both patterns use the same weighted pool to ensure execution during preferred low-traffic windows. ### 6.4 Peak Minutes Avoidance [Section titled “6.4 Peak Minutes Avoidance”](#64-peak-minutes-avoidance) To reduce scheduling collisions with other commonly-scheduled cron jobs, implementations MUST apply two minute-avoidance passes after computing the raw scattered minute value. #### 6.4.1 Hour Boundary Avoidance (`avoidHourBoundary`) [Section titled “6.4.1 Hour Boundary Avoidance (avoidHourBoundary)”](#641-hour-boundary-avoidance-avoidhourboundary) Minutes near the hour boundary (0–4 and 55–59) are subject to elevated load on GitHub Actions infrastructure, especially at 00:00 UTC. An implementation MUST remap minute values as follows: | Input range | Output | | ----------- | ---------- | | \[0, 4] | minute + 5 | | \[55, 59] | minute − 5 | | \[5, 54] | unchanged | This ensures all generated minute values are in \[5, 54]. **Scope**: Applied to ALL targeted-scatter patterns (DAILY\_AROUND, DAILY\_BETWEEN, WEEKLY\_AROUND, and their weekday variants). #### 6.4.2 Peak Minutes Avoidance (`avoidPeakMinutes`) [Section titled “6.4.2 Peak Minutes Avoidance (avoidPeakMinutes)”](#642-peak-minutes-avoidance-avoidpeakminutes) Known high-traffic periods require avoidance of minutes that fall within ±3 of the peak minute values. An implementation MUST apply the following remapping **after** `avoidHourBoundary`: | Condition | Avoid range | Replacement | | --------------------------------------- | ----------- | ----------- | | hour ∈ \[6, 9] AND minute ∈ \[27, 33] | \[27, 33] | 34 | | hour ∈ \[14, 18] AND minute ∈ \[12, 18] | \[12, 18] | 19 | | hour ∈ \[14, 18] AND minute ∈ \[42, 48] | \[42, 48] | 49 | **Rationale**: * **EU morning peak** (06:00–09:59 UTC): `:30` is a commonly-used cron minute. Staying 3 minutes away (avoiding \[27,33]) reduces collisions. * **US business hours** (14:00–18:59 UTC): `:15` and `:45` are quarter-hour marks widely used by monitoring and reporting cron jobs. Staying 3 minutes away (avoiding \[12,18] and \[42,48]) reduces collisions. **Application order**: `avoidHourBoundary` MUST be applied before `avoidPeakMinutes`. **Scope**: `avoidPeakMinutes` applies only to targeted-scatter patterns. Full-day scatter patterns that use the weighted pool (Section 6.3.1) already avoid peak windows by construction, since the pool does not include EU peak hours (06–09) or US peak hours (14–18). **Example**: ```plaintext FUZZY:DAILY_AROUND:14:00, workflow "my-scanner" Raw scattered time: 14:28 Step 1 (avoidHourBoundary): 28 → 28 (no change; 28 ∈ [5,54]) Step 2 (avoidPeakMinutes): 28 → 34 (shifted; hour ∈ [14,18], minute 28 ∈ [27,33] — wait, hour=14, so EU rule doesn't apply; US :15 rule: 28 ∉ [12,18]; :45 rule: 28 ∉ [42,48]) → no shift needed; result: 14:28 FUZZY:DAILY_AROUND:15:00, workflow "my-monitor" Raw scattered time: 15:13 Step 1 (avoidHourBoundary): 13 → 13 (no change) Step 2 (avoidPeakMinutes): 13 → 19 (shifted; hour ∈ [14,18], minute 13 ∈ [12,18]) → result: 15:19 ``` ### 6.5 Algorithm Requirements [Section titled “6.5 Algorithm Requirements”](#65-algorithm-requirements) An implementation MUST ensure: 1. Hash function produces same output for same input across platforms 2. Modulo operations use consistent integer division 3. Day wrapping uses consistent addition/subtraction rules 4. Minute and hour extraction uses consistent division and modulo operations 5. `avoidHourBoundary` is applied before `avoidPeakMinutes` for all targeted-scatter patterns 6. Full-day scatter patterns use the weighted daily time slot pool (Section 6.3.1) *** ## 7. Cron Expression Generation [Section titled “7. Cron Expression Generation”](#7-cron-expression-generation) ### 7.1 Fuzzy Cron Placeholders [Section titled “7.1 Fuzzy Cron Placeholders”](#71-fuzzy-cron-placeholders) An implementation MUST generate fuzzy cron placeholders that can be resolved later by the scattering algorithm. Placeholders MUST use the format: ```plaintext FUZZY:[:] ``` Where: * `` identifies the schedule type * `` provides optional parameters (time, day, range) * `` includes remaining cron fields (typically `* * *`) ### 7.2 Placeholder Formats [Section titled “7.2 Placeholder Formats”](#72-placeholder-formats) | Schedule Type | Placeholder Format | | ------------------ | ---------------------------------------------- | | Daily | `FUZZY:DAILY * * *` | | Daily around | `FUZZY:DAILY_AROUND:HH:MM * * *` | | Daily between | `FUZZY:DAILY_BETWEEN:SH:SM:EH:EM * * *` | | Hourly | `FUZZY:HOURLY * * *` | | Hour interval | `FUZZY:HOURLY:N * * *` | | Weekly | `FUZZY:WEEKLY * * *` | | Weekly with day | `FUZZY:WEEKLY:DOW * * DOW` | | Weekly day around | `FUZZY:WEEKLY:DOW:AROUND:HH:MM * * DOW` | | Weekly day between | `FUZZY:WEEKLY:DOW:BETWEEN:SH:SM:EH:EM * * DOW` | | Bi-weekly | `FUZZY:BI-WEEKLY * * *` | | Tri-weekly | `FUZZY:TRI-WEEKLY * * *` | ### 7.3 Placeholder Resolution [Section titled “7.3 Placeholder Resolution”](#73-placeholder-resolution) An implementation MUST provide a mechanism to resolve fuzzy placeholders to concrete cron expressions using the scattering algorithm and workflow identifier. The resolution process MUST: 1. Detect fuzzy placeholder format 2. Extract schedule type and parameters 3. Apply appropriate scattering algorithm 4. Generate valid 5-field cron expression 5. Validate resulting cron expression ### 7.4 Cron Expression Validation [Section titled “7.4 Cron Expression Validation”](#74-cron-expression-validation) Generated cron expressions MUST conform to GitHub Actions cron syntax: * 5 fields: `minute hour day-of-month month day-of-week` * Minutes: 0-59 or `*` or `*/N` * Hours: 0-23 or `*` or `*/N` * Day-of-month: 1-31 or `*` or `*/N` * Month: 1-12 or `*` or `*/N` * Day-of-week: 0-6 (Sunday=0) or `*` *** ## 8. Safeguards [Section titled “8. Safeguards”](#8-safeguards) The following safeguards are normative and apply to all scattering implementations. **R-SAFE-001**: Implementations **MUST** enforce finite scatter windows. For `around` schedules, the effective jitter window **MUST NOT** exceed ±60 minutes from the requested anchor time. For `between` schedules, the scattered time **MUST** remain inside the declared closed interval. **R-SAFE-002**: Implementations **MUST** apply collision-avoidance normalization before returning the final minute value. At minimum, the implementation **MUST** avoid hour-boundary hotspots and known quarter-hour peaks as defined by Section 6.4. This guarantee is deterministic for a given workflow identifier and schedule expression. **R-SAFE-003**: If hash input material is empty (for example, missing workflow identifier), the implementation **MUST** fail with a descriptive error and **MUST NOT** fall back to random scattering. **R-SAFE-004**: If non-unique hash input causes repeated collisions across workflows, the implementation **MUST** preserve deterministic behavior and **SHOULD** emit a warning indicating reduced distribution quality. Implementations **MUST NOT** silently switch to non-deterministic fallbacks to hide collisions. *** ## 9. Error Handling [Section titled “9. Error Handling”](#9-error-handling) ### 9.1 Syntax Errors [Section titled “9.1 Syntax Errors”](#91-syntax-errors) An implementation MUST reject invalid expressions with clear error messages: #### 9.1.1 Invalid Schedule Type [Section titled “9.1.1 Invalid Schedule Type”](#911-invalid-schedule-type) ```plaintext Error: Unknown schedule type 'monthly' Valid types: daily, weekly, hourly, bi-weekly, tri-weekly, every ``` #### 9.1.2 Invalid Time Format [Section titled “9.1.2 Invalid Time Format”](#912-invalid-time-format) ```plaintext Error: Invalid time format '25:00' in 'daily around 25:00' Time must be in 24-hour format (HH:MM, 0-23 hours) or 12-hour format with am/pm ``` #### 9.1.3 Invalid Weekday [Section titled “9.1.3 Invalid Weekday”](#913-invalid-weekday) ```plaintext Error: Unknown weekday 'mondey' in 'weekly on mondey' Valid weekdays: sunday, monday, tuesday, wednesday, thursday, friday, saturday ``` #### 9.1.4 Invalid Interval [Section titled “9.1.4 Invalid Interval”](#914-invalid-interval) ```plaintext Error: Invalid interval '5' in 'every 5h' Valid hour intervals: 1h, 2h, 3h, 4h, 6h, 8h, 12h ``` ### 9.2 Semantic Errors [Section titled “9.2 Semantic Errors”](#92-semantic-errors) #### 9.2.1 Missing Required Components [Section titled “9.2.1 Missing Required Components”](#921-missing-required-components) ```plaintext Error: 'around' requires a time specification Example: daily around 14:00 ``` #### 9.2.2 Unsupported Syntax [Section titled “9.2.2 Unsupported Syntax”](#922-unsupported-syntax) ```plaintext Error: 'daily at ' syntax is not supported Use 'daily around ' for fuzzy scheduling within ±1 hour window ``` ### 9.3 Warning Messages [Section titled “9.3 Warning Messages”](#93-warning-messages) An implementation SHOULD issue warnings for valid but suboptimal patterns: ```plaintext Warning: Consider using 'every 2h' instead of fixed interval Fixed intervals create load spikes when many workflows run simultaneously ``` ### 9.4 Error Recovery [Section titled “9.4 Error Recovery”](#94-error-recovery) An implementation SHOULD NOT attempt to correct syntax errors automatically. All errors MUST be reported to the user with actionable correction guidance. ### 9.5 Edge-Case Conformance Requirements [Section titled “9.5 Edge-Case Conformance Requirements”](#95-edge-case-conformance-requirements) The following edge-case norms are mandatory in addition to §§9.1–9.4: 1. **Invalid scatter seed**: If seed derivation produces an empty, negative, or non-integer value, the implementation **MUST** fail compilation with a descriptive error and **MUST NOT** fall back to a random or default seed. 2. **Out-of-range time values**: Inputs containing hour values outside `0..23` (24-hour), minute values outside `0..59`, or 12-hour values outside `1..12` **MUST** be rejected with an error that includes the offending token and valid range. 3. **Malformed grammar input**: Expressions that violate the ABNF in §3.1 (e.g., missing `and` in `between`, dangling modifiers, extra tokens after a valid production) **MUST** fail parsing and **MUST NOT** be auto-corrected. 4. **Error code stability**: For the same malformed input class, implementations **MUST** return a stable error code category across runs to support deterministic compliance tests. ### 9.6 Retry and Backoff Norms for Collision/Contention Paths [Section titled “9.6 Retry and Backoff Norms for Collision/Contention Paths”](#96-retry-and-backoff-norms-for-collisioncontention-paths) When compilation or scheduling pipelines detect contention that is attributable to repeated hash collisions (for example, repeated retries to acquire shared scheduler state for the same minute bucket), implementations MUST apply bounded retry behavior: 1. **R-ERR-050**: Retry loops for collision/contention handling MUST be bounded to a maximum of 3 attempts total (initial attempt + up to 2 retries). 2. **R-ERR-051**: Retry delays SHOULD use exponential backoff with jitter (initial delay at least 100 ms, 2x multiplier, maximum delay 2 s). 3. **R-ERR-052**: When retry budget is exhausted, implementations MUST fail deterministically with a stable error code and MUST NOT silently fall back to non-deterministic scheduling. *** ## 10. Compliance Testing [Section titled “10. Compliance Testing”](#10-compliance-testing) ### 10.1 Test Suite Requirements [Section titled “10.1 Test Suite Requirements”](#101-test-suite-requirements) A conforming implementation MUST pass all Level 1 tests. Implementations claiming Level 2 or Level 3 conformance MUST pass all tests for their claimed level and all lower levels. ### 10.2 Test Categories [Section titled “10.2 Test Categories”](#102-test-categories) #### 10.2.1 Syntax Parsing Tests (Level 1) [Section titled “10.2.1 Syntax Parsing Tests (Level 1)”](#1021-syntax-parsing-tests-level-1) * **T-SYNTAX-001**: Parse `daily` to `FUZZY:DAILY * * *` * **T-SYNTAX-002**: Parse `weekly` to `FUZZY:WEEKLY * * *` * **T-SYNTAX-003**: Parse `weekly on monday` to `FUZZY:WEEKLY:1 * * 1` * **T-SYNTAX-004**: Parse all weekday names correctly * **T-SYNTAX-005**: Reject invalid schedule types * **T-SYNTAX-006**: Reject invalid weekday names * **T-SYNTAX-007**: Parse case-insensitive tokens #### 10.2.2 Time Format Tests (Level 2) [Section titled “10.2.2 Time Format Tests (Level 2)”](#1022-time-format-tests-level-2) * **T-TIME-001**: Parse 24-hour format `14:00` * **T-TIME-002**: Parse 12-hour format `3pm` * **T-TIME-003**: Parse 12-hour format `11am` * **T-TIME-004**: Parse keyword `midnight` as 00:00 * **T-TIME-005**: Parse keyword `noon` as 12:00 * **T-TIME-006**: Convert `12am` to 00:00 (midnight) * **T-TIME-007**: Convert `12pm` to 12:00 (noon) * **T-TIME-008**: Reject invalid hours (>23 or <0) * **T-TIME-009**: Reject invalid minutes (>59 or <0) * **T-TIME-010**: Handle missing leading zeros (e.g., `9:30`) #### 10.2.3 Time Constraint Tests (Level 2) [Section titled “10.2.3 Time Constraint Tests (Level 2)”](#1023-time-constraint-tests-level-2) * **T-CONSTRAINT-001**: Parse `daily around 14:00` * **T-CONSTRAINT-002**: Parse `daily between 9:00 and 17:00` * **T-CONSTRAINT-003**: Parse `weekly on friday around 17:00` * **T-CONSTRAINT-004**: Handle midnight-crossing ranges (`22:00 and 02:00`) * **T-CONSTRAINT-005**: Reject `around` without time specification * **T-CONSTRAINT-006**: Reject `between` with only one time * **T-CONSTRAINT-007**: Reject `daily at ` syntax #### 10.2.4 Timezone Tests (Level 3) [Section titled “10.2.4 Timezone Tests (Level 3)”](#1024-timezone-tests-level-3) * **T-TZ-001**: Parse `utc+9` offset * **T-TZ-002**: Parse `utc-5` offset * **T-TZ-003**: Parse `utc+05:30` offset format * **T-TZ-004**: Convert `14:00 utc+9` to `05:00` UTC * **T-TZ-005**: Convert `3pm utc-5` to `20:00` UTC * **T-TZ-006**: Handle negative UTC conversion (wrap to previous day) * **T-TZ-007**: Handle >24:00 UTC conversion (wrap to next day) * **T-TZ-008**: Reject invalid offsets (e.g., `utc+25`) #### 10.2.5 Hourly and Interval Tests (Level 2/3) [Section titled “10.2.5 Hourly and Interval Tests (Level 2/3)”](#1025-hourly-and-interval-tests-level-23) * **T-HOURLY-001**: Parse `hourly` to `FUZZY:HOURLY * * *` * **T-HOURLY-002**: Parse `every 2h` to `FUZZY:HOURLY:2 * * *` * **T-HOURLY-003**: Parse `every 6 hours` to `FUZZY:HOURLY:6 * * *` * **T-INTERVAL-001**: Parse `every 5 minutes` to `*/5 * * * *` * **T-INTERVAL-002**: Parse `every 2 days` to `0 0 */2 * *` * **T-INTERVAL-003**: Reject `every 3 minutes` (below 5-minute minimum) * **T-INTERVAL-004**: Parse `bi-weekly` to `FUZZY:BI-WEEKLY * * *` * **T-INTERVAL-005**: Parse `tri-weekly` to `FUZZY:TRI-WEEKLY * * *` #### 10.2.6 Scattering Algorithm Tests (Level 1-3) [Section titled “10.2.6 Scattering Algorithm Tests (Level 1-3)”](#1026-scattering-algorithm-tests-level-1-3) * **T-SCATTER-001**: Hash produces same output for same input * **T-SCATTER-002**: Different inputs produce different outputs * **T-SCATTER-003**: Hash value is within modulo range (0 to modulo-1) * **T-SCATTER-004**: Daily schedule selects time from weighted pool (BEST/GOOD/OK tiers only) * **T-SCATTER-005**: Around schedule stays within ±60 minute window * **T-SCATTER-006**: Between schedule stays within specified range * **T-SCATTER-007**: Midnight-crossing range handles day wrap correctly * **T-SCATTER-008**: Hourly schedule produces minute in \[5, 54] * **T-SCATTER-009**: Weekly schedule selects valid day 0-6 * **T-SCATTER-010**: Same workflow gets same time across compilations * **T-SCATTER-011**: Daily schedule lands in BEST (02–05), GOOD (10–12), or OK (19–23) window * **T-SCATTER-012**: Minute values in \[5, 54] for all patterns (hour-boundary avoidance) * **T-SCATTER-013**: DAILY\_AROUND scatter landing in EU peak hours (06–09) avoids minutes \[27, 33] * **T-SCATTER-014**: DAILY\_AROUND scatter landing in US business hours (14–18) avoids minutes \[12, 18] and \[42, 48] * **T-SCATTER-015**: Weekly schedule uses weighted daily time pool (preferred windows) * **T-SCATTER-016**: Bi-weekly and tri-weekly schedules use weighted daily time pool #### 10.2.7 Cron Generation Tests (Level 1-3) [Section titled “10.2.7 Cron Generation Tests (Level 1-3)”](#1027-cron-generation-tests-level-1-3) * **T-CRON-001**: Generated cron has exactly 5 fields * **T-CRON-002**: Minute field is in range 0-59 * **T-CRON-003**: Hour field is in range 0-23 * **T-CRON-004**: Day-of-week field is in range 0-6 or `*` * **T-CRON-005**: Month and day-of-month are valid * **T-CRON-006**: Interval expressions use valid `*/N` syntax ### 10.3 Compliance Checklist [Section titled “10.3 Compliance Checklist”](#103-compliance-checklist) | Requirement | Test ID | Level | Status | | ---------------------------------- | ----------------------- | ----- | -------- | | Parse basic daily | T-SYNTAX-001 | 1 | Required | | Parse basic weekly | T-SYNTAX-002 | 1 | Required | | Parse weekday specification | T-SYNTAX-003 | 1 | Required | | Parse all weekday names | T-SYNTAX-004 | 1 | Required | | Reject invalid types | T-SYNTAX-005 | 1 | Required | | Case-insensitive parsing | T-SYNTAX-007 | 1 | Required | | Parse 24-hour format | T-TIME-001 | 2 | Required | | Parse 12-hour format | T-TIME-002, 003 | 2 | Required | | Parse time keywords | T-TIME-004, 005 | 2 | Required | | Handle 12am/12pm correctly | T-TIME-006, 007 | 2 | Required | | Validate time ranges | T-TIME-008, 009 | 2 | Required | | Parse around constraints | T-CONSTRAINT-001 | 2 | Required | | Parse between constraints | T-CONSTRAINT-002 | 2 | Required | | Handle midnight crossing | T-CONSTRAINT-004 | 2 | Required | | Parse UTC offsets | T-TZ-001, 002, 003 | 3 | Required | | Convert timezones correctly | T-TZ-004, 005 | 3 | Required | | Handle timezone day wrap | T-TZ-006, 007 | 3 | Required | | Parse hourly schedules | T-HOURLY-001, 002, 003 | 2 | Required | | Parse interval schedules | T-INTERVAL-001, 002 | 3 | Required | | Hash determinism | T-SCATTER-001, 002 | 1 | Required | | Scattering distribution | T-SCATTER-004-009 | 1-3 | Required | | Weighted daily pool | T-SCATTER-011, 015, 016 | 1-3 | Required | | Peak avoidance (hour boundary) | T-SCATTER-012 | 1-3 | Required | | Peak avoidance (EU morning peak) | T-SCATTER-013 | 2-3 | Required | | Peak avoidance (US business hours) | T-SCATTER-014 | 2-3 | Required | | Generate valid cron | T-CRON-001-006 | 1-3 | Required | ### 10.4 Test Execution [Section titled “10.4 Test Execution”](#104-test-execution) Implementations SHOULD provide: 1. Automated test suite covering all compliance tests 2. Test report indicating pass/fail status for each test 3. Conformance level declaration (Level 1, 2, or 3) *** ## Appendices [Section titled “Appendices”](#appendices) ### Appendix A: Complete Examples [Section titled “Appendix A: Complete Examples”](#appendix-a-complete-examples) #### A.1 Daily Schedule Examples [Section titled “A.1 Daily Schedule Examples”](#a1-daily-schedule-examples) ```yaml # Basic daily (scattered across full day) schedule: daily # Fuzzy: FUZZY:DAILY * * * # Might generate: 43 5 * * * (5:43 AM) # Daily around specific time schedule: daily around 14:00 # Fuzzy: FUZZY:DAILY_AROUND:14:0 * * * # Might generate: 13 14 * * * (2:13 PM, within 1-3 PM window) # Daily during business hours schedule: daily between 9:00 and 17:00 # Fuzzy: FUZZY:DAILY_BETWEEN:9:0:17:0 * * * # Might generate: 37 12 * * * (12:37 PM, within 9 AM-5 PM) # Daily with timezone conversion (JST to UTC) schedule: daily around 14:00 utc+9 # Fuzzy: FUZZY:DAILY_AROUND:5:0 * * * # Converts to 5:00 AM UTC, scatters in window 4-6 AM UTC ``` #### A.2 Weekly Schedule Examples [Section titled “A.2 Weekly Schedule Examples”](#a2-weekly-schedule-examples) ```yaml # Basic weekly (any day, any time) schedule: weekly # Fuzzy: FUZZY:WEEKLY * * * # Might generate: 43 5 * * 1 (Monday 5:43 AM) # Weekly on specific day schedule: weekly on monday # Fuzzy: FUZZY:WEEKLY:1 * * 1 # Might generate: 18 14 * * 1 (Monday 2:18 PM) # Weekly with time constraint schedule: weekly on friday around 17:00 # Fuzzy: FUZZY:WEEKLY:5:AROUND:17:0 * * 5 # Might generate: 42 16 * * 5 (Friday 4:42 PM, within 4-6 PM) ``` #### A.3 Hourly and Interval Examples [Section titled “A.3 Hourly and Interval Examples”](#a3-hourly-and-interval-examples) ```yaml # Every hour with scattered minute schedule: hourly # Fuzzy: FUZZY:HOURLY * * * # Might generate: 43 * * * * (every hour at minute 43) # Every 2 hours schedule: every 2h # Fuzzy: FUZZY:HOURLY:2 * * * # Might generate: 53 */2 * * * (every 2 hours at minute 53) # Every 5 minutes (fixed, not fuzzy) schedule: every 5 minutes # Generates: */5 * * * * (fixed interval) # Bi-weekly schedule: bi-weekly # Fuzzy: FUZZY:BI-WEEKLY * * * # Might generate: 43 5 */14 * * (every 14 days at 5:43 AM) ``` #### A.4 Timezone Conversion Examples [Section titled “A.4 Timezone Conversion Examples”](#a4-timezone-conversion-examples) ```yaml # JST (UTC+9) business hours to UTC schedule: daily between 9am utc+9 and 5pm utc+9 # Converts to: daily between 0:00 and 8:00 (UTC) # Fuzzy: FUZZY:DAILY_BETWEEN:0:0:8:0 * * * # EST (UTC-5) afternoon meeting schedule: weekly on monday around 3pm utc-5 # Converts to: weekly on monday around 20:00 (UTC) # Fuzzy: FUZZY:WEEKLY:1:AROUND:20:0 * * 1 # IST (UTC+5:30) morning standup schedule: daily around 9:30am utc+05:30 # Converts to: daily around 4:00 (UTC) # Fuzzy: FUZZY:DAILY_AROUND:4:0 * * * ``` ### Appendix B: Error Code Reference [Section titled “Appendix B: Error Code Reference”](#appendix-b-error-code-reference) | Error Code | Description | Example | | ---------------- | -------------------------- | ------------------------------- | | ERR-SYNTAX-001 | Unknown schedule type | `monthly` (not supported) | | ERR-SYNTAX-002 | Invalid time format | `25:00` (hour out of range) | | ERR-SYNTAX-003 | Invalid weekday | `mondey` (typo) | | ERR-SYNTAX-004 | Missing required component | `daily around` (no time) | | ERR-SYNTAX-005 | Unsupported syntax pattern | `daily at 14:00` (use `around`) | | ERR-TIME-001 | Hour out of range | `25` (>23) | | ERR-TIME-002 | Minute out of range | `60` (>59) | | ERR-TIME-003 | Invalid 12-hour format | `13pm` (hour >12) | | ERR-TZ-001 | Invalid UTC offset | `utc+25` (>14) | | ERR-TZ-002 | Malformed offset syntax | `utc9` (missing +/-) | | ERR-INTERVAL-001 | Invalid interval value | `every 0h` (must be >0) | | ERR-INTERVAL-002 | Unsupported interval | `every 5h` (not factor of 24) | ### Appendix C: Security Considerations [Section titled “Appendix C: Security Considerations”](#appendix-c-security-considerations) #### C.1 Hash Collision Resistance [Section titled “C.1 Hash Collision Resistance”](#c1-hash-collision-resistance) The FNV-1a 32-bit hash provides adequate collision resistance for workflow scattering purposes. The birthday paradox suggests approximately 77,000 workflows are needed for a 50% collision probability. For organizations with fewer workflows, collisions are unlikely. If collision occurs (two workflows receive identical execution times), this does not create a security vulnerability but reduces the effectiveness of load distribution. #### C.2 Predictability [Section titled “C.2 Predictability”](#c2-predictability) The deterministic nature of the scattering algorithm means execution times are predictable given the workflow identifier. This is intentional for consistency but means: * Attackers cannot cause DOS by triggering simultaneous execution * Execution times cannot be used as secrets * Load distribution is transparent and auditable #### C.3 Timezone Handling [Section titled “C.3 Timezone Handling”](#c3-timezone-handling) Implementations MUST handle timezone offsets with integer arithmetic to prevent floating-point rounding errors that could cause inconsistent execution times. Implementations SHOULD validate UTC offsets are within reasonable bounds (UTC-12 to UTC+14) to prevent overflow in time calculations. #### C.4 Input Validation [Section titled “C.4 Input Validation”](#c4-input-validation) Implementations MUST validate all user inputs before processing: * Schedule type MUST be from allowed set * Time values MUST be within valid ranges * Interval values MUST be positive integers * All string inputs MUST be sanitized to prevent injection attacks *** ## 11. Sync Notes [Section titled “11. Sync Notes”](#11-sync-notes) This section maps the fuzzy schedule specification to implementation files. | Normative Area | Implementation File(s) | | ----------------------------------------------------------------- | --------------------------------------------------------------------------------- | | Frontmatter schedule parsing and grammar handling | `pkg/parser/schedule_parser.go` | | Deterministic fuzzy scattering and peak-minute avoidance | `pkg/parser/schedule_fuzzy_scatter.go` | | Parser/scatter conformance tests | `pkg/parser/schedule_parser_test.go`, `pkg/parser/schedule_fuzzy_scatter_test.go` | | Calendar/cron visualization support for compile tooling (see §12) | `pkg/cli/compile_schedule_calendar.go` | **Hash function**: The scattering algorithm (§6.2) uses the **FNV-1a 32-bit** hash function (`FNV_offset_basis = 0x811c9dc5`, `FNV_prime = 0x01000193`) applied to the workflow identifier string `{owner}/{repo}/{workflow_file_path}`. This hash is implemented in `pkg/parser/schedule_fuzzy_scatter.go`. Alternative hash functions are permitted by §6.2.1 if they satisfy the determinism, distribution, and stability requirements, but the FNV-1a reference implementation is normative for cross-platform consistency tests. After changing fuzzy schedule semantics: 1. Update this specification section and any affected normative clauses. 2. Update parser/scatter implementation in the mapped files. 3. Re-run parser/scatter tests to verify behavior remains deterministic. Integration coverage notes: * Conforming changes SHOULD exercise end-to-end compile coverage in addition to parser-only tests so fuzzy expressions are validated after placeholder expansion into emitted cron schedules. * Changes that affect calendar rendering or weighted slot selection SHOULD include integration assertions against `pkg/cli/compile_schedule_calendar.go` output, not only unit assertions against parser helpers. *** ## 12. Calendar Output Schema [Section titled “12. Calendar Output Schema”](#12-calendar-output-schema) The compile-time schedule calendar emitted by `pkg/cli/compile_schedule_calendar.go` documents the aggregate UTC trigger density of scheduled workflows. A conforming implementation MUST treat the calendar as a human-readable console artifact rather than a machine-readable file format. | Element | Requirement | | ------------------ | ----------------------------------------------------------------------------------------------------------- | | Output stream | MUST be written to `stderr` only, and MUST NOT be emitted in JSON output mode. | | Emission condition | MUST be omitted when no scheduled workflows are present. | | Title line | MUST render the heading `Schedule Heatmap (UTC)`. | | Hour header | MUST contain 24 UTC hour labels from `00` through `23`, in ascending order. | | Day rows | MUST render exactly seven rows in `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun` order. | | Cells | MUST render one glyph per hour slot using the implementation’s intensity mapping (`·`, `░`, `▒`, `▓`, `█`). | | Legend | MUST explain the trigger-count buckets for each glyph after the grid. | | File output | MUST NOT create a separate file; the calendar is an inline stderr rendering only. | Implementations SHOULD preserve a fixed-width grid so adjacent cells remain visually aligned in plain-text terminals. ANSI styling MAY be applied when stderr is a terminal, but the unstyled text content MUST preserve the same row/column structure. ### Version 1.2.0 (Draft) — 2026-05-12 [Section titled “Version 1.2.0 (Draft) — 2026-05-12”](#version-120-draft--2026-05-12) * **Changed**: Daily, weekly, bi-weekly, and tri-weekly scattering now share the weighted 622-slot pool introduced in Sections 6.3.1 and 6.3.5–6.3.6. * **Added**: Peak-minute avoidance rules in Section 6.4 to steer schedules away from `:00`, `:15`, `:30`, and `:45` hotspot minutes during documented peak windows. * **Added**: Calendar output schema requirements (Section 12) for the compile-time heatmap rendered by `compile_schedule_calendar.go`. *** ## References [Section titled “References”](#references) ### Normative References [Section titled “Normative References”](#normative-references) * **\[RFC 2119]** S. Bradner. “Key words for use in RFCs to Indicate Requirement Levels”. RFC 2119, March 1997. * **\[ABNF]** D. Crocker, P. Overell. “Augmented BNF for Syntax Specifications: ABNF”. RFC 5234, January 2008. ### Informative References [Section titled “Informative References”](#informative-references) * **\[FNV]** G. Fowler, L. C. Noll, K.-P. Vo. “FNV Hash”. * **\[GitHub Actions Cron]** GitHub Documentation. “Events that trigger workflows - schedule”. * **\[ISO 8601]** International Organization for Standardization. “Data elements and interchange formats – Information interchange – Representation of dates and times”. ISO 8601:2004. *** ## Change Log [Section titled “Change Log”](#change-log) ### Version 1.2.0 (Draft) [Section titled “Version 1.2.0 (Draft)”](#version-120-draft) * **Changed**: Section 6.3.1 — Replaced flat hash-modulo-1440 daily scatter with a **622-entry weighted daily time slot pool** (BEST 02–05 UTC ×3, GOOD 10–12 UTC ×2, OK 19–23 UTC ×1) * **Changed**: Sections 6.3.5–6.3.6 — Weekly, bi-weekly, and tri-weekly scatter now uses the same weighted pool as the daily schedule * **Added**: Section 6.4 — **Peak Minutes Avoidance** documenting: * `avoidHourBoundary`: shifts minutes \[0,4]→\[5,9] and \[55,59]→\[50,54] * `avoidPeakMinutes`: EU peak (hours 06–09) avoids ±3 min of :30 (shifts \[27,33]→34); US business hours (14–18) avoids ±3 min of :15 (shifts \[12,18]→19) and ±3 min of :45 (shifts \[42,48]→49) * **Renumbered**: Section 6.4 (Algorithm Requirements) → Section 6.5 * **Added**: Compliance tests T-SCATTER-011 through T-SCATTER-016 covering weighted pool behavior and peak avoidance * **Updated**: Compliance checklist (Section 9.3) with new required rows for weighted pool and peak avoidance * **Added**: R-HASH-001 minor-version hash-stability requirement and DST transition behavior guidance in Section 5.3 * **Added**: Section 9.6 retry/backoff norms for collision/contention error handling ### Version 1.1.0 (Draft) [Section titled “Version 1.1.0 (Draft)”](#version-110-draft) * **Changed**: Hash function requirement relaxed from MUST to SHOULD for FNV-1a * **Added**: General hash function requirements (determinism, distribution, stability, integer output) * **Added**: Support for alternative hash functions (MurmurHash, xxHash, CityHash) * **Changed**: Moved FNV reference from normative to informative references ### Version 1.0.0 (Draft) [Section titled “Version 1.0.0 (Draft)”](#version-100-draft) * Initial specification release * Defined core fuzzy schedule syntax grammar * Specified scattering algorithm using FNV-1a hash * Added timezone conversion support * Defined three conformance levels (Basic, Standard, Complete) * Included comprehensive test suite with 50+ test cases * Added examples for all schedule types * Defined error codes and handling requirements *** *Copyright 2024 GitHub. All rights reserved.* # GH-AW as an MCP Server > Use the gh-aw MCP server to expose CLI tools to AI agents via Model Context Protocol, enabling secure workflow management. The `gh aw mcp-server` command exposes GitHub Agentic Workflows CLI commands as MCP tools, allowing chat systems and workflows to manage agentic workflows programmatically. Start the server: ```bash gh aw mcp-server ``` Or configure for any Model Context Protocol (MCP) host: ```yaml command: gh args: [aw, mcp-server] ``` ## Configuration Options [Section titled “Configuration Options”](#configuration-options) ### HTTP Server Mode [Section titled “HTTP Server Mode”](#http-server-mode) Run with HTTP/SSE transport using `--port`: ```bash gh aw mcp-server --port 8080 ``` ### Actor Validation [Section titled “Actor Validation”](#actor-validation) Control access to logs and audit tools based on repository permissions using `--validate-actor`: ```bash gh aw mcp-server --validate-actor ``` When enabled, the logs and audit tools require write/maintain/admin repository access. The server reads `GITHUB_ACTOR` and `GITHUB_REPOSITORY` env vars and caches permission check results for 1 hour. Without validation (default), all tools are available without checks. ## Configuring with GitHub Copilot Agent [Section titled “Configuring with GitHub Copilot Agent”](#configuring-with-github-copilot-agent) Configure GitHub Copilot Agent to use gh-aw MCP server: ```bash gh aw init ``` This creates `.github/workflows/copilot-setup-steps.yml` that sets up Go, GitHub CLI, and gh-aw extension before agent sessions start, making workflow management tools available to the agent. MCP server integration is enabled by default. Use `gh aw init --no-mcp` to skip MCP configuration. ## Configuring with Copilot CLI [Section titled “Configuring with Copilot CLI”](#configuring-with-copilot-cli) To add the MCP server in the interactive Copilot CLI session, start `copilot` and run: ```text /mcp add github-agentic-workflows gh aw mcp-server ``` ## Configuring with VS Code [Section titled “Configuring with VS Code”](#configuring-with-vs-code) Configure VS Code Copilot Chat to use gh-aw MCP server: ```bash gh aw init ``` This creates `.github/mcp.json` and `.github/workflows/copilot-setup-steps.yml`. MCP server integration is enabled by default. Use `gh aw init --no-mcp` to skip MCP configuration. Alternatively, create `.github/mcp.json` manually: ```json { "mcpServers": { "github-agentic-workflows": { "command": "gh", "args": ["aw", "mcp-server"] } } } ``` Reload VS Code after making changes. ## Configuring with Docker [Section titled “Configuring with Docker”](#configuring-with-docker) If `gh` is not installed locally, use the `ghcr.io/github/gh-aw` Docker image. The image ships with the GitHub CLI and gh-aw pre-installed and uses `mcp-server` as the default command. ```json { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "GITHUB_TOKEN", "-e", "GITHUB_ACTOR", "ghcr.io/github/gh-aw:latest", "mcp-server" ] } ``` Pass your GitHub token via the `GITHUB_TOKEN` environment variable. Add `--validate-actor` to the `args` array to enforce permission checks based on `GITHUB_ACTOR`. ## Available Tools [Section titled “Available Tools”](#available-tools) The MCP server exposes the following tools for workflow management: ### `status` [Section titled “status”](#status) Show status of agentic workflow files and workflows. * `pattern` (optional): Filter workflows by name pattern * `jq` (optional): Apply jq filter to JSON output Returns a JSON array with `workflow`, `agent`, `compiled`, `status`, and `time_remaining` fields. ### `compile` [Section titled “compile”](#compile) Compile Markdown workflows to GitHub Actions YAML with optional static analysis. * `workflows` (optional): Array of workflow files to compile (empty for all) * `strict` (optional): Enforce strict mode validation (default: true) * `fix` (optional): Apply automatic codemod fixes before compiling * `zizmor`, `poutine`, `actionlint` (optional): Run security scanners/linters * `jq` (optional): Apply jq filter to JSON output Returns a JSON array with `workflow`, `valid`, `errors`, `warnings`, and `compiled_file` fields. Note The `actionlint`, `zizmor`, and `poutine` scanners use Docker images that download on first use. If images are still being pulled, the tool returns a “Docker images are being downloaded. Please wait and retry the compile command.” message. Wait 15–30 seconds, then retry the request. ### `logs` [Section titled “logs”](#logs) Download and analyze workflow logs with timeout handling and size guardrails. * `workflow_name` (optional): Workflow name (empty for all) * `count` (optional): Number of runs to download (default: 100) * `start_date`, `end_date` (optional): Date range filter (YYYY-MM-DD or delta like `-1w`) * `engine`, `firewall`, `no_firewall`, `branch` (optional): Run filters * `after_run_id`, `before_run_id` (optional): Pagination by run ID * `timeout` (optional): Max seconds to download (default: 50) * `max_tokens` (optional): Output token guardrail (default: 12000) * `jq` (optional): Apply jq filter to JSON output Returns JSON with workflow run data and metrics, or continuation parameters if timeout occurred. ### `audit` [Section titled “audit”](#audit) Investigate one or more workflow runs and generate a detailed report. With a single run, returns a full audit. With two or more runs, the first is the base and the rest are compared against it (diff mode). At least one of the following run-identifier fields must be supplied: * `run_ids_or_urls` (array of strings, preferred): One or more run IDs or URLs. Single item produces a detailed audit; multiple items produce a diff against the first. * `run_id` (string or number): Alias for a single run identifier. Use this when only one run is being audited. * `run_id_or_url` (string or number, deprecated): Original single-run field. Accepted for backward compatibility — prefer `run_ids_or_urls` or `run_id`. Each identifier accepts a numeric run ID, run URL, job URL, or job URL with a step anchor (for example `https://github.com/owner/repo/actions/runs/123/job/456#step:7:1`). Optional parameters: * `artifacts` (array of strings): Artifact sets to download. Valid values: `all`, `activation`, `agent`, `detection`, `firewall`, `github-api`, `mcp`. Defaults to all sets. * `experiment` (string): Filter to runs assigned to this experiment name. * `variant` (string): Filter to runs assigned this variant. Requires `experiment`. * `jq` (optional): Apply jq filter to JSON output. Single-run returns JSON with `overview`, `metrics`, `jobs`, `downloaded_files`, `missing_tools`, `mcp_failures`, `errors`, `warnings`, `tool_usage`, `firewall_analysis`, and (when present) `experiments`. Multi-run diff returns JSON describing the changes between the base run and each comparison run. ### `checks` [Section titled “checks”](#checks) Classify CI check state for a pull request and return a normalized result. * `pr_number` (required): Pull request number to classify CI checks for * `repo` (optional): Repository in `owner/repo` format (defaults to current repository) Returns JSON with: * `state`: Aggregate check state across all check runs and commit statuses * `required_state`: State derived from check runs and policy commit statuses only (ignores optional third-party statuses like Vercel/Netlify deployments) * `pr_number`, `head_sha`, `check_runs`, `statuses`, `total_count` Normalized states: `success`, `failed`, `pending`, `no_checks`, `policy_blocked`. Use `required_state` as the authoritative CI verdict in repos with optional deployment integrations. ### `mcp-inspect` [Section titled “mcp-inspect”](#mcp-inspect) Inspect MCP servers in workflows and list available tools, resources, and roots. * `workflow_file` (optional): Workflow file to inspect (empty to list all workflows with MCP servers) * `server` (optional): Filter to specific MCP server * `tool` (optional): Show detailed info about a specific tool (requires `server`) Returns formatted text listing MCP servers, their tools/resources/roots, secret availability, and detailed tool info when `tool` is specified. ### `add` [Section titled “add”](#add) Add workflows from remote repositories to `.github/workflows`. * `workflows` (required): Array of workflow specs in `owner/repo/workflow-name[@version]` format * `number` (optional): Create multiple numbered copies * `name` (optional): Name for added workflow (without `.md` extension) ### `update` [Section titled “update”](#update) Update workflows from their source repositories and check for gh-aw updates. * `workflows` (optional): Array of workflow IDs to update (empty for all) * `major` (optional): Allow major version updates * `force` (optional): Force update even if no changes detected ### `fix` [Section titled “fix”](#fix) Apply automatic codemod-style fixes to workflow files. * `workflows` (optional): Array of workflow IDs to fix (empty for all) * `write` (optional): Write changes to files (default is dry-run) * `list_codemods` (optional): List available codemods and exit Available codemods: `timeout-minutes-migration`, `network-firewall-migration`, `sandbox-agent-false-removal`, `mcp-scripts-mode-removal`, `steps-run-secrets-to-env`. ## Using GH-AW as an MCP from an Agentic Workflow [Section titled “Using GH-AW as an MCP from an Agentic Workflow”](#using-gh-aw-as-an-mcp-from-an-agentic-workflow) Use the GH-AW MCP server from within a workflow to enable self-management (status checks, compilation, log analysis): ```yaml --- permissions: actions: read # Required for agentic-workflows tool tools: agentic-workflows: --- Check workflow status, download logs, and audit failures. ``` # GitHub Tools (for reading from GitHub) > Configure reading information from GitHub, including integrity filtering, repository access restrictions, cross-repository access, remote mode, and additional authentication. The GitHub Tools (`tools.github`) allow the agentic step of your workflow to read information such as issues and pull requests from GitHub. In most workflows, no configuration of the GitHub Tools is necessary since they are included by default with the default toolsets. By default, this provides access to the current repository and all public repositories (if permitted by the network firewall). ## GitHub Toolsets [Section titled “GitHub Toolsets”](#github-toolsets) You can enable specific API groups to increase the available tools or narrow the default selection: ```yaml tools: github: toolsets: [repos, issues, pull_requests, actions] ``` **Available**: `context`, `repos`, `issues`, `pull_requests`, `users`, `actions`, `code_security`, `discussions`, `labels`, `notifications`, `orgs`, `projects`, `gists`, `search`, `dependabot`, `experiments`, `secret_protection`, `security_advisories`, `stargazers` **Shorthand values**: * `default` — expands to `context`, `repos`, `issues`, `pull_requests`, `users` * `all` — expands to all available toolsets **except** `dependabot` (see note below) **Default**: `context`, `repos`, `issues`, `pull_requests`, `users` Some key toolsets are: * `context` (user/team info) * `repos` (repository operations, code search, commits, releases) * `issues` (issue management, comments, reactions) * `pull_requests` (PR operations) * `actions` (workflows, runs, artifacts) * `code_security` (scanning alerts) * `discussions` (discussions and comments) * `labels` (labels management) Note `toolsets: [all]` does **not** include the `dependabot` toolset. The `dependabot` toolset must be opted into explicitly. See [Using the `dependabot` toolset](#using-the-dependabot-toolset) for authentication requirements. Some toolsets require [additional authentication](#additional-authentication-for-github-tools). ## GitHub Integrity Filtering (`tools.github.min-integrity`) [Section titled “GitHub Integrity Filtering (tools.github.min-integrity)”](#github-integrity-filtering-toolsgithubmin-integrity) Sets the minimum integrity level required for content the agent can access. For public repositories, `min-integrity: approved` is applied automatically. See [Integrity Filtering](/gh-aw/reference/integrity/) for levels, examples, user blocking, and approval labels. ## GitHub Cross-Repository Reading [Section titled “GitHub Cross-Repository Reading”](#github-cross-repository-reading) By default, the GitHub Tools can read from the current repository and all public repositories (if permitted by the network firewall). To read from other private repositories, you must configure additional authentication. You can also configure the GitHub Tools to be restricted in which repositories can be accessed via the GitHub tools during AI engine execution by using the `tools.github.allowed-repos` setting. See [Cross-Repository Operations](/gh-aw/reference/cross-repository/) for details and examples. By default, the GitHub Tools can read from the current repository and all public repositories (if permitted by the network firewall). To read from other private repositories, you must configure additional authentication. See [Cross-Repository Operations](/gh-aw/reference/cross-repository/) for details and examples. ## GitHub Tools Access Modes [Section titled “GitHub Tools Access Modes”](#github-tools-access-modes) The `tools.github.mode` field controls how the agent accesses GitHub. Three values are supported: | Mode | Transport | Notes | | ----------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `local` (default) | Docker-based GitHub MCP Server inside the Actions VM | No extra authentication required | | `remote` | Hosted GitHub MCP Server managed by GitHub | Requires [additional authentication](#additional-authentication-for-github-tools) | | `gh-proxy` | Pre-authenticated `gh` CLI directly (no MCP server) | Preferred for performance; required for [integrity reactions](/gh-aw/reference/integrity/) | **`remote` mode** — uses a hosted MCP server managed by GitHub. Requires a GitHub token with appropriate permissions: ```yaml tools: github: mode: remote github-token: ${{ secrets.CUSTOM_PAT }} # Required for remote mode ``` **`gh-proxy` mode** — uses the pre-authenticated `gh` CLI directly instead of an MCP server. This offers lower latency because there is no MCP server startup overhead, and it is required for workflows that use [integrity reactions](/gh-aw/reference/integrity/). The legacy `features: {cli-proxy: true}` feature flag is equivalent and is still accepted for backward compatibility. ```yaml tools: github: mode: gh-proxy ``` ## Additional Authentication for GitHub Tools [Section titled “Additional Authentication for GitHub Tools”](#additional-authentication-for-github-tools) In some circumstances you must use a GitHub PAT or GitHub app to give the GitHub tools used by your workflow additional capabilities. This authentication relates to **reading** information from GitHub. Additional authentication to write to GitHub is handled separately through various [Safe Outputs](/gh-aw/reference/safe-outputs/). This is required when your workflow requires any of the following: * Read access to GitHub org or user information * Read access to other private repos * Read access to projects * GitHub tools [Remote Mode](#github-tools-access-modes) ### Using a Personal Access Token (PAT) [Section titled “Using a Personal Access Token (PAT)”](#using-a-personal-access-token-pat) If additional authentication is required, one way is to create a fine-grained PAT with appropriate permissions, add it as a repository secret, and reference it in your workflow: 1. Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new?description=GitHub+Agentic+Workflows+-+GitHub+tools+access\&contents=read\&issues=read\&pull_requests=read) (this link pre-fills the description and common read permissions) with: * **Repository access**: * Select specific repos or “All repositories” * **Repository permissions** (based on your GitHub tools usage): * Contents: Read (minimum for toolset: repos) * Issues: Read (for toolset: issues) * Pull requests: Read (for toolset: pull\_requests) * Projects: Read (for toolset: projects) * Security Events: Read (for toolset: dependabot, code\_security, secret\_protection, security\_advisories) * Remote mode: no additional permissions required * Adjust based on the toolsets you configure in your workflow * **Organization permissions** (if accessing org-level info): * Members: Read (for org member info in context) * Teams: Read (for team info in context) * Adjust based on the toolsets you configure in your workflow 2. Add it to your repository secrets, either by CLI or GitHub UI: ```bash gh aw secrets set MY_PAT_FOR_GITHUB_TOOLS --value "" ``` 3. Configure in your workflow frontmatter: ```yaml tools: github: github-token: ${{ secrets.MY_PAT_FOR_GITHUB_TOOLS }} ``` ### Using a GitHub App [Section titled “Using a GitHub App”](#using-a-github-app) Alternatively, you can use a GitHub App for enhanced security. See [Using a GitHub App for Authentication](/gh-aw/reference/auth/#using-a-github-app-for-authentication) for complete setup instructions. ### Using a magic secret [Section titled “Using a magic secret”](#using-a-magic-secret) Alternatively, you can set the magic secret `GH_AW_GITHUB_MCP_SERVER_TOKEN` to a suitable PAT (see the above guide for creating one). This secret name is known to GitHub Agentic Workflows and does not need to be explicitly referenced in your workflow. ```bash gh aw secrets set GH_AW_GITHUB_MCP_SERVER_TOKEN --value "" ``` ### Using the `dependabot` toolset [Section titled “Using the dependabot toolset”](#using-the-dependabot-toolset) The `dependabot` toolset requires the `vulnerability-alerts: read` and `security-events: read` permissions. These are now supported natively by `GITHUB_TOKEN`. Add them to your workflow’s `permissions:` field: ```yaml permissions: vulnerability-alerts: read security-events: read ``` Alternatively, you can authenticate with a PAT or GitHub App. If using a GitHub App, add `vulnerability-alerts: read` to your workflow’s `permissions:` field and ensure the GitHub App is configured with this permission. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Tools Reference](/gh-aw/reference/tools/) - All tool configurations * [Authentication Reference](/gh-aw/reference/auth/) - Token setup and permissions * [Integrity Filtering](/gh-aw/reference/integrity/) - Public repository content filtering * [MCPs Guide](/gh-aw/guides/mcps/) - Model Context Protocol setup # Glossary > Definitions of technical terms and concepts used throughout GitHub Agentic Workflows documentation. This glossary provides definitions for key technical terms and concepts used in GitHub Agentic Workflows. ## Core Concepts [Section titled “Core Concepts”](#core-concepts) ### Agentic [Section titled “Agentic”](#agentic) Having agency - the ability to act independently, make context-aware decisions, and adapt behavior based on circumstances. Agentic workflows use AI to understand context and choose appropriate actions, contrasting with deterministic workflows that execute fixed sequences. From “agent” + “-ic” (having the characteristics of). ### Agentic Workflow [Section titled “Agentic Workflow”](#agentic-workflow) An AI-powered workflow that reasons, makes decisions, and takes autonomous actions using natural language instructions. Written in markdown instead of complex YAML, agentic workflows interpret context and adapt behavior flexibly. For example, instead of “if issue has label X, do Y”, you write “analyze this issue and provide helpful context”, and the AI decides what’s helpful based on the specific issue content. ### Orchestration [Section titled “Orchestration”](#orchestration) Workflows that coordinate one or more worker workflows toward a shared goal. An orchestrator decides what work to do next and dispatches workers, while workers execute concrete tasks with scoped tools and limits. See the [OrchestratorOps pattern](/gh-aw/patterns/orchestrator-ops/). ### Orchestrator Workflow [Section titled “Orchestrator Workflow”](#orchestrator-workflow) A workflow that fans out work by dispatching other workflows (workers), aggregates results, and optionally posts summaries. ### Worker Workflow [Section titled “Worker Workflow”](#worker-workflow) A workflow dispatched by an orchestrator that performs a focused unit of work (triage, analysis, code changes, validation). ### Agentic Engine or Coding Agent [Section titled “Agentic Engine or Coding Agent”](#agentic-engine-or-coding-agent) The AI system (typically GitHub Copilot CLI) that executes natural language instructions in an agentic workflow. The agent interprets tasks, uses available tools (GitHub API, file system, web search), and generates outputs based on context autonomously. ### Frontmatter [Section titled “Frontmatter”](#frontmatter) Configuration section at the top of a workflow file, enclosed between `---` markers. Contains YAML settings controlling when the workflow runs, permissions, and available tools, separating technical configuration from natural language instructions. ### Compilation [Section titled “Compilation”](#compilation) Translating Markdown workflows (`.md` files) into GitHub Actions YAML format (`.lock.yml` files), including validation, import resolution, tool configuration, and security hardening. ### Workflow Lock File (.lock.yml) [Section titled “Workflow Lock File (.lock.yml)”](#workflow-lock-file-lockyml) The compiled GitHub Actions workflow file from a workflow markdown file (`.md`). Contains complete GitHub Actions YAML with security hardening applied. Both `.md` and `.lock.yml` files should be committed to version control. At runtime, GitHub Actions executes the lock file using a coding agent while referencing the markdown for instructions. ## Tools and Integration [Section titled “Tools and Integration”](#tools-and-integration) ### MCP (Model Context Protocol) [Section titled “MCP (Model Context Protocol)”](#mcp-model-context-protocol) A standardized protocol that allows AI agents to securely connect to external tools, databases, and services. MCP enables workflows to integrate with GitHub APIs, web services, file systems, and custom integrations while maintaining security controls. ### MCP Gateway [Section titled “MCP Gateway”](#mcp-gateway) A transparent proxy service that enables unified HTTP access to multiple MCP servers using different transport mechanisms (stdio, HTTP). Provides protocol translation, server isolation, authentication, and health monitoring, allowing clients to interact with multiple backends through a single HTTP endpoint. ### Trusted Bots (`sandbox.mcp.trusted-bots`) [Section titled “Trusted Bots (sandbox.mcp.trusted-bots)”](#trusted-bots-sandboxmcptrusted-bots) A frontmatter field that passes additional GitHub bot identity strings to the [MCP Gateway](#mcp-gateway). The gateway merges these with its built-in trusted identity list to determine which bot identities are permitted. This field is additive — it can only extend the gateway’s internal list, not remove built-in entries. Configured under `sandbox.mcp:` and compiled into the `trustedBots` array in the generated gateway configuration. Example entries: `github-actions[bot]`, `copilot-swe-agent[bot]`. See [MCP Gateway Reference](/gh-aw/reference/mcp-gateway/). ### MCP Server [Section titled “MCP Server”](#mcp-server) A service that implements the Model Context Protocol to provide specific capabilities to AI agents. Examples include the GitHub MCP server (for GitHub API operations), Playwright MCP server (for browser automation), or custom MCP servers for specialized tools. See [Playwright Reference](/gh-aw/reference/playwright/) for browser automation configuration. ### QMD Documentation Search (`qmd:`) [Section titled “QMD Documentation Search (qmd:)”](#qmd-documentation-search-qmd) A built-in tool that provides vector similarity search over documentation files. Configured via `tools.qmd:` in frontmatter, the `qmd` tool runs [tobi/qmd](https://github.com/tobi/qmd) as an MCP server so agents can find relevant documentation by natural language query. The search index is built in a dedicated indexing job (which has `contents: read`) and shared with the agent job via `actions/cache`, so the agent job does not need `contents: read`. Supports indexing from repository checkouts, GitHub code search queries, and cache-only read-only mode. See [QMD Documentation Search](/gh-aw/reference/qmd/). ### Tools [Section titled “Tools”](#tools) Capabilities that an AI agent can use during workflow execution. Tools are configured in the frontmatter and include GitHub operations ([`github:`](/gh-aw/reference/github-tools/)), file editing (`edit:`), web access (`web-fetch:`, `web-search:`), shell commands (`bash:`), browser automation ([`playwright:`](/gh-aw/reference/playwright/)), and custom MCP servers. ### GitHub Access Mode (`tools.github.mode`) [Section titled “GitHub Access Mode (tools.github.mode)”](#github-access-mode-toolsgithubmode) A `tools.github` field that controls how the agent accesses GitHub APIs. Three values are supported: `gh-proxy` (recommended — provides pre-authenticated `gh` CLI prompt guidance without mounting a GitHub MCP server, replacing the deprecated `features.cli-proxy: true`), `local` (Docker-based GitHub MCP server, the legacy default), and `remote` (hosted GitHub MCP server at `api.githubcopilot.com`). Use `gh-proxy` for better performance; use `local` or `remote` when MCP-based GitHub toolsets are required. See [GitHub Tools Reference](/gh-aw/reference/github-tools/). ### Allowed Repos (`tools.github.allowed-repos`) [Section titled “Allowed Repos (tools.github.allowed-repos)”](#allowed-repos-toolsgithuballowed-repos) A GitHub Tools configuration field that restricts which repositories the agent can access through GitHub tools during workflow execution. Accepts `"all"` (default — all repositories accessible by the token), `"public"` (public repositories only), `"current"` (the repository where the workflow is running, normalized to `${{ github.repository }}`), or an array of repository patterns (`"owner/repo"`, `"owner/*"`, `"owner/prefix*"`). Wildcards are only permitted at the end of the repository name component. Use `current` in reusable workflows to express “this repository only” without hard-coding owner/repo values. Patterns must be lowercase. See [GitHub Tools Reference](/gh-aw/reference/github-tools/). ```aw tools: github: toolsets: [issues, pull_requests] allowed-repos: current min-integrity: approved ``` ### Ignore If Missing (`ignore-if-missing`) [Section titled “Ignore If Missing (ignore-if-missing)”](#ignore-if-missing-ignore-if-missing) A GitHub App authentication field that gracefully skips token minting when `client-id` or `private-key` resolve to empty strings at runtime (e.g., on fork pull requests where App secrets are unavailable). When set to `true` under `github-app.ignore-if-missing`, the workflow falls back to the standard token chain (`secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN`) instead of failing. Applies consistently to all token mint paths: safe outputs, activation, pre-activation, and checkout. Default behavior (fail when keys are empty) remains unchanged when omitted or set to `false`. See [Authentication Reference](/gh-aw/reference/auth/). ```aw safe-outputs: github-app: client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} ignore-if-missing: true create-issue: ``` ## Security and Outputs [Section titled “Security and Outputs”](#security-and-outputs) ### MCP Scripts [Section titled “MCP Scripts”](#mcp-scripts) Custom MCP tools defined inline in workflow frontmatter using JavaScript or shell scripts. Enables lightweight tool creation without external dependencies while maintaining controlled secret access. Tools are generated at runtime and mounted as an MCP server with typed input parameters, default values, and environment variables. Configured via `mcp-scripts:` section. ### SARIF [Section titled “SARIF”](#sarif) Static Analysis Results Interchange Format - a standardized JSON format for reporting results from static analysis tools. Used by GitHub Code Scanning to display security vulnerabilities and code quality issues. Workflows can generate SARIF files using the `create-code-scanning-alert` safe output. ### Safe Outputs [Section titled “Safe Outputs”](#safe-outputs) Pre-approved actions the AI can take without elevated permissions. The AI generates structured output describing what to create (issues, comments, pull requests), processed by separate permission-controlled jobs. Configured via `safe-outputs:` section, letting AI agents create GitHub content without direct write access. ### Pwn Request [Section titled “Pwn Request”](#pwn-request) A critical security vulnerability that occurs when a `pull_request_target` workflow checks out and executes code from a fork PR. Because `pull_request_target` runs in the context of the target (base) branch with full write permissions and access to repository secrets, executing untrusted fork code grants an attacker the ability to exfiltrate secrets or make unauthorized changes. The compiler emits a warning (non-strict mode) or a hard error (strict mode) when `pull_request_target` is used without `checkout: false`. Add `checkout: false` to prevent the insecure checkout; use `pull_request` instead when you do not need write-back access. See the [GitHub Security Lab advisory on pwn requests](https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/). ### Threat Detection [Section titled “Threat Detection”](#threat-detection) Automated security analysis that scans agent output and code changes for potential security issues before application. When safe outputs are configured, a threat detection job automatically runs between the agent job and safe output processing to identify prompt injection attempts, secret leaks, and malicious code patches. See [Threat Detection Reference](/gh-aw/reference/threat-detection/). ### Staged Mode [Section titled “Staged Mode”](#staged-mode) A preview mode where workflows simulate actions without making changes. The AI generates output showing what would happen, but no GitHub API write operations are performed. Use for testing before production runs. See [Staged Mode](/gh-aw/reference/staged-mode/) for details. ### Integrity Filtering [Section titled “Integrity Filtering”](#integrity-filtering) A guardrail feature that controls which GitHub content an agent can access, filtering by author trust and merge status. Content below the configured `min-integrity` threshold is silently removed before the AI engine sees it. The four levels are `merged`, `approved`, `unapproved`, and `none` (most to least restrictive). For public repositories, `min-integrity: approved` is applied automatically — restricting content to owners, members, and collaborators — even without additional authentication. Set `min-integrity: none` to allow all content through for workflows designed to process untrusted input (e.g., triage bots). Three additional fields extend integrity filtering beyond the level threshold: `trusted-users` elevates specific GitHub usernames to `approved` integrity regardless of their author association; `blocked-users` unconditionally denies content from listed usernames regardless of level; and `approval-labels` promotes items bearing any listed label to `approved` integrity, enabling human-review workflows. See [Integrity Filtering](/gh-aw/reference/integrity/). ### DIFC Proxy (`tools.github.integrity-proxy`) [Section titled “DIFC Proxy (tools.github.integrity-proxy)”](#difc-proxy-toolsgithubintegrity-proxy) Controls full Data Integrity and Flow Control (DIFC) proxy enforcement. When `tools.github.min-integrity` is configured, the compiler injects proxy steps around the agent job that enforce integrity-level isolation at the network boundary. The proxy is **enabled by default** — set `tools.github.integrity-proxy: false` to disable it and rely solely on MCP gateway-level filtering. Filtered content is recorded as `DIFC_FILTERED` events in `gateway.jsonl` for later inspection. See [Integrity Filtering](/gh-aw/reference/integrity/). ### Integrity Reactions (`features.integrity-reactions`) [Section titled “Integrity Reactions (features.integrity-reactions)”](#integrity-reactions-featuresintegrity-reactions) A feature flag that enables GitHub reactions (, , , ) to promote or demote content past the integrity filter. When `integrity-reactions: true` is set, trusted members can add a reaction to an issue or comment to elevate its integrity to `approved` (endorsement reactions) or demote it to `none` (disapproval reactions) — without modifying labels. Enabling this flag automatically activates `cli-proxy` mode, which is required to identify reaction authors at the network boundary. Available from gh-aw v0.68.2. See [Maintaining Repos](/gh-aw/practices/maintaining-repos/#reactions-as-trust-signals). ### Status Comment [Section titled “Status Comment”](#status-comment) A comment posted on the triggering issue or pull request that shows workflow run status (started and completed). Configured via `status-comment: true` in `safe-outputs`. Defaults to `true` for `slash_command` and `label_command` triggers; must be explicitly enabled for other trigger types. Set `status-comment: false` to disable. Not automatically bundled with `ai-reaction` — each must be configured independently. ### Permissions [Section titled “Permissions”](#permissions) Access controls defining workflow operations. Workflows follow least privilege, starting with read-only access by default. Write operations are typically handled through safe outputs. ### Safe Output Messages [Section titled “Safe Output Messages”](#safe-output-messages) Customizable messages workflows can display during execution. Configured in `safe-outputs.messages` with types `run-started`, `run-success`, `run-failure`, and `footer`. Supports GitHub context variables like `{workflow_name}` and `{run_url}`. ### Failure Issue Reporting (`report-failure-as-issue:`) [Section titled “Failure Issue Reporting (report-failure-as-issue:)”](#failure-issue-reporting-report-failure-as-issue) A `safe-outputs` option controlling whether workflow run failures are automatically reported as GitHub issues. Defaults to `true` when safe outputs are configured. Set to `false` to suppress failure issue creation for workflows where failures are expected or handled externally: ```yaml safe-outputs: report-failure-as-issue: false ``` See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/). ### Failure Issue Repository (`failure-issue-repo:`) [Section titled “Failure Issue Repository (failure-issue-repo:)”](#failure-issue-repository-failure-issue-repo) A `safe-outputs` option that redirects failure tracking issues to a different repository. Useful when the workflow’s repository has issues disabled: ```yaml safe-outputs: failure-issue-repo: github/docs-engineering ``` See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/). ### Upload Assets [Section titled “Upload Assets”](#upload-assets) A safe output capability for uploading generated files (screenshots, charts, reports) to an orphaned git branch for persistent storage. The AI calls the `upload_asset` tool to register files, which are committed to a dedicated assets branch by a separate permission-controlled job. Assets are accessible via GitHub raw URLs. Commonly used for visual testing artifacts, data visualizations, and generated documentation. ### Base Branch [Section titled “Base Branch”](#base-branch) Configuration field in the `create-pull-request` safe output specifying which branch the pull request should target. Defaults to `github.base_ref || github.ref_name` if not specified. Useful for cross-repository pull requests targeting non-default branches. ### Minimize Comment [Section titled “Minimize Comment”](#minimize-comment) A safe output capability for hiding or minimizing GitHub comments without requiring write permissions. When minimized, comments are classified as SPAM. Requires GraphQL node IDs to identify comments. Useful for content moderation workflows. ### Add Labels (`add-labels:`) [Section titled “Add Labels (add-labels:)”](#add-labels-add-labels) A safe output capability for adding labels to issues or pull requests. Supports an `allowed` list to restrict which labels can be applied, and a `blocked` list using glob patterns to reject specific labels regardless of the allow list — providing protection against prompt injection via label manipulation. Accepts `target` (`"triggering"`, `"*"`, or a specific number), a `max` limit (default: 3), and cross-repository configuration via `target-repo`. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#add-labels-add-labels). ### Remove Labels (`remove-labels:`) [Section titled “Remove Labels (remove-labels:)”](#remove-labels-remove-labels) A safe output capability for removing labels from issues or pull requests. Supports `allowed` to restrict which labels can be removed and `blocked` to prevent removal of labels matching glob patterns. Silently skips labels not present on the target. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#remove-labels-remove-labels). ### Assign to Agent [Section titled “Assign to Agent”](#assign-to-agent) A safe output capability (`assign-to-agent:`) that programmatically assigns the GitHub Copilot coding agent to existing issues or pull requests. Automates the standard GitHub workflow for delegating implementation tasks to Copilot. Supports cross-repository PR creation via `pull-request-repo` and agent model selection via `model`. See [Assign to Copilot](/gh-aw/reference/assign-to-copilot/). ### GH\_AW\_AGENT\_TOKEN [Section titled “GH\_AW\_AGENT\_TOKEN”](#gh_aw_agent_token) A recognized “magic” repository secret name that GitHub Agentic Workflows automatically uses as a fallback Personal Access Token for `assign-to-agent` operations. When set, no explicit `github-token:` reference is needed in workflow frontmatter — the token is injected automatically. Required because GitHub App installation tokens are rejected by the Copilot assignment API. The token fallback chain is: `assign-to-agent.github-token` → `safe-outputs.github-token` → `GH_AW_AGENT_TOKEN` → `GH_AW_GITHUB_TOKEN` → `GITHUB_TOKEN`. See [Assign to Copilot](/gh-aw/reference/assign-to-copilot/). ### Custom Safe Outputs [Section titled “Custom Safe Outputs”](#custom-safe-outputs) An extension mechanism for safe outputs that enables integration with third-party services beyond built-in GitHub operations. Defined under `safe-outputs.jobs:`, custom safe outputs separate read and write operations: agents use read-only MCP tools for queries, while custom jobs execute write operations with secret access after agent completion. Supports services like Slack, Notion, Jira, or any external API. See [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/). ### Dispatch Repository (`dispatch_repository`) [Section titled “Dispatch Repository (dispatch\_repository)”](#dispatch-repository-dispatch_repository) An experimental safe output type that triggers `repository_dispatch` events in external repositories for cross-repository orchestration. Each key under `safe-outputs.dispatch_repository:` defines a named tool exposed to the agent. A tool requires a `workflow` identifier (forwarded in `client_payload` for routing), an `event_type`, and either a static `repository` slug or an `allowed_repositories` list. GitHub Actions expressions (`${{ ... }}`) are supported in repository fields and are passed through without format validation. At compile time the compiler emits a warning: `Using experimental feature: dispatch_repository`. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#repository-dispatch-dispatch_repository). ### Safe Output Actions [Section titled “Safe Output Actions”](#safe-output-actions) A mechanism for mounting any public GitHub Action as a once-callable MCP tool within the consolidated safe-outputs job. Defined under `safe-outputs.actions:`, each action is specified with a `uses` field (matching GitHub Actions syntax) and an optional `description` override. At compile time, `gh aw compile` fetches the action’s `action.yml` to resolve its inputs and pins the reference to a specific SHA. Unlike [Custom Safe Outputs](#custom-safe-outputs) (separate jobs) and [Safe Output Scripts](#safe-output-scripts) (inline JavaScript), actions run as steps inside the safe-outputs job with full secret access via `env:`. Useful for reusing existing marketplace actions as agent tools. See [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/#github-action-wrappers-safe-outputsactions). ### Safe Output Scripts [Section titled “Safe Output Scripts”](#safe-output-scripts) Lightweight inline JavaScript handlers defined under `safe-outputs.scripts:` that execute inside the consolidated safe-outputs job handler loop. Unlike [Custom Safe Outputs](#custom-safe-outputs) (`safe-outputs.jobs`), which create a separate GitHub Actions job per tool call, scripts run in-process with no job scheduling overhead. Scripts do not have direct access to repository secrets, making them suitable for lightweight processing and logging. Each script declares `description`, `inputs`, and a `script` body; the compiler wraps the body and registers the handler as an MCP tool available to the agent. See [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/#inline-script-handlers-safe-outputsscripts). ### Safe Outputs Dependencies (`safe-outputs.needs:`) [Section titled “Safe Outputs Dependencies (safe-outputs.needs:)”](#safe-outputs-dependencies-safe-outputsneeds) A `safe-outputs` option that extends the consolidated `safe_outputs` job dependencies with custom workflow jobs. `safe-outputs.needs` is merged with built-in dependencies (`agent`, `activation`, optional `detection`, optional `unlock`) and deduplicated. Useful for injecting credential-fetching or secret-provisioning jobs that the safe-outputs job depends on. Values must reference custom jobs from the top-level `jobs:` section; built-in job names are rejected at compile time with an actionable error. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#safe-outputs-dependencies-needs). ### Unassign from User [Section titled “Unassign from User”](#unassign-from-user) A safe output capability for removing user assignments from issues or pull requests. Supports an `allowed` list to restrict which users can be unassigned, and a `blocked` list using glob patterns to prevent unassignment of specific users regardless of the allow list. Configured via `unassign-from-user:` in `safe-outputs`. ### Temporary ID [Section titled “Temporary ID”](#temporary-id) A workflow-scoped identifier (format: `aw_` followed by 3–8 alphanumeric characters, e.g. `aw_abc1`) that lets an AI agent reference a resource before it is created. Safe output tools that support temporary IDs — including `create_issue`, `create_discussion`, and `add_comment` — accept a `temporary_id` field. References like `#aw_abc1` in subsequent operations are automatically resolved to actual resource numbers during execution. Useful for creating interlinked resources in a single workflow run. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/). ### Merge Pull Request (`merge-pull-request:`) [Section titled “Merge Pull Request (merge-pull-request:)”](#merge-pull-request-merge-pull-request) An experimental safe output capability for merging pull requests after policy-driven gate checks pass. Validates status checks, required approvals, resolved review threads, label and branch constraints, and GitHub mergeability before applying the merge. Supports `merge`, `squash`, and `rebase` methods and cross-repository targets. Compiling a workflow with `merge-pull-request` emits an experimental feature warning. See [Safe Outputs Specification](/gh-aw/reference/safe-outputs-specification/#type-merge_pull_request). ### Close Pull Request (`close-pull-request:`) [Section titled “Close Pull Request (close-pull-request:)”](#close-pull-request-close-pull-request) A safe output capability for closing pull requests without merging, with an optional comment. Supports filtering via `required-labels` and `required-title-prefix` to prevent unintended closures. Accepts `target` to identify the PR (`"triggering"`, `"*"`, or a specific number), cross-repository configuration via `target-repo`, and a `max` limit on closures. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#close-pull-request-close-pull-request). ### Update Issue [Section titled “Update Issue”](#update-issue) A safe output capability (`update-issue:`) for modifying existing issues without creating new ones. Each updatable field (`status`, `title`, `body`) must be explicitly enabled. Body updates accept an `operation` field: `append` (default), `prepend`, `replace`, or `replace-island` (updates a specific section delimited by HTML comments). Supports cross-repository issue updates. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#issue-updates-update-issue). ### Update Pull Request (`update-pull-request:`) [Section titled “Update Pull Request (update-pull-request:)”](#update-pull-request-update-pull-request) A safe output capability for modifying a pull request’s `title` or `body`. Each field must be explicitly enabled (`true` or `false`). The `operation` field controls how body changes are applied: `append` (default), `prepend`, or `replace`. Accepts `target` (`"triggering"`, `"*"`, or a specific number) and cross-repository updates via `target-repo`. When `target: "*"` is used, the agent must supply `pull_request_number` in the tool output. The optional `update-branch: true` field synchronizes the PR branch with the latest base branch changes before applying other updates. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#pull-request-updates-update-pull-request). ### Protected Files [Section titled “Protected Files”](#protected-files) A security mechanism on `create-pull-request` and `push-to-pull-request-branch` safe outputs that prevents AI agents from modifying sensitive repository files. By default, protects dependency manifests (e.g., `package.json`, `go.mod`), GitHub Actions workflow files, and lock files. Configured via `protected-files:` with three policies: `blocked` (default — fails with error), `allowed` (no restriction), or `fallback-to-issue` (creates a review issue for human inspection instead of applying changes). Also accepts an object form `{ policy: string, exclude: [...] }` to remove specific files or path prefixes from the default protected set while keeping protection active for the remaining files. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#protected-files). ### Allow Workflows (`allow-workflows:`) [Section titled “Allow Workflows (allow-workflows:)”](#allow-workflows-allow-workflows) A field on `create-pull-request` and `push-to-pull-request-branch` safe outputs that adds `workflows: write` to the GitHub App token’s permissions. Required when `allowed-files:` targets paths under `.github/workflows/`, because the `workflows` permission is a GitHub App-only permission that cannot be granted via `GITHUB_TOKEN`. Requires a `safe-outputs.github-app` configuration — the compiler rejects `allow-workflows: true` without one. This opt-in design keeps the elevated permission visible and auditable in the workflow source. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#allowing-workflow-file-changes-with-allow-workflows). ### Allowed Events (`allowed-events:`) [Section titled “Allowed Events (allowed-events:)”](#allowed-events-allowed-events) A field on `submit-pull-request-review:` safe outputs that restricts which PR review event types the agent may submit. Accepts an array of `APPROVE`, `COMMENT`, and `REQUEST_CHANGES`. When set, the safe-outputs handler rejects any review event not in the list, providing infrastructure-level enforcement regardless of what the agent attempts to output. If omitted, all three event types are allowed. Preferred default for bot reviews: `allowed-events: [COMMENT]`. Example: `allowed-events: [COMMENT, REQUEST_CHANGES]` prevents the agent from approving PRs. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#submit-pr-review-submit-pull-request-review). ### Supersede Older Reviews (`supersede-older-reviews:`) [Section titled “Supersede Older Reviews (supersede-older-reviews:)”](#supersede-older-reviews-supersede-older-reviews) A field on `submit-pull-request-review:` safe outputs that dismisses older `REQUEST_CHANGES` reviews from the same workflow after posting a replacement review. When `supersede-older-reviews: true` is set, the safe-output handler fetches recent reviews, identifies prior `REQUEST_CHANGES` reviews submitted by the same workflow call, and dismisses them before the new review takes effect. This is best-effort behavior — dismissal failures do not block the new review. Useful when a workflow is configured with `allowed-events: [REQUEST_CHANGES]` and repeated runs would otherwise accumulate blocking reviews. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#submit-pr-review-submit-pull-request-review). ### Deduplicate by Title (`deduplicate-by-title:`) [Section titled “Deduplicate by Title (deduplicate-by-title:)”](#deduplicate-by-title-deduplicate-by-title) A `create-issue` safe-output field that drops duplicate issues before creation by comparing titles. Accepts `true` for exact matching (after normalization) or an integer `0`–`100` for fuzzy matching within the given Levenshtein edit distance (e.g., `1` allows one-character differences). Deduplication runs at MCP tool-call time (within-run) and at apply time (against open and recently-closed repository issues). Dropped items are recorded in the safe-output summary with the matched title, edit distance, and source. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#issue-creation-create-issue). ### Allowed Fields (`create-issue:`) [Section titled “Allowed Fields (create-issue:)”](#allowed-fields-create-issue) A configuration field on `create-issue:` safe outputs that restricts which GitHub Project custom fields the agent may set when creating issues. Accepts an array of field names (e.g., `[Priority, Iteration]`). When set, the safe-outputs handler rejects any attempt to populate a field not in the list. When omitted, all project fields are permitted. Example: `allowed-fields: [Priority, Iteration]`. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/#issue-creation-create-issue). ### Allowed Files [Section titled “Allowed Files”](#allowed-files) An exclusive allowlist for `create-pull-request` and `push-to-pull-request-branch` safe outputs. When `allowed-files:` is set to a list of glob patterns, **only** files matching those patterns may be modified — every other file (including normal source files) is refused. This is a restriction, not an exception: listing `.github/workflows/*` does not additionally allow normal source files; it blocks them. Runs independently from [Protected Files](#protected-files): both checks must pass. To modify a protected file, it must both match `allowed-files` and have `protected-files: allowed`. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#restricting-changes-to-specific-files-with-allowed-files). ### Branch Prefix (`branch-prefix:`) [Section titled “Branch Prefix (branch-prefix:)”](#branch-prefix-branch-prefix) An optional field on `create-pull-request` safe outputs that prepends a fixed string to the agent-specified or auto-generated branch name. Useful when repository policies require branches to follow naming conventions (e.g., `signed/` for signed-commit workflows). The default prefix is `signed/`. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/). ### Preserve Branch Name (`preserve-branch-name:`) [Section titled “Preserve Branch Name (preserve-branch-name:)”](#preserve-branch-name-preserve-branch-name) An option on `create-pull-request` safe outputs that omits the random hex salt suffix normally appended to the agent-specified branch name. Useful when the target repository enforces naming conventions such as Jira keys in uppercase (for example, `bugfix/BR-329-red` instead of `bugfix/br-329-red-cde2a954`). Invalid characters are always replaced for safety, and casing is always preserved regardless of this setting. Defaults to `false`. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/). ### Max Patch Files (`max-patch-files:`) [Section titled “Max Patch Files (max-patch-files:)”](#max-patch-files-max-patch-files) A `create-pull-request` safe-output field that sets the maximum number of unique files allowed in a single PR’s patch. Defaults to `100`. Workflows that regenerate large sets of files (e.g., per-package API schemas) can raise this limit. If the limit is exceeded, PR creation fails with an actionable error showing the exact file count and the field to configure. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/). ### Recreate Ref (`recreate-ref:`) [Section titled “Recreate Ref (recreate-ref:)”](#recreate-ref-recreate-ref) An option on `create-pull-request` safe outputs that force-deletes and recreates the remote branch when the agent-supplied branch name already exists on the remote. Requires `preserve-branch-name: true`. The handler force-pushes the agent’s local HEAD to the stale remote ref, enabling reuse of long-lived reusable branches whose previous PR was merged. Without `recreate-ref: true`, the default behavior is to fall back (for example, open an issue when `fallback-as-issue: true`) rather than overwrite the remote. Defaults to `false`. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/). ### Create Pull Request Review Comment (`create-pull-request-review-comment:`) [Section titled “Create Pull Request Review Comment (create-pull-request-review-comment:)”](#create-pull-request-review-comment-create-pull-request-review-comment) A safe output capability for posting inline review comments on specific lines in a pull request diff. Supports single-line and multi-line comments with configurable `side` (`LEFT` or `RIGHT`). When `target: "*"` is set, the agent must supply `pull_request_number` in the tool call. For cross-repository scenarios, the agent may also supply `repo` (in `owner/repo` format) matching `target-repo` or `allowed-repos`. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#pr-review-comments-create-pull-request-review-comment). ### Reply to PR Review Comment (`reply-to-pull-request-review-comment:`) [Section titled “Reply to PR Review Comment (reply-to-pull-request-review-comment:)”](#reply-to-pr-review-comment-reply-to-pull-request-review-comment) A safe output capability for replying to existing review comments on pull requests. Allows the AI agent to respond to reviewer feedback, answer questions, or acknowledge inline review comments by their numeric comment ID. Supports an optional `footer` field (`always`, `none`, or `if-body`) to control AI attribution. Configured via `reply-to-pull-request-review-comment:` in `safe-outputs`. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#reply-to-pr-review-comment-reply-to-pull-request-review-comment). ### Resolve PR Review Thread (`resolve-pull-request-review-thread:`) [Section titled “Resolve PR Review Thread (resolve-pull-request-review-thread:)”](#resolve-pr-review-thread-resolve-pull-request-review-thread) A safe output capability for marking GitHub PR review threads as resolved. Uses the GitHub GraphQL `resolveReviewThread` mutation, requiring the thread’s node ID. Allows AI agents to clean up addressed review comments after implementing feedback. Accepts the same `target`, `target-repo`, and `allowed-repos` options as other pull-request safe outputs. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#resolve-pr-review-thread-resolve-pull-request-review-thread). ### Report Incomplete (`report_incomplete`) [Section titled “Report Incomplete (report\_incomplete)”](#report-incomplete-report_incomplete) A mandatory safe output signal that agents emit when a task cannot be completed due to an infrastructure or tool failure — for example, an MCP server crash, missing authentication, or an inaccessible repository. Unlike `noop` (which signals no action was needed), `report_incomplete` indicates an active failure that prevented the task from running. The safe-outputs handler activates failure handling regardless of agent exit code. Accepts a required `reason` field (max 1024 characters) and an optional `details` field for extended diagnostic context. ### Set Issue Type (`set-issue-type:`) [Section titled “Set Issue Type (set-issue-type:)”](#set-issue-type-set-issue-type) A safe output capability for setting or clearing the GitHub issue type on existing issues. The agent calls `set_issue_type` to assign a named type (e.g., `Bug`, `Feature`) to an issue. An `allowed` list restricts which types the agent may set; omitting it permits any type. Passing an empty string clears the current type. Supports cross-repository targeting via `target-repo` and `allowed-repos`. Configured via `set-issue-type:` in `safe-outputs`. ### Set Issue Field (`set-issue-field:`) [Section titled “Set Issue Field (set-issue-field:)”](#set-issue-field-set-issue-field) A safe output capability for setting one issue field value on existing issues. The agent calls `set_issue_field` with `value` and either `field_name` (for discovery by field label) or `field_node_id` (to skip discovery). Unknown field names return actionable errors listing available fields and suggesting explicit IDs. Supports optional `allowed-fields` restrictions (including `["*"]` wildcard) and cross-repository targeting via `target-repo` and `allowed-repos`. Configured via `set-issue-field:` in `safe-outputs`. ### Parameterized Safe-Output Fields [Section titled “Parameterized Safe-Output Fields”](#parameterized-safe-output-fields) A pattern for `workflow_call` reuse where safe-output policy and list fields accept GitHub Actions expression strings (e.g., `${{ inputs.protected-files-policy }}`) in addition to literal values. At compile time the compiler detects the `${{...}}` form and passes it through unchanged; GitHub Actions evaluates the expression at runtime before the handler executes. Enum-valued policy fields such as `protected-files` and `patch-format` validate literal values at compile time but defer expression-based values to runtime (failing closed on unrecognized input). List-valued fields such as `labels`, `allowed-repos`, and `allowed-base-branches` accept either a YAML array or a single expression string. This enables a single reusable workflow to serve callers with different constraint configurations without duplicating files. See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/#parameterizing-policy-fields-in-reusable-workflows). ## Workflow Components [Section titled “Workflow Components”](#workflow-components) ### Activation Token (`on.github-token:`, `on.github-app:`) [Section titled “Activation Token (on.github-token:, on.github-app:)”](#activation-token-ongithub-token-ongithub-app) Custom GitHub token or GitHub App used by the activation job to post reactions and status comments on the triggering item. Configured via `github-token:` (for a PAT or token expression) or `github-app:` (to mint a short-lived installation token) inside the `on:` section. Affects only the activation job — agent job tokens are configured separately via `tools.github.github-token` or `safe-outputs.github-app`. See [Authentication Reference](/gh-aw/reference/auth/). ### BYOK (Bring Your Own Key) [Section titled “BYOK (Bring Your Own Key)”](#byok-bring-your-own-key) A Copilot engine mode that routes AI requests to an external LLM provider (such as OpenAI, Anthropic, or a self-hosted Ollama/vLLM instance) instead of the default GitHub Copilot backend. Activated by setting `COPILOT_PROVIDER_BASE_URL` in `engine.env`. The three BYOK credential variables (`COPILOT_PROVIDER_BASE_URL`, `COPILOT_PROVIDER_API_KEY`, `COPILOT_PROVIDER_BEARER_TOKEN`) accept `${{ secrets.* }}` references under strict mode and are never exposed to the agent container. Use `COPILOT_MODEL` to specify the target model. See [AI Engines Reference](/gh-aw/reference/engines/#copilot-bring-your-own-key-byok-mode). ### Cron Schedule [Section titled “Cron Schedule”](#cron-schedule) A time-based trigger format. Use short syntax like `daily` or `weekly on monday` (recommended with automatic time scattering) or standard cron expressions for fixed times. Cron-based schedule items accept an optional `timezone` field with any [IANA timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (e.g., `America/New_York`) to interpret the expression in a specific timezone instead of UTC. See also [Fuzzy Scheduling](#fuzzy-scheduling) and [Time Scattering](#time-scattering). ### Ecosystem Identifiers [Section titled “Ecosystem Identifiers”](#ecosystem-identifiers) Named shorthand references to predefined domain sets used in `network.allowed` and `safe-outputs.allowed-domains`. Instead of listing individual domain names, ecosystem identifiers expand to curated sets for a language runtime or service category. Common identifiers: `python` (PyPI/pip), `node` (npm), `go` (proxy.golang.org), `github` (GitHub domains), `dev-tools` (CI/CD services such as Codecov, Snyk, Shields.io), `local` (loopback addresses), and `default-safe-outputs` (a compound set combining `defaults` + `dev-tools` + `github` + `local`, recommended as a baseline for `safe-outputs.allowed-domains`). See [Network Permissions Reference](/gh-aw/reference/network/#ecosystem-identifiers). ### Engine [Section titled “Engine”](#engine) The AI system that powers the agentic workflow - essentially “which AI to use” to execute workflow instructions. GitHub Agentic Workflows supports seven engines: **Copilot** (default), **Claude**, **Codex**, **Gemini**, **Crush** (experimental), **OpenCode** (experimental), and **Pi** (experimental). Set `engine:` in frontmatter to choose; omit it to use Copilot. See [AI Engines Reference](/gh-aw/reference/engines/). ### Enterprise API Endpoint (`api-target`) [Section titled “Enterprise API Endpoint (api-target)”](#enterprise-api-endpoint-api-target) An `engine` configuration field specifying a custom API endpoint hostname for GitHub Enterprise Cloud (GHEC) or GitHub Enterprise Server (GHES) deployments. When set, the compiler automatically adds both the API domain and the base hostname to the AWF firewall `--allow-domains` list and the `GH_AW_ALLOWED_DOMAINS` environment variable, eliminating the need for manual network configuration after each recompile. The value must be a hostname only — no protocol or path (e.g., `api.acme.ghe.com`). See [Engines Reference](/gh-aw/reference/engines/#enterprise-api-endpoint-api-target). ```aw engine: id: copilot api-target: api.acme.ghe.com ``` ### Inline Engine Definition [Section titled “Inline Engine Definition”](#inline-engine-definition) An engine configuration format that specifies a runtime adapter and optional provider settings directly in workflow frontmatter, without requiring a named catalog entry. Uses a `runtime` object (with `id` and optional `version`) to identify the adapter and an optional `provider` object for model selection, authentication, and request shaping. Useful for connecting to self-hosted or third-party AI backends. ```aw engine: runtime: id: codex provider: id: azure-openai model: gpt-4o auth: strategy: oauth-client-credentials token-url: https://auth.example.com/oauth/token client-id: AZURE_CLIENT_ID client-secret: AZURE_CLIENT_SECRET request: path-template: /openai/deployments/{model}/chat/completions query: api-version: "2024-10-01-preview" ``` See [Engines Reference](/gh-aw/reference/engines/). ### Experiments (`experiments:`) [Section titled “Experiments (experiments:)”](#experiments-experiments) A frontmatter section that enables A/B testing of workflow prompt variants across successive runs. Each key in the `experiments:` map names an experiment; the value is either a bare array of variant strings or a rich object with additional fields (`variants`, `description`, `hypothesis`, `metric`, `weight`, `min_samples`, `start_date`, `end_date`). At runtime the activation job selects one variant per experiment using a balanced round-robin counter and exposes the selection as `${{ experiments. }}` for use anywhere in the workflow body. Experiment state is persisted to dedicated `experiments/` git branches in the workflow repository. Use `gh aw experiments list` and `gh aw experiments analyze` to inspect variant distribution and statistical readiness (chi-square balance test, Bonferroni correction, EXTEND / READY\_FOR\_ANALYSIS recommendation). See [A/B Experiments](/gh-aw/practices/experiments/) and the [Experiments Specification](/gh-aw/practices/experiments-specification/). ```aw experiments: prompt_style: [concise, detailed] --- Summarize this issue in a **${{ experiments.prompt_style }}** way. ``` ### Feature Flags (`features:`) [Section titled “Feature Flags (features:)”](#feature-flags-features) A frontmatter section that enables experimental or optional compiler and runtime behaviors as key-value pairs. Feature flags provide controlled access to new capabilities before they become defaults or are fully stabilized. Common flags include `action-mode` (controls how custom action references are compiled), `copilot-requests` (enables GitHub Actions token authentication for Copilot; currently in **private preview** — will not work unless your account has been onboarded), `mcp-gateway` (enables the MCP gateway proxy), `integrity-reactions` (enables reaction-based integrity promotion and demotion), `cli-proxy` (enables CLI proxy mode for integrity enforcement at the network boundary), and `awf-diagnostic-logs` (enables AWF Docker operational diagnostics collection on failure). `byok-copilot` is deprecated because Copilot BYOK behavior is now the default for `engine: copilot`. See [Feature Flags Reference](/gh-aw/reference/feature-flags/). ### Fuzzy Scheduling [Section titled “Fuzzy Scheduling”](#fuzzy-scheduling) Natural language schedule syntax that automatically distributes workflow execution times to avoid load spikes. Instead of specifying exact times with cron expressions, fuzzy schedules like `daily`, `weekly`, or `daily on weekdays` are converted by the compiler into deterministic but scattered cron expressions. The compiler automatically adds `workflow_dispatch:` trigger for manual runs. Example: `schedule: daily on weekdays` compiles to something like `43 5 * * 1-5` with varied execution times across different workflows. ### Imports [Section titled “Imports”](#imports) Reusable workflow components shared across multiple workflows. Specified in the `imports:` field, can include tool configurations, common instructions, or security guidelines. Shared files without an `on:` field are validated but not compiled into GitHub Actions — they are only importable by other workflows. Imports support a parameterized form using `uses`/`with` syntax when the shared file declares an `import-schema`. The compiler validates the passed values, substitutes them into the shared file, and errors on conflicting imports of the same file. See [Imports Reference](/gh-aw/reference/imports/). ### Pre-Agent Steps (`pre-agent-steps:`) [Section titled “Pre-Agent Steps (pre-agent-steps:)”](#pre-agent-steps-pre-agent-steps) Steps injected into the agent job after artifacts are downloaded and before the engine executes. Defined in the `pre-agent-steps:` frontmatter field and composable via imports — imported pre-agent-steps are prepended to the main workflow’s steps in import order. Useful for setup tasks such as installing dependencies or configuring the environment before the AI engine runs. See [Imports Reference](/gh-aw/reference/imports/). ### Post-Steps (`post-steps:`) [Section titled “Post-Steps (post-steps:)”](#post-steps-post-steps) Steps injected into the agent job after the engine finishes execution. Defined in the `post-steps:` frontmatter field and composable via imports — imported post-steps are appended after the main workflow’s post-steps in import order. Useful for cleanup, reporting, or artifact publishing after the AI engine completes. See [Imports Reference](/gh-aw/reference/imports/). ### Import Schema (`import-schema`) [Section titled “Import Schema (import-schema)”](#import-schema-import-schema) A typed parameter contract declared in a shared workflow file that enables callers to pass values via `uses`/`with` syntax. The compiler validates each caller’s `with` values against the schema and substitutes them into the shared file’s frontmatter and body before processing. Supports typed fields with optional defaults; required fields without defaults cause a compile-time error if omitted. See [Imports Reference](/gh-aw/reference/imports/#import-schema-import-schema). ### MCP Gateway Settings (`engine.mcp`) [Section titled “MCP Gateway Settings (engine.mcp)”](#mcp-gateway-settings-enginemcp) `engine.mcp` is the subset of `engine:` configuration that controls MCP gateway behavior — specifically `tool-timeout` and `session-timeout`. Shared workflow files can export only these settings (without specifying an engine identifier), allowing importers to inherit MCP timeout configuration without coupling a shared component to a specific engine. The importing workflow’s own `engine.mcp` values take precedence; among imports, the first-wins strategy applies. See [Imports Reference — Importing MCP Gateway Settings](/gh-aw/reference/imports/#importing-mcp-gateway-settings). ### Runtime Import (`{{#runtime-import}}`) [Section titled “Runtime Import ({{#runtime-import}})”](#runtime-import-runtime-import) A body-level directive that injects the text content of another file at a specific point in the workflow markdown. Unlike the `imports:` frontmatter field (which merges configuration), `{{#runtime-import filepath}}` splices raw markdown text — useful for sharing reusable prompt snippets, tone instructions, or reference material. Use `{{#runtime-import? filepath}}` for an optional include that silently skips a missing file. Paths are resolved within the `.github` folder with or without the `.github/` prefix. See [Runtime Imports](/gh-aw/reference/templating/#runtime-imports). ### Emoji (`emoji:`) [Section titled “Emoji (emoji:)”](#emoji-emoji) An optional frontmatter field that attaches an emoji to represent the workflow visually in listings and UI surfaces. Accepts a single emoji character (e.g., `""`). See [Frontmatter Reference](/gh-aw/reference/frontmatter/). ### Label Trigger Shorthand [Section titled “Label Trigger Shorthand”](#label-trigger-shorthand) A compact syntax for label-based triggers: `on: issue labeled bug` or `on: pull_request labeled needs-review`. The compiler expands the shorthand to standard GitHub Actions trigger syntax and automatically includes a `workflow_dispatch` trigger with an `inputs.item_number` parameter, enabling manual dispatch for a specific issue or pull request. Supported for `issue`, `pull_request`, and `discussion` events. See [LabelOps patterns](/gh-aw/patterns/label-ops/). ### Labels [Section titled “Labels”](#labels) Optional workflow metadata for categorization and organization. Enables filtering workflows in the CLI using the `--label` flag. ### Model Alias [Section titled “Model Alias”](#model-alias) A short human-friendly name (such as `sonnet` or `mini`) that gh-aw resolves to the best available concrete model at compile time. Aliases are defined as ordered lists of provider-scoped glob patterns; the first pattern that matches an available model wins. Meta-aliases reference other aliases and are resolved recursively. Built-in vendor aliases and meta-aliases are listed in the [Model Aliases & Multipliers Reference](/gh-aw/reference/model-tables/). Custom aliases can be defined in workflow frontmatter using the [Model Alias Format Specification](/gh-aw/reference/model-alias-specification/). ### Max Effective Tokens (`max-effective-tokens`) [Section titled “Max Effective Tokens (max-effective-tokens)”](#max-effective-tokens-max-effective-tokens) A top-level frontmatter field that caps the total effective-token (ET) budget the AWF proxy will spend within a single workflow run. Effective tokens are weighted by model multipliers and are the primary cost proxy for Copilot. Applies to all engines and maps to `apiProxy.maxEffectiveTokens` in the compiled lock file. Defaults to `25000000` when omitted. Accepts an integer or a GitHub Actions expression that resolves to an integer at runtime. Example: ```aw max-effective-tokens: 5000000 ``` See [Effective Tokens Specification](/gh-aw/reference/effective-tokens-specification/) and [Cost Management](/gh-aw/reference/cost-management/). ### Max Runs (`max-runs`) [Section titled “Max Runs (max-runs)”](#max-runs-max-runs) A top-level frontmatter field that caps the number of times the AWF proxy will invoke the AI engine within a single workflow run. Applies to all engines and maps to `apiProxy.maxRuns` in the compiled lock file. Replaces the deprecated `engine.max-runs` field. Defaults to `500` when omitted. Accepts an integer or a GitHub Actions expression that resolves to an integer at runtime. Example: ```aw max-runs: 10 ``` See [Engines Reference](/gh-aw/reference/engines/). ### Network Permissions [Section titled “Network Permissions”](#network-permissions) Controls over external domains and services a workflow can access. Configured via `network:` section with options: `defaults` (common infrastructure), custom allow-lists, or `{}` (no access). ### Network Allowed Input (`network.allowed-input`) [Section titled “Network Allowed Input (network.allowed-input)”](#network-allowed-input-networkallowed-input) An opt-in frontmatter flag for `workflow_call` workflows that exposes a `network_allowed` input parameter, allowing callers to extend the compiled workflow’s network allowlist at runtime. When enabled with `network.allowed-input: true`, the compiler injects a `network_allowed: string` input into the `workflow_call` interface. Callers provide a comma-separated list of ecosystem identifiers and/or domains that are unioned with the static `network.allowed` baseline before the agent starts. The compiled workflow’s static allowlist acts as an immutable floor — callers can only add domains, never remove them. Useful for reusable workflows that serve consumers with varying network requirements without requiring per-consumer forks or recompilation. See ADR-33200 for implementation details. ```aw on: workflow_call network: allowed: [defaults] allowed-input: true # Caller can extend with network_allowed: "python,rust" ``` ### Observability (`observability.otlp`) [Section titled “Observability (observability.otlp)”](#observability-observabilityotlp) A frontmatter field that enables OpenTelemetry trace export from workflow runs. It supports single-endpoint and multi-endpoint OTLP export with optional headers. See [OpenTelemetry](/gh-aw/reference/open-telemetry/) for full configuration details, runtime variables, and span semantics. ### OTLP If-Missing (`observability.otlp.if-missing`) [Section titled “OTLP If-Missing (observability.otlp.if-missing)”](#otlp-if-missing-observabilityotlpif-missing) Controls behavior when OTLP endpoint or header values resolve to empty at runtime. Accepts `error` (default — fails startup), `warn` (logs a warning and skips MCP gateway OTLP configuration), or `ignore` (silently skips MCP gateway OTLP configuration). Useful in shared imports where OTLP secrets may be absent in some repositories — set to `ignore` to make observability opt-in without breaking workflows that lack the secrets. See [OpenTelemetry Reference](/gh-aw/reference/open-telemetry/#fields). ### Pre-Steps (`jobs..pre-steps`) [Section titled “Pre-Steps (jobs.\.pre-steps)”](#pre-steps-jobsjob-idpre-steps) Steps injected at a specific lifecycle position within a custom or built-in job’s step sequence: after the compiler-generated setup step and before the first checkout or regular `steps`. Defined under `jobs..pre-steps` in workflow frontmatter. For built-in jobs (`activation`, `pre_activation`), pre-steps are inserted after the `setup` step and before the first `actions/checkout` step. When both a main workflow and an imported workflow define `pre-steps` for the same job, imported pre-steps run first. This is distinct from the top-level `pre-steps` field, which injects steps into the agent job only. See [Custom Jobs](/gh-aw/reference/steps-jobs/#custom-jobs-jobs). ### Pre-Activation Dependencies (`on.needs:`) [Section titled “Pre-Activation Dependencies (on.needs:)”](#pre-activation-dependencies-onneeds) A frontmatter field that declares custom jobs that both the `pre_activation` and `activation` built-in jobs depend on. Use this when credentials or secrets must be fetched by a custom job before activation runs — for example, when `on.github-app` tokens come from a secrets-manager job. Values must reference custom jobs defined in the top-level `jobs:` section; built-in job names are rejected at compile time. See [Triggers Reference](/gh-aw/reference/triggers/). ### Stop After [Section titled “Stop After”](#stop-after) A workflow configuration field (`stop-after:`) that automatically prevents new runs after a specified time limit. Accepts absolute dates (`YYYY-MM-DD`, ISO 8601) or relative time deltas (`+48h`, `+7d`). Minimum granularity is hours. Useful for trial periods, experimental features, and cost-controlled schedules. Recompile with `gh aw compile --refresh-stop-time` to reset the deadline. See [Ephemerals](/gh-aw/reference/ephemerals/). ### `deployment_status` Trigger [Section titled “deployment\_status Trigger”](#deployment_status-trigger) A GitHub Actions trigger that fires when an external deployment changes state. Supported states are `error`, `failure`, `pending`, `queued`, `in_progress`, `success`, `inactive`, and `waiting`. The gh-aw compiler accepts an optional `state:` filter in the trigger definition and synthesizes a job-level `if:` condition so that the agent only runs for the specified states. A natural-language shorthand is also supported — `on: "deployment failed"` expands to `deployment_status` with `state: [failure]`. See [Frontmatter Reference](/gh-aw/reference/frontmatter/). ```aw on: deployment_status: state: [error, failure] ``` ### Triggers [Section titled “Triggers”](#triggers) Events that cause a workflow to run, defined in the `on:` section of frontmatter. Includes issue events, pull requests, schedules, manual runs, and slash commands. ### Skip Author Associations (`on.skip-author-associations`) [Section titled “Skip Author Associations (on.skip-author-associations)”](#skip-author-associations-onskip-author-associations) A pre-activation gating mechanism that skips workflow execution when the triggering event’s author has a specific `author_association` value (such as `contributor`, `first_time_contributor`, or `none`). Configured per-event in the `on.skip-author-associations` field. Compiles to a job-level `if` expression — no runtime script step cost for skipped runs. Values are case-insensitive and accept a single string or array of strings per event key. See [Triggers Reference](/gh-aw/reference/triggers/). ### Trigger File [Section titled “Trigger File”](#trigger-file) A plain GitHub Actions workflow (`.yml`) that separates trigger definitions from agentic workflow logic. Calls a compiled orchestrator’s `workflow_call` entry point in response to any GitHub event (issues, pushes, labels, manual dispatch). Decouples trigger changes from the compilation cycle — updating when an orchestrator runs requires editing only the trigger file, not recompiling the agentic workflow. Trigger files can live in the **same repository** as the orchestrator or in a **different repository** (cross-repo `workflow_call`). Cross-repo usage requires the callee repository to be public, internal, or to have explicitly granted Actions access. When using `secrets: inherit`, the caller’s secrets are passed through — including `COPILOT_GITHUB_TOKEN`, which must be configured in the caller’s repository. See [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/). ### User Rate Limit (`user-rate-limit`) [Section titled “User Rate Limit (user-rate-limit)”](#user-rate-limit-user-rate-limit) A frontmatter field that prevents individual users from triggering a workflow too frequently. Configured with `max-runs-per-window` (maximum runs per time window, 1–10), an optional `window` in minutes (default 60, max 180), an optional `events` list to restrict which trigger types count, and an optional `ignored-roles` list of exempt roles (default: `[admin, maintain, write]`). The pre-activation job checks recent runs and cancels the current run if the limit is exceeded. Example: ```aw user-rate-limit: max-runs-per-window: 5 window: 60 ignored-roles: [] ``` See [Rate Limiting Controls](/gh-aw/reference/rate-limiting-controls/). ### Weekday Schedules [Section titled “Weekday Schedules”](#weekday-schedules) Scheduled workflows configured to run only Monday through Friday using `daily on weekdays` syntax. Recommended for daily workflows to avoid the “Monday wall of work” where tasks accumulate over weekends and create a backlog on Monday morning. The compiler converts this to cron expressions with `1-5` in the day-of-week field. Example: `schedule: daily on weekdays` generates a cron like `43 5 * * 1-5`. ### workflow\_call [Section titled “workflow\_call”](#workflow_call) A trigger enabling a compiled workflow to be invoked by another workflow in the same organization. Adding `workflow_call` to the `on:` section exposes the lock file as a callable workflow, with optional inputs callers can pass for context. Commonly used with a [Trigger File](#trigger-file) to decouple trigger definitions from agentic workflow compilation. See [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/). ### workflow\_dispatch [Section titled “workflow\_dispatch”](#workflow_dispatch) A manual trigger that runs a workflow on demand from the GitHub Actions UI or via the GitHub API. Requires explicit user initiation. ## GitHub and Infrastructure Terms [Section titled “GitHub and Infrastructure Terms”](#github-and-infrastructure-terms) ### GitHub Actions [Section titled “GitHub Actions”](#github-actions) GitHub’s built-in automation platform that runs workflows in response to repository events. Agentic workflows compile to GitHub Actions YAML format, leveraging existing infrastructure for execution, permissions, and secrets. ### GitHub Projects (Projects v2) [Section titled “GitHub Projects (Projects v2)”](#github-projects-projects-v2) GitHub’s project management and tracking system organizing issues and pull requests using customizable boards, tables, and roadmaps. Provides flexible custom fields, automation, and GraphQL API access. Agentic workflows can manage project boards using the `update-project` safe output. Requires organization-level Projects permissions. ### GitHub Actions Secret [Section titled “GitHub Actions Secret”](#github-actions-secret) A secure, encrypted variable stored in repository or organization settings holding sensitive values like API keys or tokens. Access via `${{ secrets.SECRET_NAME }}` syntax. ### GitHub App (`github-app:`) [Section titled “GitHub App (github-app:)”](#github-app-github-app) A GitHub App installation used for authentication and token minting in workflows. The `github-app:` field (which replaces the deprecated `app:` key) accepts `client-id` (preferred) or `app-id` (deprecated alias) together with `private-key` to mint short-lived installation access tokens with fine-grained, automatically-revoked permissions. Can be configured in `safe-outputs:` to override the default `GITHUB_TOKEN` for all safe output operations, or in `checkout:` for accessing private repositories. Run `gh aw fix` to automatically migrate `app-id` to `client-id`. See [Authentication Reference](/gh-aw/reference/auth/#using-a-github-app-for-authentication). ### YAML [Section titled “YAML”](#yaml) A human-friendly data format for configuration files using indentation and simple syntax to represent structured data. In agentic workflows, YAML appears in frontmatter and compiled `.lock.yml` files. ### Personal Access Token (PAT) [Section titled “Personal Access Token (PAT)”](#personal-access-token-pat) A token authenticating you to GitHub’s APIs with specific permissions. Required for GitHub Copilot CLI to access Copilot services. Created at github.com/settings/personal-access-tokens. ### Agent Files [Section titled “Agent Files”](#agent-files) Markdown files with YAML frontmatter stored in `.github/agents/` defining interactive Copilot Chat agents. Created by `gh aw init`, these files can be invoked with the `/agent` command in Copilot Chat to guide workflow creation, debugging, and updates. The `agentic-workflows` agent is a unified dispatcher routing requests to specialized prompts. ### Fine-grained Personal Access Token [Section titled “Fine-grained Personal Access Token”](#fine-grained-personal-access-token) A GitHub Personal Access Token with granular permission control, specifying exactly which repositories the token can access and what permissions it has. Created at github.com/settings/personal-access-tokens. ### `RUNNER_TEMP` / `${{ runner.temp }}` [Section titled “RUNNER\_TEMP / ${{ runner.temp }}”](#runner_temp---runnertemp-) A GitHub Actions environment variable pointing to a per-job temporary directory on the runner. Agentic workflows store compiled scripts and runtime artifacts under `${RUNNER_TEMP}/gh-aw/` for compatibility with self-hosted runners that may not have write access to system directories. In shell `run:` blocks, use the shell variable form `${RUNNER_TEMP}`; in `with:` or `env:` YAML fields, use the expression form `${{ runner.temp }}`. ## Development and Compilation [Section titled “Development and Compilation”](#development-and-compilation) ### CLI (Command Line Interface) [Section titled “CLI (Command Line Interface)”](#cli-command-line-interface) The `gh aw` extension for GitHub CLI providing commands for managing agentic workflows: compile, run, status, logs, add, deploy, and project management. ### Codemod [Section titled “Codemod”](#codemod) An automated transformation script applied by `gh aw fix` that updates workflow markdown files from deprecated syntax to the current format. Codemods rename frontmatter keys, restructure values, or remove obsolete settings without changing workflow behavior. They run in dry-run mode by default; pass `--write` to apply changes. `gh aw upgrade` applies all relevant codemods automatically as part of the upgrade process. List available codemods with `gh aw fix --list-codemods`. See [Upgrading](/gh-aw/guides/upgrading/). ### Playground [Section titled “Playground”](#playground) An interactive web-based editor for authoring, compiling, and previewing agentic workflows without local installation. The Playground runs the gh-aw compiler in the browser using [WebAssembly](#webassembly-wasm) and auto-saves editor content to `localStorage` so work is preserved across sessions. Available at `/gh-aw/editor/`. ### Audit (`gh aw audit`) [Section titled “Audit (gh aw audit)”](#audit-gh-aw-audit) A CLI command that downloads workflow run artifacts and logs, analyzes MCP tool usage and network behavior, and generates a structured Markdown or JSON report. The report covers failure analysis, tool usage, MCP server status, firewall activity, token/cost metrics, behavior fingerprint, and safe-output summary. Accepts a numeric run ID or any GitHub Actions run or job URL. See [Audit Commands](/gh-aw/reference/audit/). ### Audit Diff (multi-run mode) [Section titled “Audit Diff (multi-run mode)”](#audit-diff-multi-run-mode) Passing two or more run IDs to `gh aw audit` activates diff mode: the first ID is the base and the rest are compared against it. Reports domain additions and removals, allowed/denied status changes, request volume drift, and anomaly flags across firewall, MCP tool usage, and run metrics dimensions. Useful for detecting regressions and behavioral drift between runs. See [Audit Commands](/gh-aw/reference/audit/). ### Behavior Fingerprint [Section titled “Behavior Fingerprint”](#behavior-fingerprint) A multi-dimensional characterization of a single workflow run produced by `gh aw audit`. Captures the task domain, network access patterns, tool usage profile, token consumption, and agentic assessments in a compact summary. Two runs with the same fingerprint exhibit identical observable behavior; diverging fingerprints signal regressions or unexpected changes. See [Audit Commands](/gh-aw/reference/audit/). ### Cross-Run Audit Report (`gh aw logs --format`) [Section titled “Cross-Run Audit Report (gh aw logs --format)”](#cross-run-audit-report-gh-aw-logs---format) A feature of `gh aw logs` that aggregates firewall, MCP, and metrics data across multiple workflow runs to produce a security and performance report. Includes an executive summary, domain inventory, and per-run breakdown with anomaly detection. Designed for security reviews, compliance checks, and feeding optimization agents. See [Audit Commands](/gh-aw/reference/audit/#gh-aw-logs---format-fmt). ### Deploy (`gh aw deploy`) [Section titled “Deploy (gh aw deploy)”](#deploy-gh-aw-deploy) A CLI command that orchestrates full workflow rollout to a target repository in a single invocation. `gh aw deploy` clones the target repository, runs `update` to refresh any sourced workflows, runs `add` to install the requested workflows, runs `compile --purge` to regenerate lock files and remove stale outputs, then opens a pull request with all changes for review. Replaces the manual sequence of `clone → update → add → compile → pr` commands and skips the add phase for workflows that already carry a `source:` frontmatter field to prevent duplicate installations. Accepts `--repo` to specify the target repository and `--cool-down` to set the default scheduling interval. See [CLI Reference](/gh-aw/setup/cli/). ### Effective Tokens [Section titled “Effective Tokens”](#effective-tokens) A weighted token count that normalizes raw API token usage into a single comparable value for cost estimation and monitoring. Computed by applying cache and output multipliers to each token category (input, output, cache read, cache write) and summing the results. Appears in audit reports, `gh aw logs` output, and safe-output message footers (as `{effective_tokens}` and `{effective_tokens_formatted}`). For episode-level aggregation, `total_estimated_cost` uses effective tokens as its basis. See [Effective Tokens Specification](/gh-aw/reference/effective-tokens-specification/). ### Forecast (`gh aw forecast`) [Section titled “Forecast (gh aw forecast)”](#forecast-gh-aw-forecast) An experimental CLI command that projects future Effective Token consumption using a Monte Carlo simulation. It samples historical workflow runs, applies a Poisson-bootstrap algorithm to model run frequency, and returns P10/P50/P90 percentile estimates over a configurable time horizon. Supports both local (`.github/workflows/`) and remote (`--repo`) discovery modes. Output is available as a console table or machine-readable JSON (`--json`). Useful for capacity planning, budget governance, and detecting cost regressions before they occur. See [Forecast Specification](/gh-aw/reference/forecast-specification/). ### Time Between Turns (TBT) [Section titled “Time Between Turns (TBT)”](#time-between-turns-tbt) The elapsed time between consecutive LLM API calls in an agentic workflow run. A “turn” is one complete LLM inference request; TBT measures the gap from when the model finishes one response (and tool calls are dispatched) to when the next request is sent (after all tool results are collected). TBT is an important performance and cost metric because LLM inference providers implement prompt caching with a fixed TTL: * **Anthropic** reduced their cache TTL from 1 hour to **5 minutes**. If the TBT for any turn exceeds 5 minutes, the cached prompt context expires and the full prompt must be re-processed, significantly increasing token costs. * **OpenAI** has a similar server-side prompt cache with variable TTL. `gh aw audit` reports both average and maximum TBT in the Session Analysis section. A cache warning is emitted when the TBT used for cache analysis exceeds the Anthropic 5-minute threshold: the maximum observed TBT for Copilot engine runs, where precise per-turn timestamps are available in the `events.jsonl` session log, or the estimated average TBT for other engines, where TBT is derived from total wall time divided by turn count. To reduce TBT — and keep prompt caches warm — minimize blocking tool calls, parallelize independent tool invocations, and avoid long-running shell commands in the critical path between turns. ### Ambient Context [Section titled “Ambient Context”](#ambient-context) The token footprint of the first LLM invocation in a workflow run, used as a proxy for the static context loaded at startup (system prompt, tools list, memory). Because the first invocation fires before the agent has accumulated any conversation history, its input token count primarily reflects the overhead of the configured environment rather than task-specific content. Reported as an optional `ambient_context` object in `gh aw audit` and `gh aw logs` JSON output with three fields: `input_tokens`, `cached_tokens`, and `effective_tokens`. Useful for comparing context overhead across different workflow configurations. See [Audit Commands](/gh-aw/reference/audit/). ### Firewall Analysis [Section titled “Firewall Analysis”](#firewall-analysis) A section of the `gh aw audit` report that breaks down all network requests made during a workflow run — showing allowed domains, denied domains, request volumes, and policy attribution. Derived from AWF firewall logs. Pass multiple run IDs to `gh aw audit` (e.g. `gh aw audit `) to compare firewall behavior across runs and identify new or removed domain accesses. See [Audit Commands](/gh-aw/reference/audit/) and [Network Permissions](/gh-aw/reference/network/). ### Frontmatter Hash [Section titled “Frontmatter Hash”](#frontmatter-hash) A deterministic SHA-256 hash of a workflow’s frontmatter configuration, including all imported workflow frontmatter collected in breadth-first order. The hash covers security-relevant fields (`engine`, `on`, `permissions`, `tools`, `network`, `safe-outputs`, etc.) while excluding the markdown body. Identical configurations produce identical hashes across the Go and JavaScript compiler implementations, enabling change detection, tamper verification, and reproducibility checks. See [Frontmatter Hash Specification](/gh-aw/reference/frontmatter-hash-specification/). ### actionlint [Section titled “actionlint”](#actionlint) A static analysis tool for GitHub Actions workflow files that detects syntax errors, type mismatches, and other issues. Integrated into `gh aw compile` via the `--actionlint` flag. Runs in a Docker container and reports lint findings separately from tooling/integration errors (such as Docker failures or timeouts) that prevent the linter from running. See `--actionlint --zizmor --poutine` in the [Compilation Reference](/gh-aw/reference/compilation-process/). ### poutine [Section titled “poutine”](#poutine) A security linter for GitHub Actions workflows that detects supply-chain vulnerabilities such as unpinned actions and dangerous use of pull request events. Integrated into `gh aw compile` via the `--poutine` flag. Typically used alongside [actionlint](#actionlint) and [zizmor](#zizmor). ### Validation [Section titled “Validation”](#validation) Checking workflow files for errors, security issues, and best practices. Occurs during compilation and can be enhanced with strict mode and security scanners. ### `gh aw lint` [Section titled “gh aw lint”](#gh-aw-lint) A CLI command that runs actionlint on existing `.lock.yml` workflow files without recompiling the source Markdown. Unlike `gh aw compile --actionlint`, it reads lock files directly from disk, skipping `zizmor` and `poutine`. Supports `--shellcheck` and `--pyflakes` flags to enable script integrations for shell and Python analysis. Useful for fast local feedback after manual lock-file edits. See [CLI Reference](/gh-aw/setup/cli/). ### zizmor [Section titled “zizmor”](#zizmor) A security auditing tool for GitHub Actions workflows that identifies vulnerabilities including script injections, excessive permissions, and unsafe use of GitHub context expressions. Integrated into `gh aw compile` via the `--zizmor` flag. Typically used alongside [actionlint](#actionlint) and [poutine](#poutine). ### Deterministic Lineage [Section titled “Deterministic Lineage”](#deterministic-lineage) The causal graph of edges between workflow runs computed by `gh aw logs --json`. Each edge connects a source run to a target run and captures how one run triggered another — via `workflow_dispatch`, `workflow_call`, or `workflow_run` events — along with a confidence rating and the reasons the link was established. Available under `.edges[]` in the JSON output. Use lineage data to reconstruct orchestrator-to-worker relationships without manually correlating run IDs. ### Episode [Section titled “Episode”](#episode) A deterministic rollup of related workflow runs that belong to a single logical execution. When an orchestrator dispatches workers, all participating runs are grouped into one episode with aggregate metrics including `total_runs`, `total_tokens`, `total_effective_tokens`, `total_estimated_cost`, and `risky_node_count`. Available under `.episodes[]` in `gh aw logs --json` output. Episodes are more useful than per-run metrics when one logical job spans multiple workflow runs. For Copilot cost analysis, prefer `total_effective_tokens`; `total_estimated_cost` is only a heuristic and is not reliable billing data. ```bash gh aw logs --start-date -30d --json | \ jq '.episodes[] | {id: .episode_id, workflow: .primary_workflow, effective_tokens: .total_effective_tokens}' ``` ### WebAssembly (Wasm) [Section titled “WebAssembly (Wasm)”](#webassembly-wasm) A compilation target allowing the gh-aw compiler to run in browser environments without server-side Go installation. The compiler is built as a `.wasm` module that packages markdown parsing, frontmatter extraction, import resolution, and YAML generation into a single file loaded with Go’s `wasm_exec.js` runtime. Enables interactive playgrounds, editor integrations, and offline workflow compilation tools. See [WebAssembly Compilation](/gh-aw/reference/wasm-compilation/). ## Advanced Features [Section titled “Advanced Features”](#advanced-features) ### Autoloop [Section titled “Autoloop”](#autoloop) A GitHub Next project that builds on GitHub Agentic Workflows to enable continuous, metric-driven optimization. Define a goal, a set of files the agent may modify, and an evaluation command that outputs a numeric metric — Autoloop runs on a schedule, proposes changes, and retains only those that improve the metric. Useful for continuously improving test coverage, bundle size, build times, or custom research objectives. See [Autoloop on GitHub](https://github.com/githubnext/autoloop). ### ARC (Actions Runner Controller) [Section titled “ARC (Actions Runner Controller)”](#arc-actions-runner-controller) A Kubernetes operator that manages GitHub Actions self-hosted runners as pods. When combined with the Docker-in-Docker (DinD) sidecar pattern, the runner container and the Docker daemon container have separate `/tmp` filesystems. AWF detects this topology at runtime by inspecting `DOCKER_HOST` and automatically passes `--docker-host-path-prefix` to bridge the split mount paths. No manual configuration is required for `v0.25.43`+ of AWF. See the [AWF sandbox reference](/gh-aw/reference/sandbox/). ### AWF (Agent Workflow Firewall) [Section titled “AWF (Agent Workflow Firewall)”](#awf-agent-workflow-firewall) The default coding agent sandbox that isolates AI agent execution in a container with network egress control through domain-based access lists. AWF makes the host filesystem and environment variables available inside the container while restricting outbound network access to configured domains. Enabled with `sandbox.agent: awf` (the default when `sandbox` is not specified). Use `sandbox.agent.version` to pin a specific AWF release for reproducible builds. See [Sandbox Configuration](/gh-aw/reference/sandbox/). ### AWF Reflect Route (`/reflect`) [Section titled “AWF Reflect Route (/reflect)”](#awf-reflect-route-reflect) A runtime HTTP endpoint exposed by the AWF API proxy at `http://api-proxy:10000/reflect`. Returns the currently configured inference providers and their model availability for the active run. Use this route in shared workflows or tools that need to discover gateway endpoints, check provider availability, or select a model dynamically at runtime without hardcoding upstream API URLs. The response includes an `endpoints` array (with `provider`, `base_url`, `configured`, and `models` fields) and a `models_fetch_complete` flag. See [AWF Reflect Route](/gh-aw/experimental/awf-reflect/). ### Bridge Pattern [Section titled “Bridge Pattern”](#bridge-pattern) A cross-repository event forwarding architecture for side repository workflows. Because GitHub Actions only delivers webhook events to the repository where they occur, `slash_command:` triggers cannot fire directly in a side repository. The bridge pattern solves this with two workflows: a thin relay workflow in the main repository that receives the slash command and forwards it to the side repository via `workflow_dispatch`, and a worker workflow in the side repository that performs the actual work. See [Triage from Side Repo](/gh-aw/examples/multi-repo/triage-from-side-repo/). ### Cache Memory [Section titled “Cache Memory”](#cache-memory) Persistent storage for workflows preserving data between runs. Configured via `cache-memory:` in tools section with 7-day retention in GitHub Actions cache. See [Cache Memory](/gh-aw/reference/cache-memory/). ### Comment Memory (`tools.comment-memory`) [Section titled “Comment Memory (tools.comment-memory)”](#comment-memory-toolscomment-memory) Persistent agent memory backed by a managed GitHub issue or PR comment. Before each agent run, content from `` blocks in the target comment is extracted into markdown files under `/tmp/gh-aw/comment-memory/`. Agents edit these files using standard file tools; the safe-output handler automatically upserts the managed comment after the run. Unlike [Cache Memory](#cache-memory) (7-day GitHub Actions cache retention) and [Repo Memory](#repo-memory) (permanent git branch storage), comment memory uses the triggering issue or PR as its backing store — no separate infrastructure required. Configured via `tools.comment-memory:` in frontmatter. ### Command Triggers [Section titled “Command Triggers”](#command-triggers) Special triggers responding to slash commands in issue and PR comments. Configured using the `slash_command:` section with a command name. ### Centralized Slash-Command Strategy (`strategy: centralized`) [Section titled “Centralized Slash-Command Strategy (strategy: centralized)”](#centralized-slash-command-strategy-strategy-centralized) An opt-in compilation mode for `slash_command:` workflows where the compiler generates a single shared `agentic_commands.yml` router workflow. The router listens to merged slash-command events and dispatches matching target workflows via `workflow_dispatch` with an `aw_context` payload. Enables combining slash commands with non-slash events (such as `issues` or `pull_request`) without trigger conflicts. Opt in by setting `on.slash_command.strategy: centralized`. See [Command Triggers](/gh-aw/reference/command-triggers/). ### `aw_context` [Section titled “aw\_context”](#aw_context) A structured context payload passed by the centralized slash-command router (`agentic_commands.yml`) when dispatching target workflows via `workflow_dispatch`. Contains the original GitHub event context (issue number, repository, actor, etc.) so the dispatched workflow can act on the correct resource even though it is triggered as a `workflow_dispatch`. See [Command Triggers](/gh-aw/reference/command-triggers/). ### Conclusion Job [Section titled “Conclusion Job”](#conclusion-job) An automatically generated job in compiled workflows that handles post-agent reporting and cleanup. Receives a workflow-specific concurrency group (`gh-aw-conclusion-{workflow-name}`) to prevent collision when multiple agent instances run the same workflow concurrently. Requires no manual configuration — the compiler sets the group automatically. See [Concurrency Control](/gh-aw/reference/concurrency/). ### Concurrency Control [Section titled “Concurrency Control”](#concurrency-control) Settings limiting how many workflow instances can run simultaneously. Configured via `concurrency:` field to prevent resource conflicts or rate limiting. ### Custom Agents [Section titled “Custom Agents”](#custom-agents) Specialized instructions customizing AI agent behavior for specific tasks or repositories. Stored as agent files (`.github/agents/*.agent.md`) for Copilot Chat or instruction files (`.github/copilot/instructions/`) for path-specific Copilot instructions. ### Ephemerals [Section titled “Ephemerals”](#ephemerals) A category of features for automatically expiring workflow resources to reduce repository noise and control costs. Includes workflow stop-after scheduling, safe output expiration (auto-closing issues, discussions, and pull requests), and hidden older status comments. See [Ephemerals](/gh-aw/reference/ephemerals/). ### Environment Variables (env) [Section titled “Environment Variables (env)”](#environment-variables-env) Configuration section in frontmatter defining environment variables for the workflow. Variables can reference GitHub context values, workflow inputs, or static values. Accessible via `${{ env.VARIABLE_NAME }}` syntax. ### `GITHUB_AW` [Section titled “GITHUB\_AW”](#github_aw) A system-injected environment variable set to `"true"` in every gh-aw engine execution step (both the agent run and the threat-detection run). Agents can check this variable to confirm they are running inside a GitHub Agentic Workflow. Cannot be overridden by user-defined `env:` blocks. See [Environment Variables Reference](/gh-aw/reference/environment-variables/). ### `GH_AW_PHASE` [Section titled “GH\_AW\_PHASE”](#gh_aw_phase) A system-injected environment variable identifying the active execution phase. Set to `"agent"` during the main agent run and `"detection"` during the threat-detection safety check run that precedes it. Cannot be overridden by user-defined `env:` blocks. See [Environment Variables Reference](/gh-aw/reference/environment-variables/). ### `GH_AW_VERSION` [Section titled “GH\_AW\_VERSION”](#gh_aw_version) A system-injected environment variable containing the gh-aw compiler version that generated the workflow (e.g. `"0.40.1"`). Useful for writing conditional logic that depends on a minimum feature version. Cannot be overridden by user-defined `env:` blocks. See [Environment Variables Reference](/gh-aw/reference/environment-variables/). ### `GH_AW_ALLOWED_DOMAINS` [Section titled “GH\_AW\_ALLOWED\_DOMAINS”](#gh_aw_allowed_domains) A system-injected environment variable containing the comma-separated list of domains allowed by the workflow’s network configuration. Used by safe output jobs for URL sanitization — URLs from unlisted domains are redacted in AI-generated content before it is applied. Automatically populated from `network.allowed` domains and, when `engine.api-target` is set, includes the GHES/GHEC API hostname and base domain. Cannot be overridden by user-defined `env:` blocks. See [Environment Variables Reference](/gh-aw/reference/environment-variables/). ### `GH_HOST` [Section titled “GH\_HOST”](#gh_host) An environment variable recognized by the `gh` CLI that specifies the GitHub hostname for GitHub Enterprise Server (GHES) or GitHub Enterprise Cloud (GHEC) deployments. When set, `gh` commands target the specified enterprise instance instead of `github.com`. Agentic workflows automatically configure this from `GITHUB_SERVER_URL` at agent job startup; the variable is also propagated to custom frontmatter jobs and the safe-outputs job so all `gh` calls target the correct enterprise host. See [Environment Variables Reference](/gh-aw/reference/environment-variables/). ### Label Command Trigger (`label_command`) [Section titled “Label Command Trigger (label\_command)”](#label-command-trigger-label_command) A trigger that activates a workflow when a specific label is added to an issue, pull request, or discussion. Unlike standard label filtering, the label command trigger automatically removes the applied label on activation so it can be reapplied to re-trigger the workflow. Configured via `label_command:` in the `on:` section; exposes `needs.activation.outputs.label_command` with the matched label name for downstream jobs. Can be combined with `slash_command:` to support both label-based and comment-based triggering. See [LabelOps patterns](/gh-aw/patterns/label-ops/). ```yaml on: label_command: deploy ``` ### Repo Memory [Section titled “Repo Memory”](#repo-memory) Persistent file storage via Git branches with unlimited retention. Unlike cache-memory (7-day retention), repo-memory stores files permanently in dedicated Git branches with automatic branch cloning, file access, commits, pushes, and merge conflict resolution. Setting `wiki: true` switches the backing to the GitHub Wiki’s git endpoint (`{repo}.wiki.git`), and the agent receives guidance to follow GitHub Wiki Markdown conventions (e.g. `[[Page Name]]` links). See [Repo Memory](/gh-aw/reference/repo-memory/). ### Sandbox [Section titled “Sandbox”](#sandbox) Configuration for the AI agent execution environment, providing two isolation layers: the **Coding Agent Sandbox** ([AWF](#awf-agent-workflow-firewall) by default) for network egress control, and the **MCP Gateway** for routing MCP server calls through a unified HTTP endpoint. Configured via the `sandbox:` field in frontmatter. See [Sandbox Configuration](/gh-aw/reference/sandbox/). ### Strict Mode [Section titled “Strict Mode”](#strict-mode) Enhanced validation mode enforcing additional security checks and best practices. Enabled via `strict: true` in frontmatter or `--strict` flag when compiling. ### Time Scattering [Section titled “Time Scattering”](#time-scattering) Automatic distribution of workflow execution times across the day to reduce load spikes on GitHub Actions infrastructure. When using fuzzy scheduling, the compiler deterministically assigns different start times to each workflow based on repository and workflow name. Prevents all scheduled workflows from running simultaneously at common times like midnight or the top of the hour. ### Timeout [Section titled “Timeout”](#timeout) Maximum duration a workflow can run before automatic cancellation. Configured via `timeout-minutes:` in frontmatter. The agent execution step defaults to 20 minutes; other jobs (custom jobs, safe-output jobs) use the GitHub Actions platform default of 360 minutes unless explicitly set. Custom runners support longer timeouts beyond the GitHub-hosted runner limit. ### Toolsets [Section titled “Toolsets”](#toolsets) Predefined collections of related MCP tools enabled together. Used with the GitHub MCP server to group capabilities like `repos`, `issues`, and `pull_requests`. Configured in the `toolsets:` field. ### Tracker ID [Section titled “Tracker ID”](#tracker-id) A unique identifier enabling external monitoring and coordination without bidirectional coupling. Orchestrator workflows use tracker IDs to correlate worker runs and discover outputs while workers operate independently. ### Workflow Inputs [Section titled “Workflow Inputs”](#workflow-inputs) Parameters provided when manually triggering a workflow with `workflow_dispatch`. Defined in the `on.workflow_dispatch.inputs` section with type, description, default value, and required status. ## Operational Patterns [Section titled “Operational Patterns”](#operational-patterns) Operational patterns (suffixed with “-Ops”) are established workflow architectures for common automation scenarios. Each pattern addresses specific use cases with recommended triggers, tools, and safe outputs. ### AgenticOps [Section titled “AgenticOps”](#agenticops) Repository-wide observability pattern where a scheduled workflow inspects other agentic workflows, classifies notable behavior, and publishes a structured report. When it detects repeated failures, abnormal token consumption, or other unhealthy patterns, it escalates findings into issues for follow-up. Creates a durable operational record instead of relying on ad hoc inspection of individual runs. See [MonitorOps](/gh-aw/patterns/monitor-ops/). ### BatchOps [Section titled “BatchOps”](#batchops) Pattern for processing large volumes of work items efficiently using chunked pagination, matrix fan-out, or rate-limit-aware sub-batching. BatchOps splits a backlog into parallel or sequential chunks, handles partial failures with `fail-fast: false`, and aggregates results into a consolidated report. Use when items are independent and order doesn’t matter. See [BatchOps](/gh-aw/patterns/batch-ops/). ### Central Control Plane [Section titled “Central Control Plane”](#central-control-plane) A [MultiRepoOps](#multirepoops) topology where a single private repository acts as a control plane for coordinating large-scale operations across many repositories. An orchestrator workflow filters and prioritizes targets, then dispatches per-repo worker workflows. Enables phased rollouts, policy updates, and centralized tracking using cross-repository safe outputs and secure authentication. See [MultiRepoOps — Central Control Plane](/gh-aw/patterns/multi-repo-ops/#the-central-control-plane-pattern-org-wide-rollouts). ### CorrectionOps [Section titled “CorrectionOps”](#correctionops) Pattern for improving workflows from trusted human corrections without retraining the underlying model. CorrectionOps stores predictions, compares them with later authoritative human decisions, and uses grouped diffs to update instructions, routing, thresholds, or rollout policy. See [CorrectionOps](/gh-aw/experimental/correction-ops/). ### ChatOps [Section titled “ChatOps”](#chatops) Interactive automation triggered by slash commands (`/review`, `/deploy`) in issues and pull requests, enabling human-in-the-loop automation where developers invoke AI assistance on demand. See [ChatOps](/gh-aw/patterns/chat-ops/). ### DailyOps [Section titled “DailyOps”](#dailyops) Scheduled workflows for incremental daily improvements, automating progress toward large goals through small, manageable changes on weekday schedules. ### DispatchOps [Section titled “DispatchOps”](#dispatchops) Manual workflow execution via GitHub Actions UI or CLI using `workflow_dispatch` trigger. Enables on-demand tasks, testing, and workflows requiring human judgment about timing. Workflows can accept custom input parameters. See [DispatchOps](/gh-aw/patterns/dispatch-ops/). ### IssueOps [Section titled “IssueOps”](#issueops) Automated issue management that analyzes, categorizes, and responds to issues when created. Uses issue event triggers with safe outputs for secure automated triage without requiring write permissions for the AI job. See [IssueOps Examples](/gh-aw/patterns/issue-ops/). ### LabelOps [Section titled “LabelOps”](#labelops) Workflows triggered by label changes on issues and pull requests. Uses labels as triggers, metadata, and state markers with filtering for specific label additions or removals. See [LabelOps Examples](/gh-aw/patterns/label-ops/). ### MemoryOps [Section titled “MemoryOps”](#memoryops) Stateful workflows that persist data between runs using `cache-memory` and `repo-memory`, enabling progress tracking, resumption after interruptions, and incremental processing to avoid API throttling. See [MemoryOps](/gh-aw/patterns/memory-ops/). ### MultiRepoOps [Section titled “MultiRepoOps”](#multirepoops) Cross-repository coordination extending automation patterns across multiple repositories. Uses secure authentication and cross-repository safe outputs to synchronize features, centralize tracking, and enforce organization-wide policies. See [MultiRepoOps](/gh-aw/patterns/multi-repo-ops/). ### ProjectOps [Section titled “ProjectOps”](#projectops) AI-powered GitHub Projects board management automating issue triage, routing, and field updates. Analyzes issue/PR content to make intelligent decisions about project assignment, status, priority, and custom fields using the `update-project` safe output. See [ProjectOps](/gh-aw/patterns/project-ops/). ### Side Repository [Section titled “Side Repository”](#side-repository) A [MultiRepoOps](#multirepoops) topology where workflows run from a separate dedicated automation repository targeting your main codebase. Keeps AI-generated issues, comments, and workflow runs isolated from the main repository for cleaner separation between automation infrastructure and production code. See [MultiRepoOps — Side Repository](/gh-aw/patterns/multi-repo-ops/#the-side-repository-pattern-isolated-automation). ### SpecOps [Section titled “SpecOps”](#specops) Maintaining and propagating W3C-style specifications using the `w3c-specification-writer` agent. Creates formal specifications with RFC 2119 keywords and automatically synchronizes changes to consuming implementations. See [SpecOps](/gh-aw/patterns/spec-ops/). ### ResearchPlanAssignOps [Section titled “ResearchPlanAssignOps”](#researchplanassignops) Scaffolded AI-powered code improvement strategy with four phases: research agent investigates and publishes findings, developer reviews and invokes planner agent to create actionable issues, developer assigns approved issues to Copilot for automated implementation, then reviews and merges PRs. Keeps developers in control with clear decision points at every transition. See [ResearchPlanAssignOps](/gh-aw/patterns/research-plan-assign-ops/). ### TrialOps [Section titled “TrialOps”](#trialops) Testing and validation pattern executing workflows in isolated trial repositories before production deployment. Creates temporary private repositories where workflows run safely, capturing safe outputs without modifying your actual codebase. See [TrialOps](/gh-aw/experimental/trial-ops/). ### WorkQueueOps [Section titled “WorkQueueOps”](#workqueueops) Pattern for incrementally processing a backlog of work items using a durable queue backend — issue checklists, sub-issues, [cache-memory](#cache-memory), or GitHub Discussions. Each run picks up where the last left off, making it resilient to interruptions and rate limits. Items should be idempotent and independently processable. See [WorkQueueOps](/gh-aw/patterns/workqueue-ops/). ## Related Resources [Section titled “Related Resources”](#related-resources) For detailed documentation on specific topics, see: * [Frontmatter Reference](/gh-aw/reference/frontmatter/) * [Tools Reference](/gh-aw/reference/tools/) * [MCP Scripts Reference](/gh-aw/reference/mcp-scripts/) * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) * [Using MCPs Guide](/gh-aw/guides/mcps/) * [Security Guide](/gh-aw/introduction/architecture/) * [AI Engines Reference](/gh-aw/reference/engines/) # Imports > Learn how to modularize and reuse workflow components across multiple workflows using the imports field in frontmatter for better organization and maintainability. ## Syntax [Section titled “Syntax”](#syntax) Use `imports:` in frontmatter or `{{#import ...}}` in markdown to share workflow components across multiple workflows. ```aw --- on: issues engine: copilot imports: - shared/common-tools.md - shared/mcp/tavily.md --- # Your Workflow Workflow instructions here... ``` ### Parameterized imports (`uses`/`with`) [Section titled “Parameterized imports (uses/with)”](#parameterized-imports-useswith) Shared workflows that declare an `import-schema` accept runtime parameters. Use the `uses`/`with` form to pass values: ```aw --- on: issues engine: copilot imports: - uses: shared/mcp/serena.md with: languages: ["go", "typescript"] --- ``` `uses` is an alias for `path`; `with` is an alias for `inputs`. ### Single-import constraint [Section titled “Single-import constraint”](#single-import-constraint) A workflow file can appear at most once in an import graph. If the same file is imported more than once with identical `with` values it is silently deduplicated. Importing the same file with **different** `with` values is a compile-time error: ```plaintext import conflict: 'shared/mcp/serena.md' is imported more than once with different 'with' values. An imported workflow can only be imported once per workflow. Previous 'with': {"languages":["go"]} New 'with': {"languages":["typescript"]} ``` In markdown, use `{{#runtime-import filepath}}` to inject the content of another file directly into the body at that position. This is useful for sharing reusable prompt snippets, tone instructions, or reference material across workflows. ```aw --- on: schedule engine: copilot --- {{#runtime-import .github/shared/editorial.md}} # Daily Report Generate the daily report. ``` Use `{{#runtime-import? filepath}}` to silently skip a missing file instead of failing: ```aw {{#runtime-import .github/shared/editorial.md}} # required — fails if missing {{#runtime-import? .github/shared/optional.md}} # optional — skipped if missing ``` Paths are resolved within the `.github` folder. You can specify paths with or without the `.github/` prefix — both `.github/shared/editorial.md` and `shared/editorial.md` refer to the same file. See [Runtime Imports](/gh-aw/reference/templating/#runtime-imports) for URLs, line ranges, and security details. ## Shared Workflow Components [Section titled “Shared Workflow Components”](#shared-workflow-components) Files without an `on` field are shared workflow components — validated but not compiled into GitHub Actions, only imported by other workflows. Shared components may also define import-safe `on` keys (`skip-if-match`, `skip-if-no-match`, `skip-roles`, `skip-bots`, `github-token`, `github-app`) for reuse through imports. ### Common bundles [Section titled “Common bundles”](#common-bundles) Use bundled shared components when you regularly import the same pair together: ```aw --- on: schedule: daily engine: copilot imports: - shared/reporting-otlp.md --- ``` `shared/reporting-otlp.md` combines `shared/reporting.md` and `shared/otlp.md` for telemetry-enabled reporting workflows. ## Import Schema (`import-schema`) [Section titled “Import Schema (import-schema)”](#import-schema-import-schema) Use `import-schema` to declare a typed parameter contract. Callers pass values via `with`; the compiler validates them and substitutes them into the shared file’s frontmatter and body before processing. ```aw --- # shared/deploy.md — no 'on:' field, shared component only import-schema: region: type: string required: true environment: type: choice options: [staging, production] required: true count: type: number default: 10 languages: type: array items: type: string required: true config: type: object description: Configuration object properties: apiKey: type: string required: true timeout: type: number default: 30 mcp-servers: my-server: url: "https://example.com/mcp" allowed: ["*"] --- Deploy ${{ github.aw.import-inputs.count }} items to ${{ github.aw.import-inputs.region }}. API key: ${{ github.aw.import-inputs.config.apiKey }}. Languages: ${{ github.aw.import-inputs.languages }}. ``` ### Supported types [Section titled “Supported types”](#supported-types) | Type | Description | Extra fields | | --------- | ----------------------------- | ----------------------------- | | `string` | Plain text value | — | | `number` | Numeric value | — | | `boolean` | `true`/`false` | — | | `choice` | One of a fixed set of strings | `options: [...]` | | `array` | Ordered list of values | `items.type` (element type) | | `object` | Key/value map | `properties` (one level deep) | Each field supports `required: true` and an optional `default` value. ### Accessing inputs in shared workflows [Section titled “Accessing inputs in shared workflows”](#accessing-inputs-in-shared-workflows) Use `${{ github.aw.import-inputs. }}` to substitute a top-level value; use dotted notation for object sub-fields (e.g. `${{ github.aw.import-inputs.config.apiKey }}`). Substitution applies to both frontmatter and body, so inputs can drive any field such as `mcp-servers` or `runtimes`. ### Calling a parameterized shared workflow [Section titled “Calling a parameterized shared workflow”](#calling-a-parameterized-shared-workflow) ```aw --- on: issues engine: copilot imports: - uses: shared/deploy.md with: region: us-east-1 environment: staging count: 5 languages: ["go", "typescript"] config: apiKey: my-secret-key timeout: 60 --- ``` The compiler validates `required` fields, `choice` options, array element types, and object `properties`. Unknown keys are compile-time errors. ## Path Resolution [Section titled “Path Resolution”](#path-resolution) Import paths are resolved using one of three modes depending on their format. ### Relative paths (default) [Section titled “Relative paths (default)”](#relative-paths-default) Paths that do not start with `.github/`, `/`, or an `owner/repo/` prefix are resolved relative to the importing workflow’s directory. When compiling with the default `--dir` value, that directory is `.github/workflows/`. ```aw --- on: issues engine: copilot imports: - shared/common-tools.md # → .github/workflows/shared/common-tools.md - ../agents/helper.md # → .github/agents/helper.md (.. goes up from .github/workflows/) --- ``` ### Repo-root-relative paths [Section titled “Repo-root-relative paths”](#repo-root-relative-paths) Paths starting with `.github/` or `/` are resolved from the repository root. Absolute paths (`/`) must point inside `.github/` or `.agents/`; any other prefix is rejected at compile time for security. ```aw --- on: pull_request engine: copilot imports: - .github/agents/code-reviewer.md # resolved from repo root - .github/workflows/shared/app.md # resolved from repo root --- ``` This form is required when workflows in different directories need to import the same shared file using a stable path, and is the supported way to import files from the `.github/agents/` directory. ### Cross-repo imports [Section titled “Cross-repo imports”](#cross-repo-imports) Paths matching `owner/repo/path@ref` are fetched from GitHub at compile time. The `@ref` suffix pins to a semantic tag (`@v1.0.0`), branch (`@main`), or commit SHA. Remote imports are cached in `.github/aw/imports/` by commit SHA, enabling offline compilation; local imports are never cached. See [Reusing Workflows](/gh-aw/guides/packaging-imports/) for installation and update flows. ```aw --- on: issues engine: copilot imports: - acme-org/shared-workflows/shared/reporting.md@v2.1.0 # pinned to a tag - acme-org/shared-workflows/shared/tools.md@main # track a branch - acme-org/shared-workflows/shared/helpers.md@abc1234 # locked to a SHA --- ``` ### Section references and optional imports [Section titled “Section references and optional imports”](#section-references-and-optional-imports) Append `#SectionName` to any path to import a single section from a markdown file: ```plaintext imports: - shared/tools.md#WebSearch ``` Use `?` after `import` to mark an import as optional — missing files are skipped silently instead of failing compilation. This applies to both frontmatter imports and body-level directives: ```yaml # Frontmatter — optional imports: - shared/optional-tools.md? ``` ```aw # Body — optional content injection {{#runtime-import? .github/shared/optional.md}} ``` ## Agent Files [Section titled “Agent Files”](#agent-files) Agent files are markdown documents in `.github/agents/` that add specialized instructions to the AI engine. Import them as either local or remote paths — files under `.github/agents/` are automatically recognized as agent files, and only **one agent file** may be imported per workflow. ```yaml --- on: pull_request engine: copilot imports: - .github/agents/code-reviewer.md # local - githubnext/shared-agents/.github/agents/security-reviewer.md@v1.0.0 # remote, pinned --- ``` Remote agent imports support the same `@ref` versioning and SHA-keyed caching as other remote imports. ## Frontmatter Merging [Section titled “Frontmatter Merging”](#frontmatter-merging) ### Allowed Import Fields [Section titled “Allowed Import Fields”](#allowed-import-fields) Shared workflow files (without `on:` field) can define the fields below. Other fields generate warnings and are ignored. Agent files (`.github/agents/*.md`) may additionally define `name` and `description`. | Field | Purpose | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `import-schema` | Parameter schema for `with` validation and input substitution | | `tools` | Tool configurations (`bash`, `web-fetch`, `github`, `mcp-*`, etc.) | | `mcp-servers` | Model Context Protocol server configurations | | `mcp-scripts` | MCP Scripts configurations | | `services` | Docker services for workflow execution | | `safe-outputs` | Safe output handlers and configuration | | `network` | Network permission specifications | | `permissions` | GitHub Actions permissions (validated, not merged) | | `runtimes` | Runtime version overrides (node, python, go, etc.) | | `secret-masking` | Secret masking steps | | `env` | Workflow-level environment variables | | `pre-agent-steps` | Steps that run after artifacts download, before engine execution | | `post-steps` | Steps that run after engine execution | | `github-app` | GitHub App credentials for token minting | | `checkout` | Checkout configuration for the agent job | | `engine.mcp` | MCP gateway settings (`tool-timeout`, `session-timeout`); engine identifier itself is always inherited from the importing workflow | ### Field-Specific Merge Semantics [Section titled “Field-Specific Merge Semantics”](#field-specific-merge-semantics) Imports are processed using breadth-first traversal: direct imports first, then nested. Earlier imports in the list take precedence; circular imports fail at compile time. | Field | Merge strategy | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tools:` | Deep merge; `allowed` arrays concatenate and deduplicate. MCP tool conflicts fail except on `allowed` arrays. | | `mcp-servers:` | Imported servers override same-named main servers; first-wins across imports. | | `network:` | `allowed` domains union (deduped, sorted). Main `mode` and `firewall` take precedence. | | `permissions:` | Validation only — not merged. Main must declare all imported permissions at sufficient levels (`write` ≥ `read` ≥ `none`). | | `safe-outputs:` | Each type defined once; main overrides imports. Duplicate types across imports fail. | | `runtimes:` | Main overrides imports; imported values fill in unspecified fields. | | `services:` | All services merged; duplicate names fail compilation. | | `github-app:` | Main workflow’s `github-app` takes precedence; first imported value fills in if main does not define one. | | `checkout:` | Imported checkout entries are appended after the main workflow’s entries. For duplicate (repository, path) pairs, the main workflow’s entry takes precedence: first-seen wins for `ref`, and auth is mutually exclusive — once `github-token` or `github-app` is set by the main workflow, an imported duplicate cannot add the other auth method. `checkout: false` in the main workflow disables all checkout including imported entries. | | `engine.mcp` | First-wins across imports. Shared files may define `engine:` with only `mcp.tool-timeout` and/or `mcp.session-timeout` (no engine identifier). The importing workflow’s own engine setting always takes precedence; the first imported value fills in if the main workflow does not set a value. | | `steps:` | Imported steps prepended to main; concatenated in import order. | | `pre-agent-steps:` | Imported pre-agent-steps prepended to main; concatenated in import order. | | `post-steps:` | Imported post-steps appended after main; concatenated in import order. | | `jobs:` | Not merged — define only in the main workflow. Use `safe-outputs.jobs` for importable jobs. | | `safe-outputs.jobs` | Names must be unique; duplicates fail. Order determined by `needs:` dependencies. | | `env:` | Main workflow env vars take precedence over imports. Duplicate keys across different imports fail compilation — move to the main workflow to override imported values. | Example — `tools.bash.allowed` merging: ```aw # main.md: [write] # import: [read, list] # result: [read, list, write] ``` ### Importing Steps [Section titled “Importing Steps”](#importing-steps) Share reusable pre-execution steps — such as token rotation, environment setup, or gate checks — across multiple workflows by defining them in a shared file: shared/rotate-token.md ```aw --- description: Shared token rotation setup steps: - name: Rotate GitHub App token id: get-token uses: actions/create-github-app-token@v1 with: client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} --- ``` Any workflow that imports this file gets the rotation step prepended before its own steps: my-workflow\.md ```aw --- on: issues engine: copilot imports: - shared/rotate-token.md permissions: contents: read issues: write steps: - name: Prepare context run: echo "context ready" --- # My Workflow Process the issue using the rotated token from the imported step. ``` Steps from imports run **before** steps defined in the main workflow, in import declaration order. ### Importing MCP Servers [Section titled “Importing MCP Servers”](#importing-mcp-servers) Define an MCP server configuration once and import it wherever needed: shared/mcp/tavily.md ```aw --- description: Tavily web search MCP server mcp-servers: tavily: url: "https://mcp.tavily.com/mcp/?tavilyApiKey=${{ secrets.TAVILY_API_KEY }}" allowed: ["*"] network: allowed: - mcp.tavily.com --- ``` Consumers import it with `imports: [shared/mcp/tavily.md]`. ### Importing MCP Gateway Settings [Section titled “Importing MCP Gateway Settings”](#importing-mcp-gateway-settings) Shared workflow files can export `engine.mcp.tool-timeout` and `engine.mcp.session-timeout` without specifying an engine identifier — the engine itself is always inherited from the importing workflow. shared/mcp/slow-backend.md ```aw --- description: MCP gateway settings for slow-backend MCP servers engine: mcp: tool-timeout: 5m # Allow up to 5 minutes per tool call session-timeout: 2h # Keep MCP sessions alive for long-running workflows --- ``` The importing workflow’s own `engine.mcp` settings take precedence. Among imports, the first file that declares a timeout wins for that setting. ### Importing Top-level `jobs:` [Section titled “Importing Top-level jobs:”](#importing-top-level-jobs) Top-level `jobs:` defined in a shared workflow are merged into the importing workflow’s compiled lock file. The job execution order is determined by `needs` entries — a shared job can run before or after other jobs in the final workflow: shared/build.md ```aw --- description: Shared build job that compiles artifacts for the agent to inspect jobs: build: runs-on: ubuntu-latest needs: [activation] outputs: artifact_name: ${{ steps.build.outputs.artifact_name }} steps: - uses: actions/checkout@v6 - name: Build id: build run: | npm ci && npm run build echo "artifact_name=build-output" >> "$GITHUB_OUTPUT" - uses: actions/upload-artifact@v4 with: name: build-output path: dist/ steps: - uses: actions/download-artifact@v4 with: name: ${{ needs.build.outputs.artifact_name }} path: /tmp/build-output --- ``` Import it so the `build` job runs before the agent and its artifacts are available as pre-steps: my-workflow\.md ```aw --- on: pull_request engine: copilot imports: - shared/build.md permissions: contents: read pull-requests: write --- # Code Review Workflow Review the build output in /tmp/build-output and suggest improvements. ``` In the compiled lock file the `build` job appears alongside `activation` and `agent` jobs, ordered according to each job’s `needs` declarations. ### Importing Jobs via `safe-outputs.jobs` [Section titled “Importing Jobs via safe-outputs.jobs”](#importing-jobs-via-safe-outputsjobs) Jobs defined under `safe-outputs:` can be shared across workflows. These jobs become callable MCP tools that the AI agent can invoke during execution: shared/notify.md ```aw --- description: Shared notification job safe-outputs: notify-slack: description: "Post a message to Slack" runs-on: ubuntu-latest output: "Notification sent" inputs: message: description: "Message to post" required: true type: string steps: - name: Post to Slack env: SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK_URL }} run: | curl -s -X POST "$SLACK_WEBHOOK" \ -H "Content-Type: application/json" \ -d "{\"text\":\"${{ inputs.message }}\"}" --- ``` Consumers import it with `imports: [shared/notify.md]` and instruct the agent to call `notify-slack` when appropriate. ## Self-Contained Lock Files (`inlined-imports: true`) [Section titled “Self-Contained Lock Files (inlined-imports: true)”](#self-contained-lock-files-inlined-imports-true) Setting `inlined-imports: true` embeds all imported content directly into the compiled `.lock.yml` at compile time. The resulting lock file is **self-contained** — it requires no file-system access or cross-repository checkout at runtime. Enable it whenever runtime import resolution would fail: * **Cross-organization `workflow_call`** — a trigger in Org A calling a workflow in Org B cannot check out Org B’s `.github` folder with the caller’s `GITHUB_TOKEN`, producing `fatal: repository '...' not found`. * **Repository rulesets** — workflows used as a [required status check](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) run in a restricted context that cannot access other files in the repo, producing `ERR_SYSTEM: Runtime import file not found`. Both cases are solved by bundling imports into the lock file at compile time: ```aw --- on: workflow_call: engine: copilot inlined-imports: true imports: - shared/common-tools.md - shared/security-setup.md --- # Platform Gateway Workflow Workflow instructions here. ``` After adding the flag, recompile: ```bash gh aw compile my-workflow ``` **Trade-off**: the compiled `.lock.yml` is larger because imported content is embedded inline. Note With `inlined-imports: true`, any change to an imported file requires recompiling the workflow to take effect. The compiled `.lock.yml` must be committed and pushed for the updated content to run. `inlined-imports: true` cannot be combined with agent file imports (`.github/agents/` files). If your workflow imports a custom agent file, remove it before enabling inlined imports. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Packaging and Updating](/gh-aw/guides/packaging-imports/) - Complete guide to managing workflow imports * [Frontmatter](/gh-aw/reference/frontmatter/) - Configuration options reference * [MCPs](/gh-aw/guides/mcps/) - Model Context Protocol setup * [Safe Outputs](/gh-aw/reference/safe-outputs/) - Safe output configuration details * [Network Configuration](/gh-aw/reference/network/) - Network permission management # Inline Sub-Agents > Define Copilot sub-agents directly inside a workflow markdown file using a level-2 heading delimiter. An inline Copilot sub-agent is a named agent definition embedded directly in a workflow markdown file. Instead of creating a separate file in `.github/agents/`, you define the agent’s frontmatter and instructions in a dedicated section of the same workflow file. Inline sub-agents are enabled by default. `features.inline-agents` is deprecated/no-op, and `inline-sub-agents: false` is rejected at compile time. ## Syntax [Section titled “Syntax”](#syntax) Start a sub-agent block with a level-2 heading in the following form: ```markdown ## agent: `name` ``` The block continues until the next `##` heading or end of file. There is no explicit closing marker. ### Name constraints [Section titled “Name constraints”](#name-constraints) * Must start with a lowercase letter (`a–z`) * May contain only `a–z`, `0–9`, `_`, and `-` * Examples: `file-summarizer`, `code_reviewer`, `pr-analyst` ### Structure [Section titled “Structure”](#structure) Each sub-agent block contains: 1. **YAML frontmatter** (optional) — wrapped in `---` delimiters 2. **Instructions** — natural language prompt for the agent ```markdown ## agent: `file-summarizer` --- model: claude-haiku-4.5 description: Summarizes the content of a file in a few concise sentences --- You are a file summarization assistant. When given a file path, read the file and return a brief summary (2–4 sentences) describing its purpose and key contents. Be concise and factual. ``` ## Frontmatter fields [Section titled “Frontmatter fields”](#frontmatter-fields) | Field | Required | Description | | ------------- | -------- | ----------------------------------------------------------------------------------- | | `model` | No | AI model to use (e.g. `claude-haiku-4.5`). Defaults to the parent workflow’s model. | | `description` | No | Short description of the sub-agent’s purpose. | ## Runtime behavior [Section titled “Runtime behavior”](#runtime-behavior) At runtime, each inline sub-agent block is extracted to a location that the AI engine can access natively. The destination path depends on the engine: | Engine | Destination path | | --------- | -------------------------------- | | `copilot` | `.github/agents/.agent.md` | | `claude` | `.claude/agents/.md` | | `codex` | `.codex/agents/.md` | | `gemini` | `.gemini/agents/.md` | To use a sub-agent, instruct the parent workflow’s prompt to invoke it by name: ```aw ## Test Requirements 15. **Sub-Agent Testing**: Use the `file-summarizer` sub-agent to summarize the file `.github/workflows/smoke-copilot.md`. Verify the sub-agent returns a brief summary (2–4 sentences). Mark this test as ✗ if the sub-agent is unavailable or returns an error. ``` ## Example: File Summarization Sub-Agent [Section titled “Example: File Summarization Sub-Agent”](#example-file-summarization-sub-agent) The following excerpt shows a full workflow that defines and uses an inline sub-agent. ```aw --- on: workflow_dispatch: engine: copilot --- # File Summary Task Use the `file-summarizer` sub-agent to summarize `README.md` and add a comment to the current pull request with the result. ## agent: `file-summarizer` --- model: claude-haiku-4.5 description: Summarizes the content of a file in a few concise sentences --- You are a file summarization assistant. When given a file path, read the file and return a brief summary (2–4 sentences) describing its purpose and key contents. Be concise and factual. ``` The sub-agent block at the bottom is extracted before the workflow runs and has no effect on the parent workflow’s instructions. ## Example: Multiple Sub-Agents in One Workflow [Section titled “Example: Multiple Sub-Agents in One Workflow”](#example-multiple-sub-agents-in-one-workflow) A single workflow file may contain more than one sub-agent block. Each block starts with its own `## agent: \`name\``heading and ends at the next`##\` heading or EOF. ```aw ## agent: `summarizer` --- model: claude-haiku-4.5 description: Summarizes files concisely --- Summarize the given file in 2–4 sentences. ## agent: `reviewer` --- model: claude-sonnet-4.5 description: Reviews code for quality issues --- Review the given code for bugs, style issues, and potential improvements. ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Importing Copilot Agent Files](/gh-aw/reference/copilot-custom-agents/) — Importing agents from `.github/agents/` * [DeterministicOps](/gh-aw/patterns/deterministic-ops/) — Combining deterministic steps with AI reasoning * [Markdown](/gh-aw/reference/markdown/) — Workflow markdown body reference * [Workflow Structure](/gh-aw/reference/workflow-structure/) — Overall workflow file organization * [Frontmatter](/gh-aw/reference/frontmatter/) — YAML configuration options # GitHub Integrity Filtering > How integrity filtering restricts agent access to GitHub content based on author trust and merge status, and how filtered events appear in logs. Integrity filtering (`tools.github.min-integrity`) controls which GitHub content an agent can access during a workflow run. Rather than filtering by permissions, it filters by **trust**: the author association of an issue, pull request, or comment, and whether that content has been merged into the main branch. ## How It Works [Section titled “How It Works”](#how-it-works) The MCP gateway intercepts tool calls to GitHub and applies integrity checks to each piece of content returned. If an item’s integrity level is below the configured minimum, the gateway removes it before the AI engine sees it. This happens transparently — the agent receives a reduced result set, and filtered items are logged as `DIFC_FILTERED` events for later inspection. ## Configuration [Section titled “Configuration”](#configuration) Set `min-integrity` under `tools.github` in your workflow frontmatter: ```aw tools: github: min-integrity: approved ``` `min-integrity` can be specified alone. When `allowed-repos` is omitted, it defaults to `"all"`. If `allowed-repos` is also specified, both fields must be present. ```aw tools: github: allowed-repos: "myorg/*" min-integrity: approved ``` ## Configuration Reference [Section titled “Configuration Reference”](#configuration-reference) All integrity-filtering inputs are specified under `tools.github` in your workflow frontmatter. The table below summarizes every available field: | Field | Type | Required | Default | Description | | ------------------------ | ------------------- | ----------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | `min-integrity` | string | Yes (when any guard policy field is used) | `approved` for public repos; none for private | Minimum integrity level: `merged`, `approved`, `unapproved`, or `none` | | `allowed-repos` | string or array | No | `"all"` | Repository scope: `"all"`, `"public"`, or an array of patterns like `["myorg/*", "partner/repo"]` | | `blocked-users` | array or expression | No | `[]` | GitHub usernames whose content is unconditionally denied | | `trusted-users` | array or expression | No | `[]` | GitHub usernames elevated to `approved` integrity regardless of author association | | `approval-labels` | array or expression | No | `[]` | GitHub label names that promote items to `approved` integrity | | `refusal-labels` | array or expression | No | `[]` | GitHub label names that downgrade items to `none` integrity, overriding any promotion from `trusted-users` or `approval-labels` | | `integrity-proxy` | boolean | No | `true` | Whether to run the DIFC proxy for pre-agent `gh` CLI calls. Set to `false` to disable | | `endorsement-reactions` | array | No | `["THUMBS_UP", "HEART"]` (when `integrity-reactions` enabled) | Reaction types that promote item integrity to `approved`. Requires `features.integrity-reactions: true` | | `disapproval-reactions` | array | No | `["THUMBS_DOWN", "CONFUSED"]` (when `integrity-reactions` enabled) | Reaction types that demote item integrity. Requires `features.integrity-reactions: true` | | `endorser-min-integrity` | string | No | `approved` (when `integrity-reactions` enabled) | Minimum integrity of the reactor for an endorsement or disapproval to take effect. Requires `features.integrity-reactions: true` | | `disapproval-integrity` | string | No | `none` (when `integrity-reactions` enabled) | Integrity level assigned when a qualifying disapproval reaction is added. Requires `features.integrity-reactions: true` | ## Integrity Levels [Section titled “Integrity Levels”](#integrity-levels) The full integrity hierarchy, from highest to lowest: ```text merged > approved > unapproved > none > blocked ``` | Level | What qualifies at this level | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `merged` | Pull requests that have been merged, and commits reachable from the default branch (any author) | | `approved` | Objects authored by `OWNER`, `MEMBER`, or `COLLABORATOR`; non-fork PRs on public repos; all items in private repos; trusted platform bots (e.g., dependabot); users listed in `trusted-users` | | `unapproved` | Objects authored by `CONTRIBUTOR` or `FIRST_TIME_CONTRIBUTOR` | | `none` | All objects, including `FIRST_TIMER` and users with no association (`NONE`) | | `blocked` | Items authored by users in `blocked-users` — always denied, cannot be promoted | The four configurable levels (`merged`, `approved`, `unapproved`, `none`) are cumulative and ordered from most restrictive to least. Setting `min-integrity: approved` means only items at `approved` level **or higher** (`merged`) reach the agent. Items at `unapproved` or `none` are filtered out. `blocked` is not a configurable `min-integrity` value — it is assigned automatically to items from users in `blocked-users` and is always denied regardless of the threshold, even when `min-integrity: none`. See [Blocking specific users](#blocking-specific-users). ## Scoping to Repositories [Section titled “Scoping to Repositories”](#scoping-to-repositories) `allowed-repos` defines which repositories the guard policy applies to. It accepts three forms: * **`"all"`** — All repositories the token can access (default when omitted). * **`"public"`** — Only public repositories. * **An array of patterns** — Specific repositories or owner wildcards. ```aw tools: github: allowed-repos: - "myorg/*" - "partner/shared-repo" min-integrity: approved ``` Repository patterns must be lowercase and follow one of these formats: | Pattern | Meaning | | --------------- | ---------------------------------------------------------- | | `owner/*` | All repositories under `owner` | | `owner/prefix*` | Repositories under `owner` whose name starts with `prefix` | | `owner/repo` | A single specific repository | ## Adjusting Integrity Per-Item [Section titled “Adjusting Integrity Per-Item”](#adjusting-integrity-per-item) Beyond setting a minimum level, you can override integrity for specific authors or labels. ### Blocking specific users [Section titled “Blocking specific users”](#blocking-specific-users) `blocked-users` unconditionally blocks content from listed GitHub usernames, regardless of `min-integrity`, `trusted-users`, or any labels. Blocked items receive an effective integrity of `blocked` (below `none`) and are always denied. ```aw tools: github: min-integrity: none blocked-users: - "spam-bot" - "compromised-account" ``` Use this to suppress content from known-bad accounts — automated bots, compromised users, or external contributors pending security review. ### Trusting specific users [Section titled “Trusting specific users”](#trusting-specific-users) `trusted-users` elevates content from listed GitHub usernames to `approved` integrity, regardless of their author association. This is useful for contractors, partner developers, or external contributors who should be treated as trusted even though GitHub classifies them as `CONTRIBUTOR` or `FIRST_TIME_CONTRIBUTOR`. ```aw tools: github: min-integrity: approved trusted-users: - "contractor-1" - "partner-dev" ``` Trust elevation only raises integrity — it never lowers it. A user already at `merged` stays at `merged`. `blocked-users` always takes precedence: if a user appears in both `blocked-users` and `trusted-users`, they are blocked. `trusted-users` requires `min-integrity` to be set. ### Promoting items via labels [Section titled “Promoting items via labels”](#promoting-items-via-labels) `approval-labels` promotes items bearing any listed GitHub label to `approved` integrity, enabling human-review workflows where a trusted reviewer labels content to signal it is safe for the agent. ```aw tools: github: min-integrity: approved approval-labels: - "human-reviewed" - "safe-for-agent" ``` This is useful when a workflow’s `min-integrity` would normally filter out external contributions, but a maintainer can label specific items to let them through. Promotion only raises integrity — it never lowers it. An item already at `merged` stays at `merged`. Blocked-user exclusion always takes precedence: a blocked user’s items remain blocked even if they carry an approval label. ### Refusing items via labels [Section titled “Refusing items via labels”](#refusing-items-via-labels) `refusal-labels` is the inverse of `approval-labels`. Items bearing any listed GitHub label are downgraded to `none` integrity, regardless of the author’s association or any promotion from `trusted-users` or `approval-labels`. ```aw tools: github: min-integrity: approved refusal-labels: - "needs-security-review" - "do-not-automate" ``` This is useful when a workflow’s `min-integrity` would normally allow certain content, but a maintainer can label specific items to suppress them from the agent — for example, issues flagged as security-sensitive or pull requests pending a manual compliance check. Refusal always overrides promotion: if an item carries both an `approval-labels` label and a `refusal-labels` label, the item’s effective integrity is set to `none`. Blocked-user exclusion still takes precedence: a blocked user’s items remain blocked regardless of any labels. ### Promoting and demoting items via reactions [Section titled “Promoting and demoting items via reactions”](#promoting-and-demoting-items-via-reactions) `features.integrity-reactions: true` allows maintainers to adjust item integrity using GitHub reactions, without adding labels or modifying issue state. Available from gh-aw v0.68.2. ```aw features: integrity-reactions: true tools: github: min-integrity: approved ``` When enabled, the compiler automatically enables the CLI proxy (required to identify reaction authors) and injects default reaction configuration. When an account at or above `endorser-min-integrity` adds an endorsement reaction to an issue or comment, the item’s integrity is promoted to `approved`. A disapproval reaction from such an account sets the item’s integrity to `disapproval-integrity`. The defaults are `endorsement-reactions: [THUMBS_UP, HEART]`, `disapproval-reactions: [THUMBS_DOWN, CONFUSED]`, `endorser-min-integrity: approved`, and `disapproval-integrity: none`. To override them, set the reaction fields explicitly under `tools.github`: ```aw tools: github: endorsement-reactions: - "THUMBS_UP" - "HEART" disapproval-reactions: - "THUMBS_DOWN" endorser-min-integrity: merged disapproval-integrity: unapproved ``` Valid reaction values: `THUMBS_UP`, `THUMBS_DOWN`, `HEART`, `HOORAY`, `CONFUSED`, `ROCKET`, `EYES`, `LAUGH`. The reaction fields only take effect when `features.integrity-reactions: true` is also set. ### Using GitHub Actions expressions [Section titled “Using GitHub Actions expressions”](#using-github-actions-expressions) `blocked-users`, `trusted-users`, `approval-labels`, and `refusal-labels` can each accept a GitHub Actions expression instead of a literal array. The expression is evaluated at runtime and should resolve to a comma- or newline-separated list of values. ```aw tools: github: min-integrity: approved blocked-users: ${{ vars.BLOCKED_USERS }} trusted-users: ${{ vars.TRUSTED_USERS }} approval-labels: ${{ vars.APPROVAL_LABELS }} refusal-labels: ${{ vars.REFUSAL_LABELS }} ``` This is useful for managing lists centrally via GitHub repository or organization variables rather than duplicating them across workflows. ### Effective integrity computation [Section titled “Effective integrity computation”](#effective-integrity-computation) The gateway derives each item’s effective integrity from the base level (author association, merge status, repo visibility), then applies the first matching rule below. The `min-integrity` threshold check runs against the result. 1. Author in `blocked-users` → `blocked` (always denied). 2. Item has a `refusal-labels` label → `none` (overrides any promotion). 3. Author in `trusted-users` → max(base, `approved`). 4. Item has an `approval-labels` label → max(base, `approved`). 5. Otherwise → base. ## Centralized Management via GitHub Variables [Section titled “Centralized Management via GitHub Variables”](#centralized-management-via-github-variables) Each per-item list (`blocked-users`, `trusted-users`, `approval-labels`, `refusal-labels`) can also be extended centrally using GitHub repository or organization variables. The runtime automatically unions the per-workflow values with the corresponding variable: | Workflow field | GitHub variable | | ----------------- | ------------------------------ | | `blocked-users` | `GH_AW_GITHUB_BLOCKED_USERS` | | `trusted-users` | `GH_AW_GITHUB_TRUSTED_USERS` | | `approval-labels` | `GH_AW_GITHUB_APPROVAL_LABELS` | | `refusal-labels` | `GH_AW_GITHUB_REFUSAL_LABELS` | For example, if a workflow declares `blocked-users: ["spam-bot"]` and the organization variable `GH_AW_GITHUB_BLOCKED_USERS` is set to `compromised-acct,old-bot`, the effective blocked-users list at runtime is `["spam-bot", "compromised-acct", "old-bot"]`. Variables are split on commas and newlines, trimmed, and deduplicated. Set these as repository variables (under **Settings → Secrets and variables → Actions → Variables**) or as organization-level variables to apply them across all workflows. This mechanism allows a security team to maintain a shared blocked-users list, approval-labels policy, or refusal-labels policy without modifying individual workflow files. ## Default Behavior [Section titled “Default Behavior”](#default-behavior) For **public repositories**, if no `min-integrity` is configured, the runtime automatically applies `min-integrity: approved`. This protects public workflows even when additional authentication has not been set up. For **private and internal repositories**, no guard policy is applied automatically. Content from all users is accessible by default. ## Pre-Agent Integrity Proxy [Section titled “Pre-Agent Integrity Proxy”](#pre-agent-integrity-proxy) When a guard policy is configured (`min-integrity` is set), the compiler injects a DIFC proxy that filters `gh` CLI calls in pre-agent setup steps. This ensures that custom steps running before the agent see the same integrity-filtered API responses that the agent itself operates under. The proxy: * Routes `gh` CLI calls through integrity filtering using the same MCP gateway container. * Applies the static guard policy fields (`min-integrity` and `allowed-repos`) that are available at compile time. * Does **not** apply `blocked-users`, `trusted-users`, `approval-labels`, or `refusal-labels` (those are resolved at runtime after the proxy starts). * Is automatically started before custom steps and stopped before the MCP gateway starts to avoid double-filtering. ### Disabling the proxy [Section titled “Disabling the proxy”](#disabling-the-proxy) The proxy is enabled by default whenever a guard policy is configured. To disable it, set `integrity-proxy: false`: ```aw tools: github: min-integrity: approved integrity-proxy: false ``` This is an opt-out escape hatch for workflows where pre-agent steps should not be filtered — for example, when custom steps need unfiltered API access for setup purposes. Disabling the proxy only affects pre-agent `gh` CLI calls. The agent itself always operates under the configured guard policy via the MCP gateway. ## Choosing a Level [Section titled “Choosing a Level”](#choosing-a-level) The right level depends on who you want the agent to see content from: * **Workflows that automate code review or apply changes**: `merged` or `approved` — only act on trusted content. * **Workflows that respond to maintainers and trusted contributors**: `approved` — a common, safe default for most workflows. * **Community triage or planning workflows**: `unapproved` — allow contributor input while excluding anonymous or first-time interactions. * **Public-data workflows or spam detection**: `none` — see all activity, but ensure the workflow’s outputs are not directly applied without review. Note Setting `min-integrity: none` on a public repository disables the automatic protection. Only use it when the workflow is designed to handle untrusted input. ## Examples [Section titled “Examples”](#examples) **Production-only content (strictest):** ```aw tools: github: allowed-repos: "all" min-integrity: merged ``` **Community triage workflow:** ```aw tools: github: min-integrity: unapproved ``` **Combined policy — blocking, trusting, labeling, and refusing:** ```aw tools: github: allowed-repos: "all" min-integrity: approved blocked-users: - "known-spam-bot" trusted-users: - "contractor-1" approval-labels: - "agent-approved" refusal-labels: - "needs-security-review" ``` See [Adjusting Integrity Per-Item](#adjusting-integrity-per-item) above for individual snippets covering each field. ## In Logs and Reports [Section titled “In Logs and Reports”](#in-logs-and-reports) When an item is filtered by the integrity check, the MCP gateway records a `DIFC_FILTERED` event in the run’s `gateway.jsonl` log. Each event includes: * **Server**: the MCP server that returned the filtered content * **Tool**: the tool call that produced it (e.g., `list_issues`, `get_pull_request`) * **User**: the login of the content’s author * **Reason**: a description such as `"Resource has lower integrity than agent requires."` * **Integrity tags**: the tags assigned to the item that caused it to be filtered * **Author association**: the GitHub author association (`CONTRIBUTOR`, `FIRST_TIMER`, etc.) When gateway metrics are displayed, filtered events appear in a **DIFC Filtered Events** table alongside the standard server usage table: ```text ┌────────────────────────────────────────────────────────────────────────────────────┐ │ DIFC Filtered Events │ ├────────────────┬───────────────┬───────────────┬──────────────────────────────────-┤ │ Server │ Tool │ User │ Reason │ ├────────────────┼───────────────┼───────────────┼───────────────────────────────────┤ │ github │ list_issues │ new-user │ Resource has lower integrity than │ │ │ │ │ agent requires. │ └────────────────┴───────────────┴───────────────┴───────────────────────────────────┘ ``` The `Total DIFC Filtered` count in the summary line shows how many items were suppressed during the run. ### Filtering Logs by Integrity Events [Section titled “Filtering Logs by Integrity Events”](#filtering-logs-by-integrity-events) To download only runs that had integrity-filtered content, use the `--filtered-integrity` flag with the `logs` command: ```bash gh aw logs --filtered-integrity ``` This is useful when investigating whether your `min-integrity` configuration is filtering expected content or when tuning the level after observing real traffic patterns. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [GitHub Tools Reference](/gh-aw/reference/github-tools/) — Full `tools.github` configuration * [MCP Gateway](/gh-aw/reference/mcp-gateway/) — Gateway architecture and log format * [CLI Reference: logs](/gh-aw/setup/cli/#logs) — Downloading and analyzing workflow run logs # GitHub Lockdown Mode > GitHub lockdown mode has been superseded by Integrity Filtering, which provides finer-grained content filtering based on author trust and merge status. Note **GitHub Lockdown Mode is now replaced by GitHub Integrity Filtering.** Use [Integrity Filtering](/gh-aw/reference/integrity/) instead. Integrity filtering provides finer-grained control over which content the agent can see, based on author trust and merge status, and works without requiring additional authentication. ## Migrating to Integrity Filtering [Section titled “Migrating to Integrity Filtering”](#migrating-to-integrity-filtering) Replace `lockdown: true` with `min-integrity: approved`: ```yaml # Before (deprecated) tools: github: lockdown: true # After (recommended) tools: github: min-integrity: approved ``` Replace `lockdown: false` with `min-integrity: none`: ```yaml # Before (deprecated) tools: github: lockdown: false # After (recommended) tools: github: min-integrity: none ``` ## See Also [Section titled “See Also”](#see-also) * [Integrity Filtering](/gh-aw/reference/integrity/) — Complete reference for `min-integrity`, integrity levels, user blocking, and approval labels * [GitHub Tools Reference](/gh-aw/reference/github-tools/) — Full `tools.github` configuration # Markdown > Learn agentic workflow markdown content The markdown body is the most important part of your agentic workflow, containing natural language instructions for the AI agent. The markdown follows the frontmatter and is loaded at runtime, allowing you to edit instructions directly on GitHub.com without recompilation. For example: ```aw --- ...frontmatter... --- # Issue Triage Read the issue #${{ github.event.issue.number }}. Add a comment to the issue listing useful resources and links. ``` ## Writing Effective Instructions [Section titled “Writing Effective Instructions”](#writing-effective-instructions) Write instructions as if explaining the task to a new team member. Be specific, provide context about your project and constraints, and structure instructions with headings to guide the agent’s workflow. ```aw # Good: Specific and actionable Analyze issue #${{ github.event.issue.number }} and add appropriate labels from the repository's label list. Focus on categorizing the issue type (bug, feature, documentation) and priority level (high, medium, low). # Project Context This repository follows semantic versioning and GitHub Flow. When reviewing pull requests, ensure all tests pass, documentation is updated for API changes, and breaking changes are clearly marked. # Weekly Research Report ## Research Areas Focus on competitor analysis, emerging AI development trends, and community feedback for ${{ github.repository }}. ## Output Format Create a structured report with executive summary, key findings by area, and recommended actions. ``` Use action-oriented language with clear verbs (analyze, create, update, triage) and specify expected outcomes. Help agents make consistent decisions by providing criteria and examples: ```aw # Issue Labeling Criteria Apply labels: `bug` (incorrect behavior with repro steps), `enhancement` (new features), `question` (help requests), `documentation` (docs/examples). Priority: `high-priority` (security/critical bugs), `medium-priority` (features/non-critical bugs), `low-priority` (nice-to-have improvements). ``` Anticipate unusual situations and error conditions. If a workflow fails, document the failure in an issue with error messages and context, tag it with ‘workflow-failure’, and exit gracefully without partial changes. ## Content Organization [Section titled “Content Organization”](#content-organization) Use numbered lists for multi-step processes, conditional statements for decision-making, and templates for consistent output: ```aw # Code Review Process 1. Check CI checks are passing and PR has appropriate title/description 2. Scan for code quality issues and verify error handling/logging 3. Create constructive comments and summarize assessment # Issue Triage Logic If error messages/stack traces: label 'bug', check for similar issues, request info if needed If feature request: label 'enhancement', assess scope and complexity Otherwise: label 'question'/'discussion', provide resources # Status Report Template ## Summary: [week's activities] ## Key Metrics: PRs merged, issues resolved, new contributors ## Highlights: [achievements, decisions] ## Next Week: [planned priorities] ``` ## Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) Avoid over-complexity (keep instructions focused), assuming knowledge (explain project conventions), inconsistent formatting, missing error handling, and vague success criteria. Before deploying, read instructions aloud to check clarity, review examples for accuracy, and consider edge cases. ## Templating [Section titled “Templating”](#templating) Agentic markdown supports GitHub Actions expression substitutions and conditional templating for content. See [Templating and Substitutions](/gh-aw/reference/templating/) for details. ## Editing and Iteration [Section titled “Editing and Iteration”](#editing-and-iteration) See [Editing Workflows](/gh-aw/guides/editing-workflows/) for complete guidance on when recompilation is needed versus when you can edit directly. ## Markdown Scanning [Section titled “Markdown Scanning”](#markdown-scanning) The markdown body of workflows (excluding frontmatter) is automatically scanned for malicious content when added via `gh aw add`, during trial mode, and at compile time for imported files. The scanner rejects workflows containing: Unicode abuse (zero-width characters, bidirectional overrides), hidden content (suspicious HTML comments, CSS-hidden elements), obfuscated links (data URIs, `javascript:` URLs, IP-based URLs, URL shorteners), dangerous HTML tags (`` * `` * `` * ``, `` * Remove event handlers: * `on*` attributes in HTML tags (onclick, onerror, etc.) * Preserve safe GitHub Flavored Markdown tags: * `

`, `

`, `_{`, `^{`, `` **S5: Command Injection Prevention** * Do NOT execute or interpret code blocks * Do NOT evaluate template expressions * Preserve code blocks verbatim (no escaping needed in markdown) **Excluded Content** The following content MUST NOT be sanitized: * Code blocks (` ``` `) * Inline code (`` `code` ``) * System-generated footers * System-generated metadata **Sanitization Reversibility** Sanitization transformations are LOSSY and NOT reversible. Original content is not preserved after sanitization. This is intentional to prevent attempts to bypass sanitization. **Conformance Requirement CR1: Pre-API Sanitization** All content MUST be sanitized BEFORE GitHub API invocation. Unsanitized content MUST NEVER be passed to GitHub APIs. *Verification*: Inspect handler code to confirm sanitization occurs before `octokit.*` calls. ### 9.5 Error Code Catalog [Section titled “9.5 Error Code Catalog”](#95-error-code-catalog) Implementations MUST use standardized error codes for validation and execution failures. **Error Code Table** | Code | Name | Description | When to Use | HTTP Status Equivalent | | ---- | ---------------------- | ---------------------------------------------- | --------------------------------------------------- | ------------------------ | | E001 | INVALID\_SCHEMA | Operation failed JSON schema validation | Input does not match type-specific schema | 400 Bad Request | | E002 | LIMIT\_EXCEEDED | Operation count exceeds configured max | Batch contains more operations than allowed | 429 Too Many Requests | | E003 | UNAUTHORIZED\_DOMAIN | URL contains non-allowlisted domain | Domain filtering rejected URL | 403 Forbidden | | E004 | INVALID\_TARGET\_REPO | target-repo not in allowed-repos | Cross-repository validation failed | 403 Forbidden | | E005 | MISSING\_PARENT | Referenced parent issue/PR not found | Temporary ID or parent reference cannot be resolved | 404 Not Found | | E006 | INVALID\_LABEL | Label does not exist in repository | Label validation failed | 404 Not Found | | E007 | API\_ERROR | GitHub API returned error | GitHub API call failed | 502 Bad Gateway | | E008 | SANITIZATION\_FAILED | Content contains unsanitizable unsafe patterns | Sanitization pipeline detected unremovable threats | 422 Unprocessable Entity | | E009 | CONFIG\_HASH\_MISMATCH | Configuration hash verification failed | Workflow YAML was modified after compilation | 403 Forbidden | | E010 | RATE\_LIMIT\_EXCEEDED | GitHub API rate limit exceeded | Too many API calls | 429 Too Many Requests | **Error Message Format** All errors MUST conform to this JSON structure: ```json { "error": { "code": "E002", "name": "LIMIT_EXCEEDED", "message": "Operation count exceeds configured limit", "details": { "type": "create_issue", "attempted": 5, "max": 3, "operation_index": 3 }, "timestamp": "2026-02-14T16:39:20.948Z", "workflow_run": "https://github.com/owner/repo/actions/runs/12345" } } ``` **Required Fields**: * `code`: Error code from table above (E001-E010) * `name`: Error name from table above * `message`: Human-readable description * `timestamp`: ISO 8601 timestamp **Optional Fields**: * `details`: Type-specific error context (operation\_index, field names, etc.) * `workflow_run`: URL to workflow run for provenance **Error Handling Requirements** **Requirement EH1: Early Failure Detection** Validation errors (E001-E006) MUST be detected before any GitHub API calls are made. **Requirement EH2: Clear Error Messages** Error messages MUST: * Clearly state what went wrong * Include enough context to debug (field names, values) * Suggest remediation when possible **Requirement EH3: Error Logging** All errors MUST be logged to: * GitHub Actions step output (visible in workflow run) * Job summary (visible in workflow run summary) * STDERR (for local development) *** ## 10. Execution Guarantees [Section titled “10. Execution Guarantees”](#10-execution-guarantees) ### 10.1 Atomicity [Section titled “10.1 Atomicity”](#101-atomicity) **Single-Item Operations**: Complete success or complete failure (no partial state). **Batch Operations**: Best-effort semantics; partial success reported. ### 10.2 Ordering [Section titled “10.2 Ordering”](#102-ordering) Operations execute in: 1. NDJSON file order 2. Type grouping (same type together) 3. System types last (noop, missing\_tool, missing\_data, report\_incomplete) ### 10.3 Idempotency [Section titled “10.3 Idempotency”](#103-idempotency) **Idempotent Operations**: * add\_labels (adding present label) * remove\_labels (removing absent label) * hide\_comment (hiding hidden comment) **Non-Idempotent Operations**: * create\_issue * create\_discussion * add\_comment ### 10.4 Error Handling [Section titled “10.4 Error Handling”](#104-error-handling) **Fail-Safe Principle**: One operation’s failure doesn’t prevent others from attempting. **Error Reporting**: All errors collected; execution summary reports per-type results. ### 10.5 Warn-Mode Threat Detection Failure Policy [Section titled “10.5 Warn-Mode Threat Detection Failure Policy”](#105-warn-mode-threat-detection-failure-policy) When threat detection executes in `warn` mode and reports a threat signal for a safe output, implementations MUST apply a type-specific fallback policy before any safe output side effect is committed. **Requirement WTD1 (Reviewable Annotation)**: For safe output types classified as **Reviewable** in Table WTD-A, implementations MUST convert the output into a review-first artifact that includes all of the following: 1. A prominent caution section: Danger agentic threat detected Threat detection flagged this output in warn mode. Manual review is REQUIRED before any follow-up automation. 2. A visible threat label string: `agentic threat detected`. 3. An XML comment marker in emitted markdown content: ``. **Requirement WTD2 (Convertible Fallback)**: For safe output types classified as **Convertible**, implementations MUST transform the operation into the mapped Reviewable type before execution. For this specification, `push_to_pull_request_branch` (also referred to as `update-pull-request-branch`) MUST fall back to `create_pull_request` with the WTD1 caution, label, and XML marker. **Requirement WTD3 (Non-Reviewable Abort)**: For safe output types classified as **Abort**, implementations MUST NOT apply the original safe output. Implementations MUST activate a threat-detected code path, emit an explicit failure summary, and return a machine-readable threat-detected error outcome. **Table WTD-A: Warn-Mode Threat Detection Failure Policy by Safe Output Type** | Safe output type | Warn-mode failure policy | | --------------------------------------- | ----------------------------------- | | `create_issue` | Reviewable | | `add_comment` | Reviewable | | `create_pull_request` | Reviewable | | `noop` | Abort | | `comment_memory` | Reviewable | | `update_issue` | Reviewable | | `close_issue` | Abort | | `link_sub_issue` | Abort | | `create_discussion` | Reviewable | | `update_discussion` | Reviewable | | `close_discussion` | Abort | | `update_pull_request` | Reviewable | | `close_pull_request` | Abort | | `merge_pull_request` | Abort | | `mark_pull_request_as_ready_for_review` | Abort | | `push_to_pull_request_branch` | Convertible (`create_pull_request`) | | `create_pull_request_review_comment` | Reviewable | | `submit_pull_request_review` | Reviewable | | `resolve_pull_request_review_thread` | Abort | | `reply_to_pull_request_review_comment` | Reviewable | | `add_labels` | Abort | | `remove_labels` | Abort | | `add_reviewer` | Abort | | `assign_milestone` | Abort | | `assign_to_agent` | Abort | | `assign_to_user` | Abort | | `unassign_from_user` | Abort | | `hide_comment` | Abort | | `create_project` | Abort | | `update_project` | Abort | | `create_project_status_update` | Reviewable | | `update_release` | Reviewable | | `upload_asset` | Abort | | `dispatch_workflow` | Abort | | `create_code_scanning_alert` | Reviewable | | `autofix_code_scanning_alert` | Abort | | `create_agent_session` | Abort | | `missing_tool` | Reviewable | | `missing_data` | Reviewable | | `report_incomplete` | Reviewable | **Compliance Testing**: * **T-WTD-001**: Reviewable outputs include CAUTION block, label text `agentic threat detected`, and XML comment marker. * **T-WTD-002**: `push_to_pull_request_branch` in warn-mode threat failure is converted to `create_pull_request`. * **T-WTD-003**: Abort-class outputs are not applied and produce threat-detected error outcomes. ### 10.6 Edge Case Behavior [Section titled “10.6 Edge Case Behavior”](#106-edge-case-behavior) This section defines required behavior for unusual or boundary conditions. **Empty Operations** *Scenario*: NDJSON artifact contains zero operations *Behavior*: * Safe output job MUST succeed (exit code 0) * Job summary SHOULD display: ”✓ No operations to process” * No GitHub API calls are made * No errors are raised *Rationale*: Empty operations are valid (agent may determine no action is needed). **Zero Max Limit** *Scenario*: Configuration specifies `max: 0` for a safe output type *Behavior*: * Type is DISABLED (MCP tool is not registered) * Attempts to invoke disabled type MUST return MCP error: ```json {"error": {"code": -32601, "message": "Method not found"}} ``` * No configuration is generated for disabled types *Rationale*: `max: 0` is an explicit disable signal. **API Rate Limiting** *Scenario*: GitHub API returns 429 (rate limit exceeded) or 403 with X-RateLimit-Remaining: 0 *Behavior*: * Processor MUST retry with exponential backoff: * 1st retry: After 60 seconds * 2nd retry: After 120 seconds * 3rd retry: After 240 seconds * After 3 retries, MUST fail with E010 error * Error details MUST include rate limit reset time from `X-RateLimit-Reset` header *Rationale*: Transient rate limits should not fail workflows unnecessarily. **Workflow Cancellation** *Scenario*: Workflow is manually cancelled during agent execution *Behavior*: * Safe output job MUST NOT execute if artifact upload was interrupted * Partial NDJSON artifacts MUST NOT be processed * GitHub Actions automatically handles cleanup * No additional logic required in handlers *Rationale*: GitHub Actions cancellation is handled at platform level. **Concurrent Workflow Runs** *Scenario*: Multiple workflow runs execute concurrently for the same workflow *Behavior*: * Each run operates independently * Max limits are per-run (NOT global across runs) * No coordination or locking between runs * Operations in separate runs do NOT affect each other’s limits *Rationale*: Simplicity and avoiding distributed coordination complexity. **Malformed NDJSON** *Scenario*: NDJSON artifact contains invalid JSON on one or more lines *Behavior*: * Parser MUST skip invalid lines with warning * Valid lines MUST be processed * Job summary MUST show: “! Skipped N malformed entries” * Invalid lines MUST be logged to STDERR *Rationale*: Partial failure should not prevent valid operations from executing. **Missing Artifact** *Scenario*: Safe output job cannot download artifact (artifact not found) *Behavior*: * Job MUST fail with clear error message * Error MUST suggest checking agent job completion * Exit code MUST be non-zero *Rationale*: Missing artifact indicates upstream failure that must be addressed. **Duplicate Temporary IDs** *Scenario*: Multiple operations use the same `temporary_id` *Behavior*: * First operation using the ID succeeds and establishes mapping * Subsequent operations using the same ID MUST reference the first operation’s result * If this creates ambiguity (e.g., two issues both want to be “aw\_parent”), MUST reject with E005 *Rationale*: Deterministic behavior prevents confusion. *** ## 11. Cache Memory Integrity [Section titled “11. Cache Memory Integrity”](#11-cache-memory-integrity) ### 11.1 Overview and Motivation [Section titled “11.1 Overview and Motivation”](#111-overview-and-motivation) The cache-memory subsystem provides agents with a persistent filesystem share backed by GitHub Actions cache. Prior to this specification version, caches used a flat directory structure with no integrity provenance. This allowed a `none`-integrity agent to write data into a shared cache store that was subsequently restored and consumed by a higher-integrity run—a Bell-LaPadula write-up violation (Threat T6). This section specifies the integrity-aware cache architecture that prevents cross-integrity cache contamination while preserving the ability for lower-integrity runs to read data produced by higher-integrity runs (read-down semantics). **Design Goals**: 1. **Write isolation**: Data written at integrity level *L* MUST NOT be visible to a run at integrity level *H* where trust(*H*) > trust(*L*) (no write-up). 2. **Read-down access**: A run at integrity level *L* MAY read data produced by runs at higher integrity levels (read-down is permitted and expected). 3. **Policy binding**: A cache entry MUST be invalidated when the guard policy changes, preventing data inherited under one policy from being consumed under a different, potentially more permissive policy. 4. **Transparency**: The agent MUST remain unaware of the git repository structure within the cache directory. The agent reads and writes plain files as normal. 5. **Migration**: Legacy flat-file caches (with no `.git` directory) MUST be automatically imported onto the `merged` integrity branch on first use. ### 11.2 Integrity Levels [Section titled “11.2 Integrity Levels”](#112-integrity-levels) Four integrity levels are defined, ordered from highest to lowest trust: | Level | Description | | ------------ | --------------------------------------------------------------------------- | | `merged` | Content that has passed code review and been merged into the default branch | | `approved` | Content from pull requests that have been reviewed and approved | | `unapproved` | Content from open, un-approved pull requests | | `none` | Content from workflows without a configured guard policy | The ordering MUST be: `merged` > `approved` > `unapproved` > `none`. ### 11.3 Integrity-Aware Cache Key Format [Section titled “11.3 Integrity-Aware Cache Key Format”](#113-integrity-aware-cache-key-format) **Requirement CI1: Integrity-Scoped Keys** All cache-memory keys MUST include the integrity level and policy hash as prefixes, in the following format: ```plaintext memory-{integrityLevel}-{policyHash}-[{cacheID}-]{workflowID}-{runID} ``` Where: * `{integrityLevel}` is the `min-integrity` value from the guard policy, or `none` when no guard policy is configured. * `{policyHash}` is the 8-character hex prefix of the SHA-256 policy hash (see Section 11.4), or the sentinel string `nopolicy` when no guard policy is configured. * `{cacheID}` is the user-defined cache identifier. The `default` cache ID MUST be omitted from the key to maintain a clean format. * `{workflowID}` is the sanitized workflow identifier (`GH_AW_WORKFLOW_ID_SANITIZED`). * `{runID}` is the GitHub Actions run identifier (`github.run_id`). **Examples**: ```plaintext # Default cache, with guard policy (min-integrity: unapproved, 8-char policy hash) memory-unapproved-7e4d9f12-${{ env.GH_AW_WORKFLOW_ID_SANITIZED }}-${{ github.run_id }} # Default cache, no guard policy memory-none-nopolicy-${{ env.GH_AW_WORKFLOW_ID_SANITIZED }}-${{ github.run_id }} # Named "session" cache, no guard policy memory-none-nopolicy-session-${{ env.GH_AW_WORKFLOW_ID_SANITIZED }}-${{ github.run_id }} ``` **Requirement CI2: Restore Key Cascade** Restore keys MUST use the same integrity-scoped prefix so that a partial key match never crosses integrity level boundaries: ```plaintext restore-keys: | memory-{integrityLevel}-{policyHash}-{workflowID}- memory-{integrityLevel}-{policyHash}- memory- ``` The final fallback `memory-` entry exists solely to allow migration from legacy (non-scoped) caches and MUST be removed in a future major version. ### 11.4 Policy Hash Computation [Section titled “11.4 Policy Hash Computation”](#114-policy-hash-computation) **Requirement CI3: Deterministic Policy Hash** The policy hash MUST be computed as the first 8 characters of the lowercase hex SHA-256 digest of a canonical policy string, constructed as follows: 1. For each of the following fields, produce a canonical value: * `blocked-users`: Lowercase, sort, deduplicate. If specified as a GitHub Actions expression (e.g., `${{ github.event.sender.login }}`), prefix the raw expression with `expr:` (e.g., `expr:${{ github.event.sender.login }}`). * `min-integrity`: Use the literal string value. * `repos`: If a string (`"all"` or `"public"`), lowercase. If an array, lowercase all entries, sort, and deduplicate. * `trusted-bots`: Reserved for future use; always empty. * `trusted-users`: Reserved for future use; always empty. 2. Concatenate the fields in the fixed order shown below, each followed by a newline: ```plaintext blocked-users:{canonicalBlockedUsers}\n min-integrity:{minIntegrity}\n repos:{canonicalRepos}\n trusted-bots:\n trusted-users:{canonicalTrustedUsers} ``` 3. Compute SHA-256 over the UTF-8 encoding of the canonical string. 4. Take the first 8 characters of the lowercase hexadecimal representation. **Requirement CI4: Sentinel for No-Policy Workflows** Workflows without a configured `min-integrity` field MUST use the sentinel string `nopolicy` in place of the policy hash. **Rationale**: The sentinel avoids hash computation for the common case of no guard policy and is visually distinguishable from a genuine policy hash in cache key inspection. ### 11.5 Git-Backed Integrity Branching [Section titled “11.5 Git-Backed Integrity Branching”](#115-git-backed-integrity-branching) The cache-memory directory MUST be a Git repository when integrity branching is active. The `.git` directory rides along within the GitHub Actions cache tarball, persisting integrity branch history across workflow runs. **Repository Structure**: ```plaintext /tmp/gh-aw/cache-memory/ ├── .git/ ← Git metadata (integrity branches, history) │ └── refs/heads/ │ ├── merged │ ├── approved │ ├── unapproved │ └── none ├── file-written-by-merged-run.json └── file-written-by-unapproved-run.txt ``` **Agent Transparency**: The agent MUST see and interact with only the plain files in the working directory. The agent MUST NOT need knowledge of Git or the branching structure. File system operations (read, write, delete) behave normally from the agent’s perspective. **Requirement CI5: .git Directory Exclusion from Validation** File validation steps that enforce allowed extensions, size limits, or other constraints MUST skip the `.git` directory. The Git metadata directory contains binary and extension-less files that are not agent-managed content. ### 11.6 Pre-Agent Setup (Integrity Checkout) [Section titled “11.6 Pre-Agent Setup (Integrity Checkout)”](#116-pre-agent-setup-integrity-checkout) A setup step MUST execute after the cache is restored and before the agent runs. The reference implementation of this step is `actions/setup/sh/setup_cache_memory_git.sh` (informative). All conforming implementations MUST satisfy requirements CI6–CI9 regardless of the implementation mechanism. **Requirement CI6: Git Repository Initialization** If the restored cache directory does not contain a `.git` subdirectory (fresh or legacy cache), the implementation MUST: 1. Initialize a new Git repository on the `merged` branch. 2. Stage and commit all existing files (if any) as an `initial` commit. This migrates legacy flat-file caches automatically. 3. Create all four integrity branches (`merged`, `approved`, `unapproved`, `none`) from the same baseline commit. **Requirement CI7: Integrity Branch Checkout** After initialization (or if the repository already exists), the implementation MUST check out the branch corresponding to the run’s `min-integrity` value. If `min-integrity` is absent, the `none` branch MUST be used. **Requirement CI8: Merge-Down from Higher-Integrity Branches** Before the agent executes, the implementation MUST merge all higher-integrity branches into the current branch, in descending trust order (highest first), using the `theirs` merge strategy (`-X theirs`) so that higher-integrity content takes precedence in conflicts. The merge semantics table is: | Run integrity | Branches merged in (read access) | Branches NOT merged in | | ------------- | ---------------------------------- | -------------------------------- | | `merged` | (none — highest, no merge-down) | `approved`, `unapproved`, `none` | | `approved` | `merged` | `unapproved`, `none` | | `unapproved` | `merged`, `approved` | `none` | | `none` | `merged`, `approved`, `unapproved` | (none — reads all) | **Requirement CI9: Merge Failure Handling** If a merge from a higher-integrity branch fails for reasons other than “nothing to merge” or “already up-to-date”, the implementation MUST abort the merge, restore the working tree to its pre-merge state, and exit with a non-zero status code to fail the workflow step. ### 11.7 Post-Agent Commit (Integrity Persistence) [Section titled “11.7 Post-Agent Commit (Integrity Persistence)”](#117-post-agent-commit-integrity-persistence) A commit step MUST execute after the agent completes and before the cache is saved. The reference implementation is `actions/setup/sh/commit_cache_memory_git.sh` (informative). The step MUST execute regardless of whether the agent step succeeded or failed (i.e., unconditional execution, not gated on agent success). **Requirement CI10: Agent Changes Committed** The implementation MUST: 1. Stage all changes within the cache directory (`git add -A`). 2. Commit on the current integrity branch with a message of the form `run-{GITHUB_RUN_ID}`. 3. Allow empty commits (`--allow-empty`) so that runs that made no file changes still produce a commit marker in the branch history. **Requirement CI11: Repository Compaction** After committing, the implementation MUST invoke `git gc --auto` to prevent unbounded growth of the Git object database within the cache tarball. **Requirement CI12: No-Repository Fallback** If no `.git` directory is present at commit time (e.g., the setup step was skipped), the commit step MUST exit cleanly with a diagnostic message and MUST NOT fail the workflow. ### 11.8 Lifecycle Diagram [Section titled “11.8 Lifecycle Diagram”](#118-lifecycle-diagram) The following diagram illustrates the full per-run lifecycle: ```plaintext GitHub Actions Cache Restore │ ▼ setup_cache_memory_git.sh 1. If no .git: git init -b merged, import files, create all branches 2. git checkout {integrity} 3. For each higher-integrity branch (descending): git merge {branch} -X theirs │ ▼ Agent Execution (reads/writes plain files — unaware of git) │ ▼ commit_cache_memory_git.sh [if: always()] 1. git add -A 2. git commit --allow-empty -m "run-{run_id}" 3. git gc --auto │ ▼ GitHub Actions Cache Save (tarball includes .git directory with all integrity branches) ``` ### 11.9 Compliance Requirements [Section titled “11.9 Compliance Requirements”](#119-compliance-requirements) | Requirement | Test ID | Level | | ---------------------------------------------- | -------- | ----------- | | CI1: Integrity-scoped cache keys | T-CI-001 | Required | | CI2: Restore key cascade | T-CI-002 | Required | | CI3: Deterministic policy hash | T-CI-003 | Required | | CI4: Sentinel for no-policy workflows | T-CI-004 | Required | | CI5: .git directory excluded from validation | T-CI-005 | Required | | CI6: Git repository initialization | T-CI-006 | Required | | CI7: Integrity branch checkout | T-CI-007 | Required | | CI8: Merge-down from higher-integrity branches | T-CI-008 | Required | | CI9: Merge failure handling | T-CI-009 | Required | | CI10: Agent changes committed | T-CI-010 | Required | | CI11: Repository compaction | T-CI-011 | Recommended | | CI12: No-repository fallback | T-CI-012 | Required | ### 11.10 Migration from Legacy Flat-File Caches [Section titled “11.10 Migration from Legacy Flat-File Caches”](#1110-migration-from-legacy-flat-file-caches) Existing deployments using the pre-integrity cache format MUST expect a **cache miss** on the first run after upgrading to an implementation supporting this section. **Legacy key format** (before this section): ```plaintext memory-{workflowID}-{runID} # Example: memory-my-workflow-12345678 ``` **New key format** (this section): ```plaintext memory-{integrityLevel}-{policyHash}-{workflowID}-{runID} # Example (with policy): memory-unapproved-7e4d9f12-my-workflow-12345678 # Example (without policy): memory-none-nopolicy-my-workflow-12345678 ``` The integrity level and policy hash prefixes are new components not present in legacy keys. Because the key formats differ, legacy cache entries will never match the new restore keys, resulting in a one-time cache miss. *Rationale*: Legacy cache data has no integrity provenance. Blindly consuming legacy data under the new integrity model would provide no security guarantee. The automatic migration path in Requirement CI6 handles any residual files from the old format by importing them to the `merged` branch on first initialization. Operators SHOULD communicate this expected one-time cache miss to their teams to avoid confusion during upgrade. *** **Required for Full Conformance**: * [ ] Security Architecture * [ ] Privilege separation enforced * [ ] Artifact-based communication * [ ] Threat mitigations implemented * [ ] Security properties maintained * [ ] Configuration * [ ] All global parameters supported * [ ] Type-specific parameters supported * [ ] Inheritance rules followed * [ ] Compilation-time validation * [ ] Universal Features * [ ] Max limit enforcement * [ ] Staged mode preview generation * [ ] Footer injection * [ ] Content sanitization pipeline * [ ] Safe Output Types * [ ] Mandatory: create\_issue, add\_comment, create\_pull\_request, noop, missing\_tool, missing\_data, report\_incomplete * [ ] Optional types documented if unsupported * [ ] Protocol * [ ] HTTP transport * [ ] MCP tool invocation * [ ] NDJSON persistence * [ ] Content Security * [ ] Schema validation * [ ] Domain filtering * [ ] Sanitization pipeline * [ ] Execution Guarantees * [ ] Atomicity for single-item operations * [ ] Best-effort for batch operations * [ ] Fail-safe error handling *** ## Appendix B: Security Considerations [Section titled “Appendix B: Security Considerations”](#appendix-b-security-considerations) ### Attack Surface Analysis [Section titled “Attack Surface Analysis”](#attack-surface-analysis) **Entry Points**: 1. Agent-provided tool arguments 2. Configuration in frontmatter 3. GitHub API responses **Trust Boundaries**: * Agent context (untrusted) * MCP Gateway (semi-trusted) * Safe output processor (trusted) * GitHub API (trusted) ### Mitigation Effectiveness [Section titled “Mitigation Effectiveness”](#mitigation-effectiveness) Detailed threat analysis and mitigation effectiveness assessment for all five primary threats (see Section 3.2). *** ## Appendix C: Implementation Guidance [Section titled “Appendix C: Implementation Guidance”](#appendix-c-implementation-guidance) ### Recommended Practices [Section titled “Recommended Practices”](#recommended-practices) 1. **Conservative Limits**: Start with minimal max values 2. **Staged Mode Development**: Test workflows in preview mode first 3. **Explicit Domain Lists**: Use restrictive domain filtering 4. **Expires for Temporary Resources**: Auto-close temporary issues ### Common Pitfalls [Section titled “Common Pitfalls”](#common-pitfalls) 1. **Unlimited Max**: Removes important safety constraint 2. **Permissive Domains**: Loses URL filtering protection 3. **Cross-Repo Without Allowlist**: Permits arbitrary targets 4. **Disabled Footers**: Reduces transparency *** ## Appendix D: Normative References [Section titled “Appendix D: Normative References”](#appendix-d-normative-references) * **RFC 2119**: Key words for RFCs (MUST, SHALL, etc.) * **JSON Schema Draft 7**: JSON Schema specification * **NDJSON**: Newline Delimited JSON format * **MCP Specification**: Model Context Protocol *** ## Appendix E: Informative References [Section titled “Appendix E: Informative References”](#appendix-e-informative-references) * **GitHub REST API**: * **GitHub Actions**: * **MCP Gateway Specification**: /gh-aw/reference/mcp-gateway/ *** ## Appendix G: Configuration Patterns [Section titled “Appendix G: Configuration Patterns”](#appendix-g-configuration-patterns) This appendix provides common configuration patterns for safe outputs. ### Pattern 1: Simple Issue Tracking [Section titled “Pattern 1: Simple Issue Tracking”](#pattern-1-simple-issue-tracking) Basic configuration for automated issue creation: ```yaml safe-outputs: create-issue: max: 1 labels: [automated] ``` **Use case**: Single automated issue per workflow run with consistent labeling. ### Pattern 2: Multi-Type with Global Footer [Section titled “Pattern 2: Multi-Type with Global Footer”](#pattern-2-multi-type-with-global-footer) Configuration with multiple output types sharing global settings: ```yaml safe-outputs: footer: true # Applied to all types create-issue: max: 3 labels: [bug, automated] add-comment: max: 2 hide-older-comments: true ``` **Use case**: Workflow creating multiple issues and comments with attribution footers. ### Pattern 3: Cross-Repository Operations [Section titled “Pattern 3: Cross-Repository Operations”](#pattern-3-cross-repository-operations) Secure cross-repository issue creation: ```yaml safe-outputs: allowed-github-references: - owner/repo-a - owner/repo-b create-issue: max: 5 target-repo: owner/repo-a ``` **Use case**: Creating issues in a central tracking repository from multiple workflow repositories. **Security note**: Explicit allowlist prevents unauthorized repository targeting. ### Pattern 4: Staged Mode Development [Section titled “Pattern 4: Staged Mode Development”](#pattern-4-staged-mode-development) Safe testing in preview mode: ```yaml safe-outputs: staged: true # Enable preview mode globally create-issue: max: 10 # Safe to set high in staged mode add-comment: max: 5 ``` **Use case**: Testing workflow behavior without creating real GitHub resources. **Workflow**: Test with `staged: true`, verify previews, then deploy with `staged: false`. ### Pattern 5: Type-Specific Allowlists [Section titled “Pattern 5: Type-Specific Allowlists”](#pattern-5-type-specific-allowlists) Fine-grained cross-repository control: ```yaml safe-outputs: allowed-github-references: [owner/repo-a, owner/repo-b] create-issue: allowed-repos: [owner/repo-c] # Overrides global max: 3 add-comment: # No type-specific list, uses global: repo-a, repo-b max: 2 ``` **Use case**: Different safe output types target different repositories. **Security note**: Type-specific allowlists override global allowlists. ### Pattern 6: Domain Filtering for Security [Section titled “Pattern 6: Domain Filtering for Security”](#pattern-6-domain-filtering-for-security) Restrict URLs in safe output content: ```yaml safe-outputs: allowed-domains: - github.com - "*.github.io" - docs.github.com create-issue: max: 5 ``` **Use case**: Prevent agents from including unauthorized URLs in created content. **Effect**: URLs to non-allowlisted domains are redacted during sanitization. ### Pattern 7: Temporary Resource Cleanup [Section titled “Pattern 7: Temporary Resource Cleanup”](#pattern-7-temporary-resource-cleanup) Auto-close temporary issues: ```yaml safe-outputs: create-issue: max: 10 expires: 7 # Auto-close after 7 days labels: [temporary, automated] ``` **Use case**: Issues for transient notifications that should auto-clean. **Implementation**: Scheduled workflow checks issue age and closes expired issues. ### Pattern 8: Review Comment Workflow [Section titled “Pattern 8: Review Comment Workflow”](#pattern-8-review-comment-workflow) Pull request review automation with reply support: ```yaml safe-outputs: create-pr-review-comment: max: 20 submit-pr-review: max: 1 reply-to-pull-request-review-comment: max: 10 resolve-pr-review-thread: max: 10 ``` **Use case**: Automated code review with inline comments, review replies, and thread resolution. **Workflow**: Create review comments, submit bundled review, reply to reviewer feedback, resolve addressed threads. ### Pattern 9: Project Management [Section titled “Pattern 9: Project Management”](#pattern-9-project-management) Automated project creation and updates: ```yaml safe-outputs: create-project: max: 1 update-project: max: 5 create-project-status-update: max: 3 ``` **Use case**: Creating and maintaining project boards automatically. ### Pattern 10: Grouped Issues with Parent [Section titled “Pattern 10: Grouped Issues with Parent”](#pattern-10-grouped-issues-with-parent) Create related issues under a parent: ```yaml safe-outputs: create-issue: max: 10 group: true ``` **Use case**: Workflow creates parent issue and multiple sub-issues linked via tasklists. **Effect**: First issue becomes parent, subsequent issues link to it. ### Best Practices [Section titled “Best Practices”](#best-practices) **Start Conservative**: * Begin with low `max` values * Enable `staged: true` for testing * Use explicit `allowed-repos` lists **Use Domain Filtering**: * Always configure `allowed-domains` when agents process external input * Include only trusted domains **Enable Footers**: * Keep `footer: true` (default) for transparency * Only disable when absolutely necessary **Temporary Resources**: * Use `expires` for transient issues * Clean up with `close-older-issues` for superseded content **Cross-Repository Security**: * Use type-specific `allowed-repos` for fine-grained control * Prefer explicit lists over broad permissions *** ## Appendix F: Document History [Section titled “Appendix F: Document History”](#appendix-f-document-history) ### Changelog Alignment (Reviewer and Status-Comment Updates) [Section titled “Changelog Alignment (Reviewer and Status-Comment Updates)”](#changelog-alignment-reviewer-and-status-comment-updates) This specification revision aligns with directly relevant `CHANGELOG.md` entries and with the current reviewer/status-comment PR updates: * **v0.40.1**: `add_comment` discussion handling was updated to auto-detect discussion context without requiring a `discussion` flag. * **v0.40.1**: append-only status comment behavior was documented for smoke workflow execution. * **Earlier changelog entry**: status comments were decoupled from default AI reaction behavior; explicit `on.status-comment` configuration is required when status comments are desired. * **Earlier changelog entry**: `command` trigger was renamed to `slash_command` with deprecation compatibility. **Version 1.21.0** (2026-05-19): * **Added**: `add_comment` status-comment reuse extension semantics in Section 7.1 for `target: "status"` behavior and issue/PR-only restrictions. * **Added**: Changelog alignment subsection mapping safe-output/reviewer changelog items to this specification revision. * **Updated**: Publication metadata to 1.21.0. **Version 1.20.0** (2026-05-15): * **Added**: Section 10.5 warn-mode threat-detection failure policy with mandatory reviewable annotation requirements (`agentic threat detected` caution, label, and XML marker). * **Added**: Per-type policy matrix (Table WTD-A) annotating every safe output type as Reviewable, Convertible, or Abort during warn-mode threat failures. * **Added**: Normative conversion fallback from `push_to_pull_request_branch` (`update-pull-request-branch`) to `create_pull_request`. * **Added**: Compliance tests T-WTD-001 through T-WTD-003 for warn-mode threat-detection failure handling. * **Updated**: Publication metadata to 1.20.0. **Version 1.19.0** (2026-04-30): * **Added**: Auto-injection of `create-issue` when no `safe-outputs:` section is present (or when only system types are configured). The injected config uses `max: 1`, with labels and `title-prefix` set to the workflow ID. Injection is suppressed when any non-builtin safe output is explicitly configured. * **Updated**: Section 4.3 Configuration Propagation to document the implicit `create-issue` default path. * **Updated**: Section 7.2 System Types to document `create-issue` conditional auto-injection. * **Updated**: Publication metadata to 1.19.0 **Version 1.18.0** (2026-04-21): * **Added**: `comment_memory` safe output type definition in Section 7.3, including file-based synchronization model and required permissions * **Added**: Phase 8 “Comment Memory Round-Trip” in Section 4.2 defining end-to-end flow across GitHub comment, local files, agent, artifacts, threat detection, and comment upsert * **Updated**: Publication metadata to 1.18.0 **Version 1.17.0** (2026-04-19): * **Added**: `merge_pull_request` safe output type definition in Section 7.3, including schema, policy gate semantics, and required permissions * **Documented**: Merge policy gates for checks, reviews, labels, branch constraints, file constraints, and base-branch restrictions * **Updated**: Publication metadata to 1.17.0 **Version 1.15.0** (2026-03-29): * **Added**: Section 11 “Cache Memory Integrity” specifying integrity-aware cache key format, git-backed branching, merge-down semantics, pre-agent setup, and post-agent commit requirements (CI1–CI12) * **Added**: Threat T6 “Cache Integrity Poisoning” to Section 3.2, describing Bell-LaPadula write-up violations in cache-memory and their architectural mitigations * **Added**: Terminology entries for *Integrity Level*, *Policy Hash*, *Integrity Branch*, and *Cache Poisoning* * **Updated**: Table of Contents to include Section 11 **Version 1.14.0** (2026-02-22): * **Added**: Section 5.5 “Templatable Fields” documenting support for GitHub Actions expressions in integer and boolean configuration fields * **Updated**: GP1 (`footer` global), TS1 (`max`), and TS2 (`footer` type-specific) syntax to document expression support * **Clarified**: Templatable integer fields (`max`) and templatable boolean fields (`footer`, `group`, `close-older-issues`, `hide-older-comments`, `close-older-discussions`, `draft`, `allow-empty`, `auto-merge`, `report-as-issue`, `unassign-first`) accept `${{ ... }}` GitHub Actions expressions in addition to literal values * **Added**: Conformance requirements for runtime evaluation of templatable fields **Version 1.13.0** (2026-02-18): * **Added**: Optional `discussions` field for `add-comment` and `hide-comment` safe output types to control `discussions:write` permission * **Enhanced**: Permission documentation for `add-comment` and `hide-comment` to explain conditional `discussions:write` inclusion * **Added**: Configuration examples demonstrating `discussions: false` usage for GitHub Apps without Discussions permission * **Fixed**: Issue where `add-comment` and `hide-comment` unconditionally requested `discussions:write` permission, causing 422 errors for GitHub Apps lacking Discussions permission * **Default behavior**: `discussions: true` (or omitted) includes `discussions:write` for backward compatibility * **Opt-out behavior**: `discussions: false` excludes `discussions:write` permission for GitHub Apps without Discussions permission **Version 1.12.0** (2026-02-16): * **Implemented**: MCE1 (Early Validation) for add\_comment tool with MCP server constraint enforcement * **Added**: Runtime validation in safe\_outputs\_handlers.cjs that enforces comment limits during tool invocation * **Verified**: Dual enforcement pattern now operational - MCP server validates during Phase 4, safe output processor validates during Phase 6 * **Enhanced**: Error responses now use JSON-RPC error code -32602 with actionable messages containing specific constraint details * **Tested**: Comprehensive test suite (16 test cases) validates E006/E007/E008 error handling and MCP error format compliance **Version 1.11.0** (2026-02-15): * **Added**: Section 8.3 “MCP Server Constraint Enforcement” specifying requirements for early validation during tool invocation (MCE1-MCE5) * **Enhanced**: Tool descriptions to surface operational constraints to the LLM (e.g., add\_comment mention/link/length limits) * **Clarified**: Dual enforcement pattern requiring validation at both MCP server and safe output processor layers * **Added**: Constraint consistency requirement (MCE5) ensuring limits are identical across tool schemas and enforcement code * **Added**: Example constraint table for common safe output types with error codes * **Updated**: add\_comment tool description in safe\_outputs\_tools.json to include explicit constraint documentation **Version 1.10.0** (2026-02-14): * **Added**: `reply_to_pull_request_review_comment` safe output type definition (Section 7.3) * **Updated**: Pattern 8 (Review Comment Workflow) to include reply-to-review-comment in example configuration **Version 1.9.0** (2026-02-14): * Added comprehensive validation pipeline ordering (7 stages) * Added cross-repository security model with explicit allowlist rules * Added content sanitization pipeline specification (5 stages) * Added standardized error code catalog (E001-E010) * Added edge case behavior specifications * Added terminology section for consistency * Enhanced security properties (SP6, SP7) * Improved requirements testability **Version 1.8.0** (2025-02-14): * Initial W3C-style specification release * Complete security model documentation * Comprehensive safe output type catalog * Protocol exchange pattern definitions * Content security mechanisms * Operational guarantees formalization **Future Work**: * Formal conformance test suite * Extended threat modeling * Performance benchmarks * Additional safe output type proposals *** **End of Specification** Copyright 2025 GitHub, Inc. All rights reserved. This document may be distributed and implemented according to the terms specified in the project license. # Sandbox Configuration > Configure sandbox environments for AI engines including AWF agent container, mounted tools, runtime environments, and MCP Gateway The `sandbox` field configures sandbox environments for AI engines (coding agents), providing two main capabilities: 1. **Coding Agent Sandbox** - Controls the agent runtime security using AWF (Agent Workflow Firewall) 2. **Model Context Protocol (MCP) Gateway** - Routes MCP server calls through a unified HTTP gateway ## Configuration [Section titled “Configuration”](#configuration) ### Coding Agent Sandbox [Section titled “Coding Agent Sandbox”](#coding-agent-sandbox) Configure the coding agent sandbox type to control how the AI engine is isolated: ```yaml # Use AWF (Agent Workflow Firewall) - default sandbox: agent: awf # Disable coding agent sandbox (firewall only) - use with caution sandbox: agent: false # Or omit sandbox entirely to use the default (awf) ``` **Default Behavior** If `sandbox` is not specified in your workflow, it defaults to `sandbox.agent: awf`. The coding agent sandbox is recommended for all workflows. **Disabling Coding Agent Sandbox** Setting `sandbox.agent: false` disables only the agent firewall while keeping the MCP gateway enabled. This reduces security isolation and should only be used when necessary. The MCP gateway cannot be disabled and remains active in all workflows. ### MCP Gateway (Experimental) [Section titled “MCP Gateway (Experimental)”](#mcp-gateway-experimental) Route MCP server calls through a unified HTTP gateway: ```yaml features: mcp-gateway: true sandbox: mcp: port: 8080 api-key: "${{ secrets.MCP_GATEWAY_API_KEY }}" ``` ### Combined Configuration [Section titled “Combined Configuration”](#combined-configuration) Use both coding agent sandbox and MCP gateway together: ```yaml features: mcp-gateway: true sandbox: agent: awf mcp: port: 8080 ``` ## Coding Agent Sandbox Types [Section titled “Coding Agent Sandbox Types”](#coding-agent-sandbox-types) ### AWF (Agent Workflow Firewall) [Section titled “AWF (Agent Workflow Firewall)”](#awf-agent-workflow-firewall) AWF is the default coding agent sandbox that provides network egress control through domain-based access controls. Network permissions are configured through the top-level [`network`](/gh-aw/reference/network/) field. ```yaml sandbox: agent: awf network: firewall: true allowed: - defaults - python - "api.example.com" ``` #### Filesystem Access [Section titled “Filesystem Access”](#filesystem-access) AWF makes the host filesystem visible inside the container with appropriate permissions: | Path Type | Mode | Examples | | ------------- | ---------- | ------------------------------------ | | User paths | Read-write | `$HOME`, `$GITHUB_WORKSPACE`, `/tmp` | | System paths | Read-only | `/usr`, `/opt`, `/bin`, `/lib` | | Docker socket | Hidden | `/var/run/docker.sock` (security) | #### Host Binaries [Section titled “Host Binaries”](#host-binaries) All host binaries are available without explicit mounts: system utilities, `gh`, language runtimes, build tools, and anything installed via `apt-get` or setup actions. Verify with `which `. Caution Docker socket is hidden for security. Agents cannot spawn containers. #### Environment Variables [Section titled “Environment Variables”](#environment-variables) AWF passes all environment variables via `--env-all`. The host `PATH` is captured as `AWF_HOST_PATH` and restored inside the container, preserving setup action tool paths. Note Go’s “trimmed” binaries require `GOROOT` - AWF automatically captures it after `actions/setup-go`. #### Runtime Tools [Section titled “Runtime Tools”](#runtime-tools) Setup actions work transparently. Runtimes update `PATH`, which AWF captures and restores inside the container. ```yaml --- jobs: setup: steps: - uses: actions/setup-go@v5 with: go-version: '1.25' - uses: actions/setup-python@v5 with: python-version: '3.12' --- Use `go build` or `python3` - both are available. ``` ## MCP Gateway [Section titled “MCP Gateway”](#mcp-gateway) The MCP Gateway routes all MCP server calls through a unified HTTP gateway, enabling centralized management, logging, and authentication for MCP tools. ## Feature Flags [Section titled “Feature Flags”](#feature-flags) Some sandbox features require feature flags: | Feature | Flag | Description | | ----------- | ------------- | -------------------------- | | MCP Gateway | `mcp-gateway` | Enable MCP gateway routing | Enable feature flags in your workflow: ```yaml features: mcp-gateway: true ``` ## Long Build Times [Section titled “Long Build Times”](#long-build-times) Repositories with lengthy build or test cycles — C++ codebases, large monorepos, or complex integration suites — can exhaust the default 20-minute job timeout or hit individual tool-call time limits. This section describes how to tune those limits. ### Setting the Job Timeout (`timeout-minutes`) [Section titled “Setting the Job Timeout (timeout-minutes)”](#setting-the-job-timeout-timeout-minutes) The `timeout-minutes` frontmatter field sets the maximum wall-clock time for the entire agent job. The default is 20 minutes. For repositories where a full build or test run takes 10 minutes or more, increase this value: ```yaml --- on: issues timeout-minutes: 60 # 60-minute budget for the agent job --- Fix the failing test in the C++ core library. ``` **Recommended values by repository type:** | Repository type | Typical build time | Suggested `timeout-minutes` | | --------------------------------- | ------------------ | --------------------------- | | Small (scripts, docs) | < 2 min | 20 (default) | | Medium (Go, Python, Node) | 2–10 min | 30–60 | | Large (C++, Rust, Java monorepo) | 10–30 min | 60–120 | | Very large (distributed, full CI) | > 30 min | 120–360 | GitHub Actions enforces a hard upper limit of 360 minutes (6 hours) for a single job. `timeout-minutes` also accepts a GitHub Actions expression, making it easy to parameterize in `workflow_call` reusable workflows: ```yaml on: workflow_call: inputs: job-timeout: type: number default: 60 --- timeout-minutes: ${{ inputs.job-timeout }} ``` ### Concrete Example: 30-Minute Timeout for a C++ Repository [Section titled “Concrete Example: 30-Minute Timeout for a C++ Repository”](#concrete-example-30-minute-timeout-for-a-c-repository) ```yaml --- on: issues: types: [opened, labeled] engine: copilot runs-on: [self-hosted, linux, x64, large] # fast self-hosted runner timeout-minutes: 30 # 30-minute agent budget tools: bash: [":*"] timeout: 300 # 5-minute per-tool-call budget network: allowed: - defaults - go - node --- Reproduce the bug described in this issue, add a regression test, and fix it. Build with `cmake --build build -j$(nproc)` and verify with `ctest --output-on-failure`. ``` ### Splitting Build and Test into Separate Steps [Section titled “Splitting Build and Test into Separate Steps”](#splitting-build-and-test-into-separate-steps) Instead of relying on a single large timeout, break long workflows into a custom `jobs:` setup step that caches build outputs, then runs the agent on the pre-built workspace: ```yaml --- on: issues timeout-minutes: 45 jobs: setup: steps: - name: Restore build cache uses: actions/cache@v4 with: path: build/ key: cpp-build-${{ hashFiles('CMakeLists.txt', 'src/**') }} restore-keys: cpp-build- - name: Build (if cache miss) run: | cmake -B build -DCMAKE_BUILD_TYPE=Release cmake --build build -j$(nproc) - name: Save build cache uses: actions/cache/save@v4 with: path: build/ key: cpp-build-${{ hashFiles('CMakeLists.txt', 'src/**') }} --- The build artifacts are already in `build/`. Run the failing tests with `ctest --test-dir build --output-on-failure -R ` and fix any failures. ``` Pre-building in a setup job ensures the agent’s `timeout-minutes` budget is spent on analysis and code changes, not waiting for compilation. ### Per-Tool-Call Timeout (`tools.timeout`) [Section titled “Per-Tool-Call Timeout (tools.timeout)”](#per-tool-call-timeout-toolstimeout) `tools.timeout` controls the maximum time for any single tool invocation (e.g., a `bash` command or MCP server call), in seconds. Increase this when individual commands — such as a full build or a slow test suite — routinely take longer than the engine default: ```yaml tools: timeout: 600 # 10 minutes per tool call (seconds) ``` Default values vary by engine: Claude uses 60 s, Codex uses 120 s. See [Tool Timeout Configuration](/gh-aw/reference/tools/#tool-timeout-configuration) for details. ### Self-Hosted Runners for Fast Hardware [Section titled “Self-Hosted Runners for Fast Hardware”](#self-hosted-runners-for-fast-hardware) For repositories where build time exceeds 10 minutes on standard GitHub-hosted runners, self-hosted runners with more CPU cores, faster storage, and pre-warmed dependency caches can dramatically reduce wall-clock time: ```yaml --- on: issues runs-on: [self-hosted, linux, x64, large] # 32-core self-hosted runner timeout-minutes: 30 --- Run the full test suite and fix any failures. ``` See [Self-Hosted Runners](/gh-aw/guides/self-hosted-runners/) for setup instructions, including Docker and `sudo` requirements. ### Caching Build Artifacts Between Runs [Section titled “Caching Build Artifacts Between Runs”](#caching-build-artifacts-between-runs) Use `actions/cache` in a custom `jobs.setup` block to persist build artifacts across agentic runs. This avoids redundant compilation and keeps the agent job within tighter time budgets: ```yaml --- on: issues timeout-minutes: 30 jobs: setup: steps: - uses: actions/cache@v4 with: path: | ~/.gradle/caches build/ key: gradle-${{ hashFiles('**/*.gradle*') }} restore-keys: gradle- - run: ./gradlew build -x test --parallel --- Review the failing tests and apply a fix. Build artifacts are pre-cached. ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Network Permissions](/gh-aw/reference/network/) - Configure network access controls * [AI Engines](/gh-aw/reference/engines/) - Engine-specific configuration * [Tools](/gh-aw/reference/tools/) - Configure MCP tools and servers * [Self-Hosted Runners](/gh-aw/guides/self-hosted-runners/) - Use custom hardware for long-running jobs * [Frontmatter Reference](/gh-aw/reference/frontmatter/#run-configuration-run-name-runs-on-runs-on-slim-timeout-minutes) - `timeout-minutes` syntax # Schedule Syntax > Complete reference for fuzzy schedule syntax and cron expressions This reference documents the complete schedule syntax supported by GitHub Agentic Workflows, including fuzzy schedules (recommended), time constraints, and standard cron expressions. ## Overview [Section titled “Overview”](#overview) GitHub Agentic Workflows supports human-friendly schedule expressions that are automatically converted to cron format. The system includes two types of schedules: * **Fuzzy schedules** (recommended) - Automatically scatter execution times across workflows to prevent load spikes * **Fixed schedules** - Run at specific times, but create server load when many workflows use the same time Fuzzy schedules distribute workflow execution times deterministically across all workflows in your repository. Each workflow gets a unique, consistent execution time that never changes across recompiles, preventing server load spikes. Note GitHub Actions enforces a minimum schedule interval of 5 minutes. ## Quick Reference [Section titled “Quick Reference”](#quick-reference) | Pattern | Example | Result | Type | | -------------- | ------------------------------------------ | ------------------------- | ----- | | **Daily** | `daily` | Scattered time | Fuzzy | | | `daily on weekdays` | Mon-Fri, scattered time | Fuzzy | | | `daily around 14:00` | 13:00-15:00 window | Fuzzy | | | `daily around 9am on weekdays` | Mon-Fri 8am-10am | Fuzzy | | | `daily between 9:00 and 17:00` | 9am-5pm window | Fuzzy | | | `daily between 9:00 and 17:00 on weekdays` | Mon-Fri 9am-5pm | Fuzzy | | **Hourly** | `hourly` | Scattered minute | Fuzzy | | | `hourly on weekdays` | Mon-Fri, scattered minute | Fuzzy | | | `every 2h` | Every 2 hours | Fuzzy | | | `every 2h on weekdays` | Mon-Fri every 2 hours | Fuzzy | | **Weekly** | `weekly` | Scattered day/time | Fuzzy | | | `weekly on monday` | Monday, scattered time | Fuzzy | | | `weekly on friday around 5pm` | Friday 4pm-6pm | Fuzzy | | **Bi-weekly** | `bi-weekly` | Scattered across 2 weeks | Fuzzy | | **Tri-weekly** | `tri-weekly` | Scattered across 3 weeks | Fuzzy | | **Intervals** | `every 10 minutes` | Every 10 minutes | Fixed | | | `every 2 days` | Every 2 days | Fixed | | **Cron** | `0 9 * * 1` | Standard cron | Fixed | ## Fuzzy Schedules [Section titled “Fuzzy Schedules”](#fuzzy-schedules) Fuzzy schedules automatically distribute workflow execution times to prevent server load spikes. The scattering is deterministic based on the workflow file path, so each workflow consistently gets the same execution time. ### Daily Schedules [Section titled “Daily Schedules”](#daily-schedules) Run once per day at a scattered time: ```yaml on: schedule: daily schedule: daily on weekdays # Monday-Friday only ``` Each workflow gets a unique time like `43 5 * * *` (5:43 AM) or `43 5 * * 1-5` (5:43 AM, Mon-Fri). ### Daily with Time Constraints [Section titled “Daily with Time Constraints”](#daily-with-time-constraints) Use `around` for a ±1 hour window or `between` for custom ranges. Add `on weekdays` to restrict to Monday-Friday: ```yaml on: schedule: daily around 14:00 # 13:00-15:00 schedule: daily around 3pm # 2pm-4pm schedule: daily around noon # 11am-1pm schedule: daily around 9am on weekdays # Mon-Fri 8am-10am schedule: daily around 14:00 on weekdays # Mon-Fri 13:00-15:00 schedule: daily between 9:00 and 17:00 # Business hours (9am-5pm) schedule: daily between 9:00 and 17:00 on weekdays # Mon-Fri 9am-5pm schedule: daily between 22:00 and 02:00 # Crossing midnight (10pm-2am) ``` Special time keywords: `midnight` (00:00), `noon` (12:00) ### Hourly Schedules [Section titled “Hourly Schedules”](#hourly-schedules) ```yaml on: schedule: hourly # Runs every hour with scattered minute (e.g., 58 */1 * * *) schedule: hourly on weekdays # Mon-Fri only (e.g., 58 */1 * * 1-5) ``` Each workflow gets a consistent minute offset (0-59) to prevent simultaneous execution. ### Interval Schedules [Section titled “Interval Schedules”](#interval-schedules) Add `on weekdays` to restrict interval schedules to Monday-Friday: ```yaml on: schedule: every 2h # Every 2 hours at scattered minute (e.g., 53 */2 * * *) schedule: every 2h on weekdays # Mon-Fri every 2 hours (e.g., 53 */2 * * 1-5) schedule: every 6h # Every 6 hours at scattered minute (e.g., 12 */6 * * *) schedule: every 6h on weekdays # Mon-Fri every 6 hours ``` Supported intervals: `1h`, `2h`, `3h`, `4h`, `6h`, `8h`, `12h` ### Weekly Schedules [Section titled “Weekly Schedules”](#weekly-schedules) ```yaml on: schedule: weekly # Scattered day/time (e.g., 43 5 * * 1) schedule: weekly on monday # Monday at scattered time (e.g., 43 5 * * 1) schedule: weekly on friday # Friday at scattered time (e.g., 18 14 * * 5) ``` Supported weekdays: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday` ### Weekly with Time Constraints [Section titled “Weekly with Time Constraints”](#weekly-with-time-constraints) ```yaml on: schedule: weekly on monday around 09:00 # Monday 8am-10am schedule: weekly on friday around 5pm # Friday 4pm-6pm ``` ### Bi-weekly and Tri-weekly Schedules [Section titled “Bi-weekly and Tri-weekly Schedules”](#bi-weekly-and-tri-weekly-schedules) ```yaml on: schedule: bi-weekly # Every 14 days at scattered time (e.g., 43 5 */14 * *) schedule: tri-weekly # Every 21 days at scattered time (e.g., 18 14 */21 * *) ``` Each workflow gets a deterministic time that repeats every 14 or 21 days, scattered across the full period to distribute load. ## IANA Timezone Field [Section titled “IANA Timezone Field”](#iana-timezone-field) For cron-based schedule items, use the optional `timezone` field to interpret the cron expression in a specific timezone rather than UTC: ```yaml on: schedule: - cron: "30 9 * * 1-5" timezone: "America/New_York" # 9:30 AM EST/EDT Mon-Fri - cron: "0 14 * * *" timezone: "Asia/Tokyo" # 2:00 PM JST daily - cron: "0 8 * * 1" timezone: "Europe/London" # 8:00 AM GMT/BST on Mondays ``` The `timezone` field accepts any [IANA timezone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (e.g., `America/New_York`, `Europe/London`, `Asia/Tokyo`, `UTC`). The compiler converts the cron expression to UTC using the specified timezone rules, including automatic daylight saving time handling. Note The `timezone` field applies only to cron-based schedule items (`- cron: "..."`) in the list form. For fuzzy schedules written as strings (e.g., `daily around 9am`), use the inline `utc+N` / `utc-N` offset syntax instead. ## UTC Offset Support [Section titled “UTC Offset Support”](#utc-offset-support) Use `utc+N` or `utc-N` (or `utc+HH:MM`) to convert local times to UTC: ```yaml on: schedule: daily around 14:00 utc+9 # 2:00 PM JST schedule: daily around 9am utc-5 # 9:00 AM EST schedule: daily between 9am utc-5 and 5pm utc-5 # Business hours EST schedule: weekly on monday around 08:00 utc+05:30 # Monday 8:00 AM IST ``` Common offsets: PT/PST/PDT (`utc-8`/`utc-7`), EST/EDT (`utc-5`/`utc-4`), JST (`utc+9`), IST (`utc+05:30`) ## Fixed Schedules [Section titled “Fixed Schedules”](#fixed-schedules) For fixed-time schedules, use standard cron syntax: ```yaml on: schedule: - cron: "0 2 * * *" # Daily at 2:00 AM UTC - cron: "30 6 * * 1" # Monday at 6:30 AM UTC - cron: "0 9 15 * *" # 15th of month at 9:00 AM UTC ``` ## Interval Schedules [Section titled “Interval Schedules”](#interval-schedules-1) Use `every N [unit]` syntax for various intervals: ```yaml on: # Minutes (minimum 5 minutes, fixed time) schedule: every 5 minutes # */5 * * * * schedule: every 10m # */10 * * * * (short format) # Hours (fuzzy - scattered minute) schedule: every 1h # 58 */1 * * * (minute 58) schedule: every 2 hours # 53 */2 * * * (minute 53) # Days (fixed time) schedule: every 1d # 0 0 * * * (midnight UTC) schedule: every 2 days # 0 0 */2 * * # Weeks (fixed time) schedule: every 1w # 0 0 * * 0 (Sunday midnight) schedule: every 2w # 0 0 */14 * * # Months (fixed time) schedule: every 1mo # 0 0 1 * * (1st of month) schedule: every 2mo # 0 0 1 */2 * ``` Valid minute intervals: `5m`, `10m`, `15m`, `20m`, `30m` Valid hour intervals: `1h`, `2h`, `3h`, `4h`, `6h`, `8h`, `12h` ## Time Formats [Section titled “Time Formats”](#time-formats) Supports 24-hour (`HH:MM`), 12-hour (`Ham`, `Hpm`), and keywords (`midnight`, `noon`): ```yaml Examples: 00:00, 09:30, 14:00 # 24-hour format 1am, 3pm, 11pm # 12-hour format midnight, noon # Keywords With UTC offset: 14:00 utc+9 # JST to UTC 3pm utc-5 # EST to UTC 9am utc+05:30 # IST to UTC ``` ## Standard Cron Expressions [Section titled “Standard Cron Expressions”](#standard-cron-expressions) Format: `minute hour day-of-month month day-of-week` ```yaml on: schedule: - cron: "0 9 * * 1" # Monday at 9:00 AM - cron: "*/15 * * * *" # Every 15 minutes - cron: "0 0 * * *" # Daily at midnight - cron: "0 14 * * 1-5" # Weekdays at 2:00 PM ``` See [GitHub’s cron syntax documentation](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule). ## Multiple Schedules [Section titled “Multiple Schedules”](#multiple-schedules) ```yaml on: schedule: - cron: daily - cron: weekly on monday - cron: "0 0 15 * *" # Monthly on 15th ``` ## Shorthand Format [Section titled “Shorthand Format”](#shorthand-format) Use `on: daily` as shorthand, which automatically expands to include both schedule and `workflow_dispatch`: ```yaml on: daily # Expands to: on: schedule: - cron: "FUZZY:DAILY * * *" workflow_dispatch: ``` ## Validation & Warnings [Section titled “Validation & Warnings”](#validation--warnings) The compiler warns about patterns that create load spikes: ```text ! Schedule uses fixed daily time (0:0 UTC). Consider using fuzzy schedule 'daily' instead to distribute workflow execution times. ! Schedule uses hourly interval with fixed minute offset (0). Consider using fuzzy schedule 'every 2h' instead. ! Schedule uses fixed weekly time (Monday 6:30 UTC). Consider using fuzzy schedule 'weekly on monday' instead. ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Triggers](/gh-aw/reference/triggers/) - Complete trigger configuration * [Frontmatter](/gh-aw/reference/frontmatter/) - Workflow configuration reference * [GitHub Actions Schedule Events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule) - GitHub’s schedule documentation # Using Serena > Configure the Serena MCP server for semantic code analysis and intelligent code editing in your agentic workflows. [Serena](https://github.com/oraios/serena) is an MCP server that enhances AI agents with IDE-like tools for semantic code analysis and manipulation. It supports **30+ programming languages** through Language Server Protocol (LSP) integration, enabling agents to find symbols, navigate code relationships, and edit at the symbol level — ideal for navigating and editing large, well-structured codebases. ## Quick Start [Section titled “Quick Start”](#quick-start) ### Recommended: Import shared workflow [Section titled “Recommended: Import shared workflow”](#recommended-import-shared-workflow) The preferred way to add Serena is to copy the file [`shared/mcp/serena.md`](https://github.com/github/gh-aw/blob/main/.github/workflows/shared/mcp/serena.md) into your repo and import it into your workflow, which configures the complete MCP server automatically: ```aw --- on: issues engine: copilot permissions: contents: read # NOTE: first copy `shared/mcp/serena.md` into your repository before importing it imports: - uses: shared/mcp/serena.md with: languages: ["go", "typescript"] --- ``` For Go-only workflows, use the convenience wrapper (copy [`shared/mcp/serena-go.md`](https://github.com/github/gh-aw/blob/main/.github/workflows/shared/mcp/serena-go.md) into your repository before importing it): ```aw --- on: issues engine: copilot permissions: contents: read # NOTE: first copy `shared/mcp/serena-go.md` into your repository before importing it imports: - shared/mcp/serena-go.md --- ``` ### Example: Code Analysis [Section titled “Example: Code Analysis”](#example-code-analysis) ```aw --- engine: copilot permissions: contents: read imports: - uses: shared/mcp/serena.md with: languages: ["go"] tools: github: toolsets: [default] --- # Code Quality Analyzer Analyze Go code for quality improvements: 1. Find all exported functions and check for missing documentation 2. Identify code patterns and suggest improvements ``` ## Migration from `tools.serena` [Section titled “Migration from tools.serena”](#migration-from-toolsserena) Replace `tools.serena` with the equivalent import: Before (removed) ```yaml tools: serena: ["go", "typescript"] ``` After (recommended) ```aw imports: - uses: shared/mcp/serena.md with: languages: ["go", "typescript"] ``` The shared workflow configures the full Serena MCP server (container image, entrypoint, workspace mount) explicitly. ## Language Support [Section titled “Language Support”](#language-support) Serena supports **30+ programming languages** through Language Server Protocol (LSP): | Category | Languages | | -------------- | --------------------------------------- | | **Systems** | C, C++, Rust, Go, Zig | | **JVM** | Java, Kotlin, Scala, Groovy (partial) | | **Web** | JavaScript, TypeScript, Dart, Elm | | **Dynamic** | Python, Ruby, PHP, Perl, Lua | | **Functional** | Haskell, Elixir, Erlang, Clojure, OCaml | | **Scientific** | R, Julia, MATLAB, Fortran | | **Shell** | Bash, PowerShell | | **Other** | C#, Swift, Nix, Markdown, YAML, TOML | Note Some language servers require additional dependencies. Most are automatically installed by Serena, but check the [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) documentation for specific requirements. ## Available Tools [Section titled “Available Tools”](#available-tools) Serena provides semantic code tools organized into three categories: | Category | Tools | | --------------------- | ------------------------------------------------------------------------------------------ | | **Symbol Navigation** | `find_symbol`, `find_referencing_symbols`, `get_symbol_definition`, `list_symbols_in_file` | | **Code Editing** | `replace_symbol_body`, `insert_after_symbol`, `insert_before_symbol`, `delete_symbol` | | **Project Analysis** | `find_files`, `get_project_structure`, `analyze_imports` | These tools enable agents to work at the **symbol level** rather than the file level, making code operations more precise and context-aware. ## Usage Examples [Section titled “Usage Examples”](#usage-examples) ### Find Unused Functions [Section titled “Find Unused Functions”](#find-unused-functions) ```aw --- engine: copilot imports: - shared/mcp/serena-go.md tools: github: toolsets: [default] --- # Find Unused Code 1. Configure memory: `mkdir -p /tmp/gh-aw/cache-memory/serena` 2. Use `find_symbol` and `find_referencing_symbols` to identify unused exports 3. Report findings ``` ## Best Practices [Section titled “Best Practices”](#best-practices) Pre-create the cache directory (`mkdir -p /tmp/gh-aw/cache-memory/serena`) for faster operations — Serena reuses language server indexes across runs. Pin the key with `tools.cache-memory.key: serena-analysis` in frontmatter to persist it. Prefer symbol-level operations (`replace_symbol_body`) over file-level edits. Combine Serena with other tools like `github`, `edit`, and `bash` for complete workflows. For large codebases, start with targeted analysis of specific packages before expanding scope. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **Language server not found:** Install required dependencies (e.g., `go install golang.org/x/tools/gopls@latest` for Go). **Memory permission issues:** Ensure cache directory exists with proper permissions: `mkdir -p /tmp/gh-aw/cache-memory/serena && chmod 755 /tmp/gh-aw/cache-memory/serena` **Slow initial analysis:** Expected behavior as language servers build indexes. Subsequent runs use cached data. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Imports Reference](/gh-aw/reference/imports/) - Full imports and `import-schema` syntax * [Using MCPs](/gh-aw/guides/mcps/) - General MCP server configuration * [Tools Reference](/gh-aw/reference/tools/) - Complete tools configuration * [Using MCPs](/gh-aw/guides/mcps/) - MCP introduction * [Serena GitHub Repository](https://github.com/oraios/serena) — official repo and [documentation](https://oraios.github.io/serena/) * [Language Support](https://oraios.github.io/serena/01-about/020_programming-languages.html) - Supported languages and dependencies * [Serena Tools Reference](https://oraios.github.io/serena/01-about/035_tools.html) - Complete tool documentation # Staged Mode > Preview safe output operations without making any changes, so you can see exactly what a workflow would do before it acts. Staged mode lets you run a workflow and see what [safe outputs](/gh-aw/reference/safe-outputs/) it would create — issues, comments, pull requests, and more — without actually creating anything. Every write operation is skipped; instead, a detailed preview appears in the GitHub Actions step summary with a indicator. This is useful when you’re adopting a new workflow and want to verify its behavior before it has any real effect, or when you want to share what a workflow *would* do with colleagues before enabling it in production. ## Enabling Staged Mode [Section titled “Enabling Staged Mode”](#enabling-staged-mode) Add `staged: true` to the `safe-outputs:` block in your workflow frontmatter: ```aw --- on: issues safe-outputs: staged: true create-issue: title-prefix: "[ai] " labels: [automation] --- # Issue Analyzer Analyze the issue and suggest follow-up tasks. ``` With this configuration the workflow runs fully — the AI completes its analysis — but no issues are created. Instead, the Actions run summary shows a preview of what would have been created. ## Scoping Staged Mode per Output Type [Section titled “Scoping Staged Mode per Output Type”](#scoping-staged-mode-per-output-type) Use `staged: true` on a specific type to preview only that output type while letting others execute normally: ```aw --- safe-outputs: staged: false # default: execute normally create-pull-request: staged: true # PRs: preview only add-comment: # comments: execute normally --- ``` A type-level `staged` setting overrides the global one, so you can pilot one risky output type while keeping other outputs fully active. ## What the Preview Looks Like [Section titled “What the Preview Looks Like”](#what-the-preview-looks-like) When staged mode is active the step summary contains a structured preview for each output type. The emoji appears in every heading to make previews easy to spot: ```markdown ## Staged Mode: Issue Creation Preview The following 2 issue(s) would be performed if staged mode was disabled: ### Operation 1: Add caching layer to database queries **Type**: create-issue **Title**: Add caching layer to database queries **Body**: Performance profiling shows repeated queries to the users table … **Additional Fields**: - Labels: performance, database - Assignees: octocat ### Operation 2: Update connection pool settings … --- **Preview Summary**: 2 operations previewed. No GitHub resources were created. ``` The preview includes every field the AI populated — title, body, labels, assignees — so you can evaluate the full output before enabling. ## Supported Output Types [Section titled “Supported Output Types”](#supported-output-types) Staged mode is supported by all built-in safe output types: | Output type | What the preview shows | | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | [`create-issue`](/gh-aw/reference/safe-outputs/#issue-creation-create-issue) | Title, body, labels, assignees | | [`update-issue`](/gh-aw/reference/safe-outputs/#issue-updates-update-issue) | Target issue, updated fields | | [`close-issue`](/gh-aw/reference/safe-outputs/#close-issue-close-issue) | Target issue, closing comment | | [`add-comment`](/gh-aw/reference/safe-outputs/#comment-creation-add-comment) | Target issue/PR/discussion, comment body | | [`add-labels`](/gh-aw/reference/safe-outputs/#add-labels-add-labels) | Target item, labels to add | | [`remove-labels`](/gh-aw/reference/safe-outputs/#remove-labels-remove-labels) | Target item, labels to remove | | [`create-discussion`](/gh-aw/reference/safe-outputs/#discussion-creation-create-discussion) | Title, body, category | | [`update-discussion`](/gh-aw/reference/safe-outputs/#discussion-updates-update-discussion) | Target discussion, updated fields | | [`close-discussion`](/gh-aw/reference/safe-outputs/#close-discussion-close-discussion) | Target discussion, closing comment | | [`create-pull-request`](/gh-aw/reference/safe-outputs-pull-requests/#pull-request-creation-create-pull-request) | Title, body, branch, diff | | [`update-pull-request`](/gh-aw/reference/safe-outputs/#pull-request-updates-update-pull-request) | Target PR, updated fields | | [`close-pull-request`](/gh-aw/reference/safe-outputs/#close-pull-request-close-pull-request) | Target PR | | [`create-pull-request-review-comment`](/gh-aw/reference/safe-outputs/#pr-review-comments-create-pull-request-review-comment) | File, line, comment body | | [`push-to-pull-request-branch`](/gh-aw/reference/safe-outputs-pull-requests/#push-to-pr-branch-push-to-pull-request-branch) | Branch, patch summary | | [`create-project`](/gh-aw/reference/safe-outputs/#project-creation-create-project) | Project title, description | | [`update-project`](/gh-aw/reference/safe-outputs/#project-board-updates-update-project) | Target project, project items and fields to update | | [`create-project-status-update`](/gh-aw/reference/safe-outputs/#project-status-updates-create-project-status-update) | Status, body | | [`update-release`](/gh-aw/reference/safe-outputs/#release-updates-update-release) | Target release, updated body | | [`upload-asset`](/gh-aw/reference/safe-outputs/#asset-uploads-upload-asset) | File names and sizes | | [`dispatch-workflow`](/gh-aw/reference/safe-outputs/#workflow-dispatch-dispatch-workflow) | Target workflow, inputs | | [`assign-to-agent`](/gh-aw/reference/safe-outputs/#assign-to-agent-assign-to-agent) | Target issue/PR | | [`assign-to-user`](/gh-aw/reference/safe-outputs/#assign-to-user-assign-to-user) | Target item, user | | [`create-agent-session`](/gh-aw/reference/safe-outputs/#agent-session-creation-create-agent-session) | Session details | [Custom safe output jobs](/gh-aw/reference/custom-safe-outputs/) receive the `GH_AW_SAFE_OUTPUTS_STAGED` environment variable set to `"true"` when staged mode is active, allowing you to implement your own preview behavior. ## Staged Mode for Custom Safe Output Jobs [Section titled “Staged Mode for Custom Safe Output Jobs”](#staged-mode-for-custom-safe-output-jobs) Custom jobs check `GH_AW_SAFE_OUTPUTS_STAGED` to skip the real operation and display a preview instead: ```javascript if (process.env.GH_AW_SAFE_OUTPUTS_STAGED === 'true') { core.info(' Staged mode: would send Slack notification'); await core.summary .addHeading(' Staged Mode: Slack Notification Preview', 2) .addRaw(`**Would send**: ${process.env.MESSAGE}`) .write(); return; } // Production path — actually send the notification await sendSlackMessage(process.env.MESSAGE); ``` See [Custom Safe Outputs — Staged Mode Support](/gh-aw/reference/custom-safe-outputs/#staged-mode-support) for a complete example. ## Customizing Preview Messages [Section titled “Customizing Preview Messages”](#customizing-preview-messages) Override the default preview heading and description using the `messages:` block: ```aw --- safe-outputs: staged: true messages: staged-title: " Preview: {operation}" staged-description: "The following {operation} would occur if staged mode was disabled:" create-issue: --- ``` The `{operation}` placeholder is replaced with the safe output operation name (for example, `issue creation`). ## Recommended Workflow [Section titled “Recommended Workflow”](#recommended-workflow) A common adoption pattern is to start with staged mode and disable it once you’re satisfied with the output: 1. Enable `staged: true` and trigger the workflow on a real event. 2. Open the Actions run and review the preview in the step summary. 3. Adjust the workflow prompt or configuration based on the preview. 4. Repeat until the output looks correct. 5. Remove `staged: true` (or set it to `false`) to start creating real GitHub resources. Tip Keep staged mode enabled when iterating on prompt changes, and only remove it when the workflow is stable. You can always re-enable it for a single type if you add a new safe output. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Safe Outputs](/gh-aw/reference/safe-outputs/) — All built-in safe output types and their configuration * [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/) — Adding custom jobs with staged mode support * [Frontmatter (Full)](/gh-aw/reference/frontmatter-full/) — Complete configuration reference * [Threat Detection](/gh-aw/reference/threat-detection/) — Security scanning for safe output content # Custom Steps and Jobs > Add deterministic pre-processing steps and custom GitHub Actions jobs to agentic workflows using steps:, pre-agent-steps:, post-steps:, and jobs: Custom steps and jobs let you mix deterministic computation with agentic execution. All custom steps and jobs run **outside the firewall sandbox** with standard GitHub Actions security. See [DeterministicOps](/gh-aw/patterns/deterministic-ops/) for patterns combining computation with AI reasoning. ## Custom Steps (`steps:`) [Section titled “Custom Steps (steps:)”](#custom-steps-steps) Add custom steps before agentic execution. If unspecified, a default checkout step is added automatically. ```yaml steps: - name: Install dependencies run: npm ci ``` Use custom steps to precompute data, filter triggers, or prepare context for AI agents. ## Custom Pre-Agent Steps (`pre-agent-steps:`) [Section titled “Custom Pre-Agent Steps (pre-agent-steps:)”](#custom-pre-agent-steps-pre-agent-steps) Add custom steps before MCP gateway startup in the agent job so prerequisite MCP installation/configuration can happen first. ```yaml pre-agent-steps: - name: Finalize Context run: ./scripts/prepare-agent-context.sh ``` Use pre-agent steps when work must happen right before the engine runs (for example, final context preparation or last-moment validations). ## Custom Post-Execution Steps (`post-steps:`) [Section titled “Custom Post-Execution Steps (post-steps:)”](#custom-post-execution-steps-post-steps) Add custom steps after agentic execution. Run after the AI engine completes regardless of success/failure (unless conditional expressions are used). ```yaml post-steps: - name: Upload Results if: always() uses: actions/upload-artifact@v4 with: name: workflow-results path: /tmp/gh-aw/ retention-days: 7 ``` Useful for artifact uploads, summaries, cleanup, or triggering downstream workflows. ## Custom Jobs (`jobs:`) [Section titled “Custom Jobs (jobs:)”](#custom-jobs-jobs) Define custom jobs that run before agentic execution. The agentic execution job waits for all custom jobs to complete. Custom jobs can share data with the agent through artifacts or job outputs. ```yaml jobs: super_linter: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - name: Run Super-Linter uses: super-linter/super-linter@v7 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` ### Supported Job-Level Fields [Section titled “Supported Job-Level Fields”](#supported-job-level-fields) | Field | Description | | ------------------- | --------------------------------------------------------------------------------- | | `name` | Display name for the job | | `needs` | Jobs that must complete before this job runs | | `runs-on` | Runner label — string, array, or object form | | `if` | Conditional expression to control job execution | | `permissions` | GitHub token permissions for this job | | `outputs` | Values exposed to downstream jobs | | `env` | Environment variables available to all steps | | `timeout-minutes` | Maximum job duration (GitHub Actions default: 360) | | `concurrency` | Concurrency group to prevent parallel runs | | `continue-on-error` | Allow the workflow to continue if this job fails | | `container` | Docker container to run steps in | | `services` | Service containers (e.g. databases) | | `pre-steps` | Steps injected after compiler setup steps and before checkout/`steps` in that job | | `steps` | List of steps — supports complete GitHub Actions step specification | | `uses` | Reusable workflow to call | | `with` | Input parameters for a reusable workflow | | `secrets` | Secrets passed to a reusable workflow | The `strategy` field (matrix builds) is not supported. `runs-on` accepts a string, an array of runner labels, or the object form: ```yaml jobs: build: runs-on: group: my-runner-group labels: [self-hosted, linux] steps: - uses: actions/checkout@v6 ``` When `jobs..pre-steps` is set, step execution order is deterministic: 1. Compiler-injected setup steps 2. `jobs..pre-steps` 3. Checkout steps 4. Remaining `jobs..steps` Example using `timeout-minutes` and `env`: ```yaml jobs: build: runs-on: ubuntu-latest timeout-minutes: 15 env: NODE_ENV: production steps: - uses: actions/checkout@v6 - run: npm ci && npm run build ``` ### Job Outputs [Section titled “Job Outputs”](#job-outputs) Custom jobs can expose outputs accessible in the agentic execution prompt via `${{ needs.job-name.outputs.output-name }}`: ```yaml jobs: release: outputs: release_id: ${{ steps.get_release.outputs.release_id }} version: ${{ steps.get_release.outputs.version }} steps: - id: get_release run: echo "version=${{ github.event.release.tag_name }}" >> $GITHUB_OUTPUT --- Generate highlights for release ${{ needs.release.outputs.version }}. ``` Job outputs must be string values. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [DeterministicOps](/gh-aw/patterns/deterministic-ops/) — Patterns combining deterministic steps with AI reasoning * [Frontmatter Reference](/gh-aw/reference/frontmatter/) — Complete frontmatter field reference * [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/) — Custom post-processing jobs for agentic outputs * [Imports](/gh-aw/reference/imports/) — Composing `pre-agent-steps` and `post-steps` across shared workflows # Templating > Expressions and conditional templating in agentic workflows Agentic workflows support four simple templating/substitution mechanisms: * GitHub Actions expressions in frontmatter or markdown * Conditional Templating blocks in markdown * [Imports](/gh-aw/reference/imports/) in frontmatter or markdown (compile-time) * Runtime imports in markdown (runtime file/URL inclusion) ## GitHub Actions Expressions [Section titled “GitHub Actions Expressions”](#github-actions-expressions) Agentic workflows restrict expressions in **markdown content** to prevent security vulnerabilities from exposing secrets or environment variables to the LLM. > **Note**: These restrictions apply only to markdown content. YAML frontmatter can use secrets and environment variables for workflow configuration. **Permitted expressions** in markdown include: * Event properties: `github.event.*` (issue/PR numbers, titles, states, SHAs, IDs, etc.) * Repository context: `github.actor`, `github.owner`, `github.repository`, `github.server_url`, `github.workspace` * Run metadata: `github.run_id`, `github.run_number`, `github.job`, `github.workflow` * Pattern expressions: `needs.*`, `steps.*`, `github.event.inputs.*` ### Activation Outputs [Section titled “Activation Outputs”](#activation-outputs) Use `steps.sanitized.outputs.text/title/body` in your markdown prompts to access sanitized event content: * `steps.sanitized.outputs.text` — sanitized full context (title + body for issues/PRs, body for comments) * `steps.sanitized.outputs.title` — sanitized title of the triggering issue or PR * `steps.sanitized.outputs.body` — sanitized body of the triggering issue or PR Deprecated: `needs.activation.outputs.*` Using `${{ needs.activation.outputs.text }}`, `${{ needs.activation.outputs.title }}`, or `${{ needs.activation.outputs.body }}` in workflow markdown is **deprecated**. These expressions still work but produce a deprecation warning during compilation. Use `${{ steps.sanitized.outputs.text }}` etc. directly instead. **Why:** The prompt is generated *inside* the activation job, which cannot reference its own `needs.activation.*` outputs in GitHub Actions. The compiler automatically rewrites the deprecated form to `steps.sanitized.outputs.*`, but writing the correct form directly is preferred. Other activation outputs like `comment_id`, `comment_repo`, and `slash_command` are available as `needs.activation.outputs.*` in *downstream* jobs (not in the markdown prompt itself). ### Prohibited Expressions [Section titled “Prohibited Expressions”](#prohibited-expressions) All other expressions are disallowed, including `secrets.*`, `env.*`, `vars.*`, and complex functions like `toJson()` or `fromJson()`. Expression safety is validated during compilation. Unauthorized expressions produce errors like: ```text error: unauthorized expressions: [secrets.TOKEN, env.MY_VAR]. allowed: [github.repository, github.actor, github.workflow, ...] ``` ## Conditional Markdown [Section titled “Conditional Markdown”](#conditional-markdown) Include or exclude prompt sections based on boolean expressions using `{{#if ...}} ... {{/if}}` blocks. ### Syntax [Section titled “Syntax”](#syntax) ```markdown {{#if expression}} Content to include if expression is truthy {{/if}} ``` The compiler automatically wraps expressions with `${{ }}` for GitHub Actions evaluation. For example, `{{#if github.event.issue.number}}` becomes `{{#if ${{ github.event.issue.number }} }}`. **Falsy values:** `false`, `0`, `null`, `undefined`, `""` (empty string) **Truthy values:** Everything else ### Example [Section titled “Example”](#example) ```aw --- on: issues: types: [opened] --- # Issue Analysis Analyze issue #${{ github.event.issue.number }}. {{#if github.event.issue.number}} ## Issue-Specific Analysis You are analyzing issue #${{ github.event.issue.number }}. {{/if}} {{#if github.event.pull_request.number}} ## Pull Request Analysis You are analyzing PR #${{ github.event.pull_request.number }}. {{/if}} ``` ### Limitations [Section titled “Limitations”](#limitations) The template system supports only basic conditionals - no nesting, `else` clauses, variables, loops, or complex evaluation. ## Runtime Imports [Section titled “Runtime Imports”](#runtime-imports) Runtime imports include content from files and URLs in workflow prompts **at runtime** (unlike [compile-time imports](/gh-aw/reference/imports/)). File paths are restricted to the `.github` folder. Use `{{#runtime-import filepath}}` or `{{#runtime-import? filepath}}` for optional imports. ### Macro Syntax [Section titled “Macro Syntax”](#macro-syntax) Use `{{#runtime-import filepath}}` to include file content at runtime. Optional imports use `{{#runtime-import? filepath}}` which don’t fail if the file is missing. **Important:** All file paths are resolved within the `.github` folder. You can specify paths with or without the `.github/` prefix: ```aw --- on: issues engine: copilot --- # Code Review Agent Follow these coding guidelines: {{#runtime-import coding-standards.md}} Review the code changes and provide feedback. ``` **Line range extraction:** ```aw # Bug Fix Validator The original buggy code was (from .github/docs/auth.go): {{#runtime-import docs/auth.go:45-52}} Verify the fix addresses the issue. ``` **Optional imports:** ```aw # Issue Analyzer {{#runtime-import? shared-instructions.md}} Analyze issue #${{ github.event.issue.number }}. ``` ### URL Imports [Section titled “URL Imports”](#url-imports) The macro syntax supports HTTP/HTTPS URLs. URLs are **not restricted to `.github` folder** and content is cached for 1 hour. ```aw {{#runtime-import https://raw.githubusercontent.com/org/repo/main/checklist.md}} {{#runtime-import https://example.com/standards.md:10-50}} ``` ### Security Features [Section titled “Security Features”](#security-features) All runtime imports include automatic security protections. **Content Sanitization:** YAML front matter and HTML/XML comments are automatically stripped. GitHub Actions expressions (`${{ ... }}`) are **rejected with error** to prevent template injection and unintended variable expansion. **Path Validation:** File paths are restricted to the `.github` folder to prevent access to arbitrary repository files. Path traversal and absolute paths are rejected: ```aw {{#runtime-import ../src/config.go}} # Error: Relative traversal outside .github {{#runtime-import /etc/passwd}} # Error: Absolute path not allowed ``` ### Caching [Section titled “Caching”](#caching) Fetched URLs are cached for 1 hour per workflow run at `/tmp/gh-aw/url-cache/` (keyed by SHA256 hash). The first fetch adds \~500ms–2s latency; subsequent accesses use cached content. ### Processing Order [Section titled “Processing Order”](#processing-order) Runtime imports are processed before other substitutions: 1. `{{#runtime-import}}` macros processed (files and URLs) 2. `${GH_AW_EXPR_*}` variable interpolation 3. `{{#if}}` template conditionals rendered ### Limitations [Section titled “Limitations”](#limitations-1) * **`.github` folder only:** File paths are restricted to `.github` folder for security * **No authentication:** URL fetching doesn’t support private URLs with tokens * **Per-run cache:** URL cache doesn’t persist across workflow runs * **Line numbers:** Refer to raw file content before front matter removal ### Deprecated `{{#import}}` [Section titled “Deprecated {{#import}}”](#deprecated-import) `{{#import filepath}}` (without `runtime-`) is a **deprecated** body-level shorthand. It normalizes to `{{#runtime-import filepath}}` at runtime for backward compatibility, but emits deprecation warnings at both compile time and runtime. Use `{{#runtime-import}}` directly for all new workflows. See [Imports](/gh-aw/reference/imports/) for details. ### Error Handling [Section titled “Error Handling”](#error-handling) | Error | Message | | --------------------- | ------------------------------------------------------------------------------------------------------- | | File not found | `Runtime import file not found: missing.txt` | | Invalid line range | `Invalid start line 100 for file docs/main.go (total lines: 50)` | | Path traversal | `Security: Path ../src/main.go must be within .github folder` | | GitHub Actions macros | `File template.md contains GitHub Actions macros (${{ ... }}) which are not allowed in runtime imports` | | URL fetch failure | `Failed to fetch URL https://example.com/file.txt: HTTP 404` | ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Markdown](/gh-aw/reference/markdown/) - Writing effective agentic markdown * [Workflow Structure](/gh-aw/reference/workflow-structure/) - Overall workflow organization * [Frontmatter](/gh-aw/reference/frontmatter/) - YAML configuration * [Imports](/gh-aw/reference/imports/) - Compile-time imports in frontmatter # Threat Detection > Configure automated threat detection to analyze agent output and code changes for security issues before they are applied. GitHub Agentic Workflows includes automatic threat detection to analyze agent output and code changes for potential security issues before they are applied. When safe outputs are configured, a threat detection job automatically runs to identify prompt injection attempts, secret leaks, and malicious code patches. ## How It Works [Section titled “How It Works”](#how-it-works) Threat detection provides an additional security layer by analyzing agent output for malicious content, scanning code changes for suspicious patterns, using workflow context to distinguish legitimate actions from threats, and running automatically after the main job completes but before safe outputs are applied. **Security Architecture:** ```text ┌─────────────────┐ │ Agentic Job │ (Read-only permissions) │ Generates │ │ Output & Patches│ └────────┬────────┘ │ artifacts ▼ ┌─────────────────┐ │ Threat Detection│ (Analyzes for security issues) │ Job │ └────────┬────────┘ │ approved/blocked ▼ ┌─────────────────┐ │ Safe Output Jobs│ (Write permissions, only if safe) │ Create Issues, │ │ PRs, Comments │ └─────────────────┘ ``` ## Default Configuration [Section titled “Default Configuration”](#default-configuration) Threat detection is **automatically enabled** when safe outputs are configured: ```yaml safe-outputs: create-issue: # Threat detection enabled automatically create-pull-request: ``` The default configuration uses AI-powered analysis to detect prompt injection (malicious instructions manipulating AI behavior), secret leaks (exposed API keys, tokens, passwords, credentials), and malicious patches (code changes introducing vulnerabilities, backdoors, or suspicious patterns). ## Configuration Options [Section titled “Configuration Options”](#configuration-options) ### Basic Enabled/Disabled [Section titled “Basic Enabled/Disabled”](#basic-enableddisabled) Control threat detection with a boolean flag: ```yaml safe-outputs: create-issue: threat-detection: true # Explicitly enable (default when safe-outputs exist) # Or disable entirely: safe-outputs: create-pull-request: threat-detection: false # Disable threat detection ``` Note When a workflow explicitly sets `threat-detection: false`, that setting takes precedence over any imported fragments. Imported shared workflows that configure safe outputs without a `threat-detection` key will not re-enable threat detection in the importing workflow. ### Advanced Configuration [Section titled “Advanced Configuration”](#advanced-configuration) Use object syntax for fine-grained control: ```yaml safe-outputs: create-issue: threat-detection: enabled: true # Enable/disable detection prompt: "Focus on SQL injection" # Additional analysis instructions steps: # Custom steps run before engine execution - name: Setup Security Gateway run: echo "Connecting to security gateway..." post-steps: # Custom steps run after engine execution - name: Custom Security Check run: echo "Running additional checks" ``` **Configuration Fields:** | Field | Type | Description | | ------------ | ------------------- | ------------------------------------------------------------------------- | | `enabled` | boolean | Enable or disable detection (default: `true` when safe-outputs exist) | | `prompt` | string | Custom instructions appended to default detection prompt | | `engine` | string/object/false | AI engine config (`"copilot"`, full config object, or `false` for no AI) | | `runs-on` | string/array/object | Runner for the detection job (default: inherits from workflow `runs-on`) | | `steps` | array | Additional GitHub Actions steps to run **before** AI analysis (pre-steps) | | `post-steps` | array | Additional GitHub Actions steps to run **after** AI analysis (post-steps) | ## AI-Based Detection (Default) [Section titled “AI-Based Detection (Default)”](#ai-based-detection-default) By default, threat detection uses the same AI engine as your main workflow to analyze output for security threats. **Example with Default AI Detection:** ```yaml --- on: push safe-outputs: create-pull-request: threat-detection: true # Uses Claude for analysis --- # Code Review Agent Analyze code and create pull requests with improvements. ``` The AI engine receives the workflow source context and analyzes agent output items (issues, comments, PRs), git patch files with code changes, and workflow intent to distinguish legitimate actions. **Output Format:** AI detection produces a structured JSON response: ```json { "prompt_injection": false, "secret_leak": false, "malicious_patch": false, "reasons": [] } ``` If any threat is detected (`true`), the workflow fails and safe outputs are blocked. ## Custom Prompt Instructions [Section titled “Custom Prompt Instructions”](#custom-prompt-instructions) Enhance AI analysis with domain-specific guidance: ```yaml safe-outputs: create-pull-request: threat-detection: prompt: | Focus on these additional security concerns: - SQL injection vulnerabilities in database queries - Cross-site scripting (XSS) in user input handling - Unsafe deserialization patterns - Hardcoded credentials in configuration files ``` The custom prompt is appended to the default threat detection instructions, providing specialized context for your workflow’s domain. ## Custom Engine Configuration [Section titled “Custom Engine Configuration”](#custom-engine-configuration) Override the main workflow engine for threat detection: **String Format:** ```yaml safe-outputs: create-pull-request: threat-detection: engine: copilot # Use Copilot instead of main workflow engine ``` **Object Format:** ```yaml safe-outputs: create-pull-request: threat-detection: engine: id: copilot max-turns: 3 ``` **Disable AI Engine:** ```yaml safe-outputs: create-pull-request: threat-detection: engine: false # No AI analysis, only custom steps steps: - name: Custom Scanning run: | # Run your own security tools ./security-scan.sh ``` ## Custom Detection Steps [Section titled “Custom Detection Steps”](#custom-detection-steps) Add specialized security scanning tools alongside or instead of AI detection. You can run steps **before** the AI engine (for setup, gateway connections, etc.) and steps **after** (for additional scanning based on AI results). ### Pre-Steps (`steps:`) [Section titled “Pre-Steps (steps:)”](#pre-steps-steps) Steps defined under `steps:` run **before** the AI engine executes. Use these for setup tasks such as connecting to a private AI gateway, installing security tools, or preparing artifacts. ```yaml safe-outputs: create-pull-request: threat-detection: steps: - name: Connect to Security Gateway run: | echo "Setting up secure connection to analysis gateway..." # Authentication and connection setup ``` ### Post-Steps (`post-steps:`) [Section titled “Post-Steps (post-steps:)”](#post-steps-post-steps) Steps defined under `post-steps:` run **after** the AI engine completes its analysis. Use these for additional security scanning, reporting, or cleanup. ```yaml safe-outputs: create-pull-request: threat-detection: post-steps: - name: Run Security Scanner run: | echo "Scanning agent output for threats..." # Your custom security logic here - name: Check for Secrets uses: trufflesecurity/trufflehog@main with: path: /tmp/gh-aw/threat-detection/ ``` **Available Artifacts:** Custom steps have access to `/tmp/gh-aw/threat-detection/prompt.txt` (workflow prompt), `agent_output.json` (safe output items), and `aw.patch` (git patch file). **Execution Order:** Download artifacts → Execute pre-steps (`steps:`) → Run AI analysis (if enabled) → Execute post-steps (`post-steps:`) → Upload detection log. ## Example: LlamaGuard Integration [Section titled “Example: LlamaGuard Integration”](#example-llamaguard-integration) Use Ollama with LlamaGuard 3 for specialized threat detection running after AI analysis: ```yaml --- on: push engine: copilot safe-outputs: create-pull-request: threat-detection: post-steps: - name: Ollama LlamaGuard 3 Scan uses: actions/github-script@v8 with: script: | // Install and start Ollama service await exec.exec('curl', ['-fsSL', 'https://ollama.com/install.sh', '-o', '/tmp/install.sh']); await exec.exec('sh', ['/tmp/install.sh']); exec.exec('ollama', ['serve'], { detached: true }); // Pull model and scan output await exec.exec('ollama', ['pull', 'llama-guard3:1b']); const content = require('fs').readFileSync('/tmp/gh-aw/threat-detection/agent_output.json', 'utf8'); const response = await exec.getExecOutput('curl', [ '-X', 'POST', 'http://localhost:11434/api/chat', '-H', 'Content-Type: application/json', '-d', JSON.stringify({ model: 'llama-guard3:1b', messages: [{ role: 'user', content }] }) ]); const result = JSON.parse(response.stdout); const isSafe = result.message?.content.toLowerCase().includes('safe'); if (!isSafe) core.setFailed('LlamaGuard detected threat'); timeout-minutes: 20 --- # Code Review Agent ``` Tip For a complete implementation with error handling and service readiness checks, see `.github/workflows/shared/ollama-threat-scan.md` in the repository. ## Combined AI and Custom Detection [Section titled “Combined AI and Custom Detection”](#combined-ai-and-custom-detection) Use both AI analysis and custom tools for defense-in-depth: ```yaml safe-outputs: create-pull-request: threat-detection: prompt: "Check for authentication bypass vulnerabilities" engine: copilot post-steps: - name: Static Analysis run: | # Run static analysis tool semgrep --config auto /tmp/gh-aw/threat-detection/ - name: Secret Scanner uses: trufflesecurity/trufflehog@main with: path: /tmp/gh-aw/threat-detection/aw.patch ``` ## Example: Private AI Gateway [Section titled “Example: Private AI Gateway”](#example-private-ai-gateway) Connect to a private AI gateway before running the detection engine: ```yaml safe-outputs: create-pull-request: threat-detection: steps: - name: Connect to AI Gateway run: | # Authenticate and set up connection to private AI gateway echo "Setting up gateway connection..." ./scripts/setup-gateway.sh engine: id: copilot ``` ## Error Handling [Section titled “Error Handling”](#error-handling) **When Threats Are Detected:** The threat detection job fails with a clear error message and safe output jobs are skipped: ```text ✗ Threat detected: Potential SQL injection in code changes Reasons: - Unsanitized user input in database query - Missing parameterized query pattern ``` **When Detection Fails:** If the detection process itself fails (e.g., network issues, tool errors), the workflow stops and safe outputs are not applied. This fail-safe approach prevents potentially malicious content from being processed. ## Supply Chain Protection (Protected Files) [Section titled “Supply Chain Protection (Protected Files)”](#supply-chain-protection-protected-files) Beyond AI-powered threat detection, GitHub Agentic Workflows includes a static, rule-based protection layer that guards against **supply chain attacks** — cases where an AI agent could (intentionally or accidentally) modify files that control how software is built, tested, or deployed. ### The Threat [Section titled “The Threat”](#the-threat) An AI agent operating in a repository can be tricked (through prompt injection or misconfigured tasks) into modifying: * **Dependency manifests** (`package.json`, `go.mod`, `requirements.txt`, `Gemfile`, `pom.xml`, etc.) — changing what third-party code is installed. * **CI/CD configuration** (`.github/workflows/*.yml`, `.github/dependabot.yml`, etc.) — altering how and when pipelines run, potentially exfiltrating secrets or bypassing security checks. * **Agent instruction files** (`AGENTS.md`, `CLAUDE.md`, `.claude/settings.json`, `.agents/`, etc.) — redirecting the AI agent’s behavior on subsequent runs. ### Default Remediation [Section titled “Default Remediation”](#default-remediation) Protected file protection is **enabled by default** for `create-pull-request` and `push-to-pull-request-branch`. Any patch that touches a protected file or directory causes the safe output to fail with a clear error: ```plaintext Cannot create pull request: patch modifies protected files (package.json). Set protected-files: fallback-to-issue to create a review issue instead. ``` This error is also surfaced as a **Protected Files** section in the agent failure issue or comment created by the conclusion job. ### Policy Options [Section titled “Policy Options”](#policy-options) Configure how each safe output handles protected file changes using the `protected-files` field: | Value | Behavior | | ------------------- | --------------------------------------------------------------------------------------------------- | | `blocked` (default) | Hard-block: the safe output fails with an error message | | `allowed` | No restriction — all protected file changes are permitted | | `fallback-to-issue` | Create a review issue instead of a PR / push, so a human can inspect and apply the changes manually | ```yaml safe-outputs: create-pull-request: protected-files: fallback-to-issue # human review required for protected file changes push-to-pull-request-branch: protected-files: fallback-to-issue # create issue instead of pushing protected file changes ``` ### Protected Files [Section titled “Protected Files”](#protected-files) The protection list is composed of four sources: 1. **Runtime dependency manifests** — one entry per supported package manager (npm, Go, Python, Ruby, Java, Rust, Elixir, Haskell, .NET, Bun, Deno, uv). 2. **Engine instruction files** — added automatically based on the active AI engine: * **Copilot**: `AGENTS.md` * **Claude**: `CLAUDE.md`; directory prefix `.claude/` * **Codex**: `AGENTS.md`; directory prefix `.codex/` 3. **Repository security configuration** — the `.github/` and `.agents/` path prefixes (`.github/` covers GitHub Actions workflows, Dependabot config; `.agents/` covers generic agent instruction and configuration files). 4. **Repository access control files** — matched by filename anywhere in the repository: `CODEOWNERS` (governs required code reviewers; valid at the repository root, `.github/`, or `docs/`). Tip If your workflow is explicitly designed to update dependencies or CI configuration, set `protected-files: allowed` for that safe output. In repositories where human oversight is preferred, `protected-files: fallback-to-issue` provides a middle ground: the agent performs all other operations normally, and a review issue is created for runs that involve protected files. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) | Issue | Solution | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **AI detection always fails** | Review custom prompt for overly strict instructions, check if legitimate patterns trigger detection, adjust prompt context, or temporarily disable to test | | **Custom steps not running** | Verify YAML indentation, ensure steps array is properly formatted, review compilation output, check if AI detection failed first | | **Large patches cause timeouts** | Increase `timeout-minutes`, configure `max-patch-size`, truncate content before analysis, or split changes into smaller PRs | | **False positives** | Refine prompt with specific exclusions, adjust tool thresholds, add workflow context explaining patterns, review detection logs | ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Complete safe outputs configuration * [Security Guide](/gh-aw/introduction/architecture/) - Overall security best practices * [Custom Safe Outputs](/gh-aw/reference/custom-safe-outputs/) - Creating custom output types * [Frontmatter Reference](/gh-aw/reference/frontmatter/) - All configuration options # Tools > Configure GitHub API tools, browser automation, and AI capabilities available to your agentic workflows, including GitHub tools and custom MCP servers. [Tools](/gh-aw/reference/glossary/#tools) are defined in the frontmatter to specify which GitHub API calls, browser automation, and AI capabilities are available to your workflow: ```yaml tools: edit: bash: true ``` Some tools are available by default. All tools declared in imported components are merged into the final workflow. ## Built-in Tools [Section titled “Built-in Tools”](#built-in-tools) ### Edit Tool (`edit:`) [Section titled “Edit Tool (edit:)”](#edit-tool-edit) Allows file editing in the GitHub Actions workspace. ```yaml tools: edit: ``` ### GitHub Tools (`github:`) [Section titled “GitHub Tools (github:)”](#github-tools-github) Configure GitHub API operations including toolsets, remote/local modes, and authentication. ```yaml tools: github: toolsets: [repos, issues] ``` See **[GitHub Tools Reference](/gh-aw/reference/github-tools/)** for complete configuration options. ### Bash Tool (`bash:`) [Section titled “Bash Tool (bash:)”](#bash-tool-bash) Enables shell command execution in the workspace. Defaults to safe commands (`echo`, `printf`, `ls`, `pwd`, `cat`, `head`, `tail`, `grep`, `wc`, `sort`, `uniq`, `date`, `yq`). ```yaml tools: bash: # Default safe commands bash: [] # Disable all commands bash: ["echo", "ls", "git status"] # Specific commands only bash: [":*"] # All commands (use with caution) ``` Use wildcards like `git:*` for command families or `:*` for unrestricted access. ### Web Tools [Section titled “Web Tools”](#web-tools) Enable web content fetching and search capabilities: ```yaml tools: web-fetch: # Fetch web content web-search: # Search the web (engine-dependent) ``` **Note:** Some engines require third-party Model Context Protocol (MCP) servers for web search. See [Using Web Search](/gh-aw/reference/web-search/). For the **Codex** engine, `web-search:` is disabled by default. Web search is only enabled when `web-search:` is explicitly declared in the `tools:` block. Without this declaration, Codex runs with `-c web_search="disabled"` and cannot access the web. ### Playwright Tool (`playwright:`) [Section titled “Playwright Tool (playwright:)”](#playwright-tool-playwright) Configure Playwright for browser automation and testing: ```yaml tools: playwright: version: "1.56.1" # Optional: specify version ``` See **[Playwright Reference](/gh-aw/reference/playwright/)** for complete configuration options, network access, browser support, and example workflows. ### Cache Memory (`cache-memory:`) [Section titled “Cache Memory (cache-memory:)”](#cache-memory-cache-memory) Persistent memory storage across workflow runs for trends and historical data. ```yaml tools: cache-memory: ``` See **[Cache Memory Reference](/gh-aw/reference/cache-memory/)** for complete configuration options and usage examples. ### Repo Memory (`repo-memory:`) [Section titled “Repo Memory (repo-memory:)”](#repo-memory-repo-memory) Repository-specific memory storage for maintaining context across executions. ```yaml tools: repo-memory: ``` See **[Repo Memory Reference](/gh-aw/reference/repo-memory/)** for complete configuration options and usage examples. ### QMD Documentation Search (`qmd:`) — Experimental [Section titled “QMD Documentation Search (qmd:) — Experimental”](#qmd-documentation-search-qmd--experimental) Build a local vector search index over documentation files and expose it as an MCP search tool. The index is built in a dedicated indexing job (no `contents: read` needed in the agent job): ```yaml tools: qmd: checkouts: - pattern: "docs/**/*.md" ``` See **[QMD Reference](/gh-aw/reference/qmd/)** for complete configuration options, checkout support, GitHub search integration, and cache key usage. ### Introspection on Agentic Workflows (`agentic-workflows:`) [Section titled “Introspection on Agentic Workflows (agentic-workflows:)”](#introspection-on-agentic-workflows-agentic-workflows) Provides workflow introspection, log analysis, and debugging tools. Requires `actions: read` permission: ```yaml permissions: actions: read tools: agentic-workflows: ``` See [GH-AW as an MCP Server](/gh-aw/reference/gh-aw-as-mcp-server/) for available operations. ### MCP CLI Mounting (`cli-proxy:`) [Section titled “MCP CLI Mounting (cli-proxy:)”](#mcp-cli-mounting-cli-proxy) Set `tools.cli-proxy: true` to mount each user-facing MCP server as a standalone CLI tool on `PATH`. When enabled, the agent can invoke MCP servers as shell commands rather than through the MCP protocol: ```yaml tools: cli-proxy: true ``` With CLI mounting enabled, MCP servers accessible to the workflow (such as `safeoutputs` and `mcpscripts`) are wrapped as executable commands. For example: ```bash safeoutputs add_comment --issue_number 42 --body "Analysis complete" mcpscripts mcpscripts-gh --args "issue list --limit 5" ``` The MCP gateway configuration is unchanged — servers still start as normal. Only the agent’s view changes: servers registered for CLI mounting are removed from the MCP tool list and accessed via shell instead. This reduces token consumption from large MCP tool schemas and can simplify workflow prompts when shell-style invocation is preferred. Defaults to `false`. ## Tool Timeout Configuration [Section titled “Tool Timeout Configuration”](#tool-timeout-configuration) ### Tool Operation Timeout (`tools.timeout`) [Section titled “Tool Operation Timeout (tools.timeout)”](#tool-operation-timeout-toolstimeout) Sets the per-operation timeout in seconds for tool and MCP server calls. Applies to all tools and MCP servers when supported by the engine. Defaults vary by engine (Claude: 60 s, Codex: 120 s). ```yaml tools: timeout: 120 # seconds ``` ### MCP Server Startup Timeout (`tools.startup-timeout`) [Section titled “MCP Server Startup Timeout (tools.startup-timeout)”](#mcp-server-startup-timeout-toolsstartup-timeout) Sets the timeout in seconds for MCP server initialization. Default is 120 seconds. ```yaml tools: startup-timeout: 60 # seconds ``` Both fields accept either an integer or a GitHub Actions expression string, enabling `workflow_call` reusable workflows to parameterize these values: ```yaml tools: timeout: ${{ inputs.tool-timeout }} startup-timeout: ${{ inputs.startup-timeout }} ``` Note Expression values are passed through environment variables in the compiled workflow. TOML-based engine configs (Codex MCP gateway) fall back to engine defaults when an expression is used, since TOML has no expression syntax. ## Custom MCP Servers (`mcp-servers:`) [Section titled “Custom MCP Servers (mcp-servers:)”](#custom-mcp-servers-mcp-servers) Integrate custom Model Context Protocol servers for third-party services: ```yaml mcp-servers: slack: command: "npx" args: ["-y", "@slack/mcp-server"] env: SLACK_BOT_TOKEN: "${{ secrets.SLACK_BOT_TOKEN }}" allowed: ["send_message", "get_channel_history"] ``` **Options**: `command` + `args` (process-based), `container` (Docker image), `url` + `headers` (HTTP endpoint), `registry` (MCP registry URI), `env` (environment variables), `allowed` (tool restrictions). See [MCPs Guide](/gh-aw/guides/mcps/) for setup. ### Registry Field [Section titled “Registry Field”](#registry-field) The `registry` field specifies the source URI of an MCP server in a registry. It is informational — useful for documenting server origin and enabling registry-aware tooling — and does not affect execution. gh-aw does not enforce registry usage. Works with both stdio and HTTP servers: ```yaml mcp-servers: filesystem: registry: "https://api.mcp.github.com/v0/servers/modelcontextprotocol/filesystem" command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem"] ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [GitHub Tools](/gh-aw/reference/github-tools/) - GitHub API operations, toolsets, and modes * [Playwright](/gh-aw/reference/playwright/) - Browser automation and testing configuration * [Cache Memory](/gh-aw/reference/cache-memory/) - Persistent memory across workflow runs * [Repo Memory](/gh-aw/reference/repo-memory/) - Repository-specific memory storage * [QMD Documentation Search](/gh-aw/reference/qmd/) - Vector similarity search over documentation files * [MCP Scripts](/gh-aw/reference/mcp-scripts/) - Define custom inline tools with JavaScript or shell scripts * [Frontmatter](/gh-aw/reference/frontmatter/) - All frontmatter configuration options * [Network Permissions](/gh-aw/reference/network/) - Network access control for AI engines * [MCPs](/gh-aw/guides/mcps/) - Complete Model Context Protocol setup and usage # Triggering CI > How to trigger CI workflow runs on pull requests created by agentic workflows By default, pull requests created using the default `GITHUB_TOKEN` in GitHub Actions **do not trigger CI workflow runs**. This is a GitHub Actions feature to prevent event cascades. This applies to both [`create-pull-request`](/gh-aw/reference/safe-outputs/#pull-request-creation-create-pull-request) and [`push-to-pull-request-branch`](/gh-aw/reference/safe-outputs/#push-to-pr-branch-push-to-pull-request-branch) safe outputs. Note The easiest way to fix this problem is to set a secret `GH_AW_CI_TRIGGER_TOKEN` with a Personal Access Token (PAT) with ‘Contents: Read & Write’ permission to your repo. ```bash gh aw secrets set GH_AW_CI_TRIGGER_TOKEN --value "" ``` Your browser doesn't support HTML5 video. [Download Creating a CI trigger token for agentic workflows](/gh-aw/videos/create-ci-trigger-token.mp4). Creating a CI trigger token for agentic workflows ## Authorizing Triggering CI on PRs Created by Agentic Workflows [Section titled “Authorizing Triggering CI on PRs Created by Agentic Workflows”](#authorizing-triggering-ci-on-prs-created-by-agentic-workflows) To trigger CI checks on PRs created by agentic workflows, configure additional authentication for the PR creation safe outputs. ### Using a Personal Access Token (PAT) [Section titled “Using a Personal Access Token (PAT)”](#using-a-personal-access-token-pat) 1. Create a [fine-grained PAT](https://github.com/settings/personal-access-tokens/new?name=GH_AW_CI_TRIGGER_TOKEN\&description=GitHub+Agentic+Workflows+-+CI+trigger\&contents=write) (this link pre-fills the token name, description, and Contents permission) with `Contents: Read & Write` scoped to the relevant repositories where pull requests will be created. 2. Add the PAT as a repository secret (e.g., `MY_CI_TRIGGER_PAT`) using ```bash gh aw secrets set MY_CI_TRIGGER_PAT --value "" ``` 3. Reference it in your workflow: ```yaml safe-outputs: create-pull-request: github-token-for-extra-empty-commit: ${{ secrets.MY_CI_TRIGGER_PAT }} ``` or ```yaml safe-outputs: push-to-pull-request-branch: github-token-for-extra-empty-commit: ${{ secrets.MY_CI_TRIGGER_PAT }} ``` When configured, the token will be used to push an extra empty commit to the PR branch after PR creation. This will trigger `push` and `pull_request` events normally. ### Using a GitHub App [Section titled “Using a GitHub App”](#using-a-github-app) You can also use `app` to authenticate via [the GitHub App configured for the workflow](/gh-aw/reference/auth/). ```yaml safe-outputs: create-pull-request: github-token-for-extra-empty-commit: app ``` ### Using a magic secret [Section titled “Using a magic secret”](#using-a-magic-secret) Alternatively, you can set the magic secret `GH_AW_CI_TRIGGER_TOKEN` to a suitable PAT (see the above guide for creating one). This secret name is known to GitHub Agentic Workflows and does not need to be explicitly referenced in your workflow. ```bash gh aw secrets set GH_AW_CI_TRIGGER_TOKEN --value "" ``` ## Alternative: Full Token Override [Section titled “Alternative: Full Token Override”](#alternative-full-token-override) If you want all PR operations to use a different token (not just the CI trigger), use the `github-token` field instead: ```yaml safe-outputs: create-pull-request: github-token: ${{ secrets.CI_USER_PAT }} ``` This changes the author of the PR to the user or app associated with the token, and triggers CI directly. However, it grants more permissions than the empty commit approach. ## See Also [Section titled “See Also”](#see-also) * [Authentication Reference](/gh-aw/reference/auth/) — Token setup and permissions * [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) — Full safe outputs configuration # Triggers > Triggers in GitHub Agentic Workflows The `on:` section uses standard GitHub Actions syntax to define workflow triggers. For example: ```yaml on: issues: types: [opened] ``` ## Trigger Types [Section titled “Trigger Types”](#trigger-types) GitHub Agentic Workflows supports all standard GitHub Actions triggers plus additional enhancements for reactions, cost control, and advanced filtering. ### Dispatch Triggers (`workflow_dispatch:`) [Section titled “Dispatch Triggers (workflow\_dispatch:)”](#dispatch-triggers-workflow_dispatch) Run workflows manually from the GitHub UI, API, or via `gh aw run`/`gh aw trial`. [Full syntax reference](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on). **Basic trigger:** ```yaml on: workflow_dispatch: ``` **With input parameters:** ```yaml on: workflow_dispatch: inputs: topic: description: 'Research topic' required: true type: string priority: description: 'Task priority' required: false type: choice options: - low - medium - high default: medium deploy_env: description: 'Target environment' required: false type: environment default: staging ``` #### Accessing Inputs in Markdown [Section titled “Accessing Inputs in Markdown”](#accessing-inputs-in-markdown) Use `${{ github.event.inputs.INPUT_NAME }}` expressions to access workflow\_dispatch inputs in your markdown content: ```aw --- on: workflow_dispatch: inputs: topic: description: 'Research topic' required: true type: string permissions: contents: read safe-outputs: create-discussion: --- # Research Assistant Research the following topic: "${{ github.event.inputs.topic }}" Provide a comprehensive summary with key findings and recommendations. ``` **Supported input types:** * `string` - Free-form text input * `boolean` - True/false checkbox * `choice` - Dropdown selection with predefined options * `environment` - Dropdown selection of GitHub environments configured in the repository The `environment` input type automatically populates a dropdown with environments configured in repository Settings → Environments. It returns the environment name as a string and supports a `default` value. Unlike the `manual-approval:` field, using an `environment` input does not enforce environment protection rules—it only provides the environment name as a string value for use in your workflow logic. ### Scheduled Triggers (`schedule:`) [Section titled “Scheduled Triggers (schedule:)”](#scheduled-triggers-schedule) Run workflows on a recurring schedule using human-friendly expressions or [cron syntax](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule). **Fuzzy Scheduling:** Use fuzzy schedules to automatically scatter execution times and avoid load spikes: ```yaml on: schedule: daily # Compiler assigns a unique scattered time per workflow ``` Use the `around` constraint for a preferred time with flexibility: ```yaml on: schedule: daily around 14:00 # Scatters within ±1 hour (13:00-15:00) ``` For workflows that should only run during specific hours (like business hours), use the `between` constraint: ```yaml on: schedule: daily between 9:00 and 17:00 # Scatters within 9am-5pm range ``` The compiler assigns each workflow a unique, deterministic execution time based on the file path, ensuring load distribution and consistency across recompiles. UTC offsets are supported on any time expression (e.g., `daily between 9am and 5pm utc-5`). For a fixed time, use standard cron syntax. Add an optional `timezone` field to interpret the cron in a specific IANA timezone instead of UTC: ```yaml on: schedule: - cron: "30 6 * * 1" # Monday at 06:30 UTC - cron: "0 9 15 * *" # 15th of month at 09:00 UTC - cron: "30 9 * * 1-5" timezone: "America/New_York" # 9:30 AM EST/EDT Mon-Fri ``` | Format | Example | Result | Notes | | ------------------ | --------------------------------- | -------------- | -------------------------------------------- | | **Hourly (Fuzzy)** | `hourly` | `58 */1 * * *` | Compiler assigns scattered minute | | **Daily (Fuzzy)** | `daily` | `43 5 * * *` | Compiler assigns scattered time | | | `daily around 14:00` | `20 14 * * *` | Scattered within ±1 hour (13:00-15:00) | | | `daily between 9:00 and 17:00` | `37 13 * * *` | Scattered within range (9:00-17:00) | | | `daily between 9am and 5pm utc-5` | `12 18 * * *` | With UTC offset (9am-5pm EST → 2pm-10pm UTC) | | | `daily around 3pm utc-5` | `33 19 * * *` | With UTC offset (3 PM EST → 8 PM UTC) | | **Weekly (Fuzzy)** | `weekly` or `weekly on monday` | `43 5 * * 1` | Compiler assigns scattered time | | | `weekly on friday around 5pm` | `18 16 * * 5` | Scattered within ±1 hour | | **Intervals** | `every 10 minutes` | `*/10 * * * *` | Minimum 5 minutes | | | `every 2h` | `53 */2 * * *` | Fuzzy: scattered minute offset | | | `0 */2 * * *` | `0 */2 * * *` | Cron syntax for fixed times | **Time formats:** `HH:MM` (24-hour), `midnight`, `noon`, `1pm`-`12pm`, `1am`-`12am` **UTC offsets:** Add `utc+N` or `utc-N` to any time (e.g., `daily around 14:00 utc-5`) Human-friendly formats are automatically converted to standard cron expressions, with the original format preserved as a comment in the generated workflow file. ### Issue Triggers (`issues:`) [Section titled “Issue Triggers (issues:)”](#issue-triggers-issues) Trigger on issue events. [Full event reference](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#issues). ```yaml on: issues: types: [opened, edited, labeled] ``` #### Issue Locking (`lock-for-agent:`) [Section titled “Issue Locking (lock-for-agent:)”](#issue-locking-lock-for-agent) Prevent concurrent modifications to an issue during workflow execution by setting `lock-for-agent: true`: ```yaml on: issues: types: [opened, edited] lock-for-agent: true ``` When enabled, the issue is locked at workflow start and unlocked after completion (or before safe-output processing). The unlock step uses `always()` to ensure cleanup even on failure. Useful for workflows that make multiple sequential updates to an issue or need to prevent race conditions. Example workflow: .github/workflows/locked-issue-processor.md ```aw --- on: issues: types: [opened] lock-for-agent: true permissions: contents: read safe-outputs: add-comment: max: 3 --- # Issue Processor with Locking Process the issue and make multiple updates without interference from concurrent modifications. Context: "${{ steps.sanitized.outputs.text }}" ``` ### Pull Request Triggers (`pull_request:`) [Section titled “Pull Request Triggers (pull\_request:)”](#pull-request-triggers-pull_request) Trigger on pull request events. [Full event reference](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request). When triggered by a pull request event, the coding agent has access to both the PR branch and the default branch. ```yaml on: pull_request: types: [opened, synchronize, labeled] names: [ready-for-review, needs-review] reaction: "rocket" ``` #### Fork Filtering (`forks:`) [Section titled “Fork Filtering (forks:)”](#fork-filtering-forks) Pull request workflows block forks by default for security. Use the `forks:` field to allow specific fork patterns: ```yaml on: pull_request: types: [opened, synchronize] forks: ["trusted-org/*"] # Allow forks from trusted-org ``` Fork specifications: * `["*"]` - Allow all forks (use with caution) * `["owner/*"]` - Allow forks from specific organization or user * `["owner/repo"]` - Allow specific repository * Omit `forks` field - Default behavior (same-repository PRs only) The compiler uses repository ID comparison for reliable fork detection that is not affected by repository renames. ### Comment Triggers [Section titled “Comment Triggers”](#comment-triggers) The triggers `issue_comment:`, `pull_request_review_comment:`, and `discussion_comment:` activate workflows when comments are created or edited. Note that `issue_comment` events also fire for comments on pull requests (GitHub models PR comments as issue comments). When a comment is on a pull request, the coding agent has access to both the PR branch and the default branch. ```yaml on: issue_comment: types: [created] pull_request_review_comment: types: [created] discussion_comment: types: [created] reaction: "eyes" ``` #### Comment Locking (`lock-for-agent:`) [Section titled “Comment Locking (lock-for-agent:)”](#comment-locking-lock-for-agent) For `issue_comment` events, you can lock the parent issue during workflow execution: ```yaml on: issue_comment: types: [created, edited] lock-for-agent: true ``` This prevents concurrent modifications to the issue while processing the comment. The locking behavior is identical to the `issues:` trigger (see [Issue Locking](#issue-locking-lock-for-agent) above for full details). **Note:** Pull request comments are silently skipped as pull requests cannot be locked via the issues API. ### Workflow Run Triggers (`workflow_run:`) [Section titled “Workflow Run Triggers (workflow\_run:)”](#workflow-run-triggers-workflow_run) Trigger workflows after another workflow completes. [Full event reference](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run). ```yaml on: workflow_run: workflows: ["CI"] types: [completed] branches: - main - develop ``` Workflows with `workflow_run` triggers include automatic security protections: * **`workflows` is required:** `workflow_run` must include at least one non-empty entry in `workflows`. Missing, empty (`workflows: []`), or whitespace-only entries are rejected at compile time, since GitHub Actions silently disables `on.workflow_run` triggers that do not reference any workflows. * **Repository/fork validation:** The compiler injects repository ID and fork checks, rejecting cross-repository or fork-triggered runs. * **Branch restrictions required:** Include `branches` to limit triggering branches; without them the compiler warns (or errors in strict mode). See the [Security Architecture](/gh-aw/introduction/architecture/) for details. #### Conclusion Filtering (`conclusion:`) [Section titled “Conclusion Filtering (conclusion:)”](#conclusion-filtering-conclusion) Use `conclusion:` to restrict the trigger to specific workflow run outcomes. Accepts a single value or a list. Compiles into a guarded `if:` condition — other events in the same `on:` block are unaffected. ```yaml on: workflow_run: workflows: ["CI"] types: [completed] conclusion: [failure, cancelled] ``` Valid values: `success`, `failure`, `cancelled`, `skipped`, `timed_out`, `action_required`, `neutral`, `stale`. ### Deployment Status Triggers (`deployment_status:`) [Section titled “Deployment Status Triggers (deployment\_status:)”](#deployment-status-triggers-deployment_status) Trigger workflows when a GitHub deployment status changes. [Full event reference](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#deployment_status). ```yaml on: deployment_status: ``` #### State Filtering (`state:`) [Section titled “State Filtering (state:)”](#state-filtering-state) Use `state:` to restrict the trigger to specific deployment states. The compiler compiles this into a guarded `if:` condition so the workflow only runs for the matching states. Other combined triggers (such as `workflow_dispatch`) are not blocked by the guard. ```yaml on: deployment_status: state: failure # Single state ``` ```yaml on: deployment_status: state: [error, failure] # Multiple states workflow_dispatch: # Safely combined — guard ensures dispatch passes through ``` Valid `state` values: `error`, `failure`, `pending`, `success`, `inactive`, `in_progress`, `queued`, `waiting`. Note The `state` field compiles into a GitHub Actions `if:` condition: `github.event_name != 'deployment_status' || (github.event.deployment_status.state == 'failure')`. This means the workflow still runs when triggered by other events in the same `on:` block. Workflows triggered by `deployment_status` need `deployments: read` to access the event payload: ```yaml permissions: contents: read deployments: read ``` ### Repository Dispatch Trigger (`repository_dispatch:`) [Section titled “Repository Dispatch Trigger (repository\_dispatch:)”](#repository-dispatch-trigger-repository_dispatch) Trigger a workflow from outside GitHub using a single authenticated API call. Any external system that can make an HTTP `POST` request—Jira, PagerDuty, Slack, or a custom API—can start an agentic workflow this way. [Full event reference](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#repository_dispatch). ```yaml on: repository_dispatch: types: [jira-issue-created] ``` Omit `types:` to fire on any `event_type`. #### Sending the Dispatch Request [Section titled “Sending the Dispatch Request”](#sending-the-dispatch-request) Call the GitHub dispatch API with a `repo`-scoped PAT (classic) or a token with `contents: write` permission: ```http POST https://api.github.com/repos///dispatches Authorization: Bearer Content-Type: application/json { "event_type": "jira-issue-created", "client_payload": { "issue_key": "PROJ-123", "summary": "Fix the thing" } } ``` #### Accessing the Payload [Section titled “Accessing the Payload”](#accessing-the-payload) Reference `client_payload` fields in your workflow markdown using standard GitHub Actions expressions: ```yaml on: repository_dispatch: types: [jira-issue-created] ``` ```markdown Issue ${{ github.event.client_payload.issue_key }}: ${{ github.event.client_payload.summary }} ``` ### Command Triggers (`slash_command:`) [Section titled “Command Triggers (slash\_command:)”](#command-triggers-slash_command) The `slash_command:` trigger creates workflows that respond to `/command-name` mentions in issues, pull requests, and comments. By default, command triggers listen to **all** comment-related events, which can create noise from skipped runs. Use the `events:` field to restrict where commands are active: ```yaml on: slash_command: name: investigate events: [issues, issue_comment] # Only respond in issue contexts # strategy: centralized # Optional: route via generated central trigger workflow ``` See [Command Triggers](/gh-aw/reference/command-triggers/) for complete documentation including event filtering, context text, reactions, and examples. ### Label Command Trigger (`label_command:`) [Section titled “Label Command Trigger (label\_command:)”](#label-command-trigger-label_command) The `label_command:` trigger activates a workflow when a specific label is applied to an issue, pull request, or discussion, and **automatically removes that label** so it can be re-applied to re-trigger. This treats a label as a one-shot command rather than a persistent state marker. ```yaml # Fires on issues, pull_request, and discussion by default on: label_command: deploy # Restrict to specific event types on: label_command: name: deploy events: [pull_request] # Disable automatic label removal (label stays on the item after activation) on: label_command: name: deploy remove_label: false # Shorthand string form on: "label-command deploy" ``` The compiler generates `issues`, `pull_request`, and/or `discussion` events with `types: [labeled]`, adds a `workflow_dispatch` trigger with `item_number` for manual testing, and injects a label removal step in the activation job. The matched label name is exposed as `needs.activation.outputs.label_command`. The `remove_label` field (boolean, default `true`) controls whether the label is automatically removed after activation. Set to `false` to keep the label on the item — useful when the label represents persistent state rather than a one-shot command. When `remove_label: false`, the workflow does not need `issues: write` or `pull-requests: write` permissions for label removal. `label_command` can be combined with `slash_command:` — the workflow activates when either condition is met. See [LabelOps](/gh-aw/patterns/label-ops/) for patterns and examples. ## Trigger Filtering [Section titled “Trigger Filtering”](#trigger-filtering) Triggers can be filtered by label names, and more. These filters compile into guarded `if:` conditions that ensure the workflow only runs when the specified criteria are met, while allowing other events to pass through unaffected. ### Filtering with Labels (`names:`) [Section titled “Filtering with Labels (names:)”](#filtering-with-labels-names) Filter issue and pull request triggers by label names using the `names:` field. Unlike `label_command`, the label stays on the item after the workflow runs. ```yaml on: issues: types: [labeled, unlabeled] names: [bug, critical, security] ``` Use convenient shorthand for label-based triggers: ```yaml on: issue labeled bug on: issue labeled bug, enhancement, priority-high # Multiple labels on: pull_request labeled needs-review, ready-to-merge ``` All shorthand formats compile to standard GitHub Actions syntax and automatically include the `workflow_dispatch` trigger. Supported for `issue`, `pull_request`, and `discussion` events. See [LabelOps workflows](/gh-aw/patterns/label-ops/) for automation examples. ### Filtering with Simple Conditions (`:if`) [Section titled “Filtering with Simple Conditions (:if)”](#filtering-with-simple-conditions-if) For conditions that can be expressed directly with GitHub Actions context, use `if:` without a custom job: ```yaml --- on: pull_request: types: [opened, synchronize] if: github.event.pull_request.draft == false --- ``` ### Filtering with Search Queries (`skip-if-match:`, `skip-if-no-match:`) [Section titled “Filtering with Search Queries (skip-if-match:, skip-if-no-match:)”](#filtering-with-search-queries-skip-if-match-skip-if-no-match) For conditions based on GitHub search results, use [`skip-if-match:`](#skip-if-match-condition-skip-if-match) or [`skip-if-no-match:`](#skip-if-no-match-condition-skip-if-no-match) in the `on:` section — these accept standard [GitHub search query syntax](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests) and are evaluated in the pre-activation job, producing the same skipped-not-failed behavior: ```yaml --- on: issues: types: [opened] # Skip if a duplicate issue already exists (GitHub search query syntax) skip-if-match: 'is:issue is:open label:duplicate' --- ``` ### Filtering by Repository Access Roles (`on.roles:`, `on.skip-roles`) [Section titled “Filtering by Repository Access Roles (on.roles:, on.skip-roles)”](#filtering-by-repository-access-roles-onroles-onskip-roles) Controls who can trigger agentic workflows based on repository permission level. Defaults to `[admin, maintainer, write]`. ```yaml on: issues: types: [opened] roles: [admin, maintainer, write] # Default ``` ```yaml on: workflow_dispatch: roles: all # Allow any user (! use with caution) ``` You can also skip workflow execution for users with specific repository permission levels. Useful for exempting team members from automated checks that should only apply to external contributors. ```yaml on: issues: types: [opened] skip-roles: [admin, maintainer, write] ``` Available roles: `admin`, `maintainer`/`maintain`, `write`, `triage`, `read`, `all`. Workflows with unsafe triggers (`push`, `issues`, `pull_request`) automatically enforce permission checks. Failed checks cancel the workflow with a warning. ### Filtering by Bot (`on.bots:`, `on.skip-bots:`) [Section titled “Filtering by Bot (on.bots:, on.skip-bots:)”](#filtering-by-bot-onbots-onskip-bots) You can configure which GitHub bot accounts can trigger workflows. Useful for allowing specific automation bots while maintaining security controls. ```yaml on: issues: types: [opened] bots: - "dependabot[bot]" - "renovate[bot]" - "agentic-workflows-dev[bot]" ``` Likewise you can skip workflow execution when triggered by specific GitHub actors (users or bots). ```yaml on: issues: types: [opened] skip-bots: [github-actions, copilot, dependabot] ``` **Common bot names**: * `dependabot[bot]` - GitHub Dependabot for dependency updates * `renovate[bot]` - Renovate bot for automated dependency management * `github-actions[bot]` - GitHub Actions bot * `agentic-workflows-dev[bot]` - Development bot for testing workflows **Bot name matching**: Automatic flexible matching handles bot names with or without the `[bot]` suffix. For example, specifying `github-actions` matches both `github-actions` and `github-actions[bot]` actors automatically. ### Filtering by Author Associations (`on.skip-author-associations`) [Section titled “Filtering by Author Associations (on.skip-author-associations)”](#filtering-by-author-associations-onskip-author-associations) You can skip workflow execution when a specific event is triggered by an author with a matching event payload `author_association` field (for example `github.event.comment.author_association`, `github.event.issue.author_association`, or `github.event.pull_request.author_association`). ```yaml on: issue_comment: types: [created] pull_request_review_comment: types: [created] skip-author-associations: issue_comment: contributor pull_request_review_comment: [first_time_contributor, none] ``` ### Filtering by Custom Steps (`on.steps:`) [Section titled “Filtering by Custom Steps (on.steps:)”](#filtering-by-custom-steps-onsteps) You may inject deterministic steps directly into the pre-activation job using `on.steps:`. This saves **one workflow job** compared to the multi-job pattern and is the recommended approach for lightweight filtering: .github/workflows/smart-responder.md ```yaml --- on: issues: types: [opened] steps: - id: check env: LABELS: ${{ toJSON(github.event.issue.labels.*.name) }} run: echo "$LABELS" | grep -q '"bug"' # exits 0 (outcome: success) if the label is found, 1 (outcome: failure) if not safe-outputs: add-comment: if: needs.pre_activation.outputs.check_result == 'success' --- # Bug Issue Responder Triage bug report: "${{ github.event.issue.title }}" and add-comment with a summary of the next steps. ``` Each step with an `id` gets an auto-wired output `_result` set to `${{ steps..outcome }}` — `success` when the step’s exit code is 0, `failure` when non-zero. Gate the workflow by checking `needs.pre_activation.outputs._result == 'success'`. To pass an explicit value rather than relying on exit codes, set a step output and re-expose it via `jobs.pre-activation.outputs`: ```yaml jobs: pre-activation: outputs: has_bug_label: ${{ steps.check.outputs.has_bug_label }} if: needs.pre_activation.outputs.has_bug_label == 'true' ``` When `on.steps:` need GitHub API access, use `on.permissions:` to grant the required scopes to the pre-activation job: ```yaml on: schedule: every 30m permissions: issues: read steps: - id: search uses: actions/github-script@v8 with: script: | const open = await github.rest.issues.listForRepo({ ...context.repo, state: 'open' }); core.setOutput('has_work', open.data.length > 0 ? 'true' : 'false'); jobs: pre-activation: outputs: has_work: ${{ steps.search.outputs.has_work }} if: needs.pre_activation.outputs.has_work == 'true' ``` See [Pre-Activation Steps](#pre-activation-steps-onsteps) and [Pre-Activation Permissions](#pre-activation-permissions-onpermissions) for full documentation. ### Filtering by Custom Jobs (`jobs:`) [Section titled “Filtering by Custom Jobs (jobs:)”](#filtering-by-custom-jobs-jobs) For complex custom trigger filtering you can use a separate `jobs:` entry when filtering requires heavy tooling (checkout, compiled tools, multiple runners): .github/workflows/smart-responder.md ```yaml --- on: issues: types: [opened] safe-outputs: add-comment: jobs: filter: runs-on: ubuntu-latest outputs: should-run: ${{ steps.check.outputs.result }} steps: - id: check env: LABELS: ${{ toJSON(github.event.issue.labels.*.name) }} run: | if echo "$LABELS" | grep -q '"bug"'; then echo "result=true" >> "$GITHUB_OUTPUT" else echo "result=false" >> "$GITHUB_OUTPUT" fi if: needs.filter.outputs.should-run == 'true' --- # Bug Issue Responder Triage bug report: "${{ github.event.issue.title }}" and add-comment with a summary of the next steps. ``` The compiler automatically adds the filter job as a dependency of the activation job, so when the condition is false the workflow run is **skipped** (not failed), keeping the Actions tab clean. ## Additional Trigger Options [Section titled “Additional Trigger Options”](#additional-trigger-options) Trigger support additional options for reactions, status comments, authentication tokens, and more. These options are configured in the same `on:` block as the trigger and apply to all triggers defined within that block. ### Reactions (`reaction:`) [Section titled “Reactions (reaction:)”](#reactions-reaction) Enable emoji reactions on triggering items (issues, PRs, comments, discussions) to provide visual workflow status feedback: ```yaml on: issues: types: [opened] reaction: "eyes" ``` The reaction is added to the triggering item. Use `none` to disable reactions entirely. **Available reactions:** `+1` , `-1` , `laugh` , `confused` , `heart` , `hooray` , `rocket` , `eyes` ### Status Comments (`status-comment:`) [Section titled “Status Comments (status-comment:)”](#status-comments-status-comment) Post a started/completed comment on the triggering item with a link to the workflow run: ```yaml on: issues: types: [opened] reaction: "eyes" status-comment: true ``` When `status-comment: true`, the activation job posts a comment when the workflow starts and updates it when the run completes. Setting `reaction:` alone does not create status comments — they are independent settings. For `slash_command` and `label_command` triggers, both `reaction: eyes` and `status-comment: true` are enabled by default. Disable either explicitly: ```yaml on: slash_command: my-bot reaction: none # disable the eyes reaction status-comment: false # disable the status comment ``` For all other trigger types, `status-comment` must be explicitly set to `true` to enable it. To suppress status comments, omit `status-comment:` or set it to `false`. Use an object to enable status comments while selectively disabling specific targets. The object form implies status comments are enabled; each field defaults to `true`: ```yaml on: issues: types: [opened] pull_request: types: [opened] discussion: types: [created] status-comment: issues: true # post on issue events (default) pull-requests: false # skip pull request events discussions: false # skip discussion events ``` | Field | Type | Default | Description | | --------------- | ------- | ------- | ---------------------------------------------------------------------------------- | | `issues` | boolean | `true` | Enable status comments for `issues` and `issue_comment` events | | `pull-requests` | boolean | `true` | Enable status comments for `pull_request` and `pull_request_review_comment` events | | `discussions` | boolean | `true` | Enable status comments for `discussion` and `discussion_comment` events | ### Activation Token (`on.github-token:`, `on.github-app:`) [Section titled “Activation Token (on.github-token:, on.github-app:)”](#activation-token-ongithub-token-ongithub-app) Configure a custom GitHub token or GitHub App for the activation job **and all skip-if search checks**. The activation job posts the initial reaction (and status comment if `status-comment: true`) on the triggering item, and skip-if checks use the same token to query the GitHub Search API. By default all of these operations use the workflow’s `GITHUB_TOKEN`. Use `github-token:` to supply a PAT or custom token: ```yaml on: issues: types: [opened] reaction: "eyes" github-token: ${{ secrets.MY_TOKEN }} ``` Use `github-app:` to mint a short-lived installation token instead: ```yaml on: issues: types: [opened] reaction: "rocket" github-app: client-id: ${{ vars.APP_ID }} private-key: ${{ secrets.APP_KEY }} ``` The `github-app` object accepts the same fields as the GitHub App configuration used elsewhere in the framework (`app-id`, `private-key`, and optionally `owner` and `repositories`). The token is minted once in the pre-activation job and is shared across the reaction step, the status comment step (if `status-comment: true`), and any skip-if search steps. Both `github-token` and `github-app` can be defined in a **shared agentic workflow** and will be automatically inherited by any workflow that imports it (first-wins strategy). This means a central CentralRepoOps shared workflow can define the app config once and all importing workflows benefit automatically: ```yaml # shared-ops.md - define app config once on: workflow_call: github-app: client-id: ${{ secrets.ORG_APP_ID }} private-key: ${{ secrets.ORG_APP_PRIVATE_KEY }} owner: myorg ``` ```yaml # any-workflow.md - inherits github-app from the import imports: - .github/workflows/shared/shared-ops.md on: schedule: every 30 minutes skip-if-no-match: query: "org:myorg label:agent-fix is:issue is:open" scope: none ``` Note `github-token` and `github-app` affect only the activation job (reactions, status comments, and skip-if searches). For the agent job, configure tokens via `tools.github.github-token`/`tools.github.github-app` or `safe-outputs.github-token`/`safe-outputs.github-app`. See [Authentication](/gh-aw/reference/auth/) for a full overview. ### Stop After Configuration (`stop-after:`) [Section titled “Stop After Configuration (stop-after:)”](#stop-after-configuration-stop-after) Automatically disable workflow triggering after a deadline to control costs. ```yaml on: weekly on monday stop-after: "+25h" # 25 hours from compilation time ``` Accepts absolute dates (`YYYY-MM-DD`, `MM/DD/YYYY`, `DD/MM/YYYY`, `January 2 2006`, `1st June 2025`, ISO 8601) or relative deltas (`+7d`, `+25h`, `+1d12h30m`) calculated from compilation time. The minimum granularity is hours - minute-only units (e.g., `+30m`) are not allowed. Recompiling the workflow resets the stop time. ### Manual Approval Gates (`manual-approval:`) [Section titled “Manual Approval Gates (manual-approval:)”](#manual-approval-gates-manual-approval) Require manual approval before workflow execution using GitHub environment protection rules: ```yaml on: workflow_dispatch: manual-approval: production ``` Sets the `environment` on the activation job for human-in-the-loop approval before execution. The value must match a configured environment in repository Settings → Environments (approval rules, required reviewers, wait timers). See [GitHub’s environment documentation](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) for configuration details. ### Skip-If-Match Condition (`skip-if-match:`) [Section titled “Skip-If-Match Condition (skip-if-match:)”](#skip-if-match-condition-skip-if-match) Conditionally skip workflow execution when a GitHub search query has matches. Useful for preventing duplicate scheduled runs or waiting for prerequisites. ```yaml on: daily skip-if-match: 'is:issue is:open in:title "[daily-report]"' # Skip if any match ``` ```yaml on: weekly on monday skip-if-match: query: "is:pr is:open label:urgent" max: 3 # Skip if 3 or more PRs match ``` A pre-activation check runs the search query against the current repository. If matches reach or exceed the threshold (default `max: 1`), the workflow is skipped. The query is automatically scoped to the current repository and supports all standard GitHub search qualifiers (`is:`, `label:`, `in:title`, `author:`, etc.). By default the query is scoped to the current repository. Use `scope: none` to disable this and search across an entire org. For cross-repo or org-wide searches that require elevated permissions, configure `github-token` or `github-app` at the top-level `on:` section — the same token is shared across all skip-if checks and the activation job: ```yaml on: schedule: every 15 minutes skip-if-match: query: "org:myorg label:ops:in-progress is:issue is:open" scope: none github-app: client-id: ${{ secrets.WORKFLOW_APP_ID }} private-key: ${{ secrets.WORKFLOW_APP_PRIVATE_KEY }} owner: myorg ``` | Field | Location | Description | | -------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------- | | `scope: none` | inside `skip-if-match` | Disables the automatic `repo:owner/repo` qualifier | | `github-token` | top-level `on:` | Custom PAT or token for all skip-if searches (e.g. `${{ secrets.CROSS_ORG_TOKEN }}`) | | `github-app` | top-level `on:` | Mints a short-lived installation token shared across all skip-if steps; requires `app-id` and `private-key` | `github-token` and `github-app` are mutually exclusive. String shorthand always uses the default `GITHUB_TOKEN` scoped to the current repository. ### Skip-If-No-Match Condition (`skip-if-no-match:`) [Section titled “Skip-If-No-Match Condition (skip-if-no-match:)”](#skip-if-no-match-condition-skip-if-no-match) Conditionally skip workflow execution when a GitHub search query has **no matches** (or fewer than the minimum required). This is the opposite of `skip-if-match`. ```yaml on: weekly on monday skip-if-no-match: 'is:pr is:open label:ready-to-deploy' # Skip if no matches ``` ```yaml on: workflow_dispatch: skip-if-no-match: query: "is:issue is:open label:urgent" min: 3 # Only run if 3 or more issues match ``` A pre-activation check runs the search query against the current repository. If matches are below the threshold (default `min: 1`), the workflow is skipped. Can be combined with `skip-if-match` for complex conditions. The same `scope: none` field available on `skip-if-match` works identically here. Authentication (`github-token` / `github-app`) is configured at the top-level `on:` section and is shared across all skip-if checks — a single mint step is emitted for both: ```yaml on: schedule: every 15 minutes skip-if-no-match: query: "org:myorg label:agent-fix -label:ops:agentic is:issue is:open" scope: none github-app: client-id: ${{ secrets.WORKFLOW_APP_ID }} private-key: ${{ secrets.WORKFLOW_APP_PRIVATE_KEY }} owner: myorg ``` ### Pre-Activation Steps (`on.steps:`) [Section titled “Pre-Activation Steps (on.steps:)”](#pre-activation-steps-onsteps) Inject custom deterministic steps directly into the pre-activation job. Steps run after all built-in checks (membership, stop-time, skip-if, etc.) and **before** agent execution. This saves one workflow job compared to the multi-job pattern and keeps filtering logic co-located with the trigger configuration. ```yaml on: issues: types: [opened] steps: - name: Check issue label id: label_check env: LABELS: ${{ toJSON(github.event.issue.labels.*.name) }} run: echo "$LABELS" | grep -q '"bug"' # exits 0 (outcome: success) if the label is found, 1 (outcome: failure) if not if: needs.pre_activation.outputs.label_check_result == 'success' ``` Each step with an `id` automatically gets an output `_result` wired to `${{ steps..outcome }}` (values: `success`, `failure`, `cancelled`, `skipped`). This lets you gate the workflow on whether the step **succeeded or failed** via its exit code. To pass an explicit value rather than relying on exit codes, set a step output and re-expose it via `jobs.pre-activation.outputs`: ```yaml on: issues: types: [opened] steps: - name: Check issue label id: label_check env: LABELS: ${{ toJSON(github.event.issue.labels.*.name) }} run: | if echo "$LABELS" | grep -q '"bug"'; then echo "has_bug_label=true" >> "$GITHUB_OUTPUT" else echo "has_bug_label=false" >> "$GITHUB_OUTPUT" fi jobs: pre-activation: outputs: has_bug_label: ${{ steps.label_check.outputs.has_bug_label }} if: needs.pre_activation.outputs.has_bug_label == 'true' ``` Explicit outputs defined in `jobs.pre-activation.outputs` take precedence over auto-wired `_result` outputs on key collision. ### Pre-Activation and Activation Dependencies (`on.needs:`) [Section titled “Pre-Activation and Activation Dependencies (on.needs:)”](#pre-activation-and-activation-dependencies-onneeds) Add custom jobs that both `pre_activation` and `activation` should depend on. Use this when `on.github-app` credentials come from a job output (for example, a secret-manager fetch job). ```yaml on: workflow_dispatch: needs: [secrets_fetcher] github-app: client-id: ${{ needs.secrets_fetcher.outputs.app_id }} private-key: ${{ needs.secrets_fetcher.outputs.private_key }} jobs: secrets_fetcher: runs-on: ubuntu-latest outputs: app_id: ${{ steps.fetch.outputs.app_id }} private_key: ${{ steps.fetch.outputs.private_key }} steps: - id: fetch run: | echo "app_id=123" >> "$GITHUB_OUTPUT" echo "private_key=***" >> "$GITHUB_OUTPUT" ``` `on.needs` values must reference custom jobs from top-level `jobs:`. Built-in jobs are rejected. ### Pre-Activation Permissions (`on.permissions:`) [Section titled “Pre-Activation Permissions (on.permissions:)”](#pre-activation-permissions-onpermissions) Grant additional GitHub token permission scopes to the pre-activation job. Use when `on.steps:` make GitHub API calls that require permissions beyond the defaults. ```yaml on: schedule: every 30m permissions: issues: read pull-requests: read steps: - name: Search for candidate issues id: search uses: actions/github-script@v8 with: script: | const issues = await github.rest.issues.listForRepo(context.repo); core.setOutput('has_issues', issues.data.length > 0 ? 'true' : 'false'); jobs: pre-activation: outputs: has_issues: ${{ steps.search.outputs.has_issues }} if: needs.pre_activation.outputs.has_issues == 'true' ``` Supported permission scopes: `actions`, `checks`, `contents`, `deployments`, `discussions`, `issues`, `packages`, `pages`, `pull-requests`, `repository-projects`, `security-events`, `statuses`. `on.permissions` is merged on top of any permissions already required by the pre-activation job (e.g., `contents: read` for dev-mode checkout, `actions: read` for rate limiting). ## Trigger Shorthands [Section titled “Trigger Shorthands”](#trigger-shorthands) Instead of writing full YAML trigger configurations, you can use natural-language shorthand strings with `on:`. The compiler expands these into standard GitHub Actions trigger syntax and automatically includes `workflow_dispatch` so the workflow can also be run manually. For label-based shorthands (`on: issue labeled bug`, `on: pull_request labeled needs-review`), see [Label Filtering](#filtering-with-labels-names) above. For the label-command pattern, see [Label Command Trigger](#label-command-trigger-label_command) above. ### Push and Pull Request [Section titled “Push and Pull Request”](#push-and-pull-request) ```yaml on: push to main # Push to specific branch on: push tags v* # Push tags matching pattern on: pull_request opened # PR with activity type on: pull_request merged # PR merged (maps to closed + merge condition) on: pull_request affecting src/** # PR touching paths (opened, synchronize, reopened) on: pull_request opened affecting docs/** # Activity type + path filter ``` `pull` is an alias for `pull_request`. Valid activity types: `opened`, `edited`, `closed`, `reopened`, `synchronize`, `assigned`, `unassigned`, `labeled`, `unlabeled`, `review_requested`, `merged`. ### Issues and Discussions [Section titled “Issues and Discussions”](#issues-and-discussions) ```yaml on: issue opened # Issue with activity type on: issue opened labeled bug # Issue opened with specific label (adds job condition) on: discussion created # Discussion with activity type ``` Valid issue types: `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `labeled`, `unlabeled`, `deleted`, `transferred`. Valid discussion types: `created`, `edited`, `deleted`, `transferred`, `pinned`, `unpinned`, `labeled`, `unlabeled`, `locked`, `unlocked`, `category_changed`, `answered`, `unanswered`. ### Other Shorthands [Section titled “Other Shorthands”](#other-shorthands) ```yaml on: manual # workflow_dispatch (run manually) on: manual with input version # workflow_dispatch with a string input on: workflow completed ci-test # Trigger after another workflow completes on: comment created # Issue or PR comment created on: release published # Release event (published, created, prereleased, etc.) on: repository starred # Repository starred (maps to watch event) on: repository forked # Repository forked on: dependabot pull request # PR from Dependabot (adds actor condition) on: security alert # Code scanning alert on: code scanning alert # Alias for security alert (code scanning alert) on: api dispatch custom-event # Repository dispatch with custom event type on: "deployment failed" # deployment_status with state == 'failure' guard on: "deployment error" # deployment_status with state == 'error' guard on: "deployment failed or error" # deployment_status with state == 'failure' or 'error' guard ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Schedule Syntax](/gh-aw/reference/schedule-syntax/) - Complete schedule format reference * [Command Triggers](/gh-aw/reference/command-triggers/) - Special @mention triggers and context text * [Frontmatter](/gh-aw/reference/frontmatter/) - Complete frontmatter configuration * [DeterministicOps](/gh-aw/patterns/deterministic-ops/) - Combining deterministic steps with AI reasoning * [LabelOps](/gh-aw/patterns/label-ops/) - Label-based automation workflows * [Workflow Structure](/gh-aw/reference/workflow-structure/) - Directory layout and organization # WebAssembly Compilation > How to compile the gh-aw workflow compiler to WebAssembly and use it in the browser or other JavaScript environments. Experimental WASM compilation of the GH-AW toolchain is an experimental feature. The gh-aw compiler can be built as a WebAssembly (Wasm) module, letting you compile agentic workflows directly in the browser without a server-side Go installation. ## Overview [Section titled “Overview”](#overview) The Wasm build packages the core compilation engine — markdown parsing, frontmatter extraction, import resolution, and YAML generation — into a single `.wasm` file. You load it with Go’s standard `wasm_exec.js` runtime, then call a global `compileWorkflow()` function from JavaScript. This is useful for: * **Interactive playgrounds** where users experiment with workflow syntax * **Editor integrations** that preview compiled YAML in real time * **Offline tools** that need compilation without a backend ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * Go 1.25 or later * `make` (GNU Make) ## Building [Section titled “Building”](#building) Run the following from the repository root: ```bash make build-wasm ``` This produces two artifacts: | File | Description | | ----------------------------------------- | ------------------------------------------------------ | | `gh-aw.wasm` | The compiled WebAssembly module (\~17 MB uncompressed) | | `$(go env GOROOT)/misc/wasm/wasm_exec.js` | Go’s Wasm runtime (ships with your Go installation) | Copy both files to your project: ```bash cp gh-aw.wasm your-project/ cp "$(go env GOROOT)/misc/wasm/wasm_exec.js" your-project/ ``` ## Compression [Section titled “Compression”](#compression) The raw `.wasm` binary is \~17 MB. The build pipeline pre-compresses it with [brotli](https://github.com/google/brotli) at maximum quality (`-q 11`), producing a `gh-aw.wasm.br` file of \~5 MB — a \~70% reduction. GitHub Pages serves the `.br` file automatically when the browser sends `Accept-Encoding: br`. ```bash # Manual compression (if not using the bundle script) brotli -k -q 11 gh-aw.wasm # produces gh-aw.wasm.br (~5 MB) ``` The docs site bundle script (`scripts/bundle-wasm-docs.sh`) handles this automatically. If `brotli` is not installed, it falls back to gzip (`-9`), which achieves \~6 MB. ## JavaScript API [Section titled “JavaScript API”](#javascript-api) ### Loading the module [Section titled “Loading the module”](#loading-the-module) ```html ``` ### `compileWorkflow(markdown)` [Section titled “compileWorkflow(markdown)”](#compileworkflowmarkdown) Compiles a markdown workflow string into GitHub Actions YAML. **Parameters:** | Name | Type | Required | Description | | ---------- | -------- | -------- | --------------------------------------------------------- | | `markdown` | `string` | Yes | The full markdown workflow content, including frontmatter | **Returns:** `Promise<{ yaml: string, warnings: string[], error: null }>` On failure, the promise rejects with an `Error`. ### Basic example [Section titled “Basic example”](#basic-example) ```javascript const result = await compileWorkflow(`--- name: hello-world description: A simple greeting workflow on: workflow_dispatch: engine: copilot --- Say "Hello, world!" as an issue comment. `); console.log(result.yaml); ``` ## How it works [Section titled “How it works”](#how-it-works) The Wasm build uses Go [build tags](https://pkg.go.dev/go/build#hdr-Build_Constraints) to swap platform-dependent code with lightweight stubs at compile time. The native build and Wasm build share the same core compiler — only the I/O and TUI layers differ. ### Build tag convention [Section titled “Build tag convention”](#build-tag-convention) Each stubbed file uses a pair of build constraints: * **`//go:build js || wasm`** — the stub, compiled into the Wasm module * **`//go:build !js && !wasm`** — the native implementation, excluded from Wasm ### What gets stubbed [Section titled “What gets stubbed”](#what-gets-stubbed) The Wasm build replaces four categories of functionality: **Terminal UI (`pkg/tty`, `pkg/styles`, `pkg/console`)** The native build uses [Lip Gloss](https://github.com/charmbracelet/lipgloss), [Bubble Tea](https://github.com/charmbracelet/bubbletea), and [Huh](https://github.com/charmbracelet/huh) for styled terminal output, spinners, forms, and prompts. The Wasm stubs replace these with plain-text equivalents — no ANSI escape codes, no interactive input. Stubbed console files: `banner`, `confirm`, `console`, `form`, `input`, `layout`, `list`, `progress`, `select`, `spinner`. **External tool validation (`pkg/workflow`)** The native compiler shells out to validate that tools like `npm`, `pip`, `docker`, `git`, and `gh` are installed and configured correctly. Since `os/exec` is unavailable in Wasm, these validators return `nil` (skip validation). Stubbed validators: `npm_validation`, `pip_validation`, `docker_validation`, `git_helpers`, `github_cli`, `dependabot`, `repository_features_validation`. **Remote imports (`pkg/parser`)** Fetching imports from remote GitHub repositories requires HTTP calls and `gh` CLI authentication. In the Wasm build, remote imports return an error. A JavaScript import resolver callback is planned for a future release. **GitHub token access (`pkg/parser`)** The native build retrieves GitHub tokens via `gh auth token`. The Wasm build falls back to reading `GITHUB_TOKEN` or `GH_TOKEN` environment variables only. ### String-based compilation API [Section titled “String-based compilation API”](#string-based-compilation-api) The Wasm entry point uses `CompileToYAML()`, a string-in/string-out API on the `Compiler` struct that returns YAML content without writing to disk. This method runs in no-emit mode (`WithNoEmit(true)`) and skips external validation (`WithSkipValidation(true)`). ## Architecture [Section titled “Architecture”](#architecture) The following diagram shows which packages have Wasm-specific stubs: ```plaintext cmd/gh-aw-wasm/main.go ← Wasm entry point (syscall/js) │ ├── pkg/workflow/ │ ├── compiler*.go (shared — core compiler) │ ├── compiler_string_api.go (shared — CompileToYAML) │ ├── npm_validation_wasm.go (stub — returns nil) │ ├── pip_validation_wasm.go (stub — returns nil) │ ├── docker_validation_wasm.go (stub — returns nil) │ ├── git_helpers_wasm.go (stub — returns nil) │ ├── github_cli_wasm.go (stub — returns nil) │ ├── dependabot_wasm.go (stub — returns nil) │ └── repository_features_validation_wasm.go │ (stub — returns nil) │ ├── pkg/parser/ │ ├── github_wasm.go (stub — env-only token) │ └── remote_fetch_wasm.go (stub — no remote imports) │ ├── pkg/console/ (stub — 10 files, plain text) ├── pkg/styles/theme_wasm.go (stub — no-op styles) └── pkg/tty/tty_wasm.go (stub — no TTY detection) ``` ## Limitations [Section titled “Limitations”](#limitations) The Wasm build is focused on compilation only. The following features are not available: | Feature | Reason | | ---------------------------------------------------- | ----------------------------------------- | | Interactive TUI (spinners, prompts, forms) | No terminal in the browser | | External tool validation (npm, pip, docker, git, gh) | No `os/exec` in Wasm | | Remote imports (`owner/repo/path@ref`) | No HTTP client or `gh` CLI | | Filesystem writes | Compiler runs in no-emit mode | | CLI commands (`gh aw init`, `gh aw watch`, etc.) | Only the `compileWorkflow` API is exposed | Note Import resolution (`importResolver` callback) is not currently supported in the Wasm build. Workflows that use `imports:` will produce an error. This feature is planned for a future release. # Web Search > How to add web search capabilities to GitHub Agentic Workflows using Tavily MCP server. This guide shows how to add web search to workflows using the Tavily Model Context Protocol (MCP) server, an AI-optimized search provider designed for LLM applications. While alternatives exist (Exa, SerpAPI, Brave Search), this guide focuses on Tavily configuration. ## Tavily Search [Section titled “Tavily Search”](#tavily-search) [Tavily](https://tavily.com/) provides AI-optimized search with structured JSON responses, news search capability, and fast response times through the [@tavily/mcp](https://github.com/tavily-ai/tavily-mcp) MCP server. ```aw --- on: issues engine: copilot mcp-servers: tavily: command: npx args: ["-y", "@tavily/mcp"] env: TAVILY_API_KEY: "${{ secrets.TAVILY_API_KEY }}" allowed: ["search", "search_news"] --- # Search and Respond Search the web for information about: ${{ github.event.issue.title }} Use the tavily search tool to find recent information. ``` **Setup:** 1. Sign up at [tavily.com](https://tavily.com/) and get your API key 2. Add as repository secret: `gh aw secrets set TAVILY_API_KEY --value ""` [Tavily Terms of Service](https://tavily.com/terms) Test your configuration with `gh aw mcp inspect `. ## Tool Discovery [Section titled “Tool Discovery”](#tool-discovery) To see available tools from the Tavily MCP server: ```bash # Inspect the MCP server in your workflow gh aw mcp inspect my-workflow --server tavily # List tools with details gh aw mcp list-tools tavily my-workflow --verbose ``` ## Network Permissions [Section titled “Network Permissions”](#network-permissions) Agentic workflows require explicit network permissions for MCP servers: ```yaml network: allowed: - defaults - "*.tavily.com" ``` ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [MCP Integration](/gh-aw/guides/mcps/) - Complete MCP server guide * [Tools](/gh-aw/reference/tools/) - Tool configuration reference * [AI Engines](/gh-aw/reference/engines/) - Engine capabilities and limitations * [CLI Commands](/gh-aw/setup/cli/) - CLI commands including `mcp inspect` * [Model Context Protocol Specification](https://github.com/modelcontextprotocol/specification) * [Tavily MCP Server](https://github.com/tavily-ai/tavily-mcp) * [Tavily Documentation](https://tavily.com/) # Workflow Structure > Learn how agentic workflows are organized and structured within your repository, including directory layout and file organization. Each workflow consists of: 1. **YAML Frontmatter**: Configuration options wrapped in `---`. See [Frontmatter](/gh-aw/reference/frontmatter/) for details. 2. **Markdown**: Natural language instructions for the AI. See [Markdown](/gh-aw/reference/markdown/). For example: ```aw --- on: issues: types: [opened] tools: github: toolsets: [issues] --- # Workflow Description Read the issue #${{ github.event.issue.number }}. Add a comment to the issue listing useful resources and links. ``` A workflow file may optionally include one or more inline sub-agent definitions after the main markdown body. See [Inline Sub-Agents](/gh-aw/reference/inline-sub-agents/) for details. ## File Organization [Section titled “File Organization”](#file-organization) Agentic workflows are stored in the `.github/workflows` folder as Markdown files (`*.md`) and they are compiled to GitHub Actions Workflows files (`*.lock.yml`) ```text .github/ └── workflows/ ├── ci-doctor.md # Agentic Workflow └── ci-doctor.lock.yml # Compiled GitHub Actions Workflow ``` When you run the `compile` command you generate the lock file. ```sh gh aw compile ``` ### Lock File Header [Section titled “Lock File Header”](#lock-file-header) Each compiled lock file begins with a machine-readable metadata line followed by a human-readable manifest of its external dependencies: ```yaml # gh-aw-metadata: {"schema_version":"v3","frontmatter_hash":"...","strict":true,"agent_id":"copilot"} # ___ ...ASCII logo... # This file was automatically generated by gh-aw. DO NOT EDIT. # ... # Secrets used: # - COPILOT_GITHUB_TOKEN # - GITHUB_TOKEN # # Custom actions used: # - actions/checkout@de0fac2e... # v6.0.2 # - actions/upload-artifact@bbbca2... # v4 ``` The `gh-aw-metadata` line is always first, enabling reliable machine parsing. The `Secrets used` and `Custom actions used` sections list all `secrets.*` references and external `uses:` dependencies (excluding local `./` refs) found in the compiled workflow, sorted and deduplicated. ## Editing Workflows [Section titled “Editing Workflows”](#editing-workflows) The **markdown body** is loaded at runtime and can be edited directly on GitHub.com without recompilation. Only **frontmatter changes** require recompilation. See [Editing Workflows](/gh-aw/guides/editing-workflows/) for complete guidance on when and how to recompile workflows. ## Best Practices [Section titled “Best Practices”](#best-practices) * Use descriptive names: `issue-responder.md`, `pr-reviewer.md` * Follow kebab-case convention: `weekly-summary.md` * Avoid spaces and special characters * **Commit source files**: Always commit `.md` files * **Commit generated files**: Also commit `.lock.yml` files for transparency ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Editing Workflows](/gh-aw/guides/editing-workflows/) - When to recompile vs edit directly * [Frontmatter](/gh-aw/reference/frontmatter/) - Configuration options for workflows * [Markdown](/gh-aw/reference/markdown/) - The main markdown content of workflows * [Imports](/gh-aw/reference/imports/) - Modularizing workflows with includes * [CLI Commands](/gh-aw/setup/cli/) - CLI commands for workflow management * [MCPs](/gh-aw/guides/mcps/) - Model Context Protocol configuration # CLI Commands > Complete guide to all available CLI commands for managing agentic workflows with the GitHub CLI extension, including installation, compilation, and execution. The `gh aw` CLI extension enables developers to create, manage, and execute AI-powered workflows directly from the command line. It transforms natural language markdown files into GitHub Actions. ## Most Common Commands [Section titled “Most Common Commands”](#most-common-commands) | Command | Description | | --------------------------------- | ------------------------------------------------------- | | [`gh aw init`](#init) | Set up your repository for agentic workflows | | [`gh aw add-wizard`](#add-wizard) | Add workflows with interactive guided setup | | [`gh aw add`](#add) | Add workflows from other repositories (non-interactive) | | [`gh aw new`](#new) | Create a new workflow from scratch | | [`gh aw compile`](#compile) | Convert markdown to GitHub Actions YAML | | [`gh aw list`](#list) | Quick listing of all workflows | | [`gh aw run`](#run) | Execute workflows immediately in GitHub Actions | | [`gh aw status`](#status) | Check current state of all workflows | | [`gh aw logs`](#logs) | Download and analyze workflow logs | | [`gh aw audit`](#audit) | Debug a failed workflow run | ## Installation [Section titled “Installation”](#installation) Install the GitHub CLI extension: ```bash gh extension install github/gh-aw ``` ### Pinning to a Specific Version [Section titled “Pinning to a Specific Version”](#pinning-to-a-specific-version) Pin to specific versions for production environments, team consistency, or avoiding breaking changes: ```bash gh extension install github/gh-aw@v0.1.0 # Pin to release tag gh extension install github/gh-aw@abc123def456 # Pin to commit SHA gh aw version # Check current version # Upgrade pinned version gh extension remove gh-aw gh extension install github/gh-aw@v0.2.0 ``` ### Alternative: Standalone Installer [Section titled “Alternative: Standalone Installer”](#alternative-standalone-installer) Use the standalone installer if extension installation fails (common in Codespaces, restricted networks, or with auth issues): ```bash curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash # Latest curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash -s v0.1.0 # Pinned ``` Installs to `~/.local/share/gh/extensions/gh-aw/gh-aw`. Supports Linux, macOS, FreeBSD, Windows, and Android (Termux). Works behind corporate firewalls using direct release download URLs. ### GitHub Actions Setup Action [Section titled “GitHub Actions Setup Action”](#github-actions-setup-action) Install the CLI in GitHub Actions workflows using the `setup-cli` action with automatic checksum verification and platform detection: ```yaml - name: Install gh-aw CLI uses: github/gh-aw/actions/setup-cli@main with: version: v0.37.18 ``` See the [setup-cli action README](https://github.com/github/gh-aw/blob/main/actions/setup-cli/README.md) for complete documentation. ### GitHub Enterprise Server Support [Section titled “GitHub Enterprise Server Support”](#github-enterprise-server-support) Configure for GitHub Enterprise Server deployments: ```bash export GH_HOST="github.enterprise.com" # Set hostname gh auth login --hostname github.enterprise.com # Authenticate gh aw logs workflow --repo github.enterprise.com/owner/repo # Use with commands ``` For GHE Cloud with data residency (`*.ghe.com`), see the dedicated [Debugging GHE Cloud guide](/gh-aw/troubleshooting/debug-ghe/) for setup and troubleshooting steps. Commands that support `--create-pull-request` (such as `gh aw add`, `gh aw init`, `gh aw update`, and `gh aw upgrade`) automatically detect the enterprise host from the git remote and route PR creation to the correct GHES instance. No extra flags are needed. `gh aw audit` and `gh aw add-wizard` also auto-detect the GHES host from the git remote, so running them inside a GHES repository works without setting `GH_HOST` manually. #### Configuring `gh` CLI on GHES [Section titled “Configuring gh CLI on GHES”](#configuring-gh-cli-on-ghes) The compiled agent job automatically runs `configure_gh_for_ghe.sh` before the agent starts executing. The script detects the GitHub host from the `GITHUB_SERVER_URL` environment variable (set by GitHub Actions on GHES) and configures `gh` to authenticate against it. No configuration is required for the agent to use `gh` CLI commands on your GHES instance. Custom workflow jobs (independent GitHub Actions jobs defined in workflow frontmatter) and the safe-outputs job automatically have `GH_HOST` derived from `GITHUB_SERVER_URL` at the start of each job. On github.com this is a no-op; on GHES/GHEC it ensures all `gh` CLI commands in the job target the correct instance without any manual setup. For custom `steps:` that require additional authentication setup (for example, when running `gh` commands without a `GH_TOKEN` in scope), the helper script is available: ```yaml steps: - name: Configure gh for GHE run: source /opt/gh-aw/actions/configure_gh_for_ghe.sh - name: Fetch repository data env: GH_TOKEN: ${{ github.token }} run: | gh issue list --state open --limit 500 --json number,labels gh pr list --state open --limit 200 --json number,title ``` The script is installed to `/opt/gh-aw/actions/configure_gh_for_ghe.sh` by the setup action. When `GH_TOKEN` is already set in the environment, the script skips `gh auth login` and only exports `GH_HOST` — the token handles authentication. Note Custom steps run outside the agent firewall sandbox and have access to standard GitHub Actions environment variables including `GITHUB_SERVER_URL`, `GITHUB_TOKEN`, and `GH_TOKEN`. ## Global Options [Section titled “Global Options”](#global-options) | Flag | Description | | ----------------- | ------------------------------------------------------------ | | `-h`, `--help` | Show help (`gh aw help [command]` for command-specific help) | | `-v`, `--verbose` | Enable verbose output with debugging details | ### The `--push` Flag [Section titled “The --push Flag”](#the---push-flag) The `run` command supports `--push` to automatically commit and push changes before dispatching the workflow. It stages all changes, commits, and pushes to the remote. Requires a clean working directory. For `init`, `update`, and `upgrade`, use `--create-pull-request` to create a pull request with the changes instead. ## Commands [Section titled “Commands”](#commands) Commands are organized by workflow lifecycle: creating, building, testing, monitoring, and managing workflows. ### Getting Workflows [Section titled “Getting Workflows”](#getting-workflows) #### `init` [Section titled “init”](#init) Initialize repository for agentic workflows. Configures `.gitattributes`, creates the dispatcher agent file (`.github/agents/agentic-workflows.agent.md`), and performs non-interactive setup. Enables MCP server integration by default (use `--no-mcp` to skip). ```bash gh aw init # Initialize repository with defaults (non-interactive) gh aw init --no-mcp # Skip MCP server integration gh aw init --codespaces "" # Configure devcontainer for current repo only gh aw init --codespaces repo1,repo2 # Configure devcontainer for additional repos gh aw init --completions # Install shell completions gh aw init --create-pull-request # Initialize and open a pull request ``` **Options:** `--no-mcp`, `--codespaces`, `--completions`, `--create-pull-request` #### `add-wizard` [Section titled “add-wizard”](#add-wizard) Add a workflow with interactive guided setup. Checks requirements, adds the markdown file, and generates the compiled YAML. Prompts for missing API keys and secrets. For remote workflows, this command follows frontmatter [`redirect`](/gh-aw/reference/frontmatter/#redirect-redirect) declarations before installation. ```bash gh aw add-wizard githubnext/agentics/ci-doctor # Interactive setup gh aw add-wizard https://github.com/org/repo/blob/main/workflows/my-workflow.md gh aw add-wizard https://example.com/workflows/my-workflow.json # Arbitrary URL (JSON workflow) gh aw add-wizard githubnext/agentics/ci-doctor --skip-secret # Skip secret prompt ``` **Options:** `--skip-secret`, `--dir/-d`, `--engine/-e`, `--no-gitattributes`, `--no-stop-after`, `--stop-after` #### `add` [Section titled “add”](#add) Add workflows from The Agentics collection or other repositories to `.github/workflows`. For remote workflows, this command follows frontmatter [`redirect`](/gh-aw/reference/frontmatter/#redirect-redirect) declarations before installation. ```bash gh aw add githubnext/agentics/ci-doctor # Add single workflow gh aw add githubnext/agentics/ci-doctor@v1.0.0 # Add specific version gh aw add githubnext/agentics/ci-doctor --dir shared # Organize in subdirectory gh aw add githubnext/agentics/ci-doctor --create-pull-request # Create PR instead of commit gh aw add https://example.com/workflows/my-workflow.md # Arbitrary HTTPS URL (markdown) gh aw add https://example.com/workflows/my-workflow.json # Arbitrary HTTPS URL (JSON workflow definition) ``` **Options:** `--dir/-d`, `--create-pull-request`, `--no-gitattributes`, `--append`, `--disable-security-scanner`, `--engine/-e`, `--force/-f`, `--name/-n`, `--no-stop-after`, `--stop-after` Repository-level packages can declare an [`aw.yml` manifest](/gh-aw/reference/aw-yml-package-manifest/) at the repository root or in a nested package folder to define installable files, package `README.md`, schema compatibility, and minimum supported CLI versions. `add` and `add-wizard` also accept arbitrary `http(s)://` URLs. The fetched response is dispatched by `Content-Type`: `text/markdown` (and `text/x-markdown`) is installed as a raw gh-aw workflow, and `application/json` (or any `*+json` suffix) is converted to a workflow markdown file before installation. Unknown content types produce an actionable error listing the detected type. For non-GitHub hosts, no include/dispatch-workflow dependency resolution is performed, and no GitHub authentication token is sent to the remote server. ##### JSON Workflow Field Mapping [Section titled “JSON Workflow Field Mapping”](#json-workflow-field-mapping) When importing a JSON workflow definition (for example, a payload from the Copilot automation API), the importer translates JSON fields into gh-aw frontmatter and workflow body: | JSON field | Mapped to | Notes | | ----------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `triggers.interval` | `on:` (fuzzy schedule) | `hourly` → `every 1h`, `daily` → `daily`, `weekly` → `weekly`. A single interval trigger emits the inline shorthand (`on: daily`); the compiler randomizes cron at compile time. | | `triggers.issues` | `on.issues.types` | A `query` filter has no gh-aw equivalent and emits a per-field warning. | | `triggers.workflow_run` | `on.workflow_run` (`workflows`, `types`) | A `conclusions` filter emits a per-field warning. | | `tools` | `tools:` | A 40-entry lookup maps GitHub tool IDs to gh-aw toolsets (`issues`, `pull-requests`, `repos`, etc.). `execute` maps to `bash: "*"` (with a review warning); `web_search` maps to `web-search:`. Built-in read/edit/search tools are silently skipped. Unrecognized tools emit a per-tool warning. | | `permissions` | `permissions:` | Passed through unchanged. | | `prompt` | Workflow body | Used when an `instructions` field is absent. | Unrecognized fields are preserved as commented hints in the generated workflow. #### `new` [Section titled “new”](#new) Create a workflow template in `.github/workflows/`. Opens for editing automatically. ```bash gh aw new # Interactive mode gh aw new my-custom-workflow # Create template (.md extension optional) gh aw new my-workflow --force # Overwrite if exists gh aw new my-workflow --engine claude # Inject engine into frontmatter ``` **Options:** `--force`, `--engine/-e`, `--interactive/-i` When `--engine` is specified, the engine is injected into the generated frontmatter template: ```yaml --- permissions: contents: read engine: claude network: defaults ... ``` #### `secrets` [Section titled “secrets”](#secrets) Manage GitHub Actions secrets and tokens. ##### `secrets set` [Section titled “secrets set”](#secrets-set) Create or update a repository secret (from stdin, flag, or environment variable). ```bash gh aw secrets set MY_SECRET # From stdin (current repo) gh aw secrets set MY_SECRET --repo myorg/myrepo # Specify target repo gh aw secrets set MY_SECRET --value "secret123" # From flag gh aw secrets set MY_SECRET --value-from-env MY_TOKEN # From env var ``` **Options:** `--repo`, `--value`, `--value-from-env`, `--api-url` ##### `secrets bootstrap` [Section titled “secrets bootstrap”](#secrets-bootstrap) Analyze workflows to determine required secrets and interactively prompt for missing ones. Auto-detects engines in use and validates tokens before uploading to the repository. ```bash gh aw secrets bootstrap # Analyze all workflows and prompt for missing secrets gh aw secrets bootstrap --engine copilot # Check only Copilot secrets gh aw secrets bootstrap --non-interactive # Display missing secrets without prompting ``` **Options:** `--engine` (copilot, claude, codex, gemini, crush), `--non-interactive`, `--repo` See [Authentication](/gh-aw/reference/auth/) for details. ### Building [Section titled “Building”](#building) #### `fix` [Section titled “fix”](#fix) Auto-fix deprecated workflow fields using codemods. Runs in dry-run mode by default; use `--write` to apply changes. ```bash gh aw fix # Check all workflows (dry-run) gh aw fix --write # Fix all workflows gh aw fix my-workflow --write # Fix specific workflow gh aw fix --list-codemods # List available codemods ``` **Options:** `--dir/-d`, `--list-codemods`, `--write` Available codemods include: * `expires-integer-to-string` — converts bare integer `expires` values (e.g., `expires: 7`) to the preferred day-string format (e.g., `expires: 7d`) in all `safe-outputs` blocks. * `steps-run-secrets-to-env` — rewrites **all** `${{ ... }}` expressions in step `run:` commands to `$VARNAME` references (or `$env:VARNAME` for PowerShell steps) and adds step-level `env` bindings. Secrets, `env.*`, and `github.token` use stable legacy names; all other expressions receive `EXPR_*` names. Required for strict-mode compliance. * `engine-env-secrets-to-engine-config` — removes secret-bearing entries from `engine.env` that are unsafe under strict mode, preserving required engine credential keys. Run `gh aw fix --list-codemods` to see all available codemods. #### `compile` [Section titled “compile”](#compile) Compile Markdown workflows to GitHub Actions YAML. Remote imports cached in `.github/aw/imports/`. ```bash gh aw compile # Compile all workflows gh aw compile my-workflow # Compile specific workflow gh aw compile --watch # Auto-recompile on changes gh aw compile --validate --strict # Schema + strict mode validation gh aw compile --fix # Run fix before compilation gh aw compile --zizmor # Security scan (warnings) gh aw compile --strict --zizmor # Security scan (fails on findings) gh aw compile --dependabot # Generate dependency manifests gh aw compile --purge # Remove orphaned .lock.yml files ``` If the repository root contains an [`aw.yml` manifest](/gh-aw/reference/aw-yml-package-manifest/), `gh aw compile` validates it before compiling workflows. **Options:** `--action-mode`, `--action-tag`, `--actionlint`, `--actions-repo`, `--allow-action-refs`, `--approve`, `--dependabot`, `--dir/-d`, `--engine/-e`, `--fail-fast`, `--fix`, `--force`, `--force-refresh-action-pins`, `--json/-j`, `--logical-repo`, `--no-check-update`, `--no-emit`, `--poutine`, `--purge`, `--refresh-stop-time`, `--runner-guard`, `--schedule-seed`, `--stats`, `--strict`, `--trial`, `--validate`, `--validate-images`, `--watch/-w`, `--zizmor` **`--approve` flag:** When compiling a workflow that already has a lock file, the compiler enforces *safe update mode* — any newly added secrets or custom actions not present in the previous manifest require explicit approval. Pass `--approve` to accept these changes and regenerate the manifest baseline. On first compile (no existing lock file), enforcement is skipped automatically and `--approve` is not needed. **Error Reporting:** Displays detailed error messages with file paths, line numbers, column positions, and contextual code snippets. **JSON Output (`--json`):** Emits an array of `ValidationResult` objects. Each result includes a `labels` field listing all repository labels referenced in safe-outputs (`create-issue.labels`, `create-discussion.labels`, `create-pull-request.labels`, `add-labels.allowed`). Use `--json --no-emit` to collect label references without writing compiled files. **Dependabot Integration (`--dependabot`):** Generates dependency manifests and `.github/dependabot.yml` by analyzing runtime tools across all workflows. See [Dependabot Support reference](/gh-aw/reference/dependabot/). **Strict Mode (`--strict`):** Enforces security best practices: no write permissions (use [safe-outputs](/gh-aw/reference/safe-outputs/)), explicit `network` config, no wildcard domains, pinned Actions, no deprecated fields. See [Strict Mode reference](/gh-aw/reference/frontmatter/#strict-mode-strict). **Shared Workflows:** Workflows without an `on` field are detected as shared components. Validated with relaxed schema and skip compilation. See [Imports reference](/gh-aw/reference/imports/). #### `validate` [Section titled “validate”](#validate) Validate agentic workflows by running the compiler with all linters enabled, without generating lock files. Equivalent to `gh aw compile --validate --no-emit --zizmor --actionlint --poutine`. ```bash gh aw validate # Validate all workflows gh aw validate my-workflow # Validate specific workflow gh aw validate my-workflow daily # Validate multiple workflows gh aw validate --json # Output results in JSON format gh aw validate --strict # Enforce strict mode validation gh aw validate --fail-fast # Stop at the first error gh aw validate --dir custom/workflows # Validate from custom directory gh aw validate --engine copilot # Override AI engine ``` **Options:** `--allow-action-refs`, `--dir/-d`, `--engine/-e`, `--fail-fast`, `--json/-j`, `--no-check-update`, `--stats`, `--strict`, `--validate-images` All linters (`zizmor`, `actionlint`, `poutine`), `--validate`, and `--no-emit` are always-on defaults and cannot be disabled. Accepts the same workflow ID format as `compile`. #### `lint` [Section titled “lint”](#lint) Lint existing `.lock.yml` workflow files from disk with actionlint only. This command does not recompile Markdown workflows, and skips `zizmor`/`poutine`. ```bash gh aw lint # Lint all .github/workflows/*.lock.yml gh aw lint .github/workflows/foo.lock.yml # Lint a specific lock file gh aw lint --dir .github/workflows # Lint all lock files in a directory gh aw lint --shellcheck --pyflakes # Enable actionlint script integrations ``` **Options:** `--dir/-d`, `--shellcheck`, `--pyflakes` By default, shellcheck and pyflakes integrations are disabled to reduce noise for generated `run:` scripts. Built-in actionlint ignore patterns cover gh-aw-specific extensions such as `job.workflow_*` context properties and the `copilot-requests` permission scope. ### Testing [Section titled “Testing”](#testing) #### `trial` [Section titled “trial”](#trial) Test workflows in temporary private repositories (default) or run directly in specified repository (`--host-repo`). Results saved to `trials/`. ```bash gh aw trial githubnext/agentics/ci-doctor # Test remote workflow gh aw trial ./workflow.md --logical-repo owner/repo # Act as different repo gh aw trial ./workflow.md --host-repo owner/repo # Run directly in repository gh aw trial ./workflow.md --dry-run # Preview without executing ``` **Options:** `-e/--engine`, `--repeat`, `--delete-host-repo-after`, `--logical-repo/-l`, `--clone-repo`, `--trigger-context`, `--host-repo`, `--dry-run`, `--append`, `--auto-merge-prs`, `--disable-security-scanner`, `--force-delete-host-repo-before`, `--timeout`, `--yes/-y` **Secret Handling:** API keys required for the selected engine are automatically checked. If missing from the target repository, they are prompted for interactively and uploaded. #### `run` [Section titled “run”](#run) Execute workflows immediately in GitHub Actions. Displays workflow URL for tracking. ```bash gh aw run workflow # Run workflow gh aw run workflow1 workflow2 # Run multiple workflows gh aw run workflow --repeat 3 # Run 4 times total (1 initial + 3 repeats) gh aw run workflow --push # Auto-commit, push, and dispatch workflow gh aw run workflow --push --ref main # Push to specific branch gh aw run workflow --json # Output triggered workflow results as JSON ``` **Options:** `--repeat`, `--push` (see [—push flag](#the---push-flag)), `--ref`, `--enable-if-needed`, `--json/-j`, `--auto-merge-prs`, `--dry-run`, `--engine/-e`, `--raw-field/-F`, `--repo/-r`, `--approve` When `--json` is set, a JSON array of triggered workflow results is written to stdout. When `--push` is used, automatically recompiles outdated `.lock.yml` files, stages all transitive imports, and triggers workflow run after successful push. Without `--push`, warnings are displayed for missing or outdated lock files. Note Codespaces Permissions Requires `workflows:write` permission. In Codespaces, either configure custom permissions in `devcontainer.json` ([docs](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-repository-access-for-your-codespaces)) or authenticate manually: `unset GH_TOKEN && gh auth login` ### Monitoring [Section titled “Monitoring”](#monitoring) #### `list` [Section titled “list”](#list) List workflows with basic information (name, engine, compilation status) without checking GitHub Actions state. ```bash gh aw list # List all workflows gh aw list ci- # Filter by pattern (case-insensitive) gh aw list --json # Output in JSON format gh aw list --label automation # Filter by label gh aw list --dir custom/workflows # List from a local custom directory gh aw list --repo owner/repo --path .github/workflows # List from a remote repository ``` **Options:** `--json`, `--label`, `--dir/-d`, `--path`, `--repo` Two flags control the workflow directory location, with different purposes: * `--dir` (`-d`): overrides the **local** workflow directory. Applies only when `--repo` is not set. * `--path`: specifies the workflow directory path in a **remote** repository. Use together with `--repo`. Fast enumeration without GitHub API queries. For detailed status including enabled/disabled state and run information, use `status` instead. #### `status` [Section titled “status”](#status) List workflows with state, enabled/disabled status, schedules, and labels. With `--ref`, includes latest run status. ```bash gh aw status # All workflows gh aw status --ref main # With run info for main branch gh aw status --label automation # Filter by label gh aw status --repo owner/other-repo # Check different repository ``` **Options:** `--ref`, `--label`, `--json`, `--repo` #### `logs` [Section titled “logs”](#logs) Download and analyze logs with tool usage, network patterns, errors, warnings. Results cached for 10-100x speedup on subsequent runs. ```bash gh aw logs workflow # Download logs for workflow gh aw logs -c 10 --start-date -1w # Filter by count and date gh aw logs --ref main --parse --json # With markdown/JSON output for branch ``` With `--json`, the output also includes deterministic lineage data under `.episodes[]` and `.edges[]`. Use these fields to group orchestrated runs into execution episodes instead of reconstructing relationships from `.runs[]` alone. **Workflow name matching**: The logs command accepts both workflow IDs (kebab-case filename without `.md`, e.g., `ci-failure-doctor`) and display names (from frontmatter, e.g., `CI Failure Doctor`). Matching is case-insensitive for convenience: ```bash gh aw logs ci-failure-doctor # Workflow ID gh aw logs CI-FAILURE-DOCTOR # Case-insensitive ID gh aw logs "CI Failure Doctor" # Display name gh aw logs "ci failure doctor" # Case-insensitive display name ``` **`--after` flag (cache cleanup):** Deletes cached run folders in the output directory whose run creation date is older than the specified cutoff. Accepts the same date/time delta formats as `--start-date` and `--end-date` (e.g. `-1d`, `-1w`, `-1mo`) as well as absolute dates (`YYYY-MM-DD`). Cleanup runs before the download step to free disk space first; failures are non-fatal and logged as warnings. ```bash gh aw logs --after -1w # Clean folders older than 1 week, then download latest runs gh aw logs --after -30d # Clean folders older than 30 days gh aw logs --after 2024-01-01 # Clean folders from before a specific date gh aw logs my-workflow --after -1mo -c 20 # Clean up, then download 20 runs of a specific workflow ``` Only directories matching the `run-{ID}` naming pattern inside the output directory are considered. The run’s creation timestamp is read from `run_summary.json` inside each folder; if that file is absent (e.g., incomplete download), the directory’s modification time is used as a fallback. **`--train` flag:** Trains log template weights from the downloaded runs and writes `drain3_weights.json` to the logs output directory. The trained weights improve anomaly detection accuracy in subsequent `gh aw audit` and `gh aw logs` runs. To embed weights into the binary as defaults, copy the file to `pkg/agentdrain/data/default_weights.json` and rebuild. ```bash gh aw logs --train # Train on last 10 runs gh aw logs my-workflow --train -c 50 # Train on up to 50 runs of a specific workflow ``` **`--stdin` flag:** Reads run IDs or URLs from stdin (one per line) instead of discovering runs from the GitHub API. Mutually exclusive with the workflow-name positional argument. Date, count, and workflow-name filters are ignored when `--stdin` is set; content filters (`--engine`, `--firewall`, `--safe-output`, etc.) still apply. Blank lines and `#`-prefixed comment lines are ignored. Bare numeric IDs require `--repo owner/repo` because they carry no embedded repo context. Full run URLs are self-contained and do not require `--repo`. ```bash cat run-ids.txt | gh aw logs --stdin echo "1234567890" | gh aw logs --stdin --engine claude cat run-ids.txt | gh aw logs --stdin --repo owner/repo # required for bare numeric IDs ``` **Options:** `--after`, `--after-run-id`, `--artifacts`, `--before-run-id`, `--count/-c`, `--end-date`, `--engine/-e`, `--filtered-integrity`, `--firewall`, `--format`, `--json/-j`, `--last`, `--no-firewall`, `--no-staged`, `--output/-o`, `--parse`, `--ref`, `--repo/-r`, `--safe-output`, `--start-date`, `--stdin`, `--summary-file`, `--timeout`, `--tool-graph`, `--train` #### `audit` [Section titled “audit”](#audit) Analyze workflow runs with detailed reports. The `audit` command has three modes: a single-run audit (default), a cross-run diff, and a cross-run security report. ##### `audit ` [Section titled “audit \”](#audit-run-id) Analyze a single run with a rich multi-section report. Accepts run IDs, workflow run URLs, job URLs, and step-level URLs. Auto-detects Copilot coding agent runs for specialized parsing. Job URLs automatically extract specific job logs; step URLs extract specific steps; without step, extracts first failing step. ```bash gh aw audit 12345678 # By run ID gh aw audit https://github.com/owner/repo/actions/runs/123 # By workflow run URL gh aw audit https://github.com/owner/repo/actions/runs/123/job/456 # By job URL (extracts first failing step) gh aw audit https://github.com/owner/repo/actions/runs/123/job/456#step:7:1 # By step URL (extracts specific step) gh aw audit 12345678 --parse # Parse logs to markdown gh aw audit 12345678 --repo owner/repo # Specify repository for bare run ID ``` **`--stdin` flag:** Reads run IDs or URLs from stdin (one per line), bypassing the need to pass positional arguments. Mutually exclusive with positional run-ID arguments. Blank lines and `#`-prefixed lines are ignored. Bare numeric IDs require `--repo owner/repo`; full URLs carry their own repo context. ```bash echo "1234567890" | gh aw audit --stdin echo -e "1234567890\n9876543210" | gh aw audit --stdin # diff mode: first is base cat run-ids.txt | gh aw audit --stdin --repo owner/repo ``` **Options:** `--parse`, `--json`, `--repo/-r`, `--stdin` The `--repo` flag accepts `owner/repo` format and is required when passing a bare numeric run ID without a full URL, allowing the command to locate the correct repository. Logs are saved to `logs/run-{id}/` with filenames indicating the extraction level. Pre-agent failures (integrity filtering, missing secrets, binary install) surface the actual error in `failure_analysis.error_summary`. Invalid run IDs return a human-readable error. **Report sections:** | Section | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------ | | **Overview** | Run status, duration, trigger event, repository | | **Engine Configuration** | Engine ID, model, CLI version, firewall version, MCP servers configured | | **Prompt Analysis** | Prompt size and source file | | **Session & Agent Performance** | Wall time, turn count, average turn duration, tokens per minute, timeout detection, agent active ratio | | **MCP Server Health** | Per-server request counts, error rates, average latency, health status, and slowest tool calls | | **Safe Output Summary** | Total safe output items broken down by type (comments, PRs, issues, etc.) | | **Metrics** | Tool usage, token consumption, cost | | **MCP Failures** | Failed MCP tool calls with error details | | **Firewall Analysis** | Network requests blocked or allowed by the firewall | | **Jobs** | Status of each GitHub Actions job in the run | | **Artifacts** | Downloaded artifacts and their contents | ##### Multi-run diff mode [Section titled “Multi-run diff mode”](#multi-run-diff-mode) Compare behavior between two or more workflow runs to detect policy regressions, new unauthorized domains, behavioral drift, and changes in MCP tool usage or run metrics. Pass multiple run IDs directly to `audit` — the first is the base, the rest are comparisons: ```bash gh aw audit 12345 12346 # Compare two runs gh aw audit 12345 12346 12347 12348 # Compare base against 3 runs gh aw audit 12345 12346 --format markdown # Markdown output for PR comments gh aw audit 12345 12346 --json # JSON for CI integration gh aw audit 12345 12346 --repo owner/repo # Specify repository ``` The diff output shows: new or removed network domains, status changes (allowed denied), volume changes (>100% threshold), MCP tool invocation changes, run metric comparisons (token usage, duration, turns), tokens-per-turn changes, and per-tool and per-bash-command call breakdowns. **Options:** `--format` (pretty, markdown; default: pretty), `--json`, `--repo/-r` Cross-run security reports (`audit report` removed in v0.66.1) Cross-run security and performance reports are now generated by `gh aw logs --format`. Use `--count` or `--last` to control the number of runs analyzed. ```bash gh aw logs --format markdown # Report on recent runs (default: last 10) gh aw logs agent-task --format markdown --count 10 # Last 10 runs of a workflow gh aw logs agent-task --format markdown --last 5 --json # JSON output gh aw logs --format pretty # Console-formatted output gh aw logs --format markdown --repo owner/repo --count 10 # Specify repository ``` See [Audit Commands](/gh-aw/reference/audit/) for the full reference. #### `outcomes` [Section titled “outcomes”](#outcomes) Check what happened to a workflow run’s safe outputs (accepted, rejected, ignored, or pending). ```bash gh aw outcomes 1234567890 # Check outcomes for a specific run gh aw outcomes 1234567890 --json # JSON output gh aw outcomes 1234567890 --repo owner/repo # Specify repository gh aw outcomes 1234567890 --outcomes-dir ./otlp # Write outcome JSONL for OTLP export ``` **Options:** `--json/-j`, `--repo/-r`, `--output/-o`, `--outcomes-dir` #### `health` [Section titled “health”](#health) Display workflow health metrics and success rates. ```bash gh aw health # Summary of all workflows (last 7 days) gh aw health issue-monster # Detailed metrics for specific workflow gh aw health --days 30 # Summary for last 30 days gh aw health --threshold 90 # Warn if below 90% success rate gh aw health --json # Output in JSON format gh aw health issue-monster --days 90 # 90-day metrics for workflow ``` **Options:** `--days`, `--threshold`, `--repo`, `--json` Shows success/failure rates, trend indicators (↑ improving, → stable, ↓ degrading), execution duration, token usage, costs, and warnings when success rate drops below threshold. #### `checks` [Section titled “checks”](#checks) Classify CI check state for a pull request and emit a normalized result. ```bash gh aw checks 42 # Classify checks for PR #42 gh aw checks 42 --repo owner/repo # Specify repository gh aw checks 42 --json # Output in JSON format ``` **Options:** `--repo/-r`, `--json/-j` Maps PR check rollups to one of the following normalized states: `success`, `failed`, `pending`, `no_checks`, `policy_blocked`. JSON output includes two state fields: `state` (aggregate across all checks) and `required_state` (derived from required checks only, ignoring optional third-party statuses like deployment integrations). ### Management [Section titled “Management”](#management) #### `enable` [Section titled “enable”](#enable) Enable one or more workflows by ID, or all workflows if no IDs provided. ```bash gh aw enable # Enable all workflows gh aw enable ci-doctor # Enable specific workflow gh aw enable ci-doctor daily # Enable multiple workflows gh aw enable ci-doctor --repo owner/repo # Enable in specific repository ``` **Options:** `--repo` #### `disable` [Section titled “disable”](#disable) Disable one or more workflows and cancel any in-progress runs. ```bash gh aw disable # Disable all workflows gh aw disable ci-doctor # Disable specific workflow gh aw disable ci-doctor daily # Disable multiple workflows gh aw disable ci-doctor --repo owner/repo # Disable in specific repository ``` **Options:** `--repo` #### `remove` [Section titled “remove”](#remove) Remove workflows (both `.md` and `.lock.yml`). Accepts a workflow ID (basename without `.md`) or prefix pattern. By default, also removes orphaned include files no longer referenced by any workflow. ```bash gh aw remove my-workflow # Remove specific workflow gh aw remove test- # Remove all workflows starting with 'test-' gh aw remove my-workflow --keep-orphans # Remove but keep orphaned include files ``` **Options:** `--dir/-d`, `--keep-orphans` #### `update` [Section titled “update”](#update) Update workflows based on `source` field (`owner/repo/path@ref`). By default, performs a 3-way merge to preserve local changes; use `--no-merge` to override with upstream. Semantic versions update within same major version. By default, `update` also force-updates all GitHub Actions referenced in your workflows (both in `actions-lock.json` and workflow files) to their latest major version. Use `--disable-release-bump` to restrict force-updates to core `actions/*` actions only. If no workflows in the repository contain a `source` field, the command exits gracefully with an informational message rather than an error. This is expected behavior for repositories that have not yet added updatable workflows. ```bash gh aw update # Update all with source field gh aw update ci-doctor # Update specific workflow (3-way merge) gh aw update ci-doctor --no-merge # Override local changes with upstream gh aw update ci-doctor --major --force # Allow major version updates gh aw update --disable-release-bump # Update workflows; only force-update core actions/* gh aw update --repo owner/repo # Update workflows in another repository gh aw update --create-pull-request # Update and open a pull request ``` **Options:** `--dir`, `--no-merge`, `--major`, `--force`, `--engine`, `--no-stop-after`, `--stop-after`, `--disable-release-bump`, `--create-pull-request`, `--no-compile`, `--no-redirect`, `--cool-down`, `--repo/-r` The `--no-redirect` flag causes `update` to fail when the source workflow has a [`redirect`](/gh-aw/reference/frontmatter/) field, rather than following the redirect to its new location. Use this when you want explicit control over redirect handling. The `--repo/-r` flag runs the update against a different repository. The target repository is checked out in an isolated shallow clone under `.github/aw/updates/`. When combined with `--create-pull-request`, the resulting PR is opened against the target repository instead of the current one. #### `deploy` [Section titled “deploy”](#deploy) Roll out one or more workflows to a target repository through a pull request. The command clones the target repository into an isolated shallow checkout, refreshes existing sourced workflows, adds the requested workflows, recompiles lock files with purge enabled, and opens a pull request against the target repository. ```bash gh aw deploy githubnext/agentics/ci-doctor --repo owner/repo gh aw deploy githubnext/agentics/repo-assist githubnext/agentics/ci-doctor --repo owner/repo --force gh aw deploy ./my-workflow.md --repo owner/repo ``` **Options:** `--repo/-r` (required), `--name/-n`, `--engine/-e`, `--force/-f`, `--append`, `--no-gitattributes`, `--dir/-d`, `--no-stop-after`, `--stop-after`, `--disable-security-scanner`, `--cool-down` The `--repo` flag is required and accepts `owner/repo` form. The target repository is checked out under `.github/aw/updates/` inside the current working tree, so the command must be run from inside a git repository. Workflows already present in the target with a `source` frontmatter field are refreshed through the update phase and skipped by the add phase to avoid duplicate-add errors. The pull request commit title is `chore: deploy agentic workflows`. The default `--cool-down` value is `7d`. #### `upgrade` [Section titled “upgrade”](#upgrade) Upgrade repository with latest agent files and apply codemods to all workflows. ```bash gh aw upgrade # Upgrade repository agent files and all workflows gh aw upgrade --no-fix # Update agent files only (skip codemods, actions, and compilation) gh aw upgrade --create-pull-request # Upgrade and open a pull request gh aw upgrade --audit # Run dependency health audit gh aw upgrade --audit --json # Dependency audit in JSON format ``` **Options:** `--dir/-d`, `--no-fix`, `--no-actions`, `--no-compile`, `--create-pull-request`, `--audit`, `--json/-j`, `--approve` ### Advanced [Section titled “Advanced”](#advanced) #### `mcp` [Section titled “mcp”](#mcp) Manage MCP (Model Context Protocol) servers in workflows. `mcp inspect` auto-detects mcp-scripts. ```bash gh aw mcp list workflow # List servers for workflow gh aw mcp list-tools # List tools for server gh aw mcp inspect workflow # Inspect and test servers gh aw mcp add # Add MCP tool to workflow ``` See [MCPs Guide](/gh-aw/guides/mcps/). #### `pr transfer` [Section titled “pr transfer”](#pr-transfer) Transfer pull request to another repository, preserving changes, title, and description. ```bash gh aw pr transfer --repo target-owner/target-repo ``` #### `mcp-server` [Section titled “mcp-server”](#mcp-server) Run MCP server exposing gh-aw commands as tools. Spawns subprocesses to isolate GitHub tokens. ```bash gh aw mcp-server # stdio transport gh aw mcp-server --port 8080 # HTTP server with SSE gh aw mcp-server --validate-actor # Enable actor validation ``` **Options:** `--port` (HTTP server port), `--cmd` (custom subprocess command), `--validate-actor` (enforce actor validation for logs and audit tools) **Available Tools:** status, compile, logs, audit, checks, mcp-inspect, add, update, fix When `--validate-actor` is enabled, logs and audit tools require write+ repository access via GitHub API (permissions cached for 1 hour). See [MCP Server Guide](/gh-aw/reference/gh-aw-as-mcp-server/). #### `domains` [Section titled “domains”](#domains) List network domains configured in agentic workflows. ```bash gh aw domains # List all workflows with domain counts gh aw domains weekly-research # List domains for specific workflow gh aw domains --json # Output summary in JSON format gh aw domains weekly-research --json # Output workflow domains in JSON format ``` **Options:** `--json/-j` When no workflow is specified, lists all workflows with a summary of allowed and blocked domain counts. When a workflow is specified, lists all effective allowed and blocked domains including domains expanded from ecosystem identifiers (e.g. `node`, `python`, `github`) and engine defaults. ### Utility Commands [Section titled “Utility Commands”](#utility-commands) #### `version` [Section titled “version”](#version) Show gh-aw version and product information. ```bash gh aw version ``` #### `completion` [Section titled “completion”](#completion) Generate and manage shell completion scripts for tab completion. ```bash gh aw completion install # Auto-detect and install gh aw completion uninstall # Remove completions gh aw completion bash # Generate bash script gh aw completion zsh # Generate zsh script gh aw completion fish # Generate fish script gh aw completion powershell # Generate powershell script ``` **Subcommands:** `install`, `uninstall`, `bash`, `zsh`, `fish`, `powershell`. See [Shell Completions](#shell-completions). #### `project` [Section titled “project”](#project) Create and manage GitHub Projects V2 boards. ##### `project new` [Section titled “project new”](#project-new) Create a new GitHub Project V2 owned by a user or organization with optional repository linking. ```bash gh aw project new "My Project" --owner @me # Create user project gh aw project new "Team Board" --owner myorg # Create org project gh aw project new "Bugs" --owner myorg --link myorg/myrepo # Create and link to repo gh aw project new "Project Q1" --owner myorg --with-project-setup # Create with standard views and fields ``` **Options:** * `--owner` (required): Project owner - use `@me` for current user or specify organization name * `--link`: Repository to link project to (format: `owner/repo`) * `--with-project-setup`: Create standard project views and custom fields **Token Requirements:** Caution The default `GITHUB_TOKEN` cannot create projects. Use a Personal Access Token (PAT) with Projects permissions: * **Classic PAT**: `project` scope (user projects) or `project` + `repo` (org projects) * **Fine-grained PAT**: Organization permissions → Projects: Read & Write Configure via `GH_AW_PROJECT_GITHUB_TOKEN` environment variable or `gh auth login`. See [Authentication](/gh-aw/reference/auth/). #### `hash-frontmatter` [Section titled “hash-frontmatter”](#hash-frontmatter) Compute a deterministic SHA-256 hash of workflow frontmatter for detecting configuration changes. ```bash gh aw hash-frontmatter my-workflow.md gh aw hash-frontmatter .github/workflows/audit-workflows.md ``` Includes all frontmatter fields, imported workflow frontmatter (BFS traversal), template expressions containing `env.` or `vars.`, and version information (gh-aw, awf, agents). ## Shell Completions [Section titled “Shell Completions”](#shell-completions) Enable tab completion for workflow names, engines, and paths. After running `gh aw completion install`, restart your shell or source your configuration file. ### Manual Installation [Section titled “Manual Installation”](#manual-installation) ```bash # Bash gh aw completion bash > ~/.bash_completion.d/gh-aw && source ~/.bash_completion.d/gh-aw # Zsh gh aw completion zsh > "${fpath[1]}/_gh-aw" && compinit # Fish gh aw completion fish > ~/.config/fish/completions/gh-aw.fish # PowerShell gh aw completion powershell | Out-String | Invoke-Expression ``` ## Debug Logging [Section titled “Debug Logging”](#debug-logging) Enable detailed debugging with namespace, message, and time diffs. ```bash DEBUG=* gh aw compile # All logs DEBUG=cli:* gh aw compile # CLI only DEBUG=*,-tests gh aw compile # All except tests ``` Use `--verbose` flag for user-facing details. ## Smart Features [Section titled “Smart Features”](#smart-features) ### Fuzzy Workflow Name Matching [Section titled “Fuzzy Workflow Name Matching”](#fuzzy-workflow-name-matching) Auto-suggests similar workflow names on typos using Levenshtein distance. ```bash gh aw compile audti-workflows # ✗ workflow file not found # Did you mean: audit-workflows? ``` Works with: compile, enable, disable, logs, mcp commands. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) | Issue | Solution | | ---------------------------------- | ------------------------------------------------------------------------ | | `command not found: gh` | Install from [cli.github.com](https://cli.github.com/) | | `extension not found: aw` | Run `gh extension install github/gh-aw` | | Compilation fails with YAML errors | Check indentation, colons, and array syntax in frontmatter | | Workflow not found | Check typo suggestions or run `gh aw status` to list available workflows | | Permission denied | Check file permissions or repository access | | Trial creation fails | Check GitHub rate limits and authentication | See [Common Issues](/gh-aw/troubleshooting/common-issues/) and [Error Reference](/gh-aw/troubleshooting/errors/) for detailed troubleshooting. ## Related Documentation [Section titled “Related Documentation”](#related-documentation) * [Quick Start](/gh-aw/setup/quick-start/) - Get your first workflow running * [Frontmatter](/gh-aw/reference/frontmatter/) - Configuration options * [Reusing Workflows](/gh-aw/guides/packaging-imports/) - Adding and updating workflows * [Security Guide](/gh-aw/introduction/architecture/) - Security best practices * [MCP Server Guide](/gh-aw/reference/gh-aw-as-mcp-server/) - MCP server configuration * [Agent Factory](/gh-aw/agent-factory-status/) - Agent factory status # Creating Agentic Workflows > Create agentic workflows using AI agents like Copilot, Claude, or Codex from GitHub's web interface, terminal, or VS Code. Author powerful automation workflows in natural language with interactive guidance and automatic best practices. **Estimated time: 5-15 minutes** depending on complexity You can author new agentic workflows using a coding agent or other AI chat system, under your guidance. For interactive coding agents, this can be a conversation about what you want the workflow to do, with the agent asking clarifying questions and generating the workflow for you. In this guide, we show you how to create agentic workflows in the GitHub web interface (github.com), your coding agent, or in VS Code Agent Mode. ## GitHub Web Interface [Section titled “GitHub Web Interface”](#github-web-interface) **If you have access to GitHub Copilot**, you can create and edit Agentic Workflows directly from the Web Interface. This technique is slow and non-interactive but it is incredibly useful to turn an idea to reality in a couple minutes. For a more fine grained, interactive experience we recommend using a coding agent (see next section). Use one of these prompts in your repository. * Issue Triage ```markdown Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md The purpose of the workflow is to triage new issues: label them by type and priority, identify duplicates, ask clarifying questions when the description is unclear, and assign them to the right team members. ``` * Activity Report ```markdown Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md The purpose of the workflow is a daily report on recent activity in the repository, delivered as an issue. The report should summarize new issues, pull requests merged, and any open blockers. ``` * Documentation Updater ```markdown Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md The purpose of the workflow is to run daily and keep the repository documentation up to date: identify doc files that are out of sync with recent code changes and open a pull request with the necessary updates. ``` * AGENTS.md Maintainer ```markdown Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md The purpose of the workflow is to run weekly and maintain the AGENTS.md file: review merged pull requests and updated source files since the last run, then open a pull request that keeps AGENTS.md accurate and current. ``` Your browser doesn't support HTML5 video. [Download Create an agentic workflow from the GitHub web interface](/gh-aw/videos/create-workflow-on-github.mp4). Create an agentic workflow from the GitHub web interface Tip On the first run in a new repository, the workflow will surely fail because the secrets are not configured. The agentic workflow should detect the missing tokens and create an issue with instructions on how to configure them. ## VSCode/Claude/Codex/Copilot [Section titled “VSCode/Claude/Codex/Copilot”](#vscodeclaudecodexcopilot) Follow these steps to create an agentic workflow using VSCode or your coding CLI agent. 1. **Start your coding agent**. Choose your preferred coding agent and start it in the context of your repository. For example, you can: * Start [VSCode Agent Mode](https://code.visualstudio.com/docs/copilot/agents/overview) * Start your CLI coding agent in your repository 2. **Create an agentic workflow**. Enter the following prompt into your coding agent: ```text Create a workflow for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/create.md The purpose of the workflow is a daily report on recent activity in the repository, delivered as an issue. ``` You can replace the last line with your desired workflow purpose and as much additional detail, context, goals, guardrails and purpose as you like. This will create a new [workflow markdown file](/gh-aw/reference/workflow-structure/) in `.github/workflows/` with the appropriate configuration. Some agents will create a pull request to add these changes to your repository. 3. **Setup required secrets**. If you haven’t done so already, [set up your repository secrets](/gh-aw/reference/engines/) for your chosen engine (Copilot, Claude, or Codex). If not using Copilot, also adjust the `engine:` field in your workflow’s [frontmatter](/gh-aw/reference/frontmatter/). After merging the pull request, you can run the workflow to see it in action. Either: * trigger runs manually from the Actions tab in GitHub.com, or * use [the `gh aw run` command](/gh-aw/setup/cli/#run) to trigger runs from your terminal. ## Initialize the Repository [Section titled “Initialize the Repository”](#initialize-the-repository) Running `gh aw init` is **required** to enable the authoring experience in the GitHub code agent. This step configures your repository so that you can create and modify agentic workflows directly from [github.com](https://github.com) or the GitHub mobile app, using the Copilot coding agent. ```bash gh aw init ``` Alternatively, run this prompt in your coding agent: ```text Initialize this repository for GitHub Agentic Workflows using https://raw.githubusercontent.com/github/gh-aw/main/install.md ``` This command: * Creates a **dispatcher agent** at `.github/agents/agentic-workflows.agent.md`, which registers the `agentic-workflows` custom agent in GitHub Copilot and enables workflow authoring via `/agent agentic-workflows` in Copilot Chat on github.com and the GitHub mobile app. * Sets up **MCP server integration** so that Copilot has access to gh-aw tools when creating or editing workflows. * Updates `.gitattributes` to mark generated `.lock.yml` files correctly. * Configures **VS Code settings** for the best local authoring experience. Once initialized, you and your team can create and edit workflows by opening a Copilot Chat session on github.com or the GitHub app and running: ```text /agent agentic-workflows Create a new workflow that... ``` ## Manual Editing [Section titled “Manual Editing”](#manual-editing) If you prefer to create workflows manually, you can 1. Create the workflow file in `.github/workflows/.md` 2. Install the [GitHub CLI](https://cli.github.com/) and the GitHub Agentic Workflows extension: ```bash gh extension install github/gh-aw ``` 3. Compile the workflow markdown into a YAML workflow file using: ```bash gh aw compile ``` This will generate a workflow YAML lock file `.github/workflows/.lock.yml` based on the content of your markdown file. 4. Add, commit and push the workflow file and its lock file to your repository. ```bash git add .github/workflows/.md git add .github/workflows/.lock.yml git commit -m "Add workflow" git push ``` 5. If you haven’t done so already, [set up your repository secrets](/gh-aw/reference/engines/) for the coding agent your workflow will be using. You can now trigger runs of the workflow either from the Actions tab in GitHub.com or using the `gh aw run` command from your terminal. ## Adding an Existing Workflow [Section titled “Adding an Existing Workflow”](#adding-an-existing-workflow) To add a workflow from another repository, see [Reusing Workflows](/gh-aw/guides/packaging-imports/#adding-workflows). ## Learn More About Agentic Authoring [Section titled “Learn More About Agentic Authoring”](#learn-more-about-agentic-authoring) The [Agentic Authoring](/gh-aw/guides/agentic-authoring/) contains additional techniques to leverage agents to help build better agentic workflows. # Quick Start > Get your first agentic workflow running in minutes. Install the extension, add a sample workflow, set up secrets, and run your first AI-powered automation. ## Adding an Automated Daily Status Workflow to Your Repo [Section titled “Adding an Automated Daily Status Workflow to Your Repo”](#adding-an-automated-daily-status-workflow-to-your-repo) **Estimated time: 10 minutes** In this guide you will add an existing, pre-baked workflow to an existing GitHub repository where you are a maintainer - the automated [**Daily Repo Status Report**](https://github.com/githubnext/agentics/blob/main/workflows/daily-repo-status.md?plain=1), running in GitHub Actions. Your browser doesn't support HTML5 video. [Download Install the extension, add a workflow, and trigger a run from the CLI](/gh-aw/videos/install-and-add-workflow-in-cli.mp4). Install the extension, add a workflow, and trigger a run from the CLI The aim here is to become familiar with **automated AI**: to install something that will run **automatically**, **recurringly**, in the context of your repository. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) Before installing, ensure you have: * **AI Account** - [GitHub Copilot](https://github.com/features/copilot), [Anthropic Claude](https://www.anthropic.com/), [OpenAI Codex](https://openai.com/api/), or [Google Gemini](https://ai.google.dev/gemini-api) * **GitHub Repository** - A repository where you have write access * **GitHub Actions** enabled - Check in [Settings → Actions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository) * **GitHub CLI** (`gh`) v2.0.0+ - [Install here](https://cli.github.com). Check version: `gh --version` * **Logged in to GitHub CLI** - Verify with `gh auth status` and run `gh auth login --scopes repo,workflow` if needed * **Operating System**: Linux, macOS, or Windows with WSL ### Step 1 - Install the extension [Section titled “Step 1 - Install the extension”](#step-1---install-the-extension) Install the GitHub Agentic Workflows extension: ```text gh extension install github/gh-aw ``` Tip If you are encountering authentication issues, use this script instead: ```text curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash ``` or login interactively: ```text gh auth login ``` ### Step 2 - Add the sample workflow and trigger a run [Section titled “Step 2 - Add the sample workflow and trigger a run”](#step-2---add-the-sample-workflow-and-trigger-a-run) From your repository root run: ```text gh aw add-wizard githubnext/agentics/daily-repo-status ``` `add-wizard` accepts workflow references in `//` format. In this example, `githubnext/agentics/daily-repo-status` points to the `daily-repo-status.md` workflow in the `githubnext/agentics` repository. This will take you through an interactive process to: 1. **Check prerequisites** - Verify repository permissions. 2. **Select an AI Engine** - Choose between Copilot, Claude, Codex, or Gemini. 3. **Set up the required secret** - [`COPILOT_GITHUB_TOKEN`](/gh-aw/reference/auth/#copilot_github_token) (a separate GitHub token with Copilot access — distinct from the default `GITHUB_TOKEN`), [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key), [`OPENAI_API_KEY`](/gh-aw/reference/auth/#openai_api_key), or [`GEMINI_API_KEY`](/gh-aw/reference/auth/#gemini_api_key). See [Authentication](/gh-aw/reference/auth/) for setup instructions. 4. **Add the workflow** - Adds the workflow file (`.md`) and its generated GitHub Actions lock file (`.lock.yml`) to `.github/workflows/`. 5. **Optionally trigger an initial run** - Starts the workflow immediately. Note **Setting up `COPILOT_GITHUB_TOKEN`?** 1. [Create a fine-grained PAT](https://github.com/settings/personal-access-tokens/new) under your user account. 2. Under **Permissions → Account permissions**, set **Copilot Requests** to **Read**, then generate the token. 3. Add it as a repository secret from your repository root with `gh secret set COPILOT_GITHUB_TOKEN < /path/to/token.txt`, or use the GitHub UI. See [Authentication](/gh-aw/reference/auth/#copilot_github_token) for more detail. Note **Setting up `ANTHROPIC_API_KEY`?** 1. Create an API key in [Anthropic Console](https://console.anthropic.com/settings/keys). 2. Add it as a repository secret from your repository root with `gh secret set ANTHROPIC_API_KEY < /path/to/key.txt`, or use the GitHub UI. See [Authentication](/gh-aw/reference/auth/#anthropic_api_key) for more detail. Tip **Having trouble?** Check your [repository secrets](/gh-aw/reference/auth/), see the [FAQ](/gh-aw/reference/faq/) and [Common Issues](/gh-aw/troubleshooting/common-issues/). ### Step 3 - Wait for the workflow to complete [Section titled “Step 3 - Wait for the workflow to complete”](#step-3---wait-for-the-workflow-to-complete) An automated workflow run can take 2-3 minutes. Once your initial run is complete, a new issue will be created in your repository with a “Daily Repo Report”. The report will be automatically generated and will analyze: * Recent repository activity (issues, PRs, discussions, releases, code changes) * Progress tracking, goal reminders and highlights * Project status and recommendations * Actionable next steps for maintainers The report will look something like this:  ### Step 4 - Customize your workflow (optional) [Section titled “Step 4 - Customize your workflow (optional)”](#step-4---customize-your-workflow-optional) With GitHub Agentic Workflows, you are in control! Your repository automation is fully customizable. You should shape your repo automation to match your priorities and your needs. To customize it now: 1. Open the workflow markdown file located at `.github/workflows/daily-repo-status.md` in your repository. 2. Edit the section “What to include” to list things you are having trouble with regularly in your repository: your issue backlog, your CI setup, your testing, the performance of your software, your roadmap. Any or all of these, or anything else you want to improve. You can also customize the style and process sections to guide the coding agent’s behavior. 3. If you changed the [frontmatter](/gh-aw/reference/frontmatter/) (the configuration block between the `---` markers at the top of the file), regenerate the compiled workflow by running: ```text gh aw compile ``` For example, set your engine in frontmatter: ```aw --- engine: claude --- ``` 4. Commit and push to your repository. 5. Optionally trigger another run by running: ```text gh aw run daily-repo-status ``` After waiting for the workflow to complete, check the new issue created with your updated report! ## What’s next? [Section titled “What’s next?”](#whats-next) There are hundreds of other ways to use GitHub Agentic Workflows! Explore some of these in [Peli’s Agent Factory](https://github.github.com/gh-aw/blog/2026-01-12-welcome-to-pelis-agent-factory/). Continue learning with these resources: * [Creating Agentic Workflows](/gh-aw/setup/creating-workflows/) * [How Agentic Workflows Work](/gh-aw/introduction/how-they-work/) * [Frequently Asked Questions](/gh-aw/reference/faq/) # Common Issues > Frequently encountered issues when working with GitHub Agentic Workflows and their solutions. Frequently encountered issues, organized by workflow stage and component. ## Installation Issues [Section titled “Installation Issues”](#installation-issues) ### Extension Installation Fails [Section titled “Extension Installation Fails”](#extension-installation-fails) If `gh extension install github/gh-aw` fails, use the standalone installer (works in Codespaces and restricted networks). Pass a tag as the second argument to pin a version ([releases](https://github.com/github/gh-aw/releases)). Verify with `gh extension list`. ```bash curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash -s -- v0.40.0 ``` ## Organization Policy Issues [Section titled “Organization Policy Issues”](#organization-policy-issues) ### Custom Actions Not Allowed in Enterprise Organizations [Section titled “Custom Actions Not Allowed in Enterprise Organizations”](#custom-actions-not-allowed-in-enterprise-organizations) **Error:** `The action github/gh-aw/actions/setup@... is not allowed in {ORG} because all actions must be from a repository owned by your enterprise, created by GitHub, or verified in the GitHub Marketplace.` **Cause:** Enterprise policies restrict which GitHub Actions can be used. **Solution:** An admin must add `github/gh-aw@*` to the organization’s allowed actions, either through Settings → Actions → Policies → “Allow select actions and reusable workflows” ([docs](https://docs.github.com/en/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#allowing-select-actions-and-reusable-workflows-to-run)), or by editing a centralized `policies/actions.yml`: ```yaml allowed_actions: - "actions/*" - "github/gh-aw@*" ``` Wait a few minutes for policy propagation, then re-run. Tip The gh-aw actions are open source at [github.com/github/gh-aw/tree/main/actions](https://github.com/github/gh-aw/tree/main/actions) and pinned to specific SHAs. ## Repository Configuration Issues [Section titled “Repository Configuration Issues”](#repository-configuration-issues) ### Actions Restrictions Reported During Init [Section titled “Actions Restrictions Reported During Init”](#actions-restrictions-reported-during-init) The CLI validates three permission layers. Fix restrictions in Repository Settings → Actions → General: 1. **Actions disabled**: Enable Actions ([docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository)) 2. **Local-only**: Switch to “Allow all actions” or enable GitHub-created actions ([docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-github-actions-permissions-for-your-repository)) 3. **Selective allowlist**: Enable “Allow actions created by GitHub” checkbox ([docs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-select-actions-and-reusable-workflows-to-run)) Note Organization policies override repository settings. Contact admins if settings are grayed out. ## Workflow Compilation Issues [Section titled “Workflow Compilation Issues”](#workflow-compilation-issues) ### Frontmatter Field Not Taking Effect [Section titled “Frontmatter Field Not Taking Effect”](#frontmatter-field-not-taking-effect) If a frontmatter setting appears to be silently ignored, the field name may be misspelled. The compiler does not warn about unknown field names — they are silently discarded. Caution Common frontmatter field name mistakes: | Wrong | Correct | | ---------------- | ------------------------------------------------- | | `agent:` | `engine:` | | `mcp-servers:` | `tools:` (under which MCP servers are configured) | | `tool-sets:` | `toolsets:` (under `tools.github:`) | | `allowed_repos:` | `allowed-repos:` (under `tools.github:`) | | `timeout:` | `timeout-minutes:` | Run `gh aw compile --verbose` to confirm which settings were parsed. If your setting is missing from the output, check the [Frontmatter Reference](/gh-aw/reference/frontmatter/) for the correct field name. ### Compilation Failures [Section titled “Compilation Failures”](#compilation-failures) * **Won’t compile:** check YAML syntax (indentation, colons with spaces), required fields (`on:`), and types against the schema; use `gh aw compile --verbose`. * **Lock file not generated:** fix errors (`gh aw compile 2>&1 | grep -i error`) and check write permissions on `.github/workflows/`. * **Orphaned lock files:** clear stale `.lock.yml` files with `gh aw compile --purge` after deleting `.md` workflows. ## Import and Include Issues [Section titled “Import and Include Issues”](#import-and-include-issues) * **Import file not found:** import paths are relative to the repository root (e.g., `.github/workflows/shared/tools.md`); verify with `git status`. * **Multiple agent files error:** import only one `.github/agents/` file per workflow. * **Circular dependencies:** compilation hangs indicate circular imports — remove the circular reference. ## Tool Configuration Issues [Section titled “Tool Configuration Issues”](#tool-configuration-issues) ### GitHub Tools Not Available [Section titled “GitHub Tools Not Available”](#github-tools-not-available) Configure using `toolsets:` ([tools reference](/gh-aw/reference/github-tools/)): ```yaml tools: github: toolsets: [repos, issues] ``` ### Toolset Missing Expected Tools [Section titled “Toolset Missing Expected Tools”](#toolset-missing-expected-tools) Check [GitHub Toolsets](/gh-aw/reference/github-tools/), combine toolsets (`toolsets: [default, actions]`), or inspect with `gh aw mcp inspect `. ### MCP Server Connection Failures [Section titled “MCP Server Connection Failures”](#mcp-server-connection-failures) Verify package installation, syntax, and environment variables: ```yaml mcp-servers: my-server: command: "npx" args: ["@myorg/mcp-server"] env: API_KEY: "${{ secrets.MCP_API_KEY }}" ``` ### OpenCode/Crush MCP Tools Not Being Called [Section titled “OpenCode/Crush MCP Tools Not Being Called”](#opencodecrush-mcp-tools-not-being-called) When integrating OpenCode-compatible engines (such as `crush`), runs can complete without ever invoking MCP or file tools. Use this `.crush.json`. Port `10004` is the local AWF API proxy port (with `--enable-api-proxy`); `MCP_GATEWAY_PORT` and `MCP_GATEWAY_API_KEY` are expanded from workflow env at runtime (substitute concrete values when running outside a workflow): ```json { "provider": { "copilot-proxy": { "name": "Copilot Proxy", "type": "openai-compatible", "baseURL": "http://host.docker.internal:10004", "models": ["gpt-4.1", "claude-sonnet-4-6"] } }, "model": "copilot-proxy/claude-sonnet-4-6", "mcp": { "safeoutputs": { "type": "http", "url": "http://host.docker.internal:${MCP_GATEWAY_PORT}/mcp/safeoutputs", "headers": { "Authorization": "${MCP_GATEWAY_API_KEY}" }, "disabled": false, "timeout": 30000 } }, "agent": { "build": { "permission": { "bash": "allow", "edit": "allow", "read": "allow", "glob": "allow", "grep": "allow", "write": "allow", "external_directory": "allow" } } } } ``` Key gotchas: * Crush/OpenCode does not auto-discover MCP servers — declare an explicit top-level `mcp` block with routed URLs (`http://host.docker.internal:${MCP_GATEWAY_PORT}/mcp/`). * Use `agent.build.permission` (singular) — `permissions` is silently ignored, leaving tools unavailable. * `external_directory` defaults to `ask` in non-interactive mode, which becomes an implicit deny. Set it to `allow` only when access outside the workspace (e.g., `/tmp`, mounted dirs) is required. * For direct Copilot endpoints (`api.githubcopilot.com`), do **not** append `/v1`. For other OpenAI-compatible providers, use the provider’s documented base path so `/chat/completions` is appended correctly. Keep the local proxy URL (`http://host.docker.internal:10004`) as-is. * When using `--enable-api-proxy`, pass `COPILOT_GITHUB_TOKEN` in the execute step’s `env:` so the proxy can authenticate: ```yaml - name: Execute env: COPILOT_GITHUB_TOKEN: ${{ steps.copilot-token.outputs.token }} run: | awf --enable-api-proxy -- crush run "" ``` ### Playwright Network Access Denied [Section titled “Playwright Network Access Denied”](#playwright-network-access-denied) Add domains to `network.allowed`: ```yaml network: allowed: - github.com - "*.github.io" ``` ### Cannot Find Module ‘playwright’ [Section titled “Cannot Find Module ‘playwright’”](#cannot-find-module-playwright) `Error: Cannot find module 'playwright'` — Playwright is provided as MCP tools, not as an npm package. Use the MCP tools instead of `require('playwright')`: ```javascript // ✗ Don't: const playwright = require('playwright') // ✓ Do: use MCP tools await mcp__playwright__browser_navigate({ url: "https://example.com" }); await mcp__playwright__browser_snapshot(); ``` See [Playwright Tool documentation](/gh-aw/reference/tools/#playwright-tool-playwright) for all available tools. ### Playwright MCP Initialization Failure (EOF Error) [Section titled “Playwright MCP Initialization Failure (EOF Error)”](#playwright-mcp-initialization-failure-eof-error) `Failed to register tools error="initialize: EOF" name=playwright` — Chromium crashes before tool registration completes due to missing Docker security flags. Upgrade to 0.41.0+ with `gh extension upgrade gh-aw`. ## Permission Issues [Section titled “Permission Issues”](#permission-issues) ### Write Operations Fail [Section titled “Write Operations Fail”](#write-operations-fail) All writes (issues, comments, PR updates) must go through the `safe-outputs` system — declare the types your workflow needs in frontmatter: ```yaml safe-outputs: create-issue: title-prefix: "[bot] " labels: [automation] add-comment: # no configuration required; uses defaults update-issue: # no configuration required; uses defaults ``` If your operation isn’t in the [Safe Outputs reference](/gh-aw/reference/safe-outputs/), it may not be supported yet. See the [Safe Outputs Specification](/gh-aw/reference/safe-outputs-specification/) for the full list. ### Safe Outputs Not Creating Issues [Section titled “Safe Outputs Not Creating Issues”](#safe-outputs-not-creating-issues) Disable staged mode: ```yaml safe-outputs: staged: false create-issue: title-prefix: "[bot] " labels: [automation] ``` ### Project Field Type Errors [Section titled “Project Field Type Errors”](#project-field-type-errors) GitHub Projects reserves field names like `REPOSITORY`. Use alternatives (`repo`, `source_repository`, `linked_repo`): ```yaml # ✗ Wrong: repository # ✓ Correct: repo safe-outputs: update-project: fields: repo: "myorg/myrepo" ``` Delete conflicting fields in Projects UI and recreate. ## Engine-Specific Issues [Section titled “Engine-Specific Issues”](#engine-specific-issues) * **Copilot CLI not found:** verify compilation succeeded — compiled workflows include CLI installation steps. * **Model not available:** use the default (`engine: copilot`) or specify an available model (`engine: {id: copilot, model: gpt-4}`). ### Copilot License or Inference Access Issues [Section titled “Copilot License or Inference Access Issues”](#copilot-license-or-inference-access-issues) If a workflow fails at the Copilot inference step despite a correctly configured `COPILOT_GITHUB_TOKEN` (authentication or quota errors), the PAT owner may lack a valid Copilot license or inference access. Test locally with the [Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli): ```bash export COPILOT_GITHUB_TOKEN="" copilot -p "write a haiku" ``` If this fails, contact your organization administrator to enable Copilot for the token owner. Note `COPILOT_GITHUB_TOKEN` must belong to a user account with an active Copilot subscription. Org-managed licenses may impose additional restrictions on programmatic API access. ## GitHub Enterprise Server Issues [Section titled “GitHub Enterprise Server Issues”](#github-enterprise-server-issues) Tip For a complete walkthrough of setting up and debugging workflows on **GHE Cloud with data residency** (`*.ghe.com`), see [Debugging GHE Cloud with Data Residency](/gh-aw/troubleshooting/debug-ghe/). ### Copilot Engine Prerequisites on GHES [Section titled “Copilot Engine Prerequisites on GHES”](#copilot-engine-prerequisites-on-ghes) Before running Copilot-based workflows on GHES, verify: * **Site admin:** GitHub Connect enabled (links GHES to github.com for Copilot cloud services), enterprise-level Copilot licensing activated, and outbound HTTPS allowed to `api.githubcopilot.com` and `api.enterprise.githubcopilot.com`. * **Enterprise/org admin:** a Copilot seat assigned to the `COPILOT_GITHUB_TOKEN` owner, and the org Copilot policy permits usage. * **Workflow config:** ```aw engine: id: copilot api-target: api.enterprise.githubcopilot.com network: allowed: - defaults - api.enterprise.githubcopilot.com ``` See [Enterprise API Endpoint](/gh-aw/reference/engines/#enterprise-api-endpoint-api-target) for GHEC/GHES `api-target` values. ### Copilot GHES: Common Error Messages [Section titled “Copilot GHES: Common Error Messages”](#copilot-ghes-common-error-messages) | Error | Cause | Fix | | -------------------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Error loading models: 400 Bad Request` | Enterprise Copilot not licensed or GitHub Connect not enabled | Enable GitHub Connect and enterprise Copilot in site admin settings | | `403 "unauthorized: not licensed to use Copilot"` | No Copilot seat for PAT owner | Site admin enables Copilot; org admin assigns a seat to the token owner | | `403 "Resource not accessible by personal access token"` | Wrong token type or missing permissions | Use fine-grained PAT with **Copilot Requests: Read**, or classic PAT with `copilot` scope — see [`COPILOT_GITHUB_TOKEN`](/gh-aw/reference/auth/#copilot_github_token) | | `Could not resolve to a Repository` | `GH_HOST` not set in custom jobs | Recompile (`gh aw compile`), or set `GH_HOST=github.company.com` explicitly for local CLI commands | | Firewall blocking `api.` | Domain not in allowed list | Add to `network.allowed` (see below) | | `gh aw add-wizard` creates PR on github.com | Not inside a GHES repo clone | Run from within GHES repo, or use `gh aw add` + `gh pr create` | For firewall issues, add the GHES domain to your workflow’s allowed list: ```aw engine: id: copilot api-target: api.company.ghe.com network: allowed: - defaults - company.ghe.com - api.company.ghe.com ``` ## Context Expression Issues [Section titled “Context Expression Issues”](#context-expression-issues) * **Unauthorized expression:** use only [allowed expressions](/gh-aw/reference/templating/) (`github.event.issue.number`, `github.repository`, `steps.sanitized.outputs.text`). `secrets.*` and `env.*` are disallowed. * **Sanitized context empty:** `steps.sanitized.outputs.text` requires issue/PR/comment events (`on: issues:`), not `push:` or similar triggers. ## Build and Test Issues [Section titled “Build and Test Issues”](#build-and-test-issues) * **Documentation build fails:** clean install (`cd docs && rm -rf node_modules package-lock.json && npm install && npm run build`) and check for malformed frontmatter, MDX syntax errors, or broken links. * **Tests failing after changes:** run `make fmt && make lint && make test-unit` before iterating. ## Network and Connectivity Issues [Section titled “Network and Connectivity Issues”](#network-and-connectivity-issues) ### Firewall Denials for Package Registries [Section titled “Firewall Denials for Package Registries”](#firewall-denials-for-package-registries) Add ecosystem identifiers ([Network Configuration Guide](/gh-aw/guides/network-configuration/)): ```yaml network: allowed: - defaults # Infrastructure - python # PyPI - node # npm - containers # Docker - go # Go modules ``` ### Other Network Issues [Section titled “Other Network Issues”](#other-network-issues) * **URLs appearing as `(redacted)`:** add domains to the allowed list ([Network Permissions](/gh-aw/reference/network/)) — e.g., `allowed: [defaults, "api.example.com"]`. * **Cannot download remote imports:** verify network (`curl -I https://raw.githubusercontent.com/github/gh-aw/main/README.md`) and auth (`gh auth status`). * **MCP server connection timeout:** use local servers (`command: "node"`, `args: ["./server.js"]`). ## Cache Issues [Section titled “Cache Issues”](#cache-issues) * **Cache not restoring:** verify key patterns match (caches expire after 7 days) — `cache: { key: deps-${{ hashFiles('package-lock.json') }}, restore-keys: deps- }`. * **Cache memory not persisting:** configure the cache-memory MCP server — `tools.cache-memory.key: memory-${{ github.workflow }}-${{ github.run_id }}`. ## Integrity Filtering Blocking Expected Content [Section titled “Integrity Filtering Blocking Expected Content”](#integrity-filtering-blocking-expected-content) On public repositories, `min-integrity: approved` is applied automatically — restricting agent visibility to content from owners, members, and collaborators. As a result, workflows can’t see issues, PRs, or comments from external contributors, and triage workflows don’t process community contributions. To allow all contributors (only safe when the workflow validates input and uses restrictive safe outputs): ```yaml tools: github: min-integrity: none ``` Use `min-integrity: unapproved` as a middle ground for community triage workflows. See [Integrity Filtering](/gh-aw/reference/integrity/) for details. ## Workflow Failures and Debugging [Section titled “Workflow Failures and Debugging”](#workflow-failures-and-debugging) ### Timeout Errors [Section titled “Timeout Errors”](#timeout-errors) GitHub Actions marks the run as `timed_out` when the job exceeds `timeout-minutes` (default: 20 min). The table below maps each engine’s error patterns to the right fix; after updating frontmatter, recompile with `gh aw compile`. See [Long Build Times](/gh-aw/reference/sandbox/#long-build-times) for caching strategies and self-hosted runner recommendations. | Engine | Error Pattern | Fix Setting | | ------- | -------------------------------------------------------------- | ----------------------------------- | | All | `The job has exceeded the maximum execution time of N minutes` | `timeout-minutes: N` in frontmatter | | Claude | `Bash tool timed out after 60 seconds` | `tools: timeout: N` (default: 60s) | | Claude | `Reached maximum number of turns (N). Stopping.` | `max-turns: N` | | Codex | `Tool call timed out after 120 seconds` | `tools: timeout: N` (default: 120s) | | Copilot | *(task incomplete, workflow succeeds)* | `max-continuations: N` | | Any | `Failed to register tools error="initialize: timeout"` | `tools: startup-timeout: N` | ```yaml timeout-minutes: 60 # job-level limit tools: timeout: 600 # per-tool-call limit (seconds) startup-timeout: 300 # MCP server startup limit (seconds) max-turns: 30 # Claude: max turns max-continuations: 5 # Copilot: autopilot continuations ``` ### Why Did My Workflow Fail? [Section titled “Why Did My Workflow Fail?”](#why-did-my-workflow-fail) Common causes: missing tokens, permission mismatches, network restrictions, disabled tools, or rate limits. The fastest path is to ask an agent with the run URL — it audits logs, identifies the root cause, and suggests fixes. Using Copilot Chat (requires [agentic authoring setup](/gh-aw/guides/agentic-authoring/#configuring-your-repository)): ```text /agent agentic-workflows debug https://github.com/OWNER/REPO/actions/runs/RUN_ID ``` Using any coding agent (no setup required): ```text Debug this workflow run using https://raw.githubusercontent.com/github/gh-aw/main/debug.md The failed workflow run is at https://github.com/OWNER/REPO/actions/runs/RUN_ID ``` For manual investigation: `gh aw audit `, `gh aw logs`, inspect `.lock.yml`. See the [Debugging Workflows](/gh-aw/troubleshooting/debugging/) guide for a full walkthrough. ### Enable Debug Logging [Section titled “Enable Debug Logging”](#enable-debug-logging) Enable verbose mode (`--verbose`), set `ACTIONS_STEP_DEBUG = true`, or inspect MCP config (`gh aw mcp inspect`). The `DEBUG` environment variable activates detailed internal logging for any `gh aw` command — output goes to `stderr` and each line shows the namespace (`workflow:compiler`), message, and time since the previous entry. Common namespaces: `cli:compile_command`, `workflow:compiler`, `workflow:expression_extraction`, `parser:frontmatter`. Wildcards match any suffix. ```bash DEBUG=* gh aw compile # all logs DEBUG=workflow:* gh aw compile my-workflow # specific package DEBUG=workflow:*,cli:* gh aw compile my-workflow # multiple packages DEBUG=*,-workflow:test gh aw compile my-workflow # exclude a logger DEBUG_COLORS=0 DEBUG=* gh aw compile 2>&1 | tee debug.log # capture to file ``` ## Operational Runbooks [Section titled “Operational Runbooks”](#operational-runbooks) See [Workflow Health Monitoring Runbook](https://github.com/github/gh-aw/blob/main/.github/aw/runbooks/workflow-health.md) for diagnosing errors. ## Getting Help [Section titled “Getting Help”](#getting-help) Review [reference docs](/gh-aw/reference/workflow-structure/), search [existing issues](https://github.com/github/gh-aw/issues), or create an issue. See [Error Reference](/gh-aw/troubleshooting/errors/) and [Frontmatter Reference](/gh-aw/reference/frontmatter/). # Debugging GHE Cloud with Data Residency > Step-by-step guide for setting up and debugging agentic workflows on GitHub Enterprise Cloud with data residency (*.ghe.com). This guide walks you through setting up and running agentic workflows on **GitHub Enterprise Cloud with data residency** (`*.ghe.com`). It reflects the configuration needed as of `gh aw` **v0.61.1+** for enterprises using data residency in the EU or other regions. Tip The one thing you must do differently from github.com is set `api-target` in your workflow frontmatter to `copilot-api..ghe.com`. Everything else flows from that. Based on the debugging discussion in [github/gh-aw#18480](https://github.com/github/gh-aw/issues/18480). ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * A repository on your GHE Cloud data residency instance (e.g., `yourorg.ghe.com`) * The `gh aw` CLI extension **v0.61.1 or later** (`gh extension install github/gh-aw`) * Copilot enabled for your enterprise * The `gh` CLI authenticated with your GHE instance: ```bash gh auth login --hostname yourorg.ghe.com ``` ## Setup [Section titled “Setup”](#setup) ### Step 1: Initialize Your Repository [Section titled “Step 1: Initialize Your Repository”](#step-1-initialize-your-repository) ```bash GH_HOST=yourorg.ghe.com gh aw init ``` ### Step 2: Add a Workflow [Section titled “Step 2: Add a Workflow”](#step-2-add-a-workflow) ```bash GH_HOST=yourorg.ghe.com gh aw add-wizard githubnext/agentics/repo-assist ``` Follow the prompts to configure the workflow for your repository. ### Step 3: Configure the Engine for GHE (Critical) [Section titled “Step 3: Configure the Engine for GHE (Critical)”](#step-3-configure-the-engine-for-ghe-critical) Open the generated workflow `.md` file (e.g., `.github/workflows/repo-assist.md`) and ensure the `engine` section in the YAML frontmatter includes `api-target` pointing to your enterprise’s Copilot API subdomain: ```aw engine: id: "copilot" api-target: "copilot-api.yourorg.ghe.com" ``` Replace `yourorg` with your enterprise’s slug — the subdomain portion of `yourorg.ghe.com`. **Why this is required**: On GHE Cloud with data residency, Copilot inference runs on a dedicated subdomain (`copilot-api.yourorg.ghe.com`) rather than the default `api.githubcopilot.com`. Without `api-target`, the AWF api-proxy routes requests to the wrong host, resulting in authentication failures. See [Enterprise API Endpoint](/gh-aw/reference/engines/#enterprise-api-endpoint-api-target) for full `api-target` documentation. ### Step 4: Compile [Section titled “Step 4: Compile”](#step-4-compile) ```bash GH_HOST=yourorg.ghe.com gh aw compile repo-assist ``` The compiler (v0.61.1+) will automatically: * Add your GHE domains (`api.yourorg.ghe.com`, `copilot-api.yourorg.ghe.com`) to the firewall allow-list * Set `--copilot-api-target` for the AWF api-proxy * Configure `GH_HOST` so the `gh` CLI targets the correct host ### Step 5: Commit, Push, and Run [Section titled “Step 5: Commit, Push, and Run”](#step-5-commit-push-and-run) ```bash git add .github/workflows/repo-assist.md .github/workflows/repo-assist.lock.yml git commit -m "Add repo-assist agentic workflow" git push # Dispatch the workflow GH_HOST=yourorg.ghe.com gh workflow run repo-assist.lock.yml --ref main ``` ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) If the workflow fails, start by using the Copilot CLI to help diagnose the issue. ### Debugging with Copilot CLI Locally [Section titled “Debugging with Copilot CLI Locally”](#debugging-with-copilot-cli-locally) The fastest way to diagnose failures is to use the Copilot CLI interactively from your local machine. This lets you confirm Copilot can authenticate against your GHE instance and then use Copilot itself to help debug workflow failures. 1. **Ensure you’re authenticated with your GHE instance**: ```bash GH_HOST=yourorg.ghe.com gh auth status ``` 2. **Launch the Copilot CLI**: ```bash GH_HOST=yourorg.ghe.com copilot ``` 3. **Select the agentic-workflows agent** — when Copilot starts, run `/agent` and choose `agentic-workflows` from the list. 4. **Ask Copilot to run and debug the workflow** — trigger the workflow, wait for it to complete, and then ask Copilot to analyze the results. For example: ```plaintext Run the repo-assist workflow and check if it succeeds. If it fails, help me debug the failure. ``` Copilot has access to your workflow files, run logs, and the `gh aw audit` tool, so it can inspect failures end-to-end and suggest fixes. ### Common Errors [Section titled “Common Errors”](#common-errors) #### ”Authentication failed” [Section titled “”Authentication failed””](#authentication-failed) ```plaintext Error: Authentication failed Your GitHub token may be invalid, expired, or lacking the required permissions. ``` **Cause**: The `api-target` is missing or incorrect. The api-proxy is sending Copilot requests to the wrong endpoint. **Fix**: Verify your `.md` frontmatter has: ```aw engine: id: "copilot" api-target: "copilot-api.yourorg.ghe.com" ``` Then recompile with `GH_HOST=yourorg.ghe.com gh aw compile`. #### ”none of the git remotes point to a known GitHub host” [Section titled “”none of the git remotes point to a known GitHub host””](#none-of-the-git-remotes-point-to-a-known-github-host) **Cause**: `GH_HOST` is not set. The `gh` CLI doesn’t recognize your GHE instance as a GitHub host. **Fix**: Upgrade to `gh aw` v0.61.1+ and recompile. The compiler now auto-configures `GH_HOST` for GHE instances. #### ”Not Found” during checkout steps [Section titled “”Not Found” during checkout steps”](#not-found-during-checkout-steps) **Cause**: The lock file is trying to access `github.com` repositories with your GHE-scoped token. This can happen with local builds of the compiler that use `actions/checkout` instead of the published `github/gh-aw-actions` action reference. **Fix**: Always compile with the installed `gh aw` extension rather than a local binary: ```bash GH_HOST=yourorg.ghe.com gh aw compile ``` See also [Copilot GHES: Common Error Messages](/gh-aw/troubleshooting/common-issues/#copilot-ghes-common-error-messages) for additional error patterns. ### Advanced: Testing Copilot on the Runner Directly [Section titled “Advanced: Testing Copilot on the Runner Directly”](#advanced-testing-copilot-on-the-runner-directly) If you need to verify that Copilot auth works on the Actions runner itself (outside the AWF sandbox), add a temporary diagnostic step to the lock file before the Execute step: ```yaml - name: Test Copilot CLI directly env: GH_HOST: yourorg.ghe.com GH_TOKEN: ${{ github.token }} run: | echo "GH_HOST=$GH_HOST" echo "GITHUB_SERVER_URL=$GITHUB_SERVER_URL" /usr/local/bin/copilot --version /usr/local/bin/copilot --prompt "Say hello" --log-level all 2>&1 | head -50 ``` If this step succeeds but the Execute step fails, the problem is in the firewall or api-proxy configuration, not in Copilot auth. ### Advanced: Capturing HTTP Traffic [Section titled “Advanced: Capturing HTTP Traffic”](#advanced-capturing-http-traffic) To see exactly which hosts the Copilot CLI contacts, add these environment variables to the Execute step: ```yaml env: NODE_DEBUG: fetch,undici UNDICI_DEBUG: full ``` Caution The Copilot CLI uses Node.js `fetch()`/`undici` internally, not the built-in `http`/`https` modules. Setting `NODE_DEBUG=http,https` will capture nothing. You must use `UNDICI_DEBUG=full`. The traffic capture reveals the four domains the CLI uses on data residency: | Domain | Purpose | | ------------------------------------------- | ------------------------------------------------- | | `api.yourorg.ghe.com` | REST API, Copilot auth (`/copilot_internal/user`) | | `copilot-api.yourorg.ghe.com` | Inference, model listing, MCP | | `copilot-telemetry-service.yourorg.ghe.com` | Telemetry | | `api.githubcopilot.com` | Shared Copilot services | ### Advanced: Checking Firewall Logs [Section titled “Advanced: Checking Firewall Logs”](#advanced-checking-firewall-logs) Download the workflow run artifacts and inspect `sandbox/firewall/logs/access.log`. Each line shows whether a domain was allowed (`TCP_TUNNEL`) or blocked (`DENIED`). Verify that your `yourorg.ghe.com` domains appear as `TCP_TUNNEL`. ## Required Domains Reference [Section titled “Required Domains Reference”](#required-domains-reference) For GHE Cloud with data residency, the following domains must be reachable from inside the AWF sandbox. The compiler adds most of these automatically when `api-target` is set: | Domain | Auto-added by compiler? | Required for | | ------------------------------------------- | :------------------------: | ---------------------- | | `yourorg.ghe.com` | ✓ | Git, web UI | | `api.yourorg.ghe.com` | ✓ | REST API, Copilot auth | | `copilot-api.yourorg.ghe.com` | ✓ | Inference, models, MCP | | `copilot-telemetry-service.yourorg.ghe.com` | ✗ (add manually if needed) | Telemetry | To add the telemetry domain manually: ```aw network: allowed: - defaults - copilot-telemetry-service.yourorg.ghe.com ``` # Debugging Workflows > How to run, debug, and investigate agentic workflow failures using the Copilot CLI, gh aw audit, and log analysis. This guide shows you how to debug agentic workflow failures on **github.com** using the Copilot CLI, the `gh aw` debugging commands, and manual investigation techniques. Tip The fastest path to a fix is to let an AI agent debug it for you. Launch the Copilot CLI, load the agentic-workflows agent, and paste the failing run URL. ## Debugging with the Copilot CLI [Section titled “Debugging with the Copilot CLI”](#debugging-with-the-copilot-cli) The Copilot CLI can audit logs, trace failures, and suggest fixes interactively. This is the recommended first step for any workflow failure. ### Step 1: Launch the Copilot CLI [Section titled “Step 1: Launch the Copilot CLI”](#step-1-launch-the-copilot-cli) ```bash copilot ``` ### Step 2: Load the Agentic Workflows Agent [Section titled “Step 2: Load the Agentic Workflows Agent”](#step-2-load-the-agentic-workflows-agent) Once inside the Copilot CLI, run: ```text /agent ``` Select **agentic-workflows** from the list. This gives Copilot access to the `gh aw audit`, `gh aw logs`, and other debugging tools. ### Step 3: Ask Copilot to Debug the Failure [Section titled “Step 3: Ask Copilot to Debug the Failure”](#step-3-ask-copilot-to-debug-the-failure) Paste the failing run URL and ask Copilot to investigate: ```text Debug this workflow run: https://github.com/OWNER/REPO/actions/runs/RUN_ID ``` Copilot will: * Download and audit the run logs * Identify the root cause (missing tools, permission errors, network blocks, etc.) * Suggest targeted fixes or open a pull request with the fix You can also ask follow-up questions: ```text What domains were blocked by the firewall? Show me the safe-outputs from this run. Why did the MCP server fail to connect? ``` ### Alternative: Copilot Chat on GitHub.com [Section titled “Alternative: Copilot Chat on GitHub.com”](#alternative-copilot-chat-on-githubcom) If your repository is [configured for agentic authoring](/gh-aw/guides/agentic-authoring/), you can use Copilot Chat directly on GitHub.com: ```text /agent agentic-workflows debug https://github.com/OWNER/REPO/actions/runs/RUN_ID ``` ### Alternative: Any Coding Agent [Section titled “Alternative: Any Coding Agent”](#alternative-any-coding-agent) For coding agents that don’t have the agentic-workflows agent pre-configured, use the standalone debug prompt: ```text Debug this workflow run using https://raw.githubusercontent.com/github/gh-aw/main/debug.md The failed workflow run is at https://github.com/OWNER/REPO/actions/runs/RUN_ID ``` The agent will install `gh aw`, analyze logs, identify the root cause, and suggest a fix. ## Debugging with CLI Commands [Section titled “Debugging with CLI Commands”](#debugging-with-cli-commands) ### Auditing a Specific Run [Section titled “Auditing a Specific Run”](#auditing-a-specific-run) `gh aw audit` gives a comprehensive breakdown of a single run — overview, metrics, tool usage, MCP failures, firewall analysis, behavior fingerprint, and artifacts: ```bash # By run ID gh aw audit 12345678 # By full URL gh aw audit https://github.com/OWNER/REPO/actions/runs/12345678 # By job URL (extracts first failing step) gh aw audit https://github.com/OWNER/REPO/actions/runs/123/job/456 # By step URL (extracts a specific step) gh aw audit https://github.com/OWNER/REPO/actions/runs/123/job/456#step:7:1 # Parse to markdown for sharing gh aw audit 12345678 --parse ``` Audit output includes: * **Failure analysis** with error summary and root cause * **Behavior fingerprint** — multi-dimensional characterization of the run’s network, tool, and cost profile * **Tool usage** — which tools were called, which failed, and why * **MCP server status** — connection failures, timeout errors, and per-server health * **Firewall analysis** — blocked domains, allowed traffic, and policy attribution * **Token/cost metrics** — per-run inference spend and token usage * **Safe-outputs** — structured outputs the agent produced To compare behavior between two runs and detect regressions across firewall, MCP, and metrics dimensions, pass multiple run IDs directly to `audit`: ```bash gh aw audit 12345678 12345679 gh aw audit 12345678 12345679 --format markdown ``` For security and performance trends across multiple runs, use `gh aw logs --format`: ```bash gh aw logs my-workflow --format markdown --count 10 gh aw logs my-workflow --format markdown --last 5 --json ``` See [Audit Commands](/gh-aw/reference/audit/) for complete flag documentation. ### Analyzing Workflow Logs [Section titled “Analyzing Workflow Logs”](#analyzing-workflow-logs) `gh aw logs` downloads and analyzes logs across multiple runs with tool usage, network patterns, errors, and warnings: ```bash # Download logs for a workflow gh aw logs my-workflow # Filter by count and date range gh aw logs my-workflow -c 10 --start-date -1w # Include firewall analysis gh aw logs my-workflow --firewall # Include safe-output details gh aw logs my-workflow --safe-output # JSON output for scripting gh aw logs my-workflow --json ``` Results are cached locally for 10–100× speedup on subsequent runs. ### Checking Workflow Health [Section titled “Checking Workflow Health”](#checking-workflow-health) `gh aw health` gives a quick overview of workflow status across all workflows in a repository: ```bash gh aw health ``` ### Inspecting MCP Configuration [Section titled “Inspecting MCP Configuration”](#inspecting-mcp-configuration) If you suspect MCP server issues, inspect the compiled configuration: ```bash # List all workflows with MCP servers gh aw mcp list # Inspect MCP servers for a specific workflow gh aw mcp inspect my-workflow # Open the web-based MCP inspector gh aw mcp inspect my-workflow --inspector ``` ## Common Errors [Section titled “Common Errors”](#common-errors) ### ”Authentication failed” [Section titled “”Authentication failed””](#authentication-failed) ```text Error: Authentication failed Your GitHub token may be invalid, expired, or lacking the required permissions. ``` **Cause**: The Copilot token is missing, expired, or lacks required permissions. **Fix**: 1. Verify you have an active Copilot subscription 2. Check that the token has the **Copilot Requests** permission (for fine-grained PATs) 3. If using a custom `COPILOT_GITHUB_TOKEN`, verify it’s valid: ```bash gh auth status ``` 4. See [Authentication Reference](/gh-aw/reference/auth/) for token setup details ### ”Tool not found” or Missing Tool Calls [Section titled “”Tool not found” or Missing Tool Calls”](#tool-not-found-or-missing-tool-calls) **Cause**: The workflow references a tool that isn’t configured or the MCP server failed to connect. **Fix**: 1. Run `gh aw mcp inspect my-workflow` to verify tool configuration 2. Check that the MCP server version is compatible 3. Ensure `tools:` section in frontmatter includes the required tool 4. Run `gh aw audit ` to see which tools were available vs. requested ### Network / Firewall Blocks [Section titled “Network / Firewall Blocks”](#network--firewall-blocks) ```text DENIED CONNECT registry.npmjs.org:443 ``` **Cause**: The agent tried to reach a domain not in the firewall allow-list. **Fix**: Add the domain to the `network.allowed` list in your workflow frontmatter: ```aw network: allowed: - defaults - registry.npmjs.org ``` Or use an ecosystem shorthand: ```aw network: allowed: - defaults - node # Adds npm, yarn, pnpm registries - python # Adds PyPI, conda registries ``` See [Network Configuration](/gh-aw/guides/network-configuration/) for common domain configurations. ### Safe-Outputs Not Creating Issues / Comments [Section titled “Safe-Outputs Not Creating Issues / Comments”](#safe-outputs-not-creating-issues--comments) **Cause**: The safe-outputs job failed, the agent didn’t produce the expected output, or permissions are missing. **Fix**: 1. Run `gh aw audit ` and check the safe-outputs section 2. See [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) for configuration details ### Compilation Errors [Section titled “Compilation Errors”](#compilation-errors) **Cause**: The workflow frontmatter has schema validation errors or unsupported fields. **Fix**: 1. Run the compiler with verbose output: ```bash gh aw compile my-workflow --verbose ``` 2. Run the fixer for auto-correctable issues: ```bash gh aw fix --write ``` 3. Validate without compiling: ```bash gh aw compile --validate ``` 4. See [Error Reference](/gh-aw/troubleshooting/errors/) for specific error messages ## Advanced Debugging [Section titled “Advanced Debugging”](#advanced-debugging) ### Enable Debug Logging [Section titled “Enable Debug Logging”](#enable-debug-logging) The `DEBUG` environment variable enables detailed internal logging for any `gh aw` command: ```bash # All debug logs DEBUG=* gh aw compile my-workflow # CLI-specific logs DEBUG=cli:* gh aw audit 12345678 # Workflow compilation logs DEBUG=workflow:* gh aw compile my-workflow # Multiple packages DEBUG=workflow:*,cli:* gh aw compile my-workflow ``` Tip Debug output goes to `stderr`. Capture it with `2>&1 | tee debug.log`. ### Enable GitHub Actions Debug Logging [Section titled “Enable GitHub Actions Debug Logging”](#enable-github-actions-debug-logging) Set the `ACTIONS_STEP_DEBUG` secret to `true` in your repository to enable verbose step-level logging in GitHub Actions: 1. Go to **Settings → Secrets and variables → Actions** 2. Add a secret: `ACTIONS_STEP_DEBUG` = `true` 3. Re-run the workflow This produces much more detailed logs in the Actions UI. ### Inspecting Firewall Logs [Section titled “Inspecting Firewall Logs”](#inspecting-firewall-logs) Download the workflow run artifacts and look for `sandbox/firewall/logs/access.log`. Each line shows whether a domain was allowed (`TCP_TUNNEL`) or blocked (`DENIED`): ```text TCP_TUNNEL/200 api.github.com:443 DENIED CONNECT blocked-domain.com:443 ``` You can also use the CLI: ```bash gh aw logs my-workflow --firewall gh aw audit # Includes firewall analysis ``` ### Inspecting Artifacts [Section titled “Inspecting Artifacts”](#inspecting-artifacts) Workflow runs produce several artifacts useful for debugging: | Artifact | Location | Contents | | ------------------- | --------------------------- | ------------------------------------ | | `prompt.txt` | `/tmp/gh-aw/aw-prompts/` | The full prompt sent to the AI agent | | `agent_output.json` | `/tmp/gh-aw/safeoutputs/` | Structured safe-output data | | `agent-stdio.log` | `/tmp/gh-aw/` | Raw agent stdin/stdout log | | `firewall-logs/` | `/tmp/gh-aw/firewall-logs/` | Network access logs | Download artifacts from the GitHub Actions run page or via the CLI: ```bash gh run download --repo OWNER/REPO ``` ### Recompiling for a Quick Fix [Section titled “Recompiling for a Quick Fix”](#recompiling-for-a-quick-fix) If you’ve identified the issue and made a change to the `.md` file, recompile and push: ```bash gh aw compile my-workflow git add .github/workflows/my-workflow.md .github/workflows/my-workflow.lock.yml git commit -m "fix: update workflow configuration" git push ``` # Error Reference > Comprehensive reference of error messages in GitHub Agentic Workflows, including schema validation, compilation, and runtime errors with solutions. This reference documents common error messages, organized by when they occur during the workflow lifecycle. Tip When you mistype a frontmatter field, the compiler suggests a correction via fuzzy matching. Look for “Did you mean” hints in the output (e.g., `permisions` → `permissions`). ## Schema Validation Errors [Section titled “Schema Validation Errors”](#schema-validation-errors) Detected during compilation when frontmatter does not conform to the JSON schema. | Error | Cause | Fix | | -------------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------- | | `frontmatter not properly closed` | Missing closing `---` delimiter | Enclose frontmatter between two `---` lines | | `failed to parse frontmatter: ...` | Invalid YAML syntax | Check indentation (spaces, not tabs), colons followed by spaces, quoted special characters | | `timeout-minutes must be an integer` | Wrong value type | Use the documented type — e.g., `timeout-minutes: 10`, not `"10"` | | `Unknown property: ...` | Misspelled field name | Apply the “Did you mean” suggestion; see [Frontmatter Reference](/gh-aw/reference/frontmatter/) | | `imports field must be an array of strings` | Wrong syntax for `imports:` | Use list form: `- shared/tools.md` | | `multiple agent files found in imports: ...` | More than one agent file imported | Import only one file from `.github/agents/` per workflow | ## Compilation Errors [Section titled “Compilation Errors”](#compilation-errors) Raised when converting the `.md` workflow to its `.lock.yml`. | Error | Cause | Fix | | ----------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------- | | `workflow file not found: ...` | Path is wrong or missing | Verify the file exists under `.github/workflows/`; run `gh aw compile` to compile all | | `failed to resolve import '...'` | Import path or permissions | Confirm the file exists relative to repo root and is readable | | `invalid workflowspec: must be owner/repo/path[@ref]` | Wrong remote import format | Use `owner/repo/path[@ref]` (e.g., `github/gh-aw/.github/workflows/shared/example.md@main`) | | `section 'name' not found` | Referenced section missing | Internal processing issue — verify the section exists; report if persistent | ## Runtime Errors [Section titled “Runtime Errors”](#runtime-errors) Raised when the compiled workflow executes in GitHub Actions. ### Time Delta Errors [Section titled “Time Delta Errors”](#time-delta-errors) The `stop-after` and similar fields accept relative deltas (`+24h`, `+3d`, `+1d12h30m`) and absolute dates (`2025-12-31`, `December 31, 2025`). | Error | Fix | | ----------------------------------------------- | --------------------------------------------------------------------------------------- | | `invalid time delta format: ...` | Use supported units: `h` (minimum), `d`, `w`, `mo` | | `minute unit 'm' is not allowed for stop-after` | Convert minutes to hours, rounding up (e.g., `+2h` instead of `+90m`) | | `time delta too large: ...` | Stay within: 12 months, 52 weeks, 365 days, 8760 hours | | `duplicate unit '[unit]' in time delta` | Combine values for the same unit (e.g., `+3d` instead of `+1d2d`) | | `unable to parse date-time: ...` | Use a supported format like `2025-12-31 23:59:59`, `December 31, 2025`, or `12/31/2025` | ### Other Runtime Errors [Section titled “Other Runtime Errors”](#other-runtime-errors) | Error | Fix | | ------------------------- | --------------------------------------------------------------------------------- | | `jq not found in PATH` | Install `jq` — Ubuntu/Debian: `sudo apt-get install jq`; macOS: `brew install jq` | | `authentication required` | Run `gh auth login`, or ensure `GITHUB_TOKEN` is available in Actions | ## Engine-Specific Errors [Section titled “Engine-Specific Errors”](#engine-specific-errors) | Error | Fix | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `manual-approval value must be a string` | Use a string: `manual-approval: "Approve deployment to production"` | | `invalid frontmatter key 'triggers:'` | Use `on:` instead of `triggers:` to match standard GitHub Actions syntax — see [Triggers](/gh-aw/reference/triggers/) | | `invalid on: section format` | Follow [GitHub Actions syntax](/gh-aw/reference/triggers/) (e.g., `on: push`, `on: { push: { branches: [main] } }`) | ## File Processing Errors [Section titled “File Processing Errors”](#file-processing-errors) | Error | Fix | | -------------------------------------------------------------- | -------------------------------------------------------------- | | `failed to read file ...` | Verify the file exists, is readable, and the disk is not full | | `failed to create .github/workflows directory` | Check filesystem permissions and disk space | | `workflow file '...' already exists. Use --force to overwrite` | Re-run with `--force` (e.g., `gh aw init my-workflow --force`) | ## MCP Configuration Errors [Section titled “MCP Configuration Errors”](#mcp-configuration-errors) | Error | Fix | | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `failed to parse existing mcp.json: ...` | Validate JSON (`cat .github/mcp.json \| jq .`) or delete to regenerate | | `failed to marshal mcp.json: ...` | Internal error — report with reproduction steps | | `http MCP tool '...' missing required 'url' field` | Add `url:` to the HTTP MCP server configuration | | `unable to determine MCP type for tool '...'` | Specify at least one of `type`, `url`, `command`, or `container` | | `tool '...' mcp configuration cannot specify both 'container' and 'command'` | Use either `container:` or `command:`, not both | | `tool '...' mcp configuration with type 'http' cannot use 'container' field` | Remove `container:` from HTTP MCP servers (only valid for stdio) | ## Strict Mode Errors [Section titled “Strict Mode Errors”](#strict-mode-errors) Strict mode is the default. To opt out, use `gh aw compile` without `--strict` and avoid `strict: false` in frontmatter — see [Strict Mode](/gh-aw/reference/frontmatter/#strict-mode-strict). | Error | Fix | | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `'network' configuration is required` | Add `network: defaults`, explicit allowed domains, or `network: {}` to deny all | | `write permission 'contents: write' is not allowed` | Use [safe outputs](/gh-aw/reference/safe-outputs/) (e.g., `create-issue`, `create-pull-request`) instead of write permissions | | `wildcard '*' is not allowed in network.allowed domains` | Use specific domains, wildcard patterns (`*.cdn.example.com`), or ecosystem identifiers (`python`, `node`) | | `custom MCP server '...' with container must have network configuration` | Add `network:` with allowed domains to containerized MCP servers | | `engine does not support firewall` | Use an engine with firewall support (e.g., `copilot`), or remove `--strict` | | `This workflow is running on a public repository but was not compiled with strict mode.` | Recompile with `gh aw compile --strict` | ## Safe Output & Workflow Errors [Section titled “Safe Output & Workflow Errors”](#safe-output--workflow-errors) | Error | Fix | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `cannot use 'command' with 'issues' in the same workflow` | Remove the conflicting event trigger — `command:` auto-handles these events. Use `events:` inside the command to restrict scope | | `workflow uses safe-outputs.create-issue but repository ... does not have issues enabled` | Enable the feature in Settings → General → Features, or use a different safe output | | `job name cannot be empty` | Internal error — report with your workflow file | ## Toolset Configuration [Section titled “Toolset Configuration”](#toolset-configuration) ### Tool Not Found After Migrating to Toolsets [Section titled “Tool Not Found After Migrating to Toolsets”](#tool-not-found-after-migrating-to-toolsets) The tool may be in a different toolset, or you chose a narrower one. Check [GitHub Toolsets](/gh-aw/reference/github-tools/), run `gh aw mcp inspect ` to list available tools, then add the required toolset. ### Invalid Toolset Name [Section titled “Invalid Toolset Name”](#invalid-toolset-name) `invalid toolset: '...' is not a valid toolset` — valid names: `context`, `repos`, `issues`, `pull_requests`, `users`, `actions`, `code_security`, `discussions`, `labels`, `notifications`, `orgs`, `projects`, `gists`, `search`, `dependabot`, `experiments`, `secret_protection`, `security_advisories`, `stargazers`, `default`, `all`. ### Toolsets and Allowed Conflict [Section titled “Toolsets and Allowed Conflict”](#toolsets-and-allowed-conflict) When both `toolsets:` and `allowed:` are specified, `allowed:` restricts tools to only those listed within the enabled toolsets. Prefer using only `toolsets:`: ```yaml # Recommended tools: github: toolsets: [issues] # Advanced: restrict within toolset tools: github: toolsets: [issues] allowed: [create_issue] ``` ### GitHub MCP Server Read-Only Enforcement [Section titled “GitHub MCP Server Read-Only Enforcement”](#github-mcp-server-read-only-enforcement) `GitHub MCP server read-only mode cannot be disabled` — the GitHub MCP server is always read-only. Remove `read-only: false` (or set it to `true`). Use [safe outputs](/gh-aw/reference/safe-outputs/) for write operations. ## Troubleshooting Tips [Section titled “Troubleshooting Tips”](#troubleshooting-tips) * Use `--verbose` for detailed error information * Validate YAML syntax and file paths * Consult the [Frontmatter Reference](/gh-aw/reference/frontmatter-full/) * Compile frequently to catch errors early; use `--strict` to surface security issues * Add features incrementally ## Getting Help [Section titled “Getting Help”](#getting-help) If your error isn’t listed: 1. Re-run with `gh aw compile --verbose` 2. Search this page (Ctrl+F / Cmd+F) for keywords from the error 3. Use an agent with the [debug.md prompt](https://raw.githubusercontent.com/github/gh-aw/main/debug.md) to investigate failing runs 4. Review [workflow patterns](/gh-aw/patterns/issue-ops/) and [Common Issues](/gh-aw/troubleshooting/common-issues/) 5. [Report the issue on GitHub](https://github.com/github/gh-aw/issues)}}