Connect your code
GitHub
Install the Nullgap GitHub App, link the installation to your organisation, and choose which repositories it can read.
Repositories on github.com are connected through the Nullgap GitHub App. Installing the app on GitHub gives Nullgap access; linking the installation in the console says which Nullgap organisation that access belongs to.
For a GitHub server you host yourself, see GitHub Enterprise Server.
#What you need first
- To be an admin or owner of the Nullgap organisation. Connecting is done in the console; an API key cannot do it.
- On GitHub, to be able to install apps on the account, and to pass the verified link step: the account is your own personal account, or you administer every repository the installation covers.
#Permissions the app asks for
GitHub shows the permissions when you install the app. If that list ever differs from this table, GitHub's page is the one that applies.
| Permission | Access | Why Nullgap needs it |
|---|---|---|
| Contents | Read and write | Read: fetch the code at the commit under review or the version under test. Write: push a fix to a new branch named nullgap/fix-... when you ask for a fix. |
| Pull requests | Read and write | Read a pull request and its diff. Post inline comments, reply in their threads, and open fix pull requests. |
| Issues | Read and write | Post and update the summary comment and reply on the pull request's conversation. GitHub serves that conversation through its issue-comment interface. Nullgap does not read or create issues. |
| Checks | Read and write | Create and update the Nullgap Security Review check on a commit. |
| Metadata | Read-only | List the repositories the installation covers. GitHub requires it of every app. |
The app is told about pull requests being opened, updated, reopened and closed, about comments on pull requests, and about the app being installed, removed or given a different set of repositories.
What the write access is not used for:
- Nullgap never merges anything and never force-pushes.
- A fix is pushed only to a new branch. A branch name that already exists is never reused or overwritten.
- A fix that would change build, pipeline or Nullgap configuration files is not delivered at all. See verified fixes.
#Install and link
- In the console, open Integrations. Under Source code, in the GitHub row, press Install on GitHub. GitHub opens in a new tab.
- Choose the account, then All repositories or Only select repositories, and install.
- GitHub sends your browser back to the console, which starts the verified link step below.
- On success you land on Repositories, and the installation appears in Integrations as GitHub installation followed by its number.
If GitHub does not send you back, or you installed the app earlier, press Link installation in the GitHub row and paste the installation number. It is the number at the end of the address of the installation's settings page on GitHub, after /installations/.
#The verified link step
#Why it exists
Anyone can install a public GitHub App, and installation numbers can be guessed. Without a check, a person could link someone else's installation to their own Nullgap organisation and have that account's code reviewed into their console. So before an installation is linked, Nullgap asks GitHub one question: can the person at the keyboard administer this installation?
#How it works
- Nullgap sends your browser to GitHub to confirm who you are. GitHub may ask you to authorise the app for your user account.
- GitHub sends the browser back, and Nullgap asks GitHub, as you, which installations of the app you can reach and which repositories of this installation you administer.
The installation is linked only if GitHub's answer shows one of these:
- the installation is on your own personal account; or
- you are an administrator of every repository the installation covers.
Seeing some of an organisation's repositories is not enough, because the link hands over all of them.
The round trip must finish within ten minutes, in the same browser session that began it, and it can be used once. You must still be an admin of the Nullgap organisation when it finishes. A refusal is written to your audit log with the GitHub user that was refused.
#When the link is refused
The console shows GitHub was not connected with one of these reasons.
| What the page says | Cause | What to do |
|---|---|---|
| GitHub says your account does not administer that installation | You are not an administrator of every repository the app is installed on, and it is not your own account. | Ask an owner of the GitHub organisation to do the linking, or to make you an administrator of each repository the app covers. Installing the app on selected repositories that you administer also works. |
| That installation is already connected to another Nullgap organisation | An installation belongs to one Nullgap organisation. | Disconnect it there first, or install the app on a different account. |
| Nullgap has not heard about that installation from GitHub yet | GitHub's notice of the installation has not arrived. | Wait a minute, then use Link installation. |
| That took too long, or the link was already used | More than ten minutes passed, or the page was reloaded. | Start again from Integrations. |
| You are signed in as someone else than the person who started this | The browser session changed, or you are no longer an admin. | Sign in as the admin who started it and start again. |
| GitHub could not be asked just now | GitHub did not answer. | Try again in a few minutes. |
#Choosing repositories
Which repositories Nullgap can read is decided on GitHub, in the settings of the app's installation on that account. When you change the selection there, GitHub tells Nullgap and the list under Repositories follows on its own.
Which of those repositories get pull request review is decided in Nullgap, on the Repositories page, with the PR review switch. New repositories start with it on.
#Syncing
Press Sync on Repositories to read the list again from GitHub, for example after renaming a repository or changing its default branch. A repository that the installation no longer covers is removed from the list; its reviews, pentests and findings are kept.
#Linking your own GitHub login
Nullgap matches the author of a pull request, and the author of a reply command, to a person by GitHub login. If you sign in to the console with GitHub, your login is recorded for you. Otherwise set GitHub login on your profile page. Without it you can still use reply commands if GitHub says you have write access to the repository.
#Removing
- Disconnect in Integrations unlinks the installation from your organisation. Reviews stop and its repositories leave the list. Past reviews and findings are kept. The app stays installed on GitHub.
- Uninstalling the app on GitHub ends Nullgap's access. GitHub tells Nullgap, and the connection and its repositories are removed here on their own.
Do both to remove it completely.
With an API key that has the admin scope, you can list connections and remove one:
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/connections"
curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/connections/conn_1a2b3c4d5e6f"
#Next
- Your first reviewed pull request
- Checks and gating: make the check required on GitHub to block a merge.
Nullgap documentation