Install the GitHub App

This page lets you install the Spectrace GitHub App, connect the installation to your Spectrace workspace, and decide which project each repository's pull requests are verified against.

The GitHub App is the org-level integration that runs PR verification. Once installed and mapped, Spectrace receives a webhook for every pull request on a mapped repository, resolves the requirement it implements, and posts the result back as a comment and a check run under the App's own bot identity. See How PR verification works for what happens after the webhook arrives.

Prerequisites

You are an owner or admin of the Spectrace workspace (organization). Members see the App's status but cannot install or map repositories.
On GitHub, you are an owner of the organization you are installing on, or the installation targets your personal account. Enterprise-level installations are not supported.
Your GitHub account is connected to Spectrace under Settings → Integrations → GitHub → Connect GitHub. Spectrace uses that connection to know which GitHub user you are; if it is missing, the install flow sends you through it first.

Install and connect

Open the GitHub App card
Go to Settings → Integrations. Under the GitHub section there is a block titled GitHub App. If it reads "The GitHub App is not configured in this environment", the App has not been registered for this deployment and there is nothing to install yet.
Click Install Spectrace
The button takes you to GitHub's installation page for the App. Pick the account and choose All repositories or Only select repositories. You can change the repository selection on GitHub later; Spectrace picks the change up by webhook.
Let GitHub redirect you back
After you approve, GitHub returns you to Spectrace. Spectrace verifies that the installation belongs to an account you control, then claims it for your workspace. The Integrations tab shows GitHub App connected. Map each repository to a project below.
Map each repository to a project
The card lists every repository the installation covers with a project selector beside it. Choose the project whose requirements that repository's pull requests are verified against, or leave it as Not mapped. Unmapped repositories are ignored.

If you did not have permission to install on the GitHub organization, GitHub lets you request it instead. Spectrace then shows Install requested. A GitHub organization owner needs to approve it before it becomes active. Nothing is connected until an owner approves the request on GitHub and one of your workspace admins completes the connect step below.

If the redirect never happened

GitHub only redirects back to Spectrace on a fresh install started from the Install Spectrace button. Installations started from the App's own page on github.com, installs completed before the redirect was configured, and installs where you closed the tab before GitHub returned all leave a working installation that your workspace cannot yet see.

Open Settings → Integrations again. When the App is installed on a GitHub account you administer but not connected to a workspace, the card lists that account with a Connect button. Clicking it runs the same ownership checks the redirect would have and claims the installation. If the account is already connected to a different Spectrace workspace, the card says so and offers no button.

How ownership is checked

Spectrace never trusts the installation id in the redirect URL. It resolves the installation through the App's own credentials and then checks that you control the account it belongs to:

Personal account — the installation's account must be the GitHub user connected to your Spectrace account.
Organization — Spectrace mints an installation token and asks GitHub for your membership in that organization. You must be an active member with the admin (owner) role. Billing managers, ordinary members, and pending invitations are refused.

The organization check depends on the App holding the Organization → Members: read permission. REQUIRED_APP_PERMISSIONS in the code (and the generated GitHub App permissions table built from it) list only repository permissions; the members permission is required in addition for organization installs. When an installation predates that permission, Spectrace falls back to your connected GitHub OAuth token to answer the same question and, if that fails too, refuses with the "Members permission" message in the table below.

One installation belongs to exactly one workspace. If two workspaces race to claim the same installation, one wins and the other sees already connected to another Spectrace workspace. Spectrace never names the other workspace.

Permissions the App needs

The generated GitHub App permissions page lists the repository permissions Spectrace checks for. In summary the App asks for Pull requests: read and write (comments and PR data), Issues: read and write (GitHub routes PR comments through the Issues API), Checks: read and write (the check run), and Contents: read (the diff). Metadata: read is forced on by GitHub for every App. Organization installs additionally rely on Members: read, as described above.

The App subscribes to pull_request events. GitHub delivers installation and installation_repositories events to every App automatically; Spectrace uses them to record installs, suspensions, uninstalls, and repository additions or removals.

If the App's permissions change on GitHub, GitHub asks an organization owner to accept the new permissions. Until they do, features that need the missing permission fail: without Checks: write the check run is skipped and only the comment posts.

Repository to project mapping

A repository maps to at most one project. Mapping is done from the GitHub App card by an owner or admin of both the workspace and the target project.

