Skip to main content
The SafeDep app for Bitbucket Cloud scans pull requests for supply-chain risk directly in Bitbucket. It is a hosted service built on Atlassian Forge, so unlike Bitbucket Pipes there is no pipeline to configure or run yourself.
  • Scans newly introduced or updated dependencies on every pull request
  • Protects against malicious open source packages, known vulnerabilities, and risky licenses
  • Free for public repositories. Private (commercial) repositories need a SafeDep subscription
  • Reports to your SafeDep Cloud tenant for centralized policy and reporting across repositories

​
How it works

The Forge app is a thin forwarder: it sends pull request events to SafeDep Cloud, which runs the scan and posts the results back to Bitbucket. The app holds no scan logic and makes no decisions on its own. Two safe defaults apply until you act:
  • An installed app does nothing until the workspace is linked to a SafeDep tenant.
  • A linked workspace scans nothing until you enable repositories. New links start with an empty selection (default deny).
Some actions in this guide run from the SafeDep side. Each shows two paths: the SafeDep console at app.safedep.io and the safedep CLI.

​
Prerequisites

Bitbucket workspace

A Bitbucket Cloud workspace where you are an admin. Installing a Forge app and linking the workspace need admin access.

SafeDep Cloud account

A SafeDep Cloud tenant. Follow the Cloud Quickstart to sign up and create one.

safedep CLI (optional)

Needed only for the CLI path. The safedep CLI installed, and logged in with safedep auth login (authentication).

​
Step 1: Install the app

The app is in early access. Install it with the installation link below. The Atlassian Marketplace listing is coming.
A Bitbucket Cloud Forge app installs at the workspace level. You must be a workspace admin to install it.
  1. Open the SafeDep app installation link.
  2. Select the workspace to install into and confirm.
You can also start the install from the SafeDep console. Open Setup, and select Install Bitbucket App. Install Bitbucket App button in the SafeDep console, under Setup then Integrations Installing the app adds a SafeDep page to your workspace settings. Linking pairs the Bitbucket workspace with your SafeDep tenant. A short-lived, single-use link code proves that the same person controls both sides.
Generate a link code:
  1. Open Setup.
  2. On the Bitbucket App card, select Link a workspace.
  3. Copy the code from the panel. Link a Bitbucket workspace panel in the SafeDep console, with the link code and its expiry
The panel shows the time left before the code expires. Select Issue a new code to replace it. A new code invalidates the earlier one.Redeem the code in Bitbucket:
  1. In Bitbucket, select the settings icon, then Workspace settings. Bitbucket settings menu with Workspace settings under Bitbucket Administration
  2. In the sidebar, under Forge Apps, select SafeDep. SafeDep entry under Forge Apps in the Bitbucket workspace settings sidebar
  3. Paste the code in Link code, then select Link workspace. SafeDep page in Bitbucket workspace settings with the link code pasted
Keep the console panel open. Wait until the workspace links successfully.

​
Step 3: Enable repositories for scanning

A fresh link scans nothing. The workspace has a scan scope, selected (the default) or all:
  • selected: only repositories on the allowlist are scanned.
  • all: every repository in the workspace is scanned.
  1. Open Setup, then Integrations. The Bitbucket App card shows Connected.
  2. Select Manage repositories. Bitbucket App card in the SafeDep console, connected, with the Manage repositories button
  3. Set Scan scope to All repositories or Selected.
  4. For Selected, turn on the toggle for each repository to scan. Turn a toggle off to stop scanning that repository. Bitbucket repositories panel with the scan scope and per repository toggles
Optionally, select Sync to Projects to list the enabled repositories under Projects.

​
Step 4: Scan a pull request

Open or update a pull request on an enabled repository. The app scans changed dependencies and reports on: Results appear in the pull request as a comment from the SafeDep app, and the full report is available in your SafeDep Cloud tenant. Comment from the SafeDep app on a Bitbucket pull request with the report summary and package details Uninstall the SafeDep app from Workspace settings, under Installed apps, in Bitbucket. Uninstalling revokes the workspace link and deletes the workspace credential SafeDep holds. To connect again later, reinstall the app and link with a fresh code.
Unlinking from the SafeDep side (CLI or console) without uninstalling the app is planned.

​
Troubleshooting

​
Limitations

  • On-demand scans (safedep project scan create) are not available for Bitbucket projects yet. Pull request scanning is the scan path today.
  • Merge checks (blocking a merge on a failing scan) are not available yet.
  • The app authenticates to Bitbucket with a workspace-wide credential issued by Atlassian. Per-repository credentials are not part of the Forge model.