Skip to main content

​
Overview

ZeroPath connects to a self-hosted Bitbucket Server / Data Center instance with an HTTP access token. No app or Atlassian Connect registration is needed on the Bitbucket side. Once connected, ZeroPath lists the repositories the token can see, provisions webhooks, scans on every push and pull request, posts a build status on the pull request’s head commit, and anchors findings as inline comments on the changed lines. A connection has one of two scopes:
  • All accessible projects — one connection for the whole instance. ZeroPath discovers every repository the token can read, across all projects, and you import from all of them at once.
  • One project — the connection is limited to a single project key. Connect several projects as separate connections.
Bitbucket Cloud uses the same dialog with a workspace access token or OAuth; see the quickstart for the Cloud steps.
ZeroPath reaches the instance over HTTPS on port 443 at a bare hostname, for example bitbucket.example.com. A non-standard port (including Data Center’s default 7990), a context path such as https://host/bitbucket, or plain HTTP is not supported; front the instance with a standard HTTPS hostname if yours differs.

​
Prerequisites

  • A ZeroPath organization where you can create VCS installations and repositories.
  • A Bitbucket Data Center instance reachable from ZeroPath over HTTPS, and able to reach ZeroPath in return to deliver webhooks. A firewall that only allows the outbound direction leaves the connection looking healthy while no push or pull request event ever arrives.
  • An HTTP access token:
    • For All accessible projects, a user HTTP access token (create it from a dedicated service account under Manage account → HTTP access tokens). ZeroPath sees exactly what that user can read.
    • For One project, a project-scoped HTTP access token (Project → Settings → HTTP access tokens) or a user token.
    • The token needs Repository read/write and Pull request permissions for scanning and remediation, and Project admin wherever ZeroPath should create webhooks automatically. Repositories in projects where the token lacks admin still import and scan on demand, but their webhooks are reported as failed and no push or pull request scan is triggered for them.

​
Connect the instance

1

Open Bitbucket setup

In ZeroPath, go to Add Repositories, select the Bitbucket tab and choose Use An Access Token.
2

Enter the domain

Enter the instance hostname, for example bitbucket.example.com — no scheme, port, or path.
3

Choose the scope

Pick All accessible projects to connect the whole instance, or One project and enter the project key (the KEY in https://<host>/projects/KEY, not the display name). Project keys are matched case-insensitively.
4

Enter the token

Paste the HTTP access token. ZeroPath validates it against the instance (or the project) immediately and stores it encrypted. Running the dialog again with Update existing rotates a connection’s token in place.

​
Import repositories

Go to Repositories → Add → Bitbucket. The picker lists every unlinked repository visible through your connections, labelled by connection; a repository visible through both a project connection and an instance-wide connection is listed once, under the project connection. Search matches a prefix of the repository name or of the project name (this is how Bitbucket’s listing API filters). Select repositories individually, or choose Add all accessible Bitbucket repositories to import everything the connections can see in a background job that survives restarts and reports its progress in the dialog: how many repositories were added, skipped or failed, any connection that could not be listed, and any added repository whose webhook could not be created. Each repository is imported on its own, so one failure never undoes the others. Rerunning Add all also repairs webhooks for already-linked repositories, which count as skipped after a successful repair. Repairs that still fail are retried and then included in the failed count. A repository that has no commits yet is imported with its configured default branch and no commit, and picks up a real head on the first push. Importing does not start scans; run a full scan or wait for the schedule.

​
Webhooks

ZeroPath provisions webhooks during import and removes them when a repository or connection is deleted. Deliveries are signed with a per-project secret that ZeroPath generates, so there is nothing to configure on the Bitbucket side.
  • On Bitbucket Data Center 8.8 and newer, ZeroPath creates one project-level webhook per project, shared by every imported repository in that project.
  • On older Data Center releases, which have no project-level webhooks, ZeroPath creates one repository-level webhook per imported repository instead. The events and signing secret are the same, and pull request scanning works identically.
Both kinds subscribe to repo:refs_changed, repo:modified, pr:opened, pr:modified, pr:from_ref_updated, pr:reviewer:updated, pr:reviewer:approved, and pr:comment:added.

​
Scan

Pushes to the default branch and pull request activity trigger scans through the webhooks; scheduled and on-demand full scans work regardless. On pull requests ZeroPath posts a build status on the head commit, comments findings inline on the changed lines, and supports @zeropath bot commands in pull request comments.

​
Disconnecting

Deleting a connection removes ZeroPath’s webhooks from Bitbucket first. If a webhook cannot be removed because the token was revoked or no longer has permission, the connection is still deleted and the webhook is reported for manual removal; only a temporary outage keeps the connection around for a retry.

​
Troubleshooting