Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hopsule.com/llms.txt

Use this file to discover all available pages before exploring further.

The Hopsule GitHub integration lets you:
  • Import a repo as the source-of-truth for a project — file structure, history, and pull requests feed into Brain.
  • Analyse pull requests on every push — decisions you marked ACCEPTED become guardrails, and any change that conflicts with one is surfaced as a violation on the PR.
  • Drive automation with webhook events when analyses complete or violations are detected (see Webhooks).

​
Install the Hopsule GitHub App

1

Open Settings → Git Providers

From the organization dropdown, choose the org you want to connect. Inside Settings, click the Git Providers tab.
2

Add GitHub

Click + Add provider → GitHub. You’ll be redirected to GitHub to install the Hopsule GitHub App on either your personal account or an organization you administer.
3

Choose repositories

During installation, pick All repositories if you want Hopsule to see every repo in the account, or Only select repositories if you’d rather opt in repo-by-repo. You can change this at any time from your GitHub settings.
4

Verify

Back in Hopsule, the new GitHub connection appears in the list with a Verified badge. The installation id is shown so you can cross-reference it against the GitHub App settings page.
An organization can connect multiple GitHub installations side by side — e.g. one for your personal account and one for the company’s GitHub org. The Analyse Repository dialog lets you pick which one to pull from each time you import.

​
Import a repository

There are two entry points: From the dashboard: click + New project. The picker lists every repo across every connected provider — search, pick one, and the project name and description auto-fill from the repo metadata. Saving creates the project and queues the import in one shot. From an existing project: open the project, then click Analyse Repository in the header. The dialog walks you through provider selection and repo pick. While the import runs, the project page shows a live progress card with the import status (clone → discover → extract → save). When it finishes, the dashboard refreshes and Brain becomes browsable.

​
Pull request analysis

Once a repo is connected, every push to a pull request branch triggers analysis. Hopsule:
  1. Diffs the change against the repo’s accepted decisions.
  2. Detects any change that contradicts a decision (e.g. a decision says “use library X”, PR introduces library Y).
  3. Posts a check run on the PR with the findings.
Findings land in PR Results for the project — accept them as permanent additions to Brain, or reject them if a false positive.

​
Required permissions

The Hopsule GitHub App requests:
ScopeUsed for
contents:readCloning the repo for indexing and PR analysis.
metadata:readListing repos in the picker.
pull_requests:read + writeReading PR diffs and posting check runs.
members:readResolving which installations are visible to your org.
No write access to repo contents — Hopsule never pushes commits.

​
Org-scoped installation filter

Hopsule only shows GitHub installations whose installers are also members of your Hopsule organization. This prevents an outside user from exposing their GitHub installation to your workspace just because they ran the OAuth dance once. The lookup is enforced server-side via the UserOAuthAccount join — see the authority model for details. If you’ve configured an outbound webhook (see Webhooks), these events fire as the GitHub integration runs:
Event idWhen
project.import_completedA repo import finished successfully.
project.import_failedA repo import errored (payload includes the reason).
pr.analysis_completedHopsule finished scanning a pull request.
pr.violation_detectedA PR change conflicts with an accepted decision.
pr.results_acceptedAn admin accepted proposed PR findings.

​
Disconnecting

In Settings → Git Providers, click Disconnect on the connection card. The corresponding GitHub installation stays installed — to fully revoke access, you also need to uninstall the Hopsule app from GitHub’s Installed GitHub Apps page. Projects that were imported via the disconnected installation keep their data; only new imports and new PR analyses stop.