Start here
Getting started in a new workspace
What a new organisation sees from the invitation to a first result, the seven steps of the Getting started guide, how a step becomes done, and where the console takes you afterwards.
A new workspace opens with a guide called Getting started. It takes an organisation from an empty workspace to a first real result in its own code, in seven steps. You can stop at any point: the guide resumes where your organisation is, and the rest of the console works throughout.
This page describes the guide as you see it. If you prefer to go straight to a task, use the pull request review quickstart or the first pentest quickstart.
#How you get in
There are two ways a workspace comes to exist.
Nullgap sets it up for you. The first owner gets an e-mail with the subject "Your Nullgap workspace for ... is ready" and a link.
- Open the link and sign in with the e-mail address the invitation was sent to.
- The link works once and expires after 7 days. The message states the date.
- If the invitation is not used for a few days, one reminder is sent. There is only one.
- Nobody else can get into the workspace until the owner has accepted.
- If the link has expired or the message went astray, ask Nullgap to send it again. Links sent earlier stop working when a new one is sent.
If your workspace has a trial, it starts counting when the owner first signs in, not when the invitation was sent.
You create it yourself, by signing in and creating an organisation. You are its first owner. Some Nullgap services set every workspace up by invitation: there, after signing in, you are asked to ask your Nullgap contact for one, or a colleague to invite you to your company's workspace.
Either way, the next thing you see is the guide.
#Where the console takes you
| Address | What it is | When you land there |
|---|---|---|
/<org> | The workspace address | Always redirects to one of the two below |
/<org>/dashboard | The Dashboard | While the workspace has no repositories, and whenever you open it from the menu |
/<org>/start | New run: one box that asks "What should we test?" | Once the workspace has at least one repository |
/<org>/getting-started | The Getting started guide | From the menu entry, which is shown until the guide is finished |
<org> is your organisation's slug. The Getting started entry at the top of the menu shows how many steps are done, for example 3/7.
On New run you paste the address of a public repository or pick a connected one, and optionally a branch. It hands over to the pentest wizard, which shows the price and asks for confirmation before anything starts; nothing is started from the box itself. Members can ask for a pull request review from the same screen. Only admins and owners can start a pentest.
#The seven steps
| Step | What it is for | Who can do it | Optional |
|---|---|---|---|
| Welcome | What Nullgap does, what it needs from you, and what happens to your code | Each person, for themselves | No |
| Secure your account | Add a second sign-in factor | Each person, for themselves | Yes |
| Connect your code | Give Nullgap access to a code host, or try it on one repository first | Admins and owners | No |
| Choose repositories | Decide which repositories get a review on every pull request | Admins and owners | No |
| Get a first result | A pull request review or a pentest | Anyone for a review; admins and owners for a pentest | No |
| Read your first finding | Learn to read a finding on a real one | Anyone | No |
| Bring your team | Invite people and send results where they work | Admins and owners | Yes |
A member who opens a step that only an admin can do is told so, instead of being offered a button that would fail.
#How a step becomes done
A step is done when the workspace shows it, never because someone ticked it. Nullgap works out the state of each step from what exists.
| Step | Done when |
|---|---|
| Welcome | You press the button that says you have read it, or the organisation already has code connected |
| Secure your account | Your account has a second factor, or you signed in through your organisation's single sign-on |
| Connect your code | A code host is connected, or a repository was added by address or uploaded |
| Choose repositories | At least one repository has pull request review switched on |
| Get a first result | A review has completed (a skipped one does not count), or a pentest has completed |
| Read your first finding | A finding has been decided on (patched, accepted risk or false positive) or a fix has been started. Looking is not enough |
| Bring your team | Someone other than the first owner has been invited, or a second member has joined |
Two steps are personal: Welcome and Secure your account have their own state for each member. The other five are shared by the whole organisation.
#Skipping a step
Any step can be skipped, and the skip can be taken back.
- A personal step is skipped by you, for yourself.
- A step of the organisation is skipped for everyone, so an admin or owner decides.
- Skipping never marks a step done. A skipped step shows as Skipped, and turns to Done by itself once the workspace shows it.
The guide is finished when no step is left to do: each one is done or skipped. The menu entry then disappears. The guide stays reachable at its address.
#Step by step
#Welcome
Three short sections: what Nullgap will do, what it needs from you, and what happens to your code, including what is stored and what is never stored. The longer versions are code handling and AI processing.
#Secure your account
Add an authenticator app or a passkey. See MFA and passkeys. If you signed in through single sign-on, your identity provider decides how you prove who you are and there is nothing to set up here.
#Connect your code
Two ways to finish this step:
- Connect a code host: GitHub, GitHub Enterprise Server, GitLab, Bitbucket Cloud or Azure DevOps, whichever your installation offers. This is what pull request review needs. See connecting your code. For GitHub, the step lists what the app asks for and why.
- Try it first on one repository: add a public repository by its address or upload an archive. Such a repository can be pentested and nothing else.
#Choose repositories
Switch pull request review on for the repositories that should have it. The step shows how many repositories can be reviewed and how many have review on. Repositories added by address or uploaded are not listed here: they have no pull requests.
#Get a first result
Either of these finishes the step:
- A pull request review. Wait for the next pull request, or pick one that is open now from the list. Where the code host cannot list open pull requests, you type the number instead.
- A pentest. An admin starts it. If pentests are priced per run on your plan, you see the price and confirm it on the next page before anything starts.
The step tells you how long a run typically takes, taken from runs that really finished on the service over the last 30 days. When there are too few to say, it says that instead of guessing. It also explains what one run covers on a large codebase; see coverage.
When e-mail is set up for your installation, the admins and owners get one message when the first review has completed and one when the first pentest has completed. The messages link to the result. They do not contain findings.
#Read your first finding
A short tour on a real finding of yours, preferring one that was proven: what the proof is, what the three assurance levels mean and which one this finding has, how to triage, and how to start a fix. See reading a finding and triage.
#Bring your team
Invite people; see people and roles. The step also lists what teams usually set up next, each done or not:
| Item | Where |
|---|---|
| Notifications | Slack |
| Issue tracker | Jira or Linear |
| Single sign-on | Single sign-on |
| API key and MCP server, for developers | API keys and MCP server |
Only the invitation decides whether the step is done.
#Reading the guide with the API
The state of the guide can be read with any key:
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/onboarding/guide" | jq '{next, finished, steps: [.steps[] | {id, status}]}'
{
"next": "choose-repositories",
"finished": false,
"steps": [
{ "id": "welcome", "status": "done" },
{ "id": "secure-account", "status": "skipped" },
{ "id": "connect-code", "status": "done" },
{ "id": "choose-repositories", "status": "todo" },
{ "id": "first-result", "status": "todo" },
{ "id": "first-finding", "status": "todo" },
{ "id": "bring-team", "status": "todo" }
]
}
next is the first step that is neither done nor skipped. The full answer also has, for each step, scope (person or organisation), adminOnly, optional, doneAt, who skipped it, and its items; and facts about the workspace, such as which code hosts the installation offers and how many repositories have review on.
Read with an API key, the two personal steps describe nobody: a key is not a person. Skipping a step and marking the welcome page as read are done by a signed-in person in the console; a key cannot do either.
The open pull requests of a repository, as the guide lists them:
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories/repo_4c1d2e3f5a6b/pull-requests"
It answers { "supported": true, "items": [...] } with up to 30 pull requests, or "supported": false with an empty list when the code host cannot list them.
#If you are stuck
- A step that should be done and is not: check the Done when table above. The guide reads the workspace; reload the page after the change.
- Connecting a code host fails: see the page for that host under connecting your code.
- Anything else: open Help in the menu. See the support channel.
Nullgap documentation