Bitbucket

Trace connects to Bitbucket Cloud through a Forge app named Trace — Atlassian's supported platform for workspace-level apps. Install the app in your workspace, pair it with your Trace organization using a one-time code, and your repositories sync into the dashboard ready to scan.

How it works

1. Install the Trace app. Open the install link provided during your Trace onboarding and install the app into your Bitbucket workspace. Workspace admin permissions are required. (Trace is distributed via a private sharing link, not the Atlassian Marketplace.)
2. Get the pairing code. In Bitbucket, open your workspace settings and select the Trace app page. It displays a one-time pairing code, visible only to workspace admins.
3. Pair the workspace. In the Trace dashboard, go to Settings → Integrations → Bitbucket, click Connect workspace, and enter the code. The pairing code is how you prove control of the workspace — it binds the installation to your Trace organization and nothing else can.
4. Repositories sync. Trace lists the workspace's repositories and they appear in your dashboard. If the workspace's repository list changes later, use Re-sync repositories on the connection.

Running scans

All three scanning engines — SAST, SCA, and Secrets — run on Bitbucket repositories exactly as they do on GitHub: trigger a scan from the repository page in the dashboard and findings land in the same views.

Bitbucket support currently covers manual, dashboard-triggered scans. Pull-request-triggered scans, PR checks, and scheduled scans are not yet available for Bitbucket repositories.

What Trace can access

The Trace app requests two read-only scopes:

• read:repository:bitbucket — list and clone the workspace's repositories for scanning
• read:workspace:bitbucket — resolve the workspace's identity when pairing

Trace never holds standing Bitbucket credentials. Access tokens are short-lived (issued by Atlassian, ~4-hour lifetime) and requested just-in-time for each scan. The handoff transits a single-use, KMS-encrypted exchange that is deleted the moment the scan picks it up — seconds-lived, with a 60-second hard expiry — and the decrypted token lives only in memory for the duration of the clone. There is no app password, no OAuth consumer, and no personal access token involved.

Disconnecting

Uninstall the Trace app from your Bitbucket workspace settings. Scans on its repositories stop resolving credentials immediately; the connection shows as inactive in Trace as soon as the uninstall signal arrives, or at the latest on the next scan attempt. Reinstalling the app resets the pairing — open the Trace app page in the workspace for a fresh code and pair again.

Current limitations

• Bitbucket Cloud only. Bitbucket Data Center and Server are not supported (Forge apps exist only on Cloud).
• Manual scans only. No PR/push-triggered scans, PR check output, or scheduled scans yet.
• Workspace-wide access. Forge apps install at the workspace level; per-repository install granularity is not part of the Bitbucket model.