Nullgap.dev Docs

Connect your code

Which way to connect

Choose how to give Nullgap your code, and see what each connector can and cannot do.

Nullgap reads code in one of seven ways. Five are connections to a code host, which allow pull request review, pentests and fix pull requests. Two are read-only sources, which allow pentests and nothing else.

#Choose by situation

Your code isConnect withPage
On github.comThe Nullgap GitHub AppGitHub
On a GitHub Enterprise Server you hostA GitHub App you create on your serverGitHub Enterprise Server
On gitlab.com or a self-managed GitLabA group access token and a group webhookGitLab
On Bitbucket CloudA workspace access token and a webhookBitbucket Cloud
On Azure DevOps Services (Azure Repos)A personal access token and service hooksAzure DevOps
Public, and you only want a pentestIts https addressPublic repository
Not on a code host Nullgap can reachA .zip or .tar.gz uploadArchive upload

Bitbucket Data Center and Azure DevOps Server, the self-hosted editions, cannot be connected. Use an archive upload for code that lives there.

A self-hosted GitLab or GitHub Enterprise Server must be reachable from the internet over https. Addresses that are private, loopback or internal are refused.

#Older and newer connectors

GitHub is the original connector and the one with the most use behind it. Bitbucket Cloud, Azure DevOps and GitHub Enterprise Server are newer, and are marked new in the navigation.

#What each connector supports

GitHubGitHub Enterprise ServerGitLabBitbucket CloudAzure DevOpsPublic repositoryArchive upload
PentestsYesYesYesYesYesYesYes
Pull request reviewYesYesYesYesYesNoNo
Result shown on the commit asCheck runCheck runCommit statusBuild statusPull request statusNothingNothing
A neutral result looks different from a passYesYesIn the text onlyIn the text onlyYesn/an/a
Summary and inline commentsYesYesYesYesYesNoNo
Reply commands on commentsYesYesYesYesMembers onlyNoNo
@nullgap review commentYesYesYesYesMembers onlyNoNo
Label filtersYesYesYesNo, pull requests have no labelsYesn/an/a
Suggested change the author accepts with one clickYesYesYesNo, shown as a patchNo, shown as a patchNoNo
Fix pull requestsYesYesYesYesYesNoNo
New repositories appear on their ownYesPress SyncWith Project events on the webhookPress SyncPress Syncn/an/a
Who can connect itAdminOwnerOwnerOwnerOwnerAdminAdmin
Can be connected with an API keyNoNoNoNoNoYesYes

Notes on the rows:

  • Result shown on the commit. GitHub has a check with three outcomes, and Azure DevOps has a not applicable state that Nullgap uses for a neutral result. GitLab and Bitbucket Cloud have no finished state that is neither a pass nor a block, so there a neutral result is written as a passing status whose text starts with "Neutral, not a pass:". The icon is still green. Read checks and gating before you make the status required for merging on those hosts.
  • Reply commands and @nullgap review. A command is accepted from someone the code host says has write access to the repository, or from a member of your Nullgap organisation whose identity on that host is known to Nullgap. Azure DevOps cannot be asked about write access, so there a command is accepted only from a member of your Nullgap organisation whose Nullgap e-mail address is their Azure DevOps sign-in address. Details are on comments and commands.
  • Suggested change. On Bitbucket Cloud and Azure DevOps the same change is shown as a patch in the comment, together with a pull request to merge it from. See suggested changes.

#Read-only sources

A public repository added by address and an uploaded archive have no pull requests, checks, comments or webhooks. For these:

  • pentests, estimates, schedules and reports work as for any repository;
  • switching on pull request review is refused with read_only_repository;
  • starting a fix is refused with read_only_repository, because there is nowhere to open a pull request. You can still copy a finding's fix prompt and apply the fix yourself.

#What a connection stores

  • GitHub stores the installation number and account name. Access comes from the app installation; uninstall the app on GitHub to end it.
  • GitHub Enterprise Server, GitLab, Bitbucket Cloud and Azure DevOps store the credential you enter (a private key or an access token) and a webhook secret, encrypted. Neither is shown again. See encryption.
  • Each of those four has its own webhook address containing the connection's id. A delivery is checked against that connection's secret and handled inside that connection only. An address that does not exist answers the same 401 as a wrong secret.

#After connecting

Repositories from a connected code host appear under Repositories with pull request review switched on. Switch it off per repository there. An admin can press Sync at any time to read the repository list again:

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories/sync"

A repository that is no longer in the code host's list is removed by a sync. Its past reviews, pentests and findings are kept.

To list the connections (the two read-only sources are not listed as connections):

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/connections"

#Disconnecting

In Integrations, press Disconnect on the connection. Reviews stop for every repository under it and the repositories leave the list; past reviews and findings are kept. For a token connection, the stored token is deleted. Remove the webhook on the code host as well, or it keeps sending events that are refused.

The full field lists are in the code hosts and repositories reference.

Nullgap documentation