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.
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, open Repositories, click Add repository, select the Bitbucket tab and choose
Use an Access Token (Add or Update Access Token once a Bitbucket connection exists).
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 repository → 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.
repo:refs_changed, pr:opened,
pr:modified, and pr:from_ref_updated.
Bitbucket pauses a webhook after several consecutive failed deliveries and does not resend the
events it skipped while paused. Webhooks created by earlier ZeroPath releases also subscribe to
repo:modified, pr:reviewer:updated, pr:reviewer:approved, and pr:comment:added; ZeroPath
accepts those deliveries without acting on them, so they never count as failures. Running Add all
accessible Bitbucket repositories again recreates such webhooks with the current event list.
The Test connection button on the webhook in Bitbucket gets a successful response. It only
confirms that Bitbucket can reach ZeroPath; nothing is scanned.
Scan
Pushes to the default branch, and pull requests being opened, edited, or updated with new commits, 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 and comments findings inline on the changed lines.@zeropath bot commands in pull request comments are not supported on Bitbucket.
The build status has the build key ZeroPath Security Scan and is stored on the pull request’s
target repository, including for pull requests from forks, so a Required builds merge check
for that key blocks merging until the scan passes. It reads In progress while the scan runs,
Successful or Failed once the scan reaches a verdict, and Cancelled when the scan is
skipped, fails, or times out. Data Center older than 8.0 has no Cancelled state, so there those
scans read Failed, with the reason in the build’s description. Build statuses use the
repository build-status API, which needs Bitbucket Data Center 7.4 or newer.