📰 What's New in the gh-aw world

Recent releases and notable changes in GitHub Agentic Workflows. Entries added in the last 14 days carry a NEW badge. This section is maintained by an agentic workflow: site-updater.md checks the gh-aw project weekly and opens a PR updating the JSON data below — the lab demoing itself. 🐕🦴

Sources watched: gh-aw releases · official docs · agentics samples

How It Works — from markdown to merged

Click each stage in the pipeline to explore what happens there. This is the full journey of an agentic workflow, from authoring to a gated write on GitHub.

The security flow at a glance

Repository + Prompt Input
   → Read-only Token          # agent job gets read-only GITHUB_TOKEN
   → No Secrets in Agent      # secrets never enter the agent container
   → Sandbox + Network Firewall (AWF)
   → Safe Outputs Gate        # structured JSON requests, validated
   → Threat Detection Scan    # scans agent output for injection/exfil
   → Scoped Write Job         # separate job with exactly the needed permission

This layered model is why an agent manipulated by prompt injection still can't push code, leak secrets, or spam issues beyond configured limits.

Anatomy of an Agentic Workflow

A realistic issue-triage workflow, line by line. Click any highlighted line to see what it does. The frontmatter configures the machinery; the markdown body is the agent's actual prompt.

AI Engines — pick your coding agent

The engine: frontmatter field selects which coding agent interprets your markdown. Switching agents is a one-line change plus the matching secret. Copilot is the default and supports the broadest gh-aw feature set.

Extended engine configuration

engine:
  id: copilot
  version: latest              # pin e.g. "0.5.1" for reproducible builds
  model: gpt-5                 # override the engine's default model
  agent: technical-doc-writer  # .github/agents/technical-doc-writer.agent.md
  args: ["--add-dir", "/workspace"]
  env:
    CUSTOM_API_ENDPOINT: https://api.example.com
  api-target: api.acme.ghe.com # GHEC/GHES custom API endpoint (hostname only)
  bare: false                  # true = skip AGENTS.md / memory / auto-context

Feature support notes

*max-turns (default 500) and max-ai-credits (default 1000) are top-level fields supported across engines; behavior nuances vary. See the engines reference for the authoritative matrix.

Custom agent personas — a library of specialists

With the Copilot engine, workflows can invoke different specialized agents defined as markdown files in .github/agents/. Each agent file sets its own instructions, tone, tools, and expertise. Other engines (Claude, Codex) can still use them — the body is injected as a prompt via imports:.

Pick a persona, then click any highlighted line of its agent file to see what it does.

Calling this persona from a workflow

Combine this with orchestration (next section) and one orchestrator can route work to a triage agent, a docs agent, and a security agent — each in its own workflow with its own scoped permissions. Agents can also be defined inline in the workflow markdown (see the Inline Sub-Agents reference).

Safe Outputs — writes without write permissions

The signature security idea of gh-aw. The agent runs read-only and emits structured JSON describing what it wants to do. After validation and threat scanning, a separate job — holding exactly one write permission — executes the request. Least privilege, prompt-injection defense, auditability, and hard per-operation limits, all by construction.

{
  "type": "create_issue",
  "title": "Triage: flaky parser test",
  "body": "Intermittent failure detected in CI...",
  "labels": ["bug", "flaky-test"]
}

Explore the safe output handlers

Select a handler on the left to see its purpose and a realistic configuration.

Power features worth demoing

Multi-Agent Orchestration — agents calling agents

One workflow (the orchestrator) decides what to do and fans work out to worker workflows, each with its own scoped permissions, tools, and even a different engine or custom agent. Two safe outputs make this possible: dispatch-workflow and call-workflow.

Option 1 — dispatch-workflow (async fan-out)

The orchestrator dispatches named workflows via GitHub's workflow_dispatch API. Workers run asynchronously as independent workflow runs and can outlive the parent.

# orchestrator.md
---
on:
  schedule: [{ cron: "0 6 * * 1" }]
