gh-aw-operations

# GitHub Agentic Workflows Operations Skill This skill provides expertise in creating, managing, and troubleshooting GitHub Agentic Workflows (gh-aw framework). ## When to Use - Creating new GitHub Agentic Workflows from scratch - Configuring frontmatter fields (triggers, permissions, tools, safe-outputs, MCP servers) - Debugging compilation errors or runtime failures in gh-aw workflows - Adding safe-outputs or network allowlists to existing workflows - Importing reusable agents and skills from external repositories - Testing and deploying workflows to GitHub Actions ## Skill 1: Frontmatter Configuration ### Description Configure workflow frontmatter with all required and optional fields following gh-aw specifications. ### Implementation Pattern ```yaml --- # ===== 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 --- ``` ### Key Rules - **`edit:` is a bare key** (no value) — enables both reading and writing files. `edit: null` and `edit: true` both fail compilation. - **`read:` is not a valid tool** — file reading is provided by `edit:`. - **`bash:` is a bare key** (no value) for default safe commands, or `bash: ["cmd"]` for specific commands. - **`contents: write` / `pull-requests: write` / `issues: write` are blocked by strict mode** — use `safe-outputs:` for all write operations instead. - **`pull_request:` trigger requires `types:`** — bare `pull_request:` fails compilation. - **`workflow_dispatch:` is a bare key** — `workflow_dispatch: null` fails compilation. - **Toolsets and permissions must align** — `toolsets: [default]` includes the `issues` toolset which requires `issues: read`; only declare the toolsets you actually need. - Boolean defaults must be strings: `default: "true"` not `default: true` - Safe-output fields use hyphens: `create-pull-request` not `create_pull_request` - Imports use `owner/repo/path@ref` format, not raw GitHub URLs - Safe-outputs can be bare key (default config) or object (custom config) --- ## Skill 2: Safe-Outputs Configuration ### Description Configure safe-outputs for GitHub operations (PRs, issues, comments) with proper validation and best practices. ### Common Safe-Output Patterns #### Pattern: Pull Request Creation ```yaml 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 ``` **When to use:** - Automated code changes - Dependency upgrades - Code generation - Refactoring #### Pattern: Issue Creation ```yaml 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 ``` **When to use:** - Reporting findings - Tracking tasks - Alerting on issues - Documentation requests #### Pattern: Issue/PR Comments ```yaml safe-outputs: add-comment: target: "triggering" # Comment on triggering issue/PR max: 3 hide-older-comments: true # Hide previous comments from same workflow ``` **When to use:** - Status updates - Analysis results - Bot responses - Progress reporting #### Pattern: PR Reviews ```yaml 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 ``` **When to use:** - Code review automation - Inline suggestions - Security analysis - Style checking #### Pattern: Label Management ```yaml safe-outputs: add-labels: allowed: [bug, enhancement, documentation] max: 3 remove-labels: allowed: [needs-triage, stale] max: 3 ``` **When to use:** - Workflow status tracking - Issue classification - Automation state management ### Available Safe-Output Types - `create-pull-request` - Create PRs with code changes - `create-issue` - Create issues - `update-issue` - Update issue title/body/status - `close-issue` - Close issues - `create-discussion` - Create discussions - `update-discussion` - Update discussions - `close-discussion` - Close discussions - `add-comment` - Add comments to issues/PRs/discussions - `hide-comment` - Hide comments - `add-labels` - Add labels - `remove-labels` - Remove labels - `add-reviewer` - Add PR reviewers - `create-pull-request-review-comment` - Add PR review comments - `submit-pull-request-review` - Submit PR review - `update-pull-request` - Update PR title/body - `dispatch-workflow` - Trigger other workflows - `create-project`, `update-project` - Manage GitHub Projects - `upload-asset` - Upload files to orphaned branch --- ## Skill 3: MCP Server Integration ### Description Configure and use Model Context Protocol (MCP) servers for specialized tool access. ### Common MCP Server Configurations #### Terraform MCP Server ```yaml mcp-servers: terraform: container: "hashicorp/terraform-mcp-server:0.5.1" env: TF_LOG: "INFO" allowed: ["*"] # or specific tools ``` **Available operations:** - Read Terraform configurations - Analyze provider versions - Detect breaking changes - Generate upgrade recommendations #### Azure MCP Server ```yaml mcp-servers: azure: container: "mcr.microsoft.com/azure-sdk/azure-mcp:latest" env: AZURE_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }} ``` **Available operations:** - Azure resource queries - Best practices validation - Documentation lookup - Terraform Azure integration #### Custom MCP Server ```yaml mcp-servers: custom: container: "your-org/your-mcp-server:v1.0.0" env: API_KEY: ${{ secrets.API_KEY }} allowed: ["specific_tool1", "specific_tool2"] ``` ### Network Configuration for MCP Servers ```yaml network: allowed: - defaults # GitHub APIs - registry.terraform.io - releases.hashicorp.com - management.azure.com - custom-api.example.com ``` --- ## Skill 4: Workflow Compilation & Debugging ### Description Compile workflows and resolve common compilation errors. ### Compilation Commands ```bash # 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 ``` ### Common Compilation Errors & Fixes #### Error: Invalid tool value for `edit` **Problem:** ```yaml tools: read: null # ❌ 'read' is not a valid tool edit: null # ❌ null not valid for edit edit: true # ❌ true not valid for edit ``` **Solution:** ```yaml tools: # ✅ bare keys edit: bash: ``` #### Error: Write permissions blocked by strict mode **Problem:** ```yaml permissions: contents: write # ❌ blocked by strict mode pull-requests: write # ❌ blocked by strict mode ``` **Solution:** ```yaml permissions: # ✅ read-only contents: read pull-requests: read safe-outputs: # ✅ write operations go here create-pull-request: null ``` #### Error: `pull_request` trigger requires `types` **Problem:** ```yaml on: pull_request: # ❌ bare null not valid workflow_dispatch: null # ❌ null not valid ``` **Solution:** ```yaml on: workflow_dispatch: # ✅ bare key pull_request: # ✅ explicit types types: [opened, synchronize, reopened] ``` #### Error: Missing permission for toolset **Problem:** ```yaml tools: github: toolsets: [default] # includes 'issues' toolset permissions: contents: read # ❌ missing 'issues: read', compiler warns ``` **Solution:** ```yaml tools: github: toolsets: [pull_requests] # ✅ only what you need permissions: contents: read pull-requests: read ``` #### Error: "got array, want object" for tools **Problem:** ```yaml tools: ['bash', 'read', 'edit'] # ❌ Wrong ``` **Solution:** ```yaml tools: # ✅ Correct bash: edit: ``` #### Error: Boolean default must be string **Problem:** ```yaml workflow_dispatch: inputs: enabled: type: boolean default: true # ❌ Wrong ``` **Solution:** ```yaml workflow_dispatch: inputs: enabled: type: boolean default: "true" # ✅ Correct (quoted) ``` #### Error: Invalid safe-output field name **Problem:** ```yaml safe-outputs: create_pull_request: null # ❌ Wrong (underscore) ``` **Solution:** ```yaml safe-outputs: create-pull-request: null # ✅ Correct (hyphen) ``` #### Error: Import download failed **Problem:** ```yaml imports: - https://raw.githubusercontent.com/owner/repo/main/agent.md # ❌ Wrong ``` **Solution:** ```yaml imports: - owner/repo/.github/agents/agent.md@main # ✅ Correct ``` #### Error: Safe-outputs format **Problem:** ```yaml safe-outputs: [create-issue, create-pull-request] # ❌ Wrong (array) ``` **Solution:** ```yaml safe-outputs: # ✅ Correct (object) create-issue: null create-pull-request: null ``` --- ## Extended Patterns & Reference For deployment, testing, troubleshooting, performance optimization, security best practices, and quick reference, see [references/GH-AW-PATTERNS.md](references/GH-AW-PATTERNS.md). ### Deployment Checklist