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

Engine	Use Cases
copilot	General automation, code analysis, issue management
claude	Deep analysis, NLP, complex reasoning, documentation
codex	Code generation, refactoring, test writing

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)

Category	Examples	Trigger
Issue triage	Auto-label, auto-assign, auto-comment	on: issue
Continuous documentation	Doc healer, doc updater, glossary	schedule: daily
Code quality	Code simplifier, refiner, dead code removal	schedule: daily
CI/CD management	CI failure doctor, CI coach, CI cleaner	on: workflow_run
Security	Red team, secrets scan, code scanning fixer	schedule: daily
Metrics & analytics	Code metrics, session insights, NLP analysis	schedule: daily
Multi-repo	Feature sync, cross-repo tracking	schedule / workflow_dispatch
Project coordination	/plan command, discussion task miner	on: issue_comment

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

Threat	Mitigation
Prompt injection	Input validation, safe outputs, threat detection job, integrity filtering
Excessive agency	Read-only tokens, minimal permissions, safe output hard limits
Data exfiltration	AWF network firewall, domain allowlist, containerized sandbox
Supply chain	Pinned action SHAs, dependency scanning, zero secrets in agent
Credential theft	Zero secrets architecture, isolated write jobs

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