github-agentic-workflows

GitHub Agentic Workflows Skill

Purpose

Guide creation, deployment, and governance of GitHub Agentic Workflows (gh-aw) — markdown-defined AI automations that run inside GitHub Actions with defense-in-depth security. Developed by GitHub Next and Microsoft Research, they augment deterministic CI/CD with Continuous AI capabilities.

When to Use

• ✅ AI-driven issue triage, PR review, documentation maintenance, code quality improvement
• ✅ Multi-agent orchestration with specialized workers
• ✅ Scheduled/event-driven repository analysis and reporting
• ✅ Continuous improvement workflows (code simplification, security scanning, metrics)
• ❌ Simple deterministic shell-script automation (use traditional GitHub Actions)
• ❌ Operations requiring 100% predictable execution paths

Architecture & Security Layers

GitHub Agentic Workflows enforce five security layers:

Event → [Sandboxed Agent (read-only, firewalled)] → Proposed Output (artifact)
  → Threat Detection (AI scan) → ✓ Safe → Write Job (scoped token) → GitHub API
                                → ✗ Suspicious → Blocked

Workflow Structure

Every workflow is a markdown file with YAML frontmatter + natural language body:

---
on:
  schedule: daily          # or: issue, pull_request, discussion, workflow_dispatch, etc.
timeout-minutes: 10
permissions:
  contents: read
  issues: read
tools:
  github:
    toolsets: [issues, pull_requests, repos]
safe-outputs:
  create-issue:
    title-prefix: "[report] "
    labels: [automated, daily]
    max: 1
    close-older-issues: true
---

# Daily Repository Status Report

Analyze recent activity and create a summary issue.

## Instructions
- Review open issues, merged PRs, and recent commits
- Highlight blockers and achievements
- Provide actionable next steps for maintainers

The gh aw compile CLI generates a .lock.yml GitHub Actions workflow from this markdown.

AI Engines

Set engine in frontmatter: engine: claude

Triggers (on:)

Tools Configuration

GitHub Tools (MCP-based)

tools:
  github:
    toolsets: [issues, pull_requests, repos, code_search, actions, security]
    min-integrity: approved   # or: none (for public repos processing external contributors)

Available toolsets: issues, pull_requests, repos, code_search, actions, security, labels, discussions, projects, users, notifications, stars, gists

Custom MCP Servers

tools:
  mcp:
    brave-search:
      command: npx -y @anthropic/mcp-brave-search
      env:
        BRAVE_API_KEY: ${{ secrets.BRAVE_API_KEY }}

Integrity Filtering

Controls which users' content the agent can see. Critical for public repositories:

Safe Outputs

Safe outputs are the only way agents write to GitHub. Each type has hard constraints:

Issue Operations

safe-outputs:
  create-issue:
    title-prefix: "[auto] "    # Required prefix (prevents impersonation)
    labels: [automated]         # Allowed labels only
    max: 3                      # Hard limit per run
    close-older-issues: true    # Auto-close previous issues with same prefix
  add-labels:
    allowed: [bug, feature, enhancement, documentation, question]
  add-comment: {}               # Allow commenting on issues

PR Operations

safe-outputs:
  create-pull-request:
    title-prefix: "[auto] "
    max: 1
    branch-prefix: "auto/"
    labels: [automated]
    draft: true                 # Create as draft PR
  add-review-comment: {}

Discussion Operations

safe-outputs:
  create-discussion:
    category: "Reports"
    title-prefix: "[daily] "
    max: 1
    close-older-discussions: true

Permissions (Least Privilege)

permissions:
  contents: read          # Repository content (always read-only for agent)
  issues: read            # Issue data access
  pull-requests: read     # PR data access
  discussions: read       # Discussion access
  actions: read           # Workflow run data
  security-events: read   # Code scanning alerts

Write permissions are never granted to the agent — only to the safe output write job.

Network Permissions

Control outbound access from the agent container:

network:
  allowed-domains:
    - "api.github.com"
    - "*.githubusercontent.com"
    - "pypi.org"           # For Python package installs

All other domains are blocked by the AWF firewall.

Compilation & Deployment

# Install CLI
gh extension install github/gh-aw

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

# Compile markdown to lock file
gh aw compile

# Compile specific workflow
gh aw compile .github/workflows/my-workflow.md

# List workflows
gh aw list

# Validate without compiling
gh aw validate .github/workflows/my-workflow.md

The .lock.yml file is the actual GitHub Actions workflow. Never edit it directly — always edit the .md source and recompile.

Workflow Gallery (Key Patterns)

Issue & PR Management

• Issue Triage Agent — Auto-label and comment on new issues
• PR Triage Agent — Categorize and assign PRs
• Plan Command (/plan) — Decompose issues into sub-tasks
• Auto-Assign Issue — Route issues to appropriate team members

Continuous Improvement

• Code Simplifier — Daily complexity reduction
• Repository Quality Improver — Holistic code quality analysis
• Code Refiner — Systematic refactoring suggestions
• Dead Code Removal Agent — Find and remove unused code

Documentation & Reporting

