/gh-aw

name: gh-aw
description: >
  Create and maintain GitHub Agentic Workflows (gh-aw) for Prowler.
  Trigger: When creating agentic workflows, modifying gh-aw frontmatter, configuring safe-outputs,
  setting up MCP servers in workflows, importing Copilot Custom Agents, or debugging gh-aw compilation.
license: Apache-2.0
metadata:
  author: prowler-cloud
  version: "1.0"
  scope: [root]
  auto_invoke:
    - "Creating GitHub Agentic Workflows"
    - "Modifying gh-aw workflow frontmatter or safe-outputs"
    - "Configuring MCP servers in agentic workflows"
    - "Importing Copilot Custom Agents into workflows"
    - "Debugging gh-aw compilation errors"
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, WebFetch

When to Use

• Creating new `.github/workflows/*.md` agentic workflows
• Modifying frontmatter (triggers, permissions, safe-outputs, tools, MCP servers)
• Creating or importing `.github/agents/*.md` Copilot Custom Agents
• Debugging `gh aw compile` errors or warnings
• Configuring network access, rate limits, or footer templates

---

File Layout

.github/
├── workflows/
│   ├── {name}.md              # Frontmatter + thin context dispatcher
│   └── {name}.lock.yml        # Auto-generated — NEVER edit manually
├── agents/
│   └── {name}.md              # Full agent persona (reusable)
└── aw/
    └── actions-lock.json      # Action SHA pinning — commit this

See [references/](references/) for existing workflow and agent examples in this repo.

---

Critical Patterns

AGENTS.md Is the Source of Truth

Agent personas MUST NOT hardcode codebase layout, file paths, skill names, tech stack versions, or project conventions. All of this lives in the repo's `AGENTS.md` files and WILL go stale if duplicated.

**Instead**: Instruct the agent to READ `AGENTS.md` at runtime:

# In the agent persona:
Read `AGENTS.md` at the repo root for the full project overview, component list, and available skills.

For monorepos with component-specific `AGENTS.md` files, include a routing table that tells the agent WHICH file to read based on context — but never copy the contents of those files into the agent:

| Component | AGENTS.md | When to read |
|-----------|-----------|-------------|
| Backend   | `api/AGENTS.md`    | API errors, endpoint bugs |
| Frontend  | `ui/AGENTS.md`     | UI crashes, rendering bugs |
| Root      | `AGENTS.md`        | Cross-component, CI/CD |

**Why this matters**: Agent personas are deployed as workflow files. When `AGENTS.md` updates (new skills, renamed paths, version bumps), agents that READ it at runtime get the update automatically. Agents that HARDCODE it require a separate PR to stay current — and they won't.

Two-File Architecture

Workflow file = **config + context only**. Agent file = **all reasoning logic**.

The workflow imports the agent via `imports:` and passes sanitized runtime context. The agent contains the persona, rules, steps, and output format. This separation makes agents reusable across workflows.

Import Path Resolution

Paths resolve **relative to the importing file**, NOT from repo root:

# From .github/workflows/my-workflow.md:
imports:
  - ../agents/my-agent.md        # CORRECT
  - .github/agents/my-agent.md   # WRONG — resolves to .github/workflows/.github/agents/

Sanitized Context (Security)

NEVER pass raw `github.event.issue.body` to the agent:

${{ needs.activation.outputs.text }}

Read-Only Permissions + Safe Outputs

Workflows run read-only. Writes go through `safe-outputs`:

# GOOD
permissions:
  issues: read
safe-outputs:
  add-comment:
    hide-older-comments: true

# BAD — never give the agent write access
permissions:
  issues: write

Strict Mode

`strict: true` (default) enforces: no write permissions, explicit network config, no wildcard domains, ecosystem identifiers required. **IMPORTANT**: `strict: true` rejects custom domains in `network.allowed` — only ecosystem identifiers (`defaults`, `python`, `node`, etc.) are permitted. Workflows using custom MCP server domains (e.g., `mcp.prowler.com`) MUST use `strict: false`. This is an intentional tradeoff, not a development shortcut.

Footer Control

Prevent double footers with `messages.footer`:

safe-outputs:
  messages:
    footer: "> 🤖 Generated by [{workflow_name}]({run_url}) [Experimental]"

Variables: `{workflow_name}`, `{run_url}`, `{triggering_number}`, `{event_type}`, `{status}`.

MCP Servers

Always use `allowed` to restrict tools. Add domains to `network.allowed`:

network:
  allowed:
    - "mcp.prowler.com"

mcp-servers:
  prowler:
    url: "https://mcp.prowler.com/mcp"
    allowed:
      - prowler_hub_get_check_details
      - prowler_hub_get_check_code
      - prowler_docs_search

---

Security Hardening

Defense-in-Depth Layers (Workflow Author's Responsibility)

gh-aw provides substrate-level and plan-level security automatically. The workflow author controls configuration-level security. Apply ALL of the following:

| Layer | How | Why | |-------|-----|-----| | **Read-only permissions** | Only `read` in `permissions:` | Agent never gets write access | | **Safe outputs** | Declare writes in `safe-outputs:` | Writes happen in separate jobs with scoped permissions | | **Sanitized context** | `${{ needs.activation.outputs.text }}` | Prevents prompt injection from raw issue/PR body | | **Explicit network** | List domains in `network.allowed:` | AWF firewall blocks all other egress | | **Tool allowlisting** | `allowed:` in each `mcp-servers:` entry | Restricts which MCP tools the agent can call | | **Concurrency** | `concurrency:` with `cancel-in-progress: true` | Prevents race conditions on same trigger | | **Rate limiting** | `rate-limit:` with `max` and `window` | Prevents abuse via rapid re-triggering | | **Threat detection** | Custom `prompt` under `safe-outputs.threat-detection:` | AI scans agent output before