Nullgap.dev Docs

Connect your code

Bitbucket CloudNew

Connect a Bitbucket Cloud workspace with a workspace access token and a webhook.

A Bitbucket Cloud workspace is connected with a workspace access token you create and a webhook you add. Pull requests are then reviewed: a build status on the commit, a summary comment, inline comments, reply commands and fix pull requests.

Only Bitbucket Cloud (bitbucket.org) can be connected. Bitbucket Data Center cannot; use an archive upload for code that lives there.

#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.
  • In Bitbucket, permission to create a workspace access token and a webhook.

#Step 1: create the access token

In the workspace settings, create a workspace access token with these permissions:

PermissionAccessWhy
RepositoriesRead and writeFetch the code, set the build status, and push a fix branch.
Pull requestsRead and writeRead pull requests and their diffs, post comments, and open fix pull requests.

The token does not need permission to manage webhooks: you add the webhook yourself in step 3.

#Step 2: connect the workspace

Open Integrations. Under Source code, in the Bitbucket row, press Connect and fill in:

FieldWhat to enter
WorkspaceThe workspace ID as it appears in its address: bitbucket.org/<workspace>.
Access tokenThe token from step 1. It is stored encrypted and never shown again.

Before anything is stored, Nullgap checks that the token works for that workspace. If not, you get code_host_rejected. A workspace can be connected to one Nullgap organisation; a second gets already_connected.

#Step 3: add the webhook

When the workspace is connected, the console shows a Webhook URL and a Secret.

In Bitbucket:

  1. Open the workspace, then Settings, Workflow, Webhooks, Add webhook. A workspace webhook covers every repository; a repository webhook covers one.
  2. Paste the URL into URL and the secret into Secret.
  3. Under Triggers, choose Choose from a full list of triggers and tick, under Pull request: Created, Updated, Merged, Declined and Comment created.
  4. Leave Skip certificate verification off, then save.

Bitbucket signs each delivery with the secret. A delivery with a wrong signature, or to an address that does not exist, is answered 401.

#What you will see

The workspace appears in Integrations, and its Git repositories appear under Repositories with review switched on. Repositories added to the workspace later appear when you press Sync on Repositories.

How Bitbucket Cloud differs from GitHub:

  • The result is a build status on the commit, named Nullgap Security Review, not a check with three outcomes. A failing review sets it to FAILED. Bitbucket has no finished state that is neither a pass nor a block, so a neutral result is written as SUCCESSFUL with "(neutral)" after the name and a description that starts with "Neutral, not a pass:". The icon is still green. See checks and gating.
  • No label filters. Bitbucket Cloud pull requests have no labels, so review filters of the kind label are left out for Bitbucket repositories; the other kinds apply as usual.
  • Drafts. A pull request is treated as a draft when Bitbucket marks it so, or when its title starts with Draft:, [Draft], (Draft), WIP: or [WIP].
  • Suggested changes are shown as a patch. A verified fix for the lines under review is posted as a comment containing the change as a diff, together with a pull request to merge it from. There is no one-click button. See suggested changes.
  • People are identified by their Bitbucket account id, not by a user name, because Bitbucket Cloud has no unique user names. That id is what appears as the author of a review and on a review seat.
  • Reply commands need a permission lookup. A reply command is accepted when Bitbucket says its author has write or admin access to the repository. Reading that takes a token that may see the workspace's repository permissions. If the token may not, reply commands are refused and triage is done in the console.

#Rotating the webhook secret

In Integrations, press Rotate webhook secret on the workspace. A new secret is shown once, with the same URL. The old secret stops working at that moment, so deliveries are refused until you have pasted the new one into the webhook's Secret in Bitbucket.

Connecting the same workspace again, for example with a new access token, also issues a new webhook secret.

#What can go wrong

Message or codeCauseWhat to do
code_host_rejectedThe token is wrong, expired, or lacks read and write on repositories and pull requests for that workspace.Create a new workspace access token with those permissions.
already_connectedThe workspace is linked to another Nullgap organisation.Disconnect it there first.
step_up_requiredYour second-factor check is older than fifteen minutes.Confirm with your authenticator code, then try again.
Pull requests are not reviewedThe webhook is missing, its secret does not match, or a trigger is not ticked.Check the webhook's request history in Bitbucket.
Reply commands are answered with a refusalThe author's access could not be confirmed.See the note on reply commands above.

#Removing

Press Disconnect on the workspace. The stored token and secret are deleted, reviews stop and the repositories leave the list. Past reviews and findings are kept. Delete the webhook and revoke the token in Bitbucket.

Nullgap documentation