Changing the selector saves immediately. If the same repository was previously mapped to another project in the workspace, that older mapping is cleared.
Repositories you add to the installation on GitHub appear in the list the next time the card loads; click Refresh to fetch the current list from GitHub. Repositories removed on GitHub are marked as no longer covered when the webhook lands.
A pull request on an unmapped repository is acknowledged and skipped. Nothing is posted to the PR.
If the list is empty and reads "The App has no repositories yet", add repositories to the installation from its settings page on GitHub.

Mapping a repository also fills the project's repository fields (github_repo_url, github_repo_id, default branch) that older features read, so the App path and the legacy path described next never disagree about which project a repository belongs to.

The legacy per-repository webhook

Before the App existed, Spectrace verified pull requests through a webhook registered on each repository using a member's personal GitHub connection. That path still exists at /api/webhooks/github/pr and is registered when you link a repository to a project from the project settings drawer or the new-project flow with a connected GitHub account.

The legacy path only verifies pull requests that were already registered against a requirement, for example by the VS Code extension or the MCP tool spectrace_pr_verifications_create, and it posts comments as whichever member's connection it borrows. It cannot create check runs.

When the App covers a repository through an active, mapped installation, the legacy webhook stands down: it acknowledges the event and does nothing, so a repository with both never receives two comments. Install the App and you can leave any old repository webhooks in place.

What done looks like

Settings → Integrations → GitHub App shows the GitHub account, "all repositories" or "selected repositories", and a project selector per repository.
Opening a pull request on a mapped repository produces a check run named Spectrace verification and one comment on the PR. See Reading a verification result.

When the connect step is refused

The Integrations tab shows one of the messages below (the same reasons appear on the Connect button in the recovery list). Each names the one thing that fixes it.

You see	What it means	What to do
Your GitHub sign-in has expired or been revoked	The stored GitHub connection returned 401.	Disconnect GitHub on the same tab, Connect GitHub again, then retry.
That GitHub organization enforces SAML single sign-on	Your token is not authorised for the SAML-protected organization.	Authorise Spectrace for that organization in GitHub's SSO settings, then retry.
GitHub would not let Spectrace read your installations	The organization restricts OAuth apps, or a scope is missing.	Ask a GitHub organization owner to approve Spectrace under Third-party access, then retry.
GitHub rate-limited the request	Temporary.	Wait a few minutes and retry. Nothing is misconfigured.
Could not find that installation on your GitHub account	No installation id was supplied and Spectrace could not find exactly one installation you administer — either none, or more than one.	Start from Settings → Integrations and use the Connect button beside the account you want, or Install Spectrace.
That installation belongs to a different GitHub App	The id points at another App's installation.	Install the Spectrace App itself.
You need to be an owner or admin of that GitHub organization	Your GitHub membership in that organization is not an active admin role.	Ask a GitHub organization owner to complete the connect step, or to make you an owner.
That installation belongs to a different GitHub account	A personal-account installation, but not on the GitHub user connected to your Spectrace account.	Connect the matching GitHub account, or install on the account you are connected as.
Spectrace can only connect installations on a personal account or an organization	An enterprise-level installation.	Install on the organization instead.
Created before Spectrace asked for the Members permission	The installation token lacks Members: read and the OAuth fallback could not confirm you administer the organization.	Re-accept the App's updated permissions on GitHub, then retry.
Connect your GitHub account above first	No GitHub identity is bound to your Spectrace user in this workspace.	Click Connect GitHub, then retry.
Only an owner or admin of this workspace can install the GitHub App	Your Spectrace role is member.	Ask a workspace owner or admin.
Could not tell which workspace to install into	The install link was opened without a workspace id (for example a hand-edited or truncated URL). Installs that start on github.com land on the Integrations tab without an error.	Start from Settings → Integrations and click Install Spectrace, or use the Connect button on the card.
Already connected to another Spectrace workspace	Another workspace claimed this installation first.	Disconnect it there, or install the App on a different GitHub account for this workspace.
Spectrace's own GitHub credentials were rejected	A configuration problem in the Spectrace deployment, not your setup.	Contact support with the time it happened.
GitHub returned an error while verifying the installation	GitHub answered with a server error.	Retry in a moment. This is the only case where a plain retry is the right move.

Once installed, the card can also show Installation suspended — re-enable it on GitHub. A suspended installation routes no webhooks; unsuspend it from the App's page under your GitHub organization settings. Uninstalling the App on GitHub soft-deletes the installation in Spectrace and marks its repository mappings as removed.