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/manifestchecks the LLM connection, model, and App name, then mints a short-lived, single-usestatetoken (github_manifest_states, using the same “opaque token + SHA-256 hash + explicit expiry check” pattern asreport_links) that also carries the LLM settings. The admin’s browser submits a top-level form togithub.com. GitHub redirects back to the publicGET /integrations/github/manifest/callback, which resolvesstate, exchanges the one-timecodevia GitHub’sPOST /v1/app-manifests/{code}/conversions(libs/github_client.exchange_manifest_code), and creates the org’sintegrationsdoc: the App ID, private key, and webhook secret (github_app, encrypted with Fernet inlibs/crypto.py, like stored LLM credentials), and the LLM settings. - Installation. The
installation_idcomes only from the signedinstallationcreatedwebhook. 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()generatesopentremor-<org name>-<6 hex>. An admin-chosen name goes throughcheck_app_name(): this deployment’sgithub_app.app_slugvalues, then GitHub’s unauthenticatedGET /v1/apps/{name}andGET /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.