GitHub Integration

Syntropic137 integrates with GitHub through a GitHub App. This enables webhook-driven workflow automation — PRs opened, pushes to branches, issues labeled, and more can automatically trigger agent workflows.

Setting Up the GitHub App

The setup wizard handles GitHub App creation:

npx @syntropic137/setup github-app

This opens your browser to GitHub's App manifest flow:

You confirm the app creation on GitHub
GitHub redirects back with credentials
The CLI saves the App ID, private key (PEM), and webhook secret to ~/.syntropic137/secrets/
You choose which repositories the app can access

The entire flow takes about 30 seconds.

If you already ran npx @syntropic137/setup init, the GitHub App step was offered during initial setup. You can re-run it anytime with npx @syntropic137/setup github-app.

Trigger Rules

A trigger rule connects a GitHub event to a workflow. When a matching event arrives, Syntropic137 starts a workflow execution automatically.

# Create a trigger via CLI
syn trigger create \
  --repo owner/my-repo \
  --event pull_request.opened \
  --workflow pr-review-v1 \
  --daily-limit 20 \
  --cooldown 60

Safety Limits

Every trigger has built-in guards to prevent runaway execution:

Guard	Default	Purpose
`daily_limit`	50	Maximum executions per day per trigger
`cooldown`	30s	Minimum seconds between executions
`budget`	—	Maximum spend before pausing (optional)

These are enforced server-side and cannot be bypassed by webhook payloads.

Supported Events

Triggers can fire on any GitHub webhook event type:

push — commits pushed to a branch
pull_request.opened, pull_request.synchronize — PR activity
issues.labeled — issue triage
check_run.completed — CI results
workflow_run.completed — GitHub Actions completion
And any other GitHub webhook event

Event Delivery: Webhooks + Polling

Syntropic137 uses a hybrid approach for receiving GitHub events:

Webhooks are the primary path — real-time delivery from GitHub when your App has a reachable URL (via tunnel or public server).

Events API polling is the fallback — a background task polls GitHub's Events API on an adaptive interval. This enables zero-config onboarding without a tunnel.

GitHub's Events API does not include GitHub Actions webhook events (workflow_run, check_run, etc.). If you need to trigger workflows from Actions events, you must set up a tunnel for webhook delivery.

The system automatically deduplicates events using content-based keys (commit SHA, PR number, check run ID), so the same logical event is processed exactly once regardless of whether it arrived via webhook, polling, or both.

For a deep dive into the event pipeline, deduplication strategy, and polling configuration, see Event Ingestion.

Repository Installation

After creating the GitHub App, install it on your repositories:

Go to your GitHub App settings → Install App
Select the organization or personal account
Choose All repositories or select specific ones
Syntropic137 dynamically resolves installation IDs per repository — no reconfiguration needed when you add new repos