• Daily Issues Report — Team status summaries
• Documentation Healer — Fix stale docs and broken links
• Architecture Diagram Generator — Auto-generate C4/Mermaid diagrams
• Discussion Task Miner — Extract actionable tasks from discussions

Security & Quality

• Code Scanning Fixer — Auto-fix CodeQL/SAST findings
• Security Review Agent (/security) — On-demand security analysis
• CI Failure Doctor — Diagnose and suggest fixes for CI failures
• Malicious Code Scan — Daily security sweeps
• Breaking Change Checker — Detect API breaking changes

Metrics & Analytics

• Copilot Session Insights — ML analysis of agent behavior
• Prompt Clustering Analysis — Categorize agent prompts using ML
• Workflow Health Manager — Monitor agent success rates and costs

Multi-Repository

• Organization Health Report — Cross-repo analysis
• Feature Sync — Coordinate changes across repositories

Real-World Example: CIA Platform Issue Triage

---
on:
  issue:
    types: [opened, reopened]
timeout-minutes: 5
permissions:
  contents: read
  issues: read
tools:
  github:
    toolsets: [issues, repos, code_search]
    min-integrity: none
safe-outputs:
  add-labels:
    allowed: [bug, enhancement, documentation, security, performance, ui, data-integration]
  add-comment: {}
---

# CIA Platform Issue Triage

Analyze new issues for the Citizen Intelligence Agency platform.

## Context
This is a Java/Spring/Vaadin political intelligence platform monitoring Swedish parliament data.

## Instructions
1. Read the issue title and body carefully
2. Search the codebase for related files and patterns
3. Apply the most appropriate label from the allowed set
4. Comment with:
   - Brief analysis of the issue
   - Relevant code areas (module, package, class)
   - Suggested approach for resolution
   - Related issues if any exist

## Label Criteria
- `bug` — Incorrect behavior, crashes, data errors
- `enhancement` — New features or improvements
- `security` — Security vulnerabilities or hardening
- `performance` — Speed, memory, query optimization
- `ui` — Vaadin UI/UX improvements
- `data-integration` — External API or data pipeline issues
- `documentation` — Docs updates needed

Real-World Example: Daily Security Scan

---
on:
  schedule: "0 8 * * 1-5"
timeout-minutes: 15
permissions:
  contents: read
  security-events: read
  issues: read
tools:
  github:
    toolsets: [repos, security, issues, code_search]
safe-outputs:
  create-issue:
    title-prefix: "[security-scan] "
    labels: [security, automated]
    max: 1
    close-older-issues: true
---

# Daily Security Scan Report

Analyze repository security posture and create a summary.

## Instructions
1. Check code scanning alerts (CodeQL, Dependabot)
2. Review dependency vulnerabilities
3. Assess OWASP Top 10 exposure
4. Create a prioritized issue with findings and remediation steps
5. Reference ISO 27001, NIST CSF controls where applicable

Orchestration Patterns

Single Agent (Simple)

One workflow, one task. Best for focused automation.

Handoff Pattern

Agent A completes work, creates artifact → Agent B picks up and continues.

Reflection Pattern

Agent produces output → same or different agent reviews it → iterates until quality threshold met.

Plan-Execute Pattern (Most Powerful)

1. Plan: /plan command decomposes issue into sub-tasks
2. Execute: Copilot Coding Agent works on each sub-task
3. Review: PR review workflow validates changes
4. Merge: Human approves and merges

Labels and Organization

safe-outputs:
  add-labels:
    allowed: [agentic-workflow, automated, needs-review]

Use consistent label prefixes to track agentic work across the repository.

CLI Quick Reference

Testing Workflows

1. Validate syntax: gh aw validate .github/workflows/my-workflow.md
2. Compile: gh aw compile .github/workflows/my-workflow.md
3. Dry run: Trigger with workflow_dispatch on a test branch
4. Monitor: Check Actions tab for run status and logs
5. Review outputs: Verify safe output constraints were respected
6. Iterate: Refine instructions based on agent behavior

Integration with Hack23 ISMS

Applicable Controls

Documentation Requirements

• Update WORKFLOWS.md when adding/modifying agentic workflows
• Update SECURITY_ARCHITECTURE.md if workflows access security data
• Update THREAT_MODEL.md for new attack surfaces from agentic automation
• Track workflow costs and success rates in operational reviews

OWASP Agentic Security (Top 10 2026)

References

• Official docs: https://github.github.com/gh-aw/
• Abridged docs: https://github.github.com/gh-aw/llms-small.txt
• Full docs: https://github.github.com/gh-aw/llms-full.txt
• Blog series: https://github.github.com/gh-aw/_llms-txt/agentic-workflows.txt
• Quick Start: https://github.github.com/gh-aw/setup/quick-start/
• Creating Workflows: https://github.github.com/gh-aw/setup/creating-workflows/
• Safe Outputs Reference: https://github.github.com/gh-aw/reference/safe-outputs/
• Security Architecture: https://github.github.com/gh-aw/introduction/architecture/
• Engines Reference: https://github.github.com/gh-aw/reference/engines/
• GitHub Blog: https://github.blog/ai-and-ml/automate-repository-tasks-with-github-agentic-workflows/
• OWASP Agentic Top 10: https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/
• Hack23 Secure Development Policy: https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md