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
The app is in early access. Install it with the installation link below. The Atlassian Marketplace listing is coming.

​
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 CLI (available now) and the SafeDep console at app.safedep.io (coming soon).

​
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

The safedep CLI installed, and logged in with safedep auth login (authentication).

​
Step 1: Install the app

  1. Open the SafeDep app installation link.
  2. Select the workspace to install into and confirm.
Installing the app adds a SafeDep page to your workspace settings. Nothing is scanned yet: the workspace must be linked first. Linking pairs the Bitbucket workspace with your SafeDep tenant. A short-lived, single-use link code proves that the same person controls both sides.
The command prints the code and its expiry. The code is single-use and shown once. Running the command again generates a new code and invalidates every earlier unredeemed one, so re-running is the way to start over.

​
Redeem the code in Bitbucket

  1. In Bitbucket, open Workspace settings, then SafeDep under Apps.
  2. Paste the link code and select Link.
The page shows the linked tenant when the redeem succeeds. Verify from the CLI:

​
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.
List the workspace’s repositories with their UUIDs and current state:
Enable specific repositories by UUID:
Or scan the whole workspace:
Use --disable to remove a repository from the allowlist. Switching scope does not change the stored allowlist, so moving from all back to selected restores your earlier selection.

​
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 SafeDep comment, and the full report is available in your SafeDep Cloud tenant. Pull requests on repositories that are not enabled produce no comment, no status, and no scan.

​
Sync repositories as SafeDep projects

Optionally, adopt Bitbucket repositories as SafeDep projects so scan results are organized per project in your tenant.
Select by name (workspace/repository) or by the immutable repository UUID from repository list. The UUID flag implies the Bitbucket source, so --source is not needed:
The sync is idempotent: repeating it returns the same project for the same repository. When you sync by name and your tenant has both a GitHub installation and a Bitbucket workspace linked, pass --source bitbucket explicitly.
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.