Nullgap.dev Docs

Connect your code

GitHub Enterprise ServerNew

Connect an organisation on a GitHub server you host, using a GitHub App you create there.

For a GitHub Enterprise Server you host, you create your own GitHub App on that server and give Nullgap its App ID, name and private key. From there it behaves like GitHub: pull request review, checks, comments, reply commands, suggested changes and fix pull requests.

#What you need first

  • To be an owner of the Nullgap organisation, signed in to the console. If your account has multi-factor sign-in, you are asked for a fresh code. An API key cannot connect a code host.
  • A GitHub Enterprise Server that is reachable from the internet over https. A private, loopback or internal address is refused with private_address.
  • Permission on that server to create a GitHub App and install it on the organisation.

#Step 1: create the GitHub App on your server

On your server, go to Settings, Developer settings, GitHub Apps, New GitHub App, and give the app these repository permissions:

PermissionAccess
ContentsRead and write
Pull requestsRead and write
ChecksRead and write
MetadataRead-only

What each is used for is the same as on github.com: see permissions the app asks for.

Then:

  1. Leave the webhook off for now. You get its address and secret in step 3.
  2. Create the app and generate a private key. GitHub downloads a .pem file.
  3. Install the app on your organisation and choose the repositories it may read.

#Step 2: connect it in Nullgap

Open Integrations. Under Source code, in the GitHub Enterprise Server row, press Connect and fill in:

FieldWhat to enter
Server addressThe https address people open in a browser, for example https://github.acme.example. Not github.com.
App IDThe number at the top of the app's page.
App nameThe last part of the app's public address: letters, digits and dashes.
OrganisationThe organisation (or user) the app is installed on.
Private keyThe whole .pem file, including the BEGIN and END lines. It is stored encrypted and never shown again.

Before anything is stored, Nullgap checks that the key works on that server and that the app is installed on that organisation.

#Step 3: set the webhook

When the connection is made, the console shows a Webhook URL and a Webhook secret.

On your server, open the GitHub App you created and edit it:

  1. Under Webhook, tick Active, paste the URL into Webhook URL and the secret into Webhook secret.
  2. Under Subscribe to events, tick Pull request, Issue comment and Pull request review comment. Save.

A GitHub App has one webhook address. If you connect a second organisation that uses the same app, keep the address of the first: events for the second organisation arrive there and are handed to its connection, inside your Nullgap organisation only.

#What you will see

The organisation appears in Integrations as GitHub Enterprise Server on followed by your server's host name, and its repositories appear under Repositories with pull request review switched on. Press Sync on Repositories after you change which repositories the app can read.

#What can go wrong

Message or codeCauseWhat to do
code_host_rejected: the server did not accept the App ID and private keyWrong App ID or key, or the server cannot be reached from the internet.Check both values and that the address answers over https from outside your network.
not_installed: the GitHub App is not installed on that organisationThe app exists but is not installed on the name you entered.Install it from the app's page, then connect again.
already_connectedThat organisation on that server is linked to another Nullgap organisation.Disconnect it there first.
step_up_requiredYour second-factor check is older than fifteen minutes.Confirm with your authenticator code, then try again.
not_configuredThis kind of connection is not switched on for your Nullgap service.See getting help.
Pull requests are not reviewedThe webhook is not active, the secret does not match, or an event is not ticked.Check the app's webhook settings and its recent deliveries on your server. A delivery with a wrong secret is answered 401.

#Rotating the webhook secret

In Integrations, press Rotate webhook secret on the connection. A new secret is shown once. The old one stops working at that moment, so deliveries are refused until you have pasted the new secret into the app's webhook settings on your server.

Connecting the same organisation again, for example with a new private key, also issues a new webhook secret.

#Removing

Press Disconnect on the connection. The stored private key and secret are deleted, reviews stop and the repositories leave the list. Past reviews and findings are kept. Then switch off the app's webhook or delete the app on your server, or it keeps sending events that are refused.

Nullgap documentation