GitLab and Bitbucket push webhooks

A push webhook scans a GitLab or Bitbucket repository every time code is pushed to one branch, so a merge starts a scan with no CI step. It is the GitLab and Bitbucket counterpart of the GitHub App push scan. Merge request and pull request checks are not built yet; for those, use CI pipelines.

Works with gitlab.com, Bitbucket Cloud (bitbucket.org) and a self-managed GitLab host your operator allows.

#Set it up (Admin)

Quick path: Settings → Repository Automation, choose the repository, then Push webhooks (GitLab, Bitbucket).

1. Pick the scanners on the Dashboard first (the webhook uses the scanners, coverage, environment and time limit chosen on that page).
2. Check Branch to watch (your repository's branch, else main).
3. For a private repository, pick an Access token: a read-only token saved in Organization → Scan credentials with purpose Git access token.
   • GitLab: a project access token (or deploy token) with read_repository.
   • Bitbucket: a repository access token with Repositories: Read. A public repository needs no token.
4. Choose Create GitLab webhook (or Bitbucket). DVSentry shows the Webhook URL and the Secret once. Copy both now.
5. Add the webhook on the host:
   • GitLab: project Settings → Webhooks → Add new webhook. Paste the URL, paste the secret into Secret token, tick Push events (optionally limit it to the same branch), keep SSL verification on, Add webhook.
   • Bitbucket: Repository settings → Webhooks → Add webhook. Paste the URL, paste the secret into Secret, choose the Repository push trigger, Save.
6. Push to the branch (or use the host's Test button with a push event). The push appears under Recent pushes within a few seconds, and the scan starts within about 15 seconds.

#What runs

• A push to the watched branch starts a scan of the pushed commit with the webhook's scanners. Pushes to other branches, tags and branch deletions are ignored.
• The host may send the same push twice (a retry): it is scanned once. A second push of a commit that is already being scanned is recorded as skipped.
• Push scans are fair use: they are admitted like any scan but do not count against your plan's scan quota.
• The scan runs as the Admin who created the webhook. If that person leaves the organization, pushes are recorded as skipped with that reason; create a new webhook.
• Recent pushes shows every push with its status: pending, preparing, queued (the report exists), skipped or failed, with the reason. The report also appears in the scan list and in Automation Execution History.

#Rotate or revoke

• New secret makes a new secret at once and shows it once; the old one stops working immediately, so paste the new one into the host's webhook settings straight away.
• Revoke stops the webhook. Earlier reports stay. To start again, create a new webhook.

#Security

• The secret is made by DVSentry, shown once and stored encrypted. GitLab sends it in X-Gitlab-Token; Bitbucket signs the body with it (X-Hub-Signature: sha256=...). A wrong secret, an unknown webhook and a revoked one all get the same 401, and nothing is recorded.
• The organization and repository come from the webhook's own record, never from the push. The push must also name the repository URL you registered.
• DVSentry never calls the GitLab or Bitbucket API. The only outbound traffic is the clone, made by the repository fetcher with the same checks as every other clone.
• The access token is opened only for the clone of each scan and is never stored with the webhook, written to the report or shown to the scanners. Every use is recorded in the audit log.
• Only an Admin, signed in to the app (not with an API token), can create, rotate or revoke a webhook. Each action is in the audit log.

#Troubleshooting

Something missing or unclear? Tell us with Feedback in the app.