Hack23 Blacktrigram Github Agentic Workflows

GitHub Agentic Workflows Skill

Repository automation, running the coding agents you know and love, with strong guardrails in GitHub Actions. — gh-aw docs

Purpose

Ensures all gh-aw implementations follow best practices for agentic automation, defense-in-depth security, safe outputs, MCP integration, and Continuous AI. Enforces official patterns for AI-powered workflows running securely in GitHub Actions with isolation, permission separation, threat detection, and multi-engine support (Copilot, Claude, Codex, Gemini).

When to Apply

• Creating/modifying .github/workflows/*.md agentic workflow files
• Working with frontmatter configuration (YAML between --- markers)
• Implementing safe outputs or threat detection
• Configuring MCP servers, tools, or network permissions
• Implementing operational patterns (IssueOps, ChatOps, DailyOps, TaskOps, etc.)
• Using any AI engine: Copilot, Claude, Codex, or Gemini
• Managing workflow memory (cache-memory, repo-memory)
• Creating cross-repo, multi-PR, or stacked workflows

🔗 Related Skills

• security-architecture-validation - Security-by-design
• isms-compliance-checking - ISMS policy validation
• secure-development-lifecycle - SDLC integration

Core Principles

1. 🤖 Agentic vs Traditional Workflows

Agentic workflows use AI to understand context and make decisions through natural language. Traditional workflows execute fixed if/then logic.

---
on: issues
tools:
  github:
  edit:
---
# Analyze the issue content and suggest appropriate labels
# based on the technical domain and severity.

❌ Don't use procedural YAML: if: contains(github.event.issue.body, 'bug') → Use natural language instructions instead.

2. 📋 Workflow Structure

---
name: Workflow Name
on: trigger-events           # Required: when to run
permissions:                 # Required: least privilege (read-only)
  contents: read
engine: copilot              # AI engine: copilot | claude | codex | gemini
timeout-minutes: 30          # Prevent runaway costs
strict: true                 # Enforce security constraints
roles: [write, maintain]     # Who can trigger
tools:                       # What agent can use
  github:
    toolsets: [repos, issues]
  bash: ["git", "gh"]
network:                     # Network allowlist
  allowed: [defaults, github]
safe-outputs:                # Write operations (isolated jobs)
  create-issue:
    max: 1
threat-detection:            # Security scanning
  steps: [...]
---

# Natural Language Instructions
Clear, specific task description for the AI agent...

3. 🔐 Defense-in-Depth Security (5 Layers)

Event → Agent (read-only, sandboxed, firewalled) → Proposed Output (artifact)
  → Threat Detection (AI scan) → ✓ Safe Output Jobs (scoped write) → GitHub API
                                → ✗ Blocked

4. ✅ Safe Outputs: Permission Isolation

Core principle: Agent NEVER has direct write access. Writes go through isolated jobs.

Available Safe Outputs:

Configuration options: max (limit per run), expires (auto-close), title-prefix, labels, allowed (label allowlist), close-older-issues, github-token.

safe-outputs:
  create-issue:
    max: 1
    expires: 7d
    title-prefix: "[triage] "
    labels: [automation]
  add-labels:
    allowed: [bug, enhancement, documentation]
    max: 3
  create-pull-request:
    max: 1

5. 🔧 Tools & MCP Integration

GitHub Tools (Remote MCP)

tools:
  github:
    toolsets: [repos, issues, pull_requests, actions, code_security, discussions, projects]
    mode: remote           # Remote MCP (recommended) or local
    min-integrity: approved # Integrity filtering for public repos

Toolsets: context, repos, issues, pull_requests, actions, code_security, discussions, projects

Built-in Tools

tools:
  edit:                    # File editing
  bash: ["git", "gh"]     # Shell (specific commands only)
  web-fetch:               # HTTP GET requests
  web-search:              # Web search
  playwright:              # Browser automation
    allowed_domains: ["defaults", "github"]
  cache-memory:            # 7-day retention (Actions cache)
  repo-memory:             # Unlimited retention (Git branches)

Custom MCP Servers

mcp-servers:
  slack:
    command: "npx"
    args: ["-y", "@slack/mcp-server"]
    env:
      SLACK_BOT_TOKEN: "${{ secrets.SLACK_BOT_TOKEN }}"
    allowed: ["send_message"]

6. 🌐 Network Permissions & AWF Firewall

Default: No network access. Explicit allowlists required.

network:
  allowed:
    - defaults     # Certificates, JSON schema
    - python       # PyPI ecosystem
    - node         # npm ecosystem
    - github       # GitHub API/Pages
    - "api.example.com"  # Custom domain

Agent Workflow Firewall (AWF): Squid proxy enforces domain allowlist via iptables. All HTTP/HTTPS traffic routed through proxy. Unauthorized destinations blocked at kernel level.

7. 🎯 Operational Patterns (14 Patterns)

TaskOps is the highest-volume pattern: Plan Command drove 514 merged PRs (67% merge rate) via /plan decomposition.

8. 🔑 Authentication & Token Management

Token Precedence: safe-output token → global safe-outputs token → github-token → GH_AW_GITHUB_TOKEN secret → GITHUB_TOKEN

GitHub App (Recommended):

tools:
  github:
    app:
      app-id: ${{ vars.APP_ID }}
      private-key: ${{ secrets.APP_PRIVATE_KEY }}

9. 🚀 Multi-Engine Support

10. 🛡️ Threat Detection

threat-detection:
  prompt: |
    Check for infrastructure references, CI/CD modifications, security-sensitive changes
  steps:
    - name: Run TruffleHog
      run: trufflehog filesystem /tmp/gh-aw --only-verified
    - name: Run Semgrep
      run: semgrep scan /tmp/gh-aw/aw.patch --config=auto

11. 💾 Memory & Integrity

Cache Memory (7-day): cache-memory: — incremental processing and coordination. Repo Memory (unlimited): repo-memory: — trend analysis and historical context.

Integrity Filtering (public repos): min-integrity: approved restricts visibility to collaborators. Set min-integrity: none for public issue triage.

12. 🔄 Advanced Patterns

Cross-Repo PRs: Create PRs in other repositories using safe-outputs. Multi-PR Workflows: Create multiple related PRs in a single run. Stacked PRs: Build incremental changes using base_ref targeting. Workflow Calls: Chain workflows using workflow_call trigger.

Enforcement Rules

Rule 1: Workflow Structure

IF (creating workflow) THEN use .github/workflows/<name>.md + frontmatter + natural language + compile to .lock.yml

Rule 2: Security-First

IF (configuring workflow) THEN read-only permissions + safe outputs + strict: true + network allowlist + least privilege

Rule 3: Safe Outputs Required

IF (needs writes) THEN safe-outputs with max limits + threat detection; NEVER grant write permissions to agent job

Rule 4: Network Isolation

IF (needs external access) THEN network.allowed with specific domains/bundles; no wildcards in strict mode

Rule 5: MCP Server Security

IF (custom MCP) THEN tool filtering (allowed: []) + secrets via env + container isolation

Rule 6: Token Management

IF (using tokens) THEN secrets only (never hardcoded) + minimal scopes + prefer GitHub App

Rule 7: Operational Pattern

IF (implementing automation) THEN follow established OpPattern + document pattern + use appropriate triggers

Rule 8: Compilation

IF (modifying .md) THEN gh aw compile --strict + commit both .md and .lock.yml + validate

Anti-Patterns to REJECT

Required Patterns

✅ IssueOps Triage

---
timeout-minutes: 5
on:
  issue:
    types: [opened, reopened]
permissions:
  issues: read
tools:
  github:
    toolsets: [issues, labels]
safe-outputs:
  add-labels:
    allowed: [bug, feature, enhancement, documentation]
  add-comment: {}
---
# Issue Triage Agent
Analyze unlabeled issues, add labels, explain reasoning in comment.

✅ ChatOps with Slash Commands

---
on:
  slash_command:
    command: review
tools:
  github:
    toolsets: [repos, pull_requests, code_security]
safe-outputs:
  create-pull-request-review-comment:
    max: 10
---
# Security and quality review of the PR.

✅ DailyOps Continuous Improvement

---
on:
  schedule:
    - cron: "0 9 * * 1-5"
tools:
  github:
    toolsets: [repos, issues]
  bash: ["git", "find", "grep"]
safe-outputs:
  create-pull-request:
    max: 1
---
# Make small, incremental code quality improvements.

✅ TaskOps Multi-Phase (Highest-Volume Pattern)

---
on:
  issue_comment:
    types: [created]
tools:
  github:
    toolsets: [repos, issues]
safe-outputs:
  create-issue:
    max: 5
  link-sub-issue: {}
---
# /plan - Break down issue into actionable sub-tasks.

✅ MemoryOps Stateful Analysis

---
on: issues
tools:
  github:
  cache-memory:
  repo-memory:
safe-outputs:
  add-comment:
---
# Track issue trends: load history, analyze, update, report.

Compliance Framework

Remember

흑괘의 자동화 원칙 - Black Trigram Automation Principles

• 🤖 Agentic Intelligence - Natural language, context-aware AI decisions
• 🛡️ Security First - 5-layer defense-in-depth, never compromise isolation
• ✅ Safe by Default - Read-only agent, write through safe outputs only
• 🌐 Network Isolation - Explicit allowlists, AWF firewall enforcement
• 🔧 Tool Restriction - Minimal, purpose-specific tool and bash access
• 💾 Stateful Workflows - Memory tools for continuous improvement
• 🚀 Multi-Engine - Choose Copilot, Claude, Codex, or Gemini per task
• 🎯 Operational Patterns - Follow established patterns (14 OpPatterns)
• 🔄 Continuous AI - Systematic, automated AI application to collaboration

Every workflow is a step toward systematic AI collaboration.

Project: Black Trigram (흑괘) | Owner: Hack23 AB | License: MIT | Version: 2.0 Updated: 2026-04-02 | Docs: https://github.github.com/gh-aw/

Converted and distributed by TomeVault — claim your Tome and manage your conversions.