Github Agentic Workflows

GitHub Agentic Workflows Skill

Purpose

Comprehensive guidance for GitHub Agentic Workflows (gh-aw) — a Go-based GitHub CLI extension that enables writing agentic workflows in natural language using markdown files, compiled into GitHub Actions workflows with defense-in-depth security. Also covers Copilot coding agent orchestration, MCP server configuration, stacked PRs, and OWASP Agentic security.

When to Use

• ✅ Writing markdown-defined AI workflows (gh-aw) for automated repository tasks
• ✅ Orchestrating Copilot coding agent assignments with base_ref and custom_instructions
• ✅ Building multi-step agentic workflows with stacked PRs
• ✅ Configuring safe outputs, permissions, and AI engine selection
• ✅ Securing agentic pipelines against prompt injection and data exfiltration
• ✅ Implementing Continuous AI patterns (scheduled + event-triggered AI automation)

GitHub Agentic Workflows (gh-aw)

Overview

GitHub Agentic Workflows (gh-aw) augments deterministic CI/CD with Continuous AI — systematic, automated application of AI to software collaboration. Workflows are defined in markdown with YAML frontmatter and compiled to GitHub Actions via gh aw compile.

Key capabilities: Issue triage, CI failure diagnosis, documentation maintenance, code quality improvement, metrics/analytics, security scanning, multi-repo coordination, project planning.

Workflow Definition Format

---
timeout-minutes: 5
on:
  schedule: daily           # or cron: "0 9 * * 1-5", or event triggers
  issue:
    types: [opened, reopened]
permissions:
  contents: read
  issues: read
  pull-requests: read
tools:
  github:
    toolsets: [issues, labels, pull_requests, repos]
safe-outputs:
  create-issue:
    title-prefix: "[report] "
    labels: [automated, report]
    close-older-issues: true
  add-labels:
    allowed: [bug, feature, enhancement, documentation]
  add-comment: {}
  create-pull-request:
    title-prefix: "[auto] "
    max-changed-files: 5
---

# Workflow Title

Natural language instructions for the AI agent describing what to do.

## Context
- Repository-specific guidance
- What to analyze or act on

## Rules
- Constraints and boundaries
- Output format requirements

CLI Commands

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

# Add a workflow from the gallery
gh aw add-wizard https://github.com/github/gh-aw/blob/v0.45.5/.github/workflows/issue-triage-agent.md

# Compile markdown to GitHub Actions lock file
gh aw compile

# Run a workflow manually
gh aw run <workflow-name>

AI Engines

5-Layer Security Architecture

GitHub Event → [Isolated Container] → Proposed Output → Threat Detection → Write Job → GitHub API
                 ↑                        ↑                  ↑               ↑
            Read-only token         Structured artifact   AI-powered scan  Scoped write token
            Zero secrets            (not direct writes)   Prompt injection  Hard limits per op
            Network firewall                              Credential leak   Label constraints
            (AWF allowlist)                               Malicious code    Title prefixes

1. Read-only tokens — Agent receives read-only GitHub token; cannot push, create PRs, or delete
2. Zero secrets in agent — Write tokens/API keys exist only in isolated post-agent jobs
3. Containerized + network firewall — Agent Workflow Firewall (AWF) routes traffic through Squid proxy with domain allowlist; all other traffic dropped at kernel level
4. Safe outputs with guardrails — Agent produces structured artifact; separate gated job applies permitted actions with hard limits (max issues, required prefixes, label constraints)
5. Agentic threat detection — AI-powered scan checks for prompt injection, leaked credentials, malicious code before any output is applied

Safe Outputs Reference

safe-outputs:
  create-issue:
    title-prefix: "[auto] "          # Required prefix
    labels: [automated]               # Auto-applied labels
    close-older-issues: true           # Clean up previous runs
    max-issues: 1                      # Hard limit per run
  add-comment:
    max-comments: 3
  add-labels:
    allowed: [bug, feature, docs]      # Allowlist only
  create-pull-request:
    title-prefix: "[auto] "
    max-changed-files: 10
    labels: [automated]
  create-discussion:
    category: "Reports"

