> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Bitbucket Data Center Integration
> Connect a self-hosted Bitbucket Server or Data Center instance to ZeroPath with an HTTP access token for full scans, pull request scans, build statuses, and inline comments
## 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](/docs/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
In ZeroPath, go to **Add Repositories**, select the **Bitbucket** tab and choose
**Use An Access Token**.
Enter the instance hostname, for example `bitbucket.example.com` — no scheme, port, or path.
Pick **All accessible projects** to connect the whole instance, or **One project** and enter
the project key (the `KEY` in `https:///projects/KEY`, not the display name). Project
keys are matched case-insensitively.
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
| Symptom | Cause / fix |
| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Repositories import but their webhook is reported as failed, or **Add all** reports *added repositories have no webhook* | The token lacks **Project admin** on that project, or Bitbucket cannot reach ZeroPath. Grant admin and confirm the inbound path, then run **Add all accessible Bitbucket repositories** again to reprovision the webhooks. |
| *"Invalid Bitbucket access token or workspace/project"* on connect | Wrong project key (use the `KEY` from `https:///projects/KEY`), a revoked token, or the domain is not reachable. |
| *"Instance-wide access is only available for Bitbucket Data Center"* | **All accessible projects** was chosen with `bitbucket.org` or no domain. Cloud connections need a workspace. |
| `BITBUCKET_INSTALLATION_ALREADY_EXISTS` | That instance or project is already connected (project keys compare case-insensitively). Use **Update existing** to rotate its token. |
| *"already linked through this organization"* when importing through an instance-wide connection | The repository's project is also connected as a project connection, which takes precedence. Import it through that connection. |
| Searching for a term returns nothing | Bitbucket's listing filters are prefix matches. Search by the start of the repository name or project name. |