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 is | Connect with | Page |
|---|---|---|
| On github.com | The Nullgap GitHub App | GitHub |
| On a GitHub Enterprise Server you host | A GitHub App you create on your server | GitHub Enterprise Server |
| On gitlab.com or a self-managed GitLab | A group access token and a group webhook | GitLab |
| On Bitbucket Cloud | A workspace access token and a webhook | Bitbucket Cloud |
| On Azure DevOps Services (Azure Repos) | A personal access token and service hooks | Azure DevOps |
| Public, and you only want a pentest | Its https address | Public repository |
| Not on a code host Nullgap can reach | A .zip or .tar.gz upload | Archive 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
| GitHub | GitHub Enterprise Server | GitLab | Bitbucket Cloud | Azure DevOps | Public repository | Archive upload | |
|---|---|---|---|---|---|---|---|
| Pentests | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Pull request review | Yes | Yes | Yes | Yes | Yes | No | No |
| Result shown on the commit as | Check run | Check run | Commit status | Build status | Pull request status | Nothing | Nothing |
| A neutral result looks different from a pass | Yes | Yes | In the text only | In the text only | Yes | n/a | n/a |
| Summary and inline comments | Yes | Yes | Yes | Yes | Yes | No | No |
| Reply commands on comments | Yes | Yes | Yes | Yes | Members only | No | No |
@nullgap review comment | Yes | Yes | Yes | Yes | Members only | No | No |
| Label filters | Yes | Yes | Yes | No, pull requests have no labels | Yes | n/a | n/a |
| Suggested change the author accepts with one click | Yes | Yes | Yes | No, shown as a patch | No, shown as a patch | No | No |
| Fix pull requests | Yes | Yes | Yes | Yes | Yes | No | No |
| New repositories appear on their own | Yes | Press Sync | With Project events on the webhook | Press Sync | Press Sync | n/a | n/a |
| Who can connect it | Admin | Owner | Owner | Owner | Owner | Admin | Admin |
| Can be connected with an API key | No | No | No | No | No | Yes | Yes |
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
401as 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