Skip to content
DashboardWebsite

GitHub App Integration

GitHub webhooks trigger repository updates, comment feedback, and pull request reviews. This page describes how OpenTremor verifies GitHub deliveries and reviews pull requests. For setup steps, see the GitHub App integration guide.

sequenceDiagram
    participant GH as GitHub
    participant WH as POST /integrations/github/webhook
    participant Job as queued job (review.py)
    participant LLM as LLM provider

    GH->>WH: pull_request opened/synchronize/reopened/ready_for_review (signed)
    WH->>WH: look up integration by installation.id (or installation.app_id for a new App)
    WH->>WH: none matched → 200 ignored, else verify X-Hub-Signature-256 against that integration's secret
    WH->>WH: enqueue_pull_request_review() — record_pull_request_repository(), start_revision(head SHA)
    WH-->>GH: 202 {job_id}
    WH->>Job: scm.pull_request job — any replica's worker runs it
    Job->>Job: resolve_review() — repository and product teams, else the default review team
    Job->>GH: via GitHubScmRepository: installation token, fetch PR diff
    Job->>LLM: run_analysis_auto() — auto-route each changed file, see above
    Job->>Job: record_variant_suggestions(), scan_change(), tier 2 scoring when on, record_detections() (agent injection)
    Job->>Job: build_report_data(), resolve_and_render()
    Job->>GH: upsert_pr_comment() — edit the one report comment in place
    Job->>Job: record_pr_gate() — remember provider/repo/SHA/locator/teams
    Job->>GH: post commit status
    Job->>Job: notify pr.gate_blocked when the status is failure or pending

A triage action updates the same check without another push:

sequenceDiagram
    autonumber
    participant U as dashboard / API
    participant F as PATCH /v1/findings/{hash}/{rule_id}
    participant H as GitHub / GitLab

    U->>F: acknowledge / suppress / reopen
    F->>F: storage.update_finding_status(), record the review feedback
    F->>F: pr_gate.refresh_pr_gates_for_resource()
    F->>H: re-post the commit status for every gated changeset
    F->>H: edit the report comment, if one exists
    F-->>U: 200 (best-effort: a code-host failure never fails the triage)

Each organization registers its own GitHub App. There is no platform-wide App (OpenTremor-core#0029).

  • Manifest flow. POST /v1/orgs/{org_id}/integrations/github/manifest checks the LLM connection, model, and App name, then mints a short-lived, single-use state token (github_manifest_states, using the same “opaque token + SHA-256 hash + explicit expiry check” pattern as report_links) that also carries the LLM settings. The admin’s browser submits a top-level form to github.com. GitHub redirects back to the public GET /integrations/github/manifest/callback, which resolves state, exchanges the one-time code via GitHub’s POST /v1/app-manifests/{code}/conversions (libs/github_client.exchange_manifest_code), and creates the org’s integrations doc: the App ID, private key, and webhook secret (github_app, encrypted with Fernet in libs/crypto.py, like stored LLM credentials), and the LLM settings.
  • Installation. The installation_id comes only from the signed installation created webhook. No request body carries it, and a unique partial index on (provider, installation_id) keeps one integration per installation. A pasted id would let one organization claim another’s installation.
  • App name. GitHub App names are unique across GitHub and at most 34 characters. github_app_name() generates opentremor-<org name>-<6 hex>. An admin-chosen name goes through check_app_name(): this deployment’s github_app.app_slug values, then GitHub’s unauthenticated GET /v1/apps/{name} and GET /v1/users/{name}.

services/integrations/github_app.py’s webhook_secret_for/github_client_for read the org’s github_app for every webhook signature check and every outbound call. The webhook identifies which integration’s secret to try from the still-unverified payload (via installation.id, or installation.app_id for a new App’s first event, before it has an installation_id). That is safe because it only selects a candidate to verify against: the HMAC check gates every effect. A delivery that matches no integration is answered 200 and ignored.

libs/github_client.py’s GitHubClient is a thin httpx wrapper with no GitHub SDK. It signs an RS256 JWT for the org’s App, exchanges it for a scoped installation token, fetches the PR diff, and posts a comment and commit status. The review job calls it through GitHubScmRepository (services/integrations/github_app.py), GitHub’s adapter for the code-host port described below. The status is failure if any open finding is CRITICAL or HIGH; it is pending if any finding has status needs_review, or if an untriaged HIGH/CRITICAL agent-injection finding is holding the merge; otherwise, it is success. That mapping lives in services/integrations/pr_gate.py::compute_gate_state(), not in the review job, because two callers use it.

Triage is the second caller. A commit status is a push, not a poll. GitHub keeps the last status written to a SHA, so acknowledging or suppressing a finding in the dashboard re-posts the check for the same commit. The PR then clears without another push. The job records where it posted in pr_gates immediately before posting. This makes the status update addressable; see Clearing a held check.

The PR diff is passed to content_router.run_analysis_auto() (see Auto-routing above). A repository with no pack enabled never gets here: its pull request gets a pending status and no job. Routing sends each changed file to an enabled pack whose file_globs matches it. A file no glob claims goes to the pack whose sniff() recognises its added lines. terraform-plan declares no file_globs, so a PR diff reaches it only when a changed file contains terraform plan output. The job document’s pack field is the literal "auto", while packs_used and detections carry the actual breakdown. This also fixed a real gap: before auto-routing, the webhook always called terraform-code-change directly. Its parser silently dropped every non-.tf file in the diff without recording that in the job.

One review pipeline, one adapter per code host

Section titled “One review pipeline, one adapter per code host”

The review does not belong to GitHub. The router (routers/integrations/github.py) verifies the delivery, decides whether the author is trusted (author_association), names the changeset (gh-{owner}-{repo}-{n}), and passes a PullRequestRef to services/integrations/review.py. That service runs the review and reaches GitHub only through the ScmRepository port (services/integrations/scm.py). The port provides the diff, commit messages, comments, commit status, and pull-request URL. providers.open_repository() selects the adapter from the integration’s provider for both the review job and the triage re-post.

GitLab self-managed is the second adapter (services/integrations/gitlab.py, routers/integrations/gitlab.py; see the GitLab integration and OpenTremor-core#0013). Bitbucket Cloud is planned next. Each host has its own router and trust rule; the comment, gate, and report stay the same. The decision and rejected alternatives are in OpenTremor-core#0012. The platform/custom App split belongs to the GitHub integrations document; it is not a second provider.