GitHub Enterprise Server

CodeLotse works with GitHub Enterprise Server (GHES) the same way as with github.com: through a GitHub App that you create on your GHES host. Other code hosts are described in providers.md.

Requirements

Item	Requirement
GHES URL	https:// origin without path, for example https://github.example.com. The API is used at <GHES URL>/api/v3.
TLS	The GHES certificate must be trusted by the public CA bundle in the CodeLotse images. A GHES with a certificate from a private CA is not supported yet; there is no setting for an extra CA.
CodeLotse → GHES	Outbound HTTPS from api and worker (and, for Kubernetes, allowed in networkPolicy.egressCidrs)
GHES → CodeLotse	GHES must reach PUBLIC_URL over HTTPS to deliver webhooks; its certificate must be trusted by GHES
Browser	Users must reach both GHES and PUBLIC_URL
Clock	Synchronised (NTP); GHES rejects app JWTs from skewed clocks

Configure the URL

Docker Compose:

./deploy/compose/quavon install --github-url https://github.example.com

The installer stores GITHUB_URL in .env and checks the clock against the GHES API. Helm: set githubUrl: https://github.example.com in your values file.

GITHUB_URL is the default host of the setup page and the host that doctor checks. It is described in the configuration reference.

Create the GitHub App

1. Open the setup link (./deploy/compose/quavon setup-token).

2. Under Where is your GitHub? choose GitHub Enterprise Server and enter the host name only (for example github.example.com, no https://, port or path). IP addresses are not accepted.

3. Choose Create a new GitHub App. Optionally enter an organisation. Your browser opens the app manifest on the GHES host (/settings/apps/new, or /organizations/<org>/settings/apps/new) with these settings:

   Setting	Value
   Webhook URL	<PUBLIC_URL>/webhooks/github
   Callback URL	<PUBLIC_URL>/auth/github/callback
   Setup URL	<PUBLIC_URL>/setup/github/installed
   Visibility	private

4. Confirm the app on GHES. CodeLotse exchanges the manifest code with the GHES API and checks that the app belongs to that host.

5. Install the app on your organisation and sign in with GitHub.

An existing app can be registered instead with Use an existing GitHub App. Instance admins can register apps for further GitHub hosts later in the instance settings; each installation stays with the host of its app. The setup page registers only one review app per instance.

Webhooks

GHES sends the header X-GitHub-Enterprise-Host with every delivery. CodeLotse uses it with the app ID to find the webhook secret of the app on that host, then verifies the signature. The header only selects the secret; trust comes from the signature.

Response	Cause
401	Unknown host or app, malformed header, or wrong signature. Check the webhook secret and that the app was registered for this host.
429	Too many failed deliveries from the same source. Fix the cause; deliveries are accepted again after the window.

Check the delivery log of the app on GHES (Settings → Developer settings → GitHub Apps → Advanced) when events do not arrive.

Checks

./deploy/compose/quavon doctor checks every registered app against its host:

Code	Meaning for GHES
QD601	No app registered yet
QD602	GHES not reachable from the containers (DNS, firewall, proxy, untrusted certificate)
QD603	GHES rejected the app JWT (wrong app ID, revoked key, deleted app, clock)
QD604	Stored app credentials cannot be decrypted
QD605, QD606	Reminders for the callback and webhook URLs
QD701	Clock differs from the GitHub time by more than 30 s