safe-outputs:
  dispatch-workflow:
    workflows: [repo-triage-worker, dependency-audit-worker]
    max: 5
---

# Weekly Ops Orchestrator

Review open issues and dependency alerts. Split the work into units and
dispatch the right worker for each: use `repo-triage-worker` for unlabeled
issues, `dependency-audit-worker` for outdated dependencies. Pass a
`tracker_id` input so workers can report back to the same Project board.

The compiler validates at compile time that each target workflow exists and supports workflow_dispatch. Workers receive a JSON payload.

Option 2 — call-workflow (compile-time fan-out)

Workers are reusable workflows (workflow_call). The compiler generates a typed MCP tool per worker from its declared inputs and emits a conditional uses: job — no API call at runtime. The worker runs inside the same workflow run, preserving github.actor and billing attribution.

safe-outputs:
  call-workflow:
    workflows: [spring-boot-bugfix, frontend-dep-upgrade]

Which one should I use?

When to reach for OrchestratorOps

• Work spans multiple repositories or needs different tools/permissions per step
• Units of work benefit from parallel execution
• You want intermediate human review between phases
• Examples: multi-repo rollouts, phased dependency upgrades, initiative-level automation across many issues/PRs

Three ways "different agents" show up in gh-aw

Security & the AWF Sandbox

AI agents can be manipulated by prompt injection, malicious repository content, or compromised tools. gh-aw assumes this will happen and contains each run with layered controls. AWF — the Agent Workflow Firewall — is the default sandbox for the coding agent.

The six layers

Network permissions

AWF enforces a network allowlist. You compose it from ecosystem identifiers and custom domains:

network:
  allowed:
    - defaults          # basic infrastructure (GitHub, package proxies…)
    - python            # Python/PyPI ecosystem domains
    - node              # npm ecosystem
    - "api.example.com" # custom domain

Anything not on the list is blocked at egress — even if the agent is tricked into trying.

Sandbox configuration

sandbox:
  agent: awf                # default — Agent Workflow Firewall
  mcp-gateway:              # route all MCP calls via unified HTTP gateway
    api-key: "${{ secrets.MCP_GATEWAY_API_KEY }}"

# Disabling requires an audited, literal justification ≥ 20 chars:
sandbox:
  agent: false
features:
  dangerously-disable-sandbox-agent: "controlled environment with no internet access"

• AWF makes host binaries visible in the container — gh, language runtimes, anything from setup actions or apt-get
• Host PATH is captured as AWF_HOST_PATH and restored inside, so actions/setup-go/setup-python just work
• Boolean true justifications and ${{ }} expressions are rejected by the compiler — disabling the sandbox is deliberately noisy

Trigger-level guardrails

Tools & MCP — what the agent is allowed to touch

The tools: frontmatter declares which GitHub API operations, shell commands, browser automation, and MCP servers the agent may use. Everything is allowlist-based.

Built-in tools

tools:
  github:
    toolsets: [default]        # GitHub API operations (read scopes)
  edit:                        # file editing in the workspace
  bash: ["gh label list", "git status", "grep:*"]
  web-fetch:                   # fetch web content
  web-search:                  # engine-dependent
  playwright:
    version: "1.56.1"          # browser automation
  cache-memory:                # persistent memory across runs
  timeout: 300                 # seconds per tool call

Custom MCP servers

mcp-servers:
  slack:
    command: npx
    args: ["-y", "@slack/mcp-server"]
    env:
      SLACK_BOT_TOKEN: "${{ secrets.SLACK_BOT_TOKEN }}"
    allowed: ["send_message", "get_channel_history"]  # gateway-enforced

• Server types: command+args (process), container (Docker image), url+headers (HTTP)
• Always set allowed: — the MCP gateway filter is a real enforcement boundary, not a hint
• tools.cli-proxy: true mounts MCP servers as CLI commands on PATH (e.g. safeoutputs add_comment --item_number 42 --body "...") — saves tokens on big schemas

Composition: imports & skills

