SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsgithub-agentic-workflows

github-agentic-workflows

Deployment & operations

View repository

Updated 10-15 22:11

About this skill

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

ISMS Policy References

Core policies:

Supporting policies: