{"id":44940900,"url":"https://github.com/brendankowitz/gh-workflow-agents","last_synced_at":"2026-02-18T08:33:51.804Z","repository":{"id":336383293,"uuid":"1149032953","full_name":"brendankowitz/gh-workflow-agents","owner":"brendankowitz","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-04T16:15:04.000Z","size":636,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-04T16:36:50.029Z","etag":null,"topics":["ai","automation","copilot","devops","github-actions"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brendankowitz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-03T16:41:11.000Z","updated_at":"2026-02-04T16:22:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/brendankowitz/gh-workflow-agents","commit_stats":null,"previous_names":["brendankowitz/gh-workflow-agents"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/brendankowitz/gh-workflow-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendankowitz%2Fgh-workflow-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendankowitz%2Fgh-workflow-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendankowitz%2Fgh-workflow-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendankowitz%2Fgh-workflow-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brendankowitz","download_url":"https://codeload.github.com/brendankowitz/gh-workflow-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendankowitz%2Fgh-workflow-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29574019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T08:21:05.678Z","status":"ssl_error","status_checked_at":"2026-02-18T08:18:53.770Z","response_time":162,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","copilot","devops","github-actions"],"created_at":"2026-02-18T08:33:50.979Z","updated_at":"2026-02-18T08:33:51.798Z","avatar_url":"https://github.com/brendankowitz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/gh-agency-logo.svg\" alt=\"GH-Agency Logo\" width=\"350\"/\u003e\n  \u003ch1\u003eGH-Agency\u003c/h1\u003e\n  \u003cp\u003e\n    \u003cb\u003eReusable AI Workflow Agents for GitHub\u003c/b\u003e\n  \u003c/p\u003e\n  \u003cp\u003e\n    \u003ci\u003eAutomate product management, code review, research, and QA with intelligent agents\u003c/i\u003e\n  \u003c/p\u003e\n\n[![GitHub Actions](https://img.shields.io/badge/GitHub_Actions-2088FF?logo=github-actions\u0026logoColor=white)](https://github.com/features/actions)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-3178C6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![AI Powered](https://img.shields.io/badge/AI_Powered-Claude_Sonnet_4.5-orange)](https://www.anthropic.com/)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Security](https://img.shields.io/badge/Security-Defense_in_Depth-red)](docs/gh-agency.md#4-security-architecture)\n\n\u003c/div\u003e\n\n---\n\n\u003e **Status:** Active Development. GH-Agency provides production-ready AI agents for GitHub automation with enterprise-grade security controls. Built with a security-first architecture to defend against prompt injection and ensure safe autonomous operation.\n\n---\n\n## ✨ Overview\n\n**GH-Agency** is a suite of specialized AI agents packaged as reusable GitHub Actions. When installed on a repository, agents read `VISION.md` and `README.md` to understand their mission within their defined role, enabling any project to benefit from autonomous AI-driven workflows without building custom infrastructure.\n\n### Key Design Principles\n\n| Principle | Description |\n|-----------|-------------|\n| 🔄 **Reusable** | Install via standard GitHub Actions syntax with SHA-pinned references |\n| 🎯 **Context-Aware** | Agents ground decisions in repository-specific vision and documentation |\n| 🔒 **Secure by Default** | Defense-in-depth against prompt injection and privilege escalation |\n| 👤 **Human-in-the-Loop** | All critical actions require human approval |\n\n---\n\n## 🤖 Agent Personas\n\n### Product Manager Agent (Triage)\n\n**Role**: Custodian of project vision and primary interface for user interaction.\n\n- Issue triage and classification (bug, feature, question, spam)\n- Duplicate detection via semantic search\n- Vision alignment checking against `VISION.md`\n- State management via GitHub Labels\n\n```yaml\n- uses: brendankowitz/gh-workflow-agents/actions/triage-agent@\u003csha\u003e\n  with:\n    github-token: ${{ secrets.GITHUB_TOKEN }}\n    model: claude-sonnet-4.5\n```\n\n### Review Engineer Agent\n\n**Role**: Gatekeeper of code quality and security.\n\n- Semantic code review with inline comments\n- Security vulnerability detection\n- Dependabot PR auto-triage and merge (patches only)\n- Breaking change detection\n\n```yaml\n- uses: brendankowitz/gh-workflow-agents/actions/review-agent@\u003csha\u003e\n  with:\n    github-token: ${{ secrets.GITHUB_TOKEN }}\n    auto-approve-dependabot: 'true'\n```\n\n### Coding Agent\n\n**Role**: Autonomous code implementation from issues and PR feedback.\n\n- Implements features and bug fixes from triaged issues\n- Responds to code review feedback with iterative changes\n- Creates branches and pull requests automatically\n- Supports `/agent` slash commands for on-demand coding tasks\n- Graceful degradation: posts code as comments when push fails\n\n```yaml\n- uses: brendankowitz/gh-workflow-agents/actions/coding-agent@\u003csha\u003e\n  with:\n    github-token: ${{ secrets.GITHUB_TOKEN }}\n    copilot-token: ${{ secrets.COPILOT_GITHUB_TOKEN }}\n    app-token: ${{ steps.app-token.outputs.token }}\n    model: claude-sonnet-4.5\n```\n\n### Research Engineer Agent\n\n**Role**: Proactive environmental scanning and codebase health monitoring.\n\n- Dependency analysis and update impact assessment\n- Technical debt identification\n- Security advisory monitoring\n- Weekly \"State of the Code\" reports\n- Issue-focused research mode (triggered by triage agent)\n\n```yaml\n- uses: brendankowitz/gh-workflow-agents/actions/research-agent@\u003csha\u003e\n  with:\n    github-token: ${{ secrets.GITHUB_TOKEN }}\n    output-type: issue\n```\n\n### Consumer Agent (QA)\n\n**Role**: Consumer-driven contract testing in downstream repositories.\n\n- Integration test execution against new releases\n- Regression detection and reporting\n- Automatic issue creation in upstream repository on failure\n\n```yaml\n- uses: brendankowitz/gh-workflow-agents/actions/consumer-agent@\u003csha\u003e\n  with:\n    github-token: ${{ secrets.GITHUB_TOKEN }}\n    upstream-owner: owner\n    upstream-repo: repo\n```\n\n---\n\n## 🚀 Quick Start\n\n### 0. Repository Settings\n\nEnable these settings on your GitHub repository before installing the agent workflows:\n\n| Setting | Path | Why |\n|---------|------|-----|\n| **Allow auto-merge** | Settings → General → Pull Requests | Lets the review agent merge approved PRs automatically |\n| **Automatically delete head branches** | Settings → General → Pull Requests | Cleans up agent branches after merge |\n\n### 1. Install the Triage Agent\n\nCreate `.github/workflows/ai-triage.yml`:\n\n```yaml\nname: AI Issue Triage\non:\n  issues:\n    types: [opened, edited]\n  issue_comment:\n    types: [created]\n  workflow_dispatch:\n    inputs:\n      issue_number:\n        description: 'Issue number to triage'\n        required: true\n        type: number\n\nconcurrency:\n  group: ai-triage-${{ github.event.issue.number || github.event.inputs.issue_number }}\n  cancel-in-progress: true\n\njobs:\n  triage:\n    runs-on: ubuntu-latest\n    permissions:\n      issues: write\n      contents: read\n      actions: write\n    # Allow bot-created issues for autonomous pipelines, but skip dependabot\n    if: |\n      github.event_name == 'workflow_dispatch' || (\n        github.actor != 'dependabot[bot]' \u0026\u0026\n        !contains(github.event.comment.body || '', '/stop')\n      )\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '20'\n      - uses: brendankowitz/gh-workflow-agents/actions/triage-agent@main\n        env:\n          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}\n        with:\n          github-token: ${{ secrets.GITHUB_TOKEN }}\n          copilot-token: ${{ secrets.COPILOT_GITHUB_TOKEN }}\n          issue-number: ${{ github.event.inputs.issue_number || '' }}\n          model: claude-sonnet-4.5\n```\n\n### 2. Add Repository Context\n\nCreate `VISION.md` to guide agent decisions:\n\n```markdown\n# Project Vision\n\n## Core Principles\n1. Performance over feature density\n2. Minimal dependencies\n3. Security first\n\n## Architectural Constraints\n- All handlers must be registered via DI\n- Maximum 300 lines per file\n\n## Non-Goals\n- GUI tooling\n- Legacy runtime support\n```\n\n### 3. Pin to Commit SHAs (Recommended)\n\n```yaml\n# ❌ VULNERABLE — tags can be moved\n- uses: brendankowitz/gh-workflow-agents/actions/triage-agent@v1\n\n# ✅ SECURE — immutable reference\n- uses: brendankowitz/gh-workflow-agents/actions/triage-agent@a1b2c3d4e5f6789...\n```\n\n---\n\n## 🔒 Security Architecture\n\nGH-Agency implements **defense in depth** with multiple security layers:\n\n### Input Sanitization\n\nAll user content is sanitized before reaching the LLM:\n\n```typescript\n// Detected patterns include:\n// - \"ignore previous instructions\"\n// - \"system prompt\" references\n// - \"you are now\" role overrides\n// - Unicode/steganographic injection\n```\n\n### Prompt Architecture\n\nSystem prompts establish clear trust boundaries:\n\n```markdown\n---BEGIN UNTRUSTED ISSUE CONTENT---\n{sanitized_content}\n---END UNTRUSTED ISSUE CONTENT---\n```\n\n### Tool Permission Restriction\n\nAgents receive minimal tool access—read-only by default.\n\n### Output Validation\n\nAll LLM outputs are validated against allowlists:\n\n- Labels validated against permitted set\n- Priorities validated against enum\n- Shell metacharacters stripped\n- Content length enforced\n\n### Loop Prevention\n\nBuilt-in circuit breaker prevents runaway agents:\n\n- Maximum iteration limits (5)\n- Dispatch depth tracking (3)\n- Repetitive output detection\n- Bot actor filtering\n\n---\n\n## 📦 Repository Structure\n\n```\ngh-workflow-agents/\n├── actions/\n│   ├── triage-agent/       # Issue classification \u0026 routing\n│   ├── coding-agent/       # Autonomous code implementation\n│   ├── review-agent/       # Code review \u0026 auto-merge\n│   ├── research-agent/     # Health monitoring \u0026 research\n│   └── consumer-agent/     # Contract testing\n├── src/\n│   ├── shared/             # Shared utilities\n│   │   ├── sanitizer.ts    # Input sanitization\n│   │   ├── output-validator.ts\n│   │   ├── circuit-breaker.ts\n│   │   ├── github-app.ts   # GitHub App token generation\n│   │   └── types.ts\n│   ├── sdk/                # SDK wrappers\n│   │   ├── copilot-client.ts\n│   │   ├── github-api.ts\n│   │   └── context-loader.ts\n│   └── actions/            # Agent implementations\n├── examples/               # Example workflow files\n└── docs/\n    └── gh-agency.md        # Full specification\n```\n\n---\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Node.js 20+\n- npm or pnpm\n\n### Build\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Run tests\nnpm test\n\n# Type check\nnpm run typecheck\n\n# Bundle actions (REQUIRED after TypeScript changes)\n# GitHub Actions runs compiled JS from actions/*/dist/, not TypeScript\nnode scripts/bundle-actions.js\n```\n\n### Local Testing\n\n```bash\n# Set required environment variables\nexport GITHUB_TOKEN=your_token\nexport GITHUB_REPOSITORY=owner/repo\n\n# Run an agent\nnpx ts-node src/actions/triage-agent/index.ts\n```\n\n---\n\n## 📋 Context Files\n\nAgents automatically read these files to understand their mission:\n\n| File | Purpose | Required |\n|------|---------|----------|\n| `VISION.md` | Project goals, principles, and constraints | Recommended |\n| `README.md` | Project overview | Yes |\n| `CONTRIBUTING.md` | Contribution guidelines | Recommended |\n| `ROADMAP.md` | Feature priorities | Optional |\n| `ARCHITECTURE.md` | Technical patterns | Optional |\n\n---\n\n## 🔧 Configuration\n\n### Triage Agent\n\n| Input | Description | Default |\n|-------|-------------|---------|\n| `github-token` | GitHub token for API access | Required |\n| `copilot-token` | GitHub PAT for Copilot SDK | Optional |\n| `issue-number` | Issue number to triage (for `workflow_dispatch`) | — |\n| `model` | AI model to use | `claude-sonnet-4.5` |\n| `dry-run` | Only output analysis | `false` |\n| `enable-duplicate-detection` | Search for duplicates | `true` |\n| `enable-auto-label` | Auto-apply labels | `true` |\n\n### Coding Agent\n\n| Input | Description | Default |\n|-------|-------------|---------|\n| `github-token` | GitHub token for API access | Required |\n| `copilot-token` | GitHub PAT for Copilot SDK API calls | Required |\n| `app-token` | GitHub App token for elevated operations (workflow file pushes) | Optional |\n| `issue-number` | Issue number to implement (for `workflow_dispatch`) | — |\n| `pr-number` | PR number for review feedback (for `workflow_dispatch`) | — |\n| `model` | AI model to use | `claude-sonnet-4.5` |\n| `max-iterations` | Maximum REPL iterations | `5` |\n| `dry-run` | Plan only without executing changes | `false` |\n\n### Review Agent\n\n| Input | Description | Default |\n|-------|-------------|---------|\n| `github-token` | GitHub token for API access | Required |\n| `copilot-token` | GitHub PAT for Copilot SDK | Optional |\n| `pr-number` | PR number to review (for `workflow_dispatch`) | — |\n| `model` | AI model to use | `claude-sonnet-4.5` |\n| `mode` | `analyze-only` or `full` | `full` |\n| `auto-approve-dependabot` | Auto-approve Dependabot patches | `true` |\n| `security-focus` | Prioritize security analysis | `true` |\n| `auto-merge` | Auto-merge agent-coded PRs after approval | `true` |\n\n### Research Agent\n\n| Input | Description | Default |\n|-------|-------------|---------|\n| `github-token` | GitHub token for API access | Required |\n| `copilot-token` | GitHub PAT for Copilot SDK | Optional |\n| `model` | AI model to use | `claude-sonnet-4.5` |\n| `output-type` | `issue`, `wiki`, or `artifact` | `issue` |\n| `focus-areas` | Areas to analyze | `dependencies,security,technical-debt,industry-research` |\n| `create-actionable-issues` | Auto-create issues for recommendations | `false` |\n| `min-priority-for-issue` | Minimum priority for auto-created issues | `high` |\n| `issue-number` | Issue number for focused research (from triage) | — |\n| `mode` | `scheduled` or `issue-focused` | `scheduled` |\n\n---\n\n## 🔗 Autonomous Pipeline\n\nWhen all four workflow agents are installed, they form a self-maintaining pipeline:\n\n```\n┌──────────┐     ┌─────────┐     ┌──────────┐     ┌──────────┐\n│ Research  │────\u003e│ Triage  │────\u003e│  Coding  │────\u003e│  Review  │\n│  Agent   │     │  Agent  │     │  Agent   │     │  Agent   │\n└──────────┘     └─────────┘     └──────────┘     └──────────┘\n     │                │               │                 │\n     │           route-to-       assign-to-        approve \u0026\n     │           research         agent            auto-merge\n     │                │               │                 │\n     └────────────────┘               │            ┌────┘\n                                      │            │\n                                      ▼            ▼\n                                 changes_requested ──\u003e Coding Agent\n                                 (feedback loop)\n```\n\n**Flow**: Research finds gaps and creates issues → Triage evaluates and routes → Coding implements and creates PRs → Review approves/merges or requests changes → feedback loops back to coding.\n\nAgents chain via `workflow_dispatch` events using `actions/github-script`. Each agent's workflow includes a dispatch step to trigger the next agent in the pipeline (see [examples/](examples/)).\n\n### Label State Machine\n\nLabels coordinate agent handoffs:\n\n| Label | Meaning |\n|-------|---------|\n| `ready-for-agent` | Issue triaged and ready for coding agent |\n| `assigned-to-agent` | Coding agent is actively working |\n| `agent-coded` | PR created by coding agent, ready for review |\n| `needs-human-review` | Agent failed or needs human intervention |\n\n---\n\n## 🔑 Token Architecture\n\nAgents use up to three token types depending on the operation:\n\n| Token | Source | Used For |\n|-------|--------|----------|\n| `GITHUB_TOKEN` | Built-in | Most operations: commits, push, PR creation, issues. **Cannot** push `.github/workflows/` files. |\n| `COPILOT_GITHUB_TOKEN` | Repository secret (PAT) | Copilot SDK API calls only. Set as both `copilot-token` input and `COPILOT_GITHUB_TOKEN` env var. |\n| GitHub App token | `actions/create-github-app-token` | Elevated operations: approve PRs as a separate identity, push workflow files. Requires a GitHub App with `contents: write` and `workflows: write` permissions. |\n\n### GitHub App Setup (Optional)\n\nA GitHub App provides a separate bot identity for reviews and can push workflow files that `GITHUB_TOKEN` cannot:\n\n1. Create a GitHub App with **Contents: Write** and **Workflows: Write** permissions\n2. Install it on the target repository\n3. Add `GH_AGENCY_APP_ID` and `GH_AGENCY_PRIVATE_KEY` as repository secrets\n4. Use `actions/create-github-app-token` to generate tokens at runtime (see [examples/ai-coding.yml](examples/ai-coding.yml))\n\n### Workflow File Push Limitation\n\n`GITHUB_TOKEN` cannot push `.github/workflows/` files (GitHub security restriction). When the coding agent detects a push failure for workflow files, it:\n1. Posts the generated file contents as an issue comment for manual addition\n2. Cleans up labels (`assigned-to-agent` → `needs-human-review`)\n3. Prevents retry loops via comment-based failure detection\n\nTo enable automatic workflow file pushes, provide an `app-token` from a GitHub App with `workflows: write` permission.\n\n---\n\n## 💬 Slash Commands\n\nPost these as comments on issues or PRs to trigger the coding agent:\n\n| Command | Description |\n|---------|-------------|\n| `/agent fix [instructions]` | Fix review issues on a PR |\n| `/agent implement [instructions]` | Implement an issue |\n| `/agent update [instructions]` | Update code based on instructions |\n\nHuman comments on `agent-coded` PRs also trigger the coding agent automatically.\n\n---\n\n## 👤 Human-in-the-Loop Controls\n\n### Override Commands\n\nUsers can halt agent operations with special commands in comments:\n\n- `/stop` - Immediately halt agent processing\n- `/override` - Cancel pending agent actions\n- `/human` - Request human review, skip automation\n\n### Approval Gates\n\n| Operation | Approval Required |\n|-----------|-------------------|\n| Add labels | No |\n| Post comments | No |\n| Merge Dependabot patches | No (auto-approve) |\n| Merge agent-coded PRs | No (auto-merge after AI review) |\n| Merge human PRs | Yes (human or AI review) |\n| Create releases | Yes (human) |\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Code Standards\n\n- TypeScript strict mode\n- ESLint + Prettier formatting\n- Security-first design\n- Comprehensive type definitions\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\nGH-Agency builds on patterns and practices from:\n\n- [GitHub Copilot SDK](https://github.com/github/copilot-sdk)\n- [GitHub Actions Security Best Practices](https://docs.github.com/en/actions/security-guides)\n- [OWASP LLM Top 10 2025](https://owasp.org/www-project-top-10-for-large-language-model-applications/)\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eGH-Agency\u003c/b\u003e — Intelligent automation for the modern software development lifecycle.\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrendankowitz%2Fgh-workflow-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrendankowitz%2Fgh-workflow-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrendankowitz%2Fgh-workflow-agents/lists"}