Skip to content
DashboardWebsite

GitHub App Integration

Just want to do it in the dashboard? See the guide: Connect GitHub and choose repositories.

The server has a native GitHub App integration. Each org registers its own GitHub App and installs it on its repositories. The server analyses pull requests with packs that read the changed files, then posts a PR comment and commit status. You do not need to maintain a CI workflow.


There is no shared, platform-wide App. Each org creates its own App under its GitHub account or organization through GitHub’s App Manifest flow.

  • Credentials: GitHub sends the App’s private key and webhook secret directly to the server. They do not pass through your browser. The server stores them encrypted using Fernet, the same mechanism used for stored LLM credentials.
  • Installation: The server records the installation from GitHub’s signed installation webhook. You do not enter an installation ID.
  • Who can create it: A person who can create GitHub Apps on the target account. On a GitHub organization, that is an owner or App manager. On a personal account, anyone can create an App.

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

    GH->>WH: pull_request opened/synchronize/reopened/ready_for_review (HMAC-signed)
    WH->>WH: find the integration by installation.id (or installation.app_id) and verify X-Hub-Signature-256
    WH->>WH: add the repository to the inventory, start a revision at the head SHA
    WH-->>GH: 202 {job_id}
    WH->>Job: enqueue — any replica's worker runs it
    Job->>Job: resolve the review teams and product
    Job->>GH: installation token (the org's own App), then the PR diff
    Job->>LLM: auto-route each changed file to its pack, analyse
    Job->>Job: scan for agent injection, build the report
    Job->>GH: create or edit the one report comment, post the commit status
    Job->>Job: notify subscribed channels when the check is blocked

The server uses the unverified installation.id (or, for the first event a new App receives, installation.app_id) only to find the stored secret. It verifies the signature before taking action. If no org matches the delivery, the server answers 200 and ignores it.

The PR diff is auto-routed (see Auto-routing). Each changed file runs through an org-enabled pack whose file_globs matches it. For example, a .py file can go to python-code-change, and a .ts file can go to typescript-code-change. A pack that reads CLI output, such as terraform-plan, does not match a PR diff because the server does not run that CLI. Files no installed pack recognises appear in the job’s detections (GET /v1/jobs/{job_id}); they are not silently skipped. See POST /v1/{changeset}/ingest/auto for the response shape.


In the dashboard: Organization → Connections → GitHub. Select the LLM connection and model, enter an App name, and click Create GitHub App. You can also use the API as shown below.

Webhook-triggered runs have no interactive caller to supply an API key. They use a connection stored for the org.

In the dashboard: Organization → Connections → LLM. Or use the API:

Terminal window
curl -X POST http://localhost:8000/v1/orgs/{org_id}/llm-connections \
-H "X-API-Key: <admin-key>" -H "Content-Type: application/json" \
-d '{"connection_id": "anthropic", "provider_kind": "anthropic", "api_key": "sk-ant-..."}'

App names are unique across GitHub and can be up to 34 characters. The server can suggest one:

Terminal window
curl http://localhost:8000/v1/orgs/{org_id}/integrations/github/app-name \
-H "X-API-Key: <admin-key>"
{ "name": "opentremor-acme-3f9a1c" }

The suggested name is opentremor-<your org name>-<6 random hex characters>. Reviewers see it on report comments, for example opentremor-acme-3f9a1c[bot].

To use your own name, check it first:

Terminal window
curl "http://localhost:8000/v1/orgs/{org_id}/integrations/github/app-name?name=acme-review" \
-H "X-API-Key: <admin-key>"
{ "name": "acme-review", "result": "available", "reason": null }

A name must be 3 to 34 characters: lowercase letters and digits, with single hyphens between them. Other names return 422. The result is one of:

resultMeaning
availableNo check found the name.
takenAnother org on this deployment or a public GitHub App uses the name. Choose another name.
warningA GitHub user or organization has this login. GitHub accepts the name only if you create the App under that account.
unknownGitHub did not answer, for example because it exceeded its limit of 60 unauthenticated requests per hour. GitHub checks the name again on the creation page.

The check cannot see a private App with the same name. GitHub’s creation page reports it.

Terminal window
curl -X POST http://localhost:8000/v1/orgs/{org_id}/integrations/github/manifest \
-H "X-API-Key: <admin-key>" -H "Content-Type: application/json" \
-d '{"connection_id": "anthropic", "model": "claude-sonnet-5", "app_name": "acme-review"}'
{
"manifest": { "name": "acme-review", "hook_attributes": { "url": "..." }, "...": "..." },
"state": "a1b2c3...",
"target_url": "https://github.com/settings/apps/new"
}
  • The server checks connection_id and model. It returns 400 if the connection does not exist, is disabled, or the model is not on the allowed list. The flow stores these settings, so the integration is configured when the App is created.
  • app_name is optional. Without it, the server generates a name. With it, the server checks the name again and returns 409 if it is taken.
  • state is a single-use token that expires after 10 minutes. GitHub returns it unchanged. manifest is the JSON payload for GitHub’s App-creation form.

Submit a real, top-level browser form. Do not use fetch or XHR. GitHub’s redirect requires a top-level navigation:

<form method="post" action="https://github.com/settings/apps/new?state=a1b2c3...">
<input type="hidden" name="manifest" value='{"name": "acme-review", ...}' />
<button type="submit">Create GitHub App</button>
</form>

The dashboard submits this form. On GitHub, review the requested permissions and click Create GitHub App.

GitHub redirects the browser to GET /integrations/github/manifest/callback?code=...&state=.... The server:

  1. Resolves state to the org and admin who started the flow. It consumes the token.
  2. Exchanges code for the new App’s identity through GitHub’s POST /v1/app-manifests/{code}/conversions. GitHub sends the private key and webhook secret directly to the server.
  3. Encrypts the credentials and creates the org’s integration with the LLM settings from step 3. This replaces any existing integration for the org.
  4. Redirects the browser to {dashboard_base_url or public_base_url}/integrations/github?app_created=1.

Creating the App does not install it. Until you install it on repositories, it receives no pull request events and installation_id remains null. Install the App in GitHub’s UI. The dashboard cannot install it for you.

The integration record stores the App’s html_url (https://github.com/apps/<app-slug>). Its install page is that URL plus /installations/new:

https://github.com/apps/<app-slug>/installations/new

The dashboard shows an Install on GitHub button on the GitHub integration page. A notice remains until an installation is linked. To open the App manually, go to Settings → Developer settings → GitHub Apps on the owning account, select the App, then choose Install App from its menu.

On GitHub’s install page:

  1. Choose the account or organization that holds the repositories. The manifest creates the App as private ("public": false), so only the account where it was created is offered. A private App cannot be installed elsewhere. If you created it under a personal account but need it on an organization’s repositories, delete it and repeat the flow with the organization selected on GitHub’s App-creation page.
  2. Choose the repository scope: All repositories (including ones created later) or Only select repositories. You can change this choice later.
  3. Click Install. An organization may require an owner to approve the request. The App remains pending until approval.

Installing sends an installation created webhook. The server stores installation_id from it and adds the installed repositories to the org’s repository list. The dashboard notice disappears when the webhook arrives. Use Check again to poll while you wait.

To change repository scope or uninstall the App, go to Settings → Applications → Installed GitHub Apps → Configure on the owning account. Uninstalling sends an installation deleted webhook, which clears installation_id and stops analysis without deleting the stored App credentials. Changing repository scope updates the repository list. Uninstalling marks each repository removed and keeps its teams.

Terminal window
curl -X PUT http://localhost:8000/v1/orgs/{org_id}/integrations/github \
-H "X-API-Key: <admin-key>" -H "Content-Type: application/json" \
-d '{"connection_id": "anthropic", "model": "claude-sonnet-5"}'

The API returns 404 until the App exists. In the dashboard, these fields are under Analysis settings on the GitHub Integration page. The connection and model apply to every webhook-triggered analysis unless a repository has its own LLM settings. Auto-routing uses each matched pack’s default rule variant.

Terminal window
curl -X DELETE http://localhost:8000/v1/orgs/{org_id}/integrations/github \
-H "X-API-Key: <admin-key>"

This deletes the App credentials and LLM settings from OpenTremor and marks the org’s GitHub repositories removed, keeping their teams. It does not delete the App on GitHub; delete it there too. Until then, its deliveries reach the server and are ignored. To connect again, create a new App.


PR comment: The comment uses the same short summary layout as GET /v1/changesets/{changeset}/report?detail=summary. It includes CRITICAL and HIGH findings with suggested fixes, filtered by each finding’s triage status. For example, a finding suppressed via PATCH /v1/findings/{resource_hash}/{rule_id} on a previous push does not reappear on the next one.

One comment per pull request. Each push reruns the analysis and edits the original comment instead of adding another. The comment is identified by an invisible marker on its first line, <!-- opentremor-report:{changeset} -->. Only a comment written by the App is eligible, so adding that marker to your own comment does not make it eligible. If the comment was deleted or cannot be edited, the run posts a new one.

An edit does not send a notification like a new comment. The comment ends with a line showing when it was last rewritten and for which commit: Updated 2026-08-25 13:30 UTC — re-analysed after commit a1b2c3d. Timestamps use UTC. The first post uses this form: Analysed commit a1b2c3d · 2026-08-25 13:30 UTC.

A second marker, for replies. The body also carries <!-- opentremor:changeset={changeset} -->. The review feedback loop uses it to resolve a reply to the analysis it responds to. A pull request may be analysed many times, and the comment is rewritten each time, so the reply alone does not identify the run. The marker also lets the loop recognise this comment as its own and avoid ingesting OpenTremor’s report as reviewer feedback. Both markers are reapplied on every rewrite, including the triage refresh below, because each rewrite replaces the whole body.

The comment can include up to two links to the same analysis. Which links appear depends on the deployment’s configuration:

LinkBuilt fromWho it’s for
Open the full reportserver.dashboard_base_url, else server.public_base_urlAnyone reading the PR. A public report link needs no login and expires after 24 hours by default. An org can change the TTL using PATCH /v1/orgs/{org_id}/report-link-ttl.
Triage in the dashboardserver.dashboard_base_urlOrg members. Opens /findings?changeset={changeset}, the findings list filtered to this pull request, where findings can be acknowledged, suppressed, or marked false-positive.

The changeset is gh-{owner}-{repo}-{pr_number}, so the dashboard link filters the findings list to that pull request. The report page displays one run; the findings list is where triage happens and statuses persist across rescans.

Both links are rendered as HTML anchors with target="_blank". GitHub’s comment sanitizer removes target (its allowlist for <a> includes only href and rel), so they open in the same tab in a PR comment. The attribute takes effect wherever else the light report is rendered as HTML.

Both links come from the built-in markdown_light template. An org that has replaced that template gets the links its template renders. Add {{ report_html_url }} and {{ dashboard_url }} to keep the links.

Commit status: The status uses context: opentremor-core. It is failure if any open finding has CRITICAL or HIGH severity. Otherwise, it is pending if any finding is needs_review (see Human-in-the-loop). Low LLM confidence, a rule marked requires_review, or a human changing the status can send a finding to review. Otherwise, the status is success. Suppressed, acknowledged, and false-positive findings do not block the status. Orgs cannot configure these thresholds.

Draft pull requests: Drafts are not reviewed by default. A draft gets state: pending, with Draft: the review starts when it is marked ready, and no comment. Marking it ready (ready_for_review) starts a review of its current head. When a repository turns on Draft pull requests (Repository settings), every push to a draft is reviewed. Marking it ready starts no new review because that head was already reviewed.

Goals: When the repository’s product has active goals, the comment includes a Goals section after the report. It describes which goals and steps the pull request advances or regresses, and why. A regression of a guarded step adds a needs-review finding and holds the check at pending. The section remains on a triage refresh.

Code suggestions: Code suggestions are off by default. When enabled, a review can carry inline suggestions on lines added by the pull request for the author to apply.

Acknowledging, suppressing, or marking a finding false-positive in the dashboard changes what the check and comment should say. GitHub keeps the last written values until something updates them. PATCH /v1/findings/{resource_hash}/{rule_id} therefore reposts the commit status and rewrites the report comment for every open pull request that includes the finding.

This path edits an existing comment; it does not create one. If the PR has no report comment because it was never analysed or the comment was deleted, triage refreshes the check and stops there. A click on Acknowledge does not create a comment. The in-place update avoids that noise. The footer says: Updated … — findings re-triaged; commit a1b2c3d unchanged.

Both updates are best-effort and run in that order. The triage is saved before either update runs, so a GitHub outage does not turn a successful PATCH into a 500. If a comment cannot be edited, that does not stop its own check or the refresh for other pull requests.


GitHub’s servers must reach POST /integrations/github/webhook, so that path needs a public URL. The API calls GitHub outbound, and the manifest callback is a browser redirect. Keep the rest of the instance private:

  1. Reach the instance without opening a port, for example with a Cloudflare Tunnel or ngrok, and set server.public_base_url to the tunnel’s hostname.
  2. Allow the webhook from GitHub only. A new deployment already has the github-hooks address list, fetched from https://api.github.com/meta, and a report-mode network access rule on the webhook path. If you deleted them, Restrict to GitHub’s addresses on Platform Admin → Connections → GitHub Webhooks creates them again. Add a rule on / for your own network, check the Firewall’s Traffic tab, then enforce both.
  3. Optionally, limit the tunnel itself to the webhook path. The HMAC signature authenticates each delivery; the rules above keep other paths private.

scripts/webhook-replay in OpenTremor-core signs a stored payload with your webhook secret and posts it to the local stack, as GitHub would. Outbound calls still reach the real GitHub API, so a replayed pull_request posts its comment on the pull request named in the payload. With --from <address>, the replay also tests the network access rules. Run it with --help for the options.


MethodPathAuthDescription
GET/orgs/{org_id}/integrations/github/app-nameorg-adminSuggest an App name, or check one (?name=)
POST/orgs/{org_id}/integrations/github/manifestorg-adminStart the manifest flow, with the LLM settings and an optional App name
GET/integrations/github/manifest/callbackpublic (state token)GitHub’s redirect target — completes App creation
GET/orgs/{org_id}/integrations/githuborg-adminCurrent config and App info (never the private key or webhook secret)
PUT/orgs/{org_id}/integrations/githuborg-adminChange the LLM connection and model
DELETE/orgs/{org_id}/integrations/githuborg-adminDisconnect everything
POST/integrations/github/webhooksignatureWebhook receiver

See Integrations for full request/response shapes and status codes.


SymptomLikely cause
GitHub shows Invalid GitHub App configuration — Default events are not supported by permissions: issue_commentThe deployment predates the fix that requests Issues (read) in the manifest. Upgrade and restart the flow; nothing was created on GitHub
Manifest trigger returns 501config.server.public_base_url is not set. GitHub needs a real URL to call back
Manifest trigger returns 409The App name is used by another org on this deployment or by a public GitHub App. Pick another name, or omit app_name to get a generated one
GitHub’s creation page says the name is takenA private App, which the check cannot see, has the name. Go back and choose another
Manifest callback returns 400The state token expired (10-minute TTL) or was already used. Restart the flow
Manifest callback is a 404 page, not an API responseconfig.server.public_base_url points at the dashboard instead of the API. The manifest webhook and redirect URLs must use the API’s origin. In a split-subdomain setup, use https://api.<domain> and set server.dashboard_base_url to https://<domain> separately (see Dashboard deployment). Fix the setting, delete the half-created App on GitHub, and repeat the flow. The existing App has the wrong webhook URL and no stored credentials
App stays “Waiting for the App to be installed on a repository”The App was created but not installed. Open https://github.com/apps/<app-slug>/installations/new (the dashboard’s Install on GitHub button) and install it. The webhook fills in installation_id. If it stays empty, the App’s webhook URL may be unreachable. Check the row above and the App’s Advanced → Recent Deliveries page on GitHub
Webhook returns 401Signature mismatch. Check that the webhook secret on GitHub matches the one stored by the manifest exchange; repeat the manifest flow to replace the secret
Webhook returns 200 but nothing happensThe event or action may not be handled. pull_request opened/synchronize/reopened/ready_for_review events can trigger analysis. Drafts on repositories that skip drafts return {"detail": "no review queued"}. installation created/deleted and installation_repositories events update the installation or repository inventory. A push to the default branch can start a knowledge-source sync. issue_comment/pull_request_review/pull_request_review_comment events with created/submitted actions record reviewer feedback. A delivery from an App that was disconnected but not deleted on GitHub returns {"detail": "ignored"}
ADR changes never start a syncThe App is not subscribed to Push. An App registered before Rules from ADRs shipped keeps its original subscriptions. Add Push in its GitHub settings. Until then, Sync now and the daily sync still read the ADRs
Reviewer comments never show up in Rule HealthThe App is not subscribed to the three comment events. An App registered before the review feedback loop shipped keeps its original subscriptions. Add Issue comment, Pull request review, and Pull request review comment in its GitHub settings after granting Issues (read) permission for Issue comment. Comments from authors without write access are recorded but marked untrusted. The same applies to comments flagged by the injection scanner
Job ends up failed, no comment postedPoll GET /v1/jobs/{job_id} and read error. Common causes include missing or invalid stored LLM credentials or an exceeded monthly org budget (see Billing / quota)
Check stays pending with “No pack is enabled for this repository” and no jobEvery pack starts off. Enable one on the repository, its product, or the org, then push a commit
Job ends up done with resource_count: 0, no findingsNo enabled pack matched a changed file. Check the job’s detections (GET /v1/jobs/{job_id}) for details. No pack may recognise the file type, or the matching pack may be disabled. Enable it on the repository (enable it)