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 evaluates conditions and safety guards, then either fires the workflow or records a block with the reason.

# Create a trigger via CLI
syn triggers register \
  --repo owner/my-repo \
  --event pull_request.opened \
  --workflow pr-review-v1 \
  --cooldown 60

Triggers include safety guards (concurrency, cooldown, daily limits, idempotency), condition operators for filtering events, built-in presets, and full observability: every fire and block is recorded and queryable.

Conditions

Triggers support fine-grained filtering with dot-notation field paths and comparison operators. Use conditions to whitelist specific contributors, exclude bots, filter by branch, skip draft PRs, and more. See Trigger Conditions for the full reference.

For the complete guide on triggers, conditions, guards, and observability, see Triggers.

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.

Self-healing works without a tunnel. check_run events are automatically detected via Checks API polling (~30-90s latency). A tunnel provides real-time delivery (~1s) and access to additional CI/CD events (workflow_run, check_suite, etc.).

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

Discovering Accessible Repositories

Once the GitHub App is installed, you can list all repositories it has access to:

syn github repos
syn github repos --installation <id>    # filter by a specific installation

This queries the GitHub API through your App's installation tokens and returns repository metadata (name, owner, visibility, default branch). Use it to verify that the App can see the repos you expect before setting up trigger rules.

Syntropic137 caches the list of installations locally and refreshes it on demand when repository information is requested and the cache is more than one hour old. No webhook or tunnel is required for this to work. If you add repositories to your GitHub App installation, they will appear in syn github repos within one hour, or sooner the next time the command triggers a refresh after the cache becomes stale.