imports:
  - shared/tools.md            # reuse tools/steps/prompts across workflows

skills:                        # install Copilot skills (SHA-pinned!) pre-run
  - mattpocock/skills/tdd@801dca688564c529fa84f247f64472520d9ebe28

Imports merge tools, MCP servers, steps and prompt fragments from other files. Skills entries must be pinned to a 40-char commit SHA — supply-chain hygiene by design.

Authentication — org billing, PATs, Apps & WIF

Two distinct auth concerns in gh-aw: engine inference (paying for the AI) and GitHub operations (tokens for tools and safe outputs). Most workflows need just one engine credential — and with Copilot, the newest option needs no secret at all.

Copilot inference: two ways

permissions:
  contents: read
  copilot-requests: write   # ← that's it

# 1. Create fine-grained PAT (resource owner = YOUR user account)
#    Permissions → Account → Copilot Requests: Read
# 2. Store it:
gh aw secrets set COPILOT_GITHUB_TOKEN --value "<your-pat>"

All engine credentials

# Fastest path: analyze workflows, detect engines, prompt for missing secrets
gh aw secrets bootstrap

# Or set individual secrets
gh aw secrets set ANTHROPIC_API_KEY --value "sk-ant-..."
gh aw secrets list

Beyond inference: GitHub operations

Tools and safe outputs use the workflow's GITHUB_TOKEN by default. You need additional auth for: reading multiple repos, reading Projects, GitHub tools remote mode, cross-repo safe outputs, or outputs that must trigger CI on created PRs.

custom github-token
  → secrets.GH_AW_GITHUB_TOKEN
    → secrets.GITHUB_TOKEN

github-app:
  client-id: ${{ vars.APP_ID }}
  private-key: ${{ secrets.APP_PRIVATE_KEY }}
  owner: "my-org"
  repositories: [repo1, repo2]

permissions:
  id-token: write
engine:
  id: claude
  auth:
    federation-rule-id: fdrl_xxx
    organization-id: org_xxx
    service-account-id: svac_xxx
    workspace-id: ws_xxx

Troubleshooting quick hits

CLI Reference — the gh aw lifecycle

Commands organized by lifecycle: create → build → test → monitor → manage. Filter by phase below.

Workflow Builder — compose your own

Pick options on the left; the generated agentic workflow markdown updates live on the right. Copy it into .github/workflows/my-workflow.md and run gh aw compile.

Run Simulator — watch a run travel the guardrails

A simulated end-to-end run of an issue-triage agentic workflow. Press play and narrate each stage during your demo — including the moment the safe-outputs gate blocks an over-limit request.

Run log

Examples Gallery — real-world patterns

Complete, copy-ready workflows for common scenarios. Many of these mirror the public githubnext/agentics sample collection (installable via gh aw add githubnext/agentics/<name>).

Quick Start — first run in ~10 minutes

Install a pre-baked workflow (the Daily Repo Status Report) into a repo you maintain and watch it file its first issue.

Prerequisites

• AI account — GitHub Copilot (easiest, no extra account), Anthropic, OpenAI, or Google Gemini
• A GitHub repository with write access and Actions enabled
• GitHub CLI v2.0.0+, logged in: gh auth login --scopes repo,workflow
• Linux, macOS, or Windows with WSL

Steps

# 1. Install the extension
gh extension install github/gh-aw

# 2. Add a sample workflow with the interactive wizard
gh aw add-wizard githubnext/agentics/daily-repo-status
#    — checks prerequisites, lets you pick an engine,
#      sets up the secret, adds .md + .lock.yml, offers a first run

# 3. Watch it
gh aw status
gh run watch

# 4. Customize: edit .github/workflows/daily-repo-status.md, then
gh aw compile
gh aw run daily-repo-status

Engine secret cheat-sheet

Set with: gh secret set COPILOT_GITHUB_TOKEN < token.txt or gh aw secrets bootstrap (analyzes workflows and prompts for what's missing).

Where to go next