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:
| Permission | Access |
|---|---|
| Contents | Read and write |
| Pull requests | Read and write |
| Checks | Read and write |
| Metadata | Read-only |
What each is used for is the same as on github.com: see permissions the app asks for.
Then:
- Leave the webhook off for now. You get its address and secret in step 3.
- Create the app and generate a private key. GitHub downloads a
.pemfile. - 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:
| Field | What to enter |
|---|---|
| Server address | The https address people open in a browser, for example https://github.acme.example. Not github.com. |
| App ID | The number at the top of the app's page. |
| App name | The last part of the app's public address: letters, digits and dashes. |
| Organisation | The organisation (or user) the app is installed on. |
| Private key | The 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:
- Under Webhook, tick Active, paste the URL into Webhook URL and the secret into Webhook secret.
- 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 code | Cause | What to do |
|---|---|---|
code_host_rejected: the server did not accept the App ID and private key | Wrong 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 organisation | The app exists but is not installed on the name you entered. | Install it from the app's page, then connect again. |
already_connected | That organisation on that server is linked to another Nullgap organisation. | Disconnect it there first. |
step_up_required | Your second-factor check is older than fifteen minutes. | Confirm with your authenticator code, then try again. |
not_configured | This kind of connection is not switched on for your Nullgap service. | See getting help. |
| Pull requests are not reviewed | The 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