Gh Aw Operations Agent Skill

---
# ===== REQUIRED FIELDS =====
on:
  workflow_dispatch:
    inputs:
      parameter_name:
        description: 'Clear description of parameter'
        required: false
        type: string|boolean|choice|number
        default: "default_value"  # Boolean: "true"/"false" as strings
  schedule:
    - cron: '0 9 * * 1'  # Monday 9 AM UTC
  issues:
    types: [opened, labeled]
  pull_request:
    types: [opened, synchronize]

engine: copilot  # GitHub Copilot as AI engine

permissions:
  contents: read      # NEVER use write — strict mode blocks it
  pull-requests: read # All writes go through safe-outputs
  issues: read

# ===== TOOLS CONFIGURATION =====
tools:
  edit:              # bare key — enables file read AND edit
  bash:              # bare key — default safe commands
  github:
    toolsets: [pull_requests]  # Only include toolsets your workflow needs

# ===== MCP SERVERS (if needed) =====
mcp-servers:
  terraform:
    container: "hashicorp/terraform-mcp-server:0.5.1"
    env:
      TF_LOG: "INFO"
    allowed: ["*"]

# ===== SAFE OUTPUTS =====
safe-outputs:
  create-pull-request:
    title-prefix: "[automated] "
    labels: [automation]
    draft: true
    reviewers: [copilot]
    expires: 14
    fallback-as-issue: true
  create-issue:
    title-prefix: "[bot] "
    labels: [automation]
    expires: 7
  update-issue: null
  add-comment: null

# ===== NETWORK ACCESS =====
network:
  allowed:
    - defaults
    - registry.terraform.io
    - releases.hashicorp.com
    - api.github.com

# ===== IMPORTS (if using reusable agents/skills) =====
imports:
  - owner/repo/.github/agents/agent-name.agent.md@main
  - owner/repo/.github/skills/skill-name/SKILL.md@main
---

safe-outputs:
  create-pull-request:
    title-prefix: "[type] "
    labels: [automation, bot-generated]
    draft: true
    reviewers: [copilot]
    expires: 14  # Auto-close after 14 days
    fallback-as-issue: true  # Create issue if PR fails
    base-branch: main  # Target branch

safe-outputs:
  create-issue:
    title-prefix: "[report] "
    labels: [automation, needs-review]
    assignees: [copilot]
    expires: 7
    group: true  # Group multiple issues as sub-issues
    close-older-issues: true  # Close previous issues from same workflow

safe-outputs:
  add-comment:
    target: "triggering"  # Comment on triggering issue/PR
    max: 3
    hide-older-comments: true  # Hide previous comments from same workflow

safe-outputs:
  create-pull-request-review-comment:
    max: 10
    side: "RIGHT"
    footer: "if-body"  # Only show footer when review has body
  submit-pull-request-review:
    max: 1
    footer: false

safe-outputs:
  add-labels:
    allowed: [bug, enhancement, documentation]
    max: 3
  remove-labels:
    allowed: [needs-triage, stale]
    max: 3

mcp-servers:
  terraform:
    container: "hashicorp/terraform-mcp-server:0.5.1"
    env:
      TF_LOG: "INFO"
    allowed: ["*"]  # or specific tools

mcp-servers:
  azure:
    container: "mcr.microsoft.com/azure-sdk/azure-mcp:latest"
    env:
      AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

mcp-servers:
  custom:
    container: "your-org/your-mcp-server:v1.0.0"
    env:
      API_KEY: ${{ secrets.API_KEY }}
    allowed: ["specific_tool1", "specific_tool2"]

network:
  allowed:
    - defaults  # GitHub APIs
    - registry.terraform.io
    - releases.hashicorp.com
    - management.azure.com
    - custom-api.example.com

# Compile single workflow
gh aw compile workflow-name

# Compile all workflows
gh aw compile

# Force recompile
gh aw compile --force workflow-name

# Validate without compiling
gh aw validate workflow-name

tools:
  read: null   # ❌ 'read' is not a valid tool
  edit: null   # ❌ null not valid for edit
  edit: true   # ❌ true not valid for edit

tools:        # ✅ bare keys
  edit:
  bash:

permissions:
  contents: write       # ❌ blocked by strict mode
  pull-requests: write  # ❌ blocked by strict mode

permissions:           # ✅ read-only
  contents: read
  pull-requests: read
safe-outputs:          # ✅ write operations go here
  create-pull-request: null

on:
  pull_request:        # ❌ bare null not valid
  workflow_dispatch: null  # ❌ null not valid

on:
  workflow_dispatch:   # ✅ bare key
  pull_request:        # ✅ explicit types
    types: [opened, synchronize, reopened]

tools:
  github:
    toolsets: [default]  # includes 'issues' toolset
permissions:
  contents: read          # ❌ missing 'issues: read', compiler warns

tools:
  github:
    toolsets: [pull_requests]  # ✅ only what you need
permissions:
  contents: read
  pull-requests: read

tools: ['bash', 'read', 'edit']  # ❌ Wrong

tools:  # ✅ Correct
  bash:
  edit:

workflow_dispatch:
  inputs:
    enabled:
      type: boolean
      default: true  # ❌ Wrong

workflow_dispatch:
  inputs:
    enabled:
      type: boolean
      default: "true"  # ✅ Correct (quoted)

safe-outputs:
  create_pull_request: null  # ❌ Wrong (underscore)

safe-outputs:
  create-pull-request: null  # ✅ Correct (hyphen)

imports:
  - https://raw.githubusercontent.com/owner/repo/main/agent.md  # ❌ Wrong

imports:
  - owner/repo/.github/agents/agent.md@main  # ✅ Correct

safe-outputs: [create-issue, create-pull-request]  # ❌ Wrong (array)

safe-outputs:  # ✅ Correct (object)
  create-issue: null
  create-pull-request: null