GitHub App Integration

Enable GitHub webhooks for automated task creation from @mentions, issue assignments, and label-based triggers.

Setup

1. Create a GitHub App
2. Set webhook URL: https://your-server.com/api/github/webhook
3. Generate a webhook secret

Required Permissions

• Issues: Read & Write
• Pull requests: Read & Write

Subscribe to Events

• Issues
• Issue comments
• Pull requests
• Pull request reviews
• Pull request review comments
• Check runs
• Check suites
• Workflow runs

Configuration

# Required for GitHub webhooks
GITHUB_WEBHOOK_SECRET=your-webhook-secret

# Optional: Bot name for @mentions (default: agent-swarm-bot)
GITHUB_BOT_NAME=your-bot-name

# Optional: Additional @mention aliases (comma-separated)
GITHUB_BOT_ALIASES=heysidekick,sidekick

# Optional: Labels that trigger agent action on PR/issue label events (comma-separated, default: swarm-review)
GITHUB_EVENT_LABELS=swarm-review

# Optional: Enable bot reactions (requires GitHub App)
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY=base64-encoded-key

# Optional: Disable GitHub integration
GITHUB_DISABLE=true

Runtime cancellation flags

GitHub unassign and review-request-removal events cancel the linked swarm task by default. You can disable either behavior independently through swarm_config without redeploying workers:

• github.cancelOnUnassign — controls PR/issue unassigned events
• github.cancelOnReviewRequestRemoved — controls PR review_request_removed events

Absent key, or any value other than "false", keeps the current cancel-on-event behavior. Setting the value to "false" leaves the task untouched and the handler returns { created: false }.

# Keep tasks alive when the bot is unassigned
agent-swarm set-config global github.cancelOnUnassign false

# Keep tasks alive when a review request is removed
agent-swarm set-config global github.cancelOnReviewRequestRemoved false

Supported Events

Suppressed Events (Safety Defaults)

The following events are suppressed by default to prevent cascade behavior where agents auto-merge PRs without meaningful human review:

• PR closed/merged — No automatic task creation on PR close
• PR synchronize (new commits pushed) — No automatic task on push
• PR review submitted — No automatic task from review events
• CI check failures (check_run, check_suite, workflow_run) — No automatic task from CI events

These events still emit to the internal workflowEventBus for workflow triggers, but do not create agent tasks.

Bot Reactions

If GitHub App credentials are provided (GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY), the bot can react to comments and issues with emoji to acknowledge receipt.

Eyes Reaction on Task Pickup

When an agent picks up a GitHub-sourced task (transitions to in_progress), a 👀 reaction is automatically added to the originating GitHub entity — the comment, issue, PR, or review that triggered the task. This gives immediate visual feedback that work has begun, without requiring the agent to post a comment.

Supported event types:

• Issue/PR comments — 👀 added to the comment
• PR review comments (inline) — 👀 added to the review comment
• PR reviews (body) — 👀 added via GraphQL (REST does not support review reactions)
• Issues/PRs (assigned or labeled) — 👀 added to the issue or PR itself

Worker Git Configuration

Workers need git credentials to create PRs and push code:

GITHUB_TOKEN=your-github-token    # For git operations
GITHUB_EMAIL=worker@example.com    # Git commit email
GITHUB_NAME=Worker Agent           # Git commit name

Related

• GitLab Integration — GitLab webhook support (same adapter pattern)
• Linear Integration — Bidirectional ticket tracking with Linear
• Environment Variables — GitHub configuration variables
• Task Lifecycle — How GitHub events become tasks
• Slack Integration — Another external task source
• Sentry Integration — Automated error triage from Sentry
• AgentMail Integration — Give agents email addresses