Skip to content

Git Integration & Webhook Handling

Starform integrates with GitHub via a GitHub App (not OAuth). This gives fine-grained repo access control, scoped installation tokens, and webhook delivery.

Webhook security:

  • Every inbound webhook carries an X-Hub-Signature-256 HMAC-SHA256 signature computed with the app's webhook secret. Starbase verifies the signature on receipt and rejects any request failing verification with 401 Unauthorized. The webhook secret is stored in Starbase config, never exposed to logs.
  • Signature verification happens before any payload parsing. Malformed requests are rejected at the edge.

Deduplication:

  • GitHub retries webhooks on timeout or 5xx response. Without deduplication, retries cause duplicate builds.
  • Starbase maintains a webhook_deliveries table keyed on the X-GitHub-Delivery UUID. On receipt, Starbase checks for prior delivery of the same ID; if present, responds 200 OK without reprocessing.
  • Retention: rows older than 24 hours are pruned by nightly cron.

Push debouncing:

  • Rapid consecutive pushes to the same branch within a 5-second window collapse to a single build of the latest commit. Prevents wasted build minutes when a developer pushes 3 commits in a row.
  • Implemented via a debounce job in Starbase Worker: on push, enqueue a build job with scheduled_for = NOW() + 5s. If a second push to the same (service, branch) arrives before the scheduled time, the earlier job is cancelled and a new one is scheduled for the latest commit.

Installation lifecycle events:

Starbase handles the following GitHub App installation events:

Event Action
installation.created Record installation, link to user account via install flow state
installation.deleted Mark all services using this installation as broken, notify owner, stop webhook processing for the installation's repos
installation.suspend Temporarily disable deploys from this installation's repos; preserve data
installation.unsuspend Re-enable deploys
installation_repositories.added Update accessible repo list
installation_repositories.removed If removed repo is used by a service, mark service as broken, notify owner
push Enqueue build job (with debounce, as above)

Stale/revoked installation detection:

  • Before every build, Starbase requests a fresh installation access token (GitHub tokens expire after 1 hour). If the token request fails with 404 (uninstalled) or 401 (suspended/revoked), Starbase marks the service as broken and notifies the owner via dashboard + email.
  • Out-of-band detection: a nightly cron refreshes all installations' tokens. Failures mark services broken.

GitHub API rate limiting:

  • GitHub App installations have 5,000 requests/hour per installation. Starbase uses exponential backoff on 403 rate-limit responses (base 1s, max 60s, 5 retries).
  • Starbase caches repo listings for 5 minutes to reduce API load during repo-selection UX flows.

Cross-references

The push → webhook → enqueue entry point of the build flow → §16.2 · the GitProvider integration interface and GitHub-only MVP → Starbase §11 · the API binary that receives and validates webhooks → Starbase §13 · the debounce job runs in the Worker → Starbase §14 · the build states a debounced/cancelled job moves through → §16.12.