Integrity Filtering

By default, min-integrity: approved restricts visibility to owners/members/collaborators. For public repo triage that processes external contributor issues, set min-integrity: none in tools config. See Integrity Filtering.

Workflow Categories (Agent Factory Patterns)

Plan Command Pattern

The /plan command decomposes issues into actionable sub-tasks that Copilot coding agent can work on:

---
on:
  issue_comment:
    types: [created]
permissions:
  contents: read
  issues: read
tools:
  github:
    toolsets: [issues, repos]
safe-outputs:
  create-issue:
    title-prefix: "[plan] "
    labels: [planned]
---

# Plan Command

When a user comments `/plan` on an issue, analyze the issue and break it down
into 3-5 actionable sub-issues that can be independently implemented.

Copilot Coding Agent Orchestration

Assignment Methods

// Basic assignment via MCP tool
assign_copilot_to_issue({
  owner: "Hack23", repo: "European-Parliament-MCP-Server", issue_number: 100
})

// Feature branch assignment
assign_copilot_to_issue({
  owner: "Hack23", repo: "European-Parliament-MCP-Server",
  issue_number: 100,
  base_ref: "feature/new-tools",
  custom_instructions: "Use TypeScript strict mode. Follow MCP protocol. Add Vitest tests."
})

// Direct PR creation with custom agent
create_pull_request_with_copilot({
  owner: "Hack23", repo: "European-Parliament-MCP-Server",
  title: "Add new MCP tool", body: "Implementation details",
  base_ref: "main", custom_agent: "mcp-developer"
})

// Track progress
get_copilot_job_status({ owner: "Hack23", repo: "European-Parliament-MCP-Server", job_id: "abc123" })

Stacked PR Workflow

main ← PR 1: Data models
         ← PR 2: API client (base_ref: PR 1 branch)
              ← PR 3: MCP tools (base_ref: PR 2 branch)

Sequential Task Chaining

const step1 = await create_pull_request_with_copilot({
  owner: "Hack23", repo: "European-Parliament-MCP-Server",
  title: "Step 1: Data models", body: "Create TypeScript interfaces", base_ref: "main"
});

const step2 = await assign_copilot_to_issue({
  owner: "Hack23", repo: "European-Parliament-MCP-Server",
  issue_number: 200, base_ref: step1.branch,
  custom_instructions: "Build on models from PR #" + step1.pull_request_url.split('/').pop()
});

MCP Server Configuration

MCP server configuration is defined in .github/copilot-mcp.json. Secret references (${{ secrets.* }}) are resolved by the Copilot runtime. See .github/copilot-mcp.json for the canonical configuration.

Supply chain note: This repo uses the GitHub MCP Insiders HTTP endpoint (https://api.githubcopilot.com/mcp/insiders) as configured in .github/copilot-mcp.json. For projects that invoke @modelcontextprotocol/server-github via npx, pin it to a specific version in production to reduce supply chain risk when injecting privileged tokens.

OWASP Agentic Security

Resources

• GitHub Agentic Workflows Docs — Official documentation
• Quick Start — Installation and setup
• Agent Factory Gallery — 100+ example workflows
• Security Architecture — Defense-in-depth model
• Safe Outputs Reference — Output guardrails
• GitHub Blog: Agentic Workflows

ISMS Policy References

Core policies:

• AI Policy — Primary: Responsible AI automation, human oversight, provenance
• OWASP LLM Security Policy — Prompt-injection resistance, tool-abuse controls, safe outputs
• Secure Development Policy — Agentic PRs run the full secure-SDLC pipeline
• Information Security Policy — Governance and transparency
• Open Source Policy — Public audit trail of AI-assisted contributions

Supporting policies:

• Access Control Policy — Agent scopes, least-privilege tokens
• Change Management — Human PR review remains mandatory
• Privacy Policy — Prevent leakage of personal / confidential data in agent prompts and outputs