Bitbucket
Connect Bitbucket Cloud repositories to Safeguard. The API token scopes Safeguard needs, which Bitbucket credentials work, and step-by-step setup.
Private connections need a Safeguard update
Bitbucket Cloud has retired two API endpoints that the private connection uses to check credentials and list workspaces. Until Safeguard is updated, Verify Credentials on the Private tab can fail with Invalid credentials even when the API token is correct. Public repositories are not affected.
What it does
The Bitbucket card connects Safeguard to repositories on Bitbucket Cloud. Safeguard lists the workspaces and repositories your credentials can see, and each repository you select (at a branch or tag) becomes a project that Safeguard clones and scans for an SBOM and findings. With write scopes, Safeguard can also open fix and upgrade pull requests, comment on pull requests and set a build status for the quality gate. Find the card under Integrations on the Project/Product tab.
Public vs private
| Public | Private | |
|---|---|---|
| What you enter | One or more public repository URLs, like https://bitbucket.org/workspace/repository-name | Username and an Atlassian API token |
| Credential needed | None | An API token with Bitbucket scopes |
| What you can scan | The public repositories you add by URL | Every repository the token can read, one workspace at a time |
Supported auth methods
| Method | Use it when | Notes |
|---|---|---|
| Atlassian API token with Bitbucket scopes | Private repositories | The replacement for app passwords. Created per user, with the scopes you pick |
| None (Public tab) | Public repositories only | Nothing to create |
The dialog sends the Username and the token together (HTTP Basic authentication), so tokens that only work as a Bearer token, such as repository, project and workspace access tokens, do not work in it. Signing in with Bitbucket (OAuth) is not available.
Bitbucket Data Center: the dialog offers Bitbucket Data Center under Where does Bitbucket run?, but Safeguard reads only the Bitbucket Cloud API today, so Data Center repositories do not list. Bitbucket Data Center is not supported yet.
Permissions required
For scanning, Safeguard only reads. It writes to Bitbucket only for the optional features marked below, and only when you use them.
Atlassian API token with Bitbucket scopes
| Scope | Required? | What Safeguard uses it for |
|---|---|---|
read:user:bitbucket | Required | Checking the credentials (/user) |
read:workspace:bitbucket | Required | Listing your workspaces in Select Workspace |
read:repository:bitbucket | Required | Listing repositories, branches and tags, reading files, cloning for the scan, and the Quality gate build status |
read:pullrequest:bitbucket | Optional | Reading pull requests and their diffs, and posting pull request comments (pull request review and the quality gate) |
write:repository:bitbucket | Optional | Fix and upgrade pull requests: creating the branch and committing the changed files. Also forking a repository you cannot push to |
write:pullrequest:bitbucket | Optional | Opening fix pull requests, and merging a pull request from Safeguard |
Least privilege: read:user:bitbucket, read:workspace:bitbucket and read:repository:bitbucket.
Token types
| Token type | Works? | Notes |
|---|---|---|
| Atlassian API token with scopes (Bitbucket app) | Yes (recommended) | Enter your Atlassian account email as Username: Bitbucket's API accepts an API token with the account email |
| App password | No | Bitbucket stopped creating app passwords on September 9, 2025 and removed them on July 28, 2026 |
| Repository, project or workspace access token | No | These work only as a Bearer token, and the dialog always sends a username |
| API token without scopes (an Atlassian token for Jira or Confluence) | No | Only a token created with scopes for the Bitbucket app can call the Bitbucket API |
| OAuth consumer or Forge app | Not available yet |
Expiry: Atlassian asks for an expiry date when you create the token. Choose a short one, such as 90 days. When it expires, listing and scans fail until you paste a new token in the connection.
What we never need: any admin: or delete: scope, write:webhook:bitbucket, pipeline, runner, SSH key or permission scopes, or any write scope when you only scan.
Step-by-step setup
Create the credential in Bitbucket
- Select your profile in the top navigation bar, then Account settings.
- Open the Security tab and select Create and manage API tokens.
- Select Create API token with scopes.
- Enter a name and an expiry date, then select Next.
- Choose Bitbucket as the app and select Next.
- Select the scopes from the table above (the three required ones, plus the optional ones for fix pull requests) and select Next.
- Review and select Create token. Copy the token: Atlassian shows it only once.
Or check it from the command line
Atlassian creates API tokens only in the web page above. To check what a token can see:
# The account behind the token (Basic authentication with your Atlassian account email)
curl -s -u '<atlassian-email>:<api-token>' https://api.bitbucket.org/2.0/user
# The workspaces it can read
curl -s -u '<atlassian-email>:<api-token>' https://api.bitbucket.org/2.0/user/workspaces
# The repositories of one workspace
curl -s -u '<atlassian-email>:<api-token>' "https://api.bitbucket.org/2.0/repositories/<workspace>?pagelen=100"Connect it in Safeguard
- Open Integrations and choose the Project/Product tab.
- Click Connect on the Bitbucket card.
- For public repositories, stay on Public, enter a Name, paste each URL and click Add. Then click Next.
- For private repositories, choose Private and enter a Name (and an optional Description). Keep Bitbucket Cloud under Where does Bitbucket run?.
- Under Bitbucket Credentials, enter your Atlassian account email in Username and paste the token into Access Token / App Password.
- Click Verify Credentials. "Credentials verified successfully" means Bitbucket accepted them.
- Click Next. Under Select Workspace, choose a workspace, then select the repositories and the branch or tag of each. You can switch workspaces and add repositories from several.
- Finish with the Connect button (fast, deep or progressive scan).
Webhooks and triggers
This integration has no webhooks to set up. Each selected repository is scanned when you connect it. To rescan new commits, set a schedule under Integrations > Scheduled, or choose Rescan from the connection's menu under Project Configurations.
What we read and store
- Read: the token's account, its workspaces and repositories, branches and tags, and the contents of each selected repository at the chosen branch or tag. For pull request features, the pull request, its diff and its comments.
- Stored: the connection's settings including the username, the repositories you selected, the SBOM and findings of each scan, and the token, which is encrypted at rest with a per-workspace key and never shown again after you save it.
- Not stored: source code. The scanner makes a shallow clone into a temporary folder and deletes it when the scan ends.
- No customer data from this integration is sent to third-party LLMs.
Troubleshooting
| Message you see | Cause | Fix |
|---|---|---|
Invalid credentials | Bitbucket refused the username and token: the username is not your Atlassian account email, the token expired or lacks read:user:bitbucket, or it is an app password or access token. See also the note at the top of this page | Use your account email and an API token with the required scopes |
Failed to verify credentials | Safeguard could not reach Bitbucket | Try again in a few minutes |
Please enter both username and access token to verify | One of the two fields is empty | Fill in Username and Access Token / App Password |
No workspaces found or Failed to fetch workspaces | The token lacks read:workspace:bitbucket, or the workspace list could not be read | Add the scope; see the note at the top of this page |
Invalid repository URL | A URL on the Public tab is not a public Bitbucket repository | Copy the URL from the repository page, or connect it on the Private tab |
git clone failed: ... (on a scan) | The token lost access to the repository or expired, or the branch or tag no longer exists | Check the token's scopes and expiry, then update the connection |
Rotation and disconnect
- Rotate: create a new API token with the same scopes. Under Project Configurations on the Project/Product tab, open the connection's menu, choose Update, paste the new token, click Verify Credentials, and click Save Changes. Then revoke the old token under Account settings > Security > Create and manage API tokens.
- Disconnect: choose Delete from the connection's menu under Project Configurations and confirm Delete configuration. Then revoke the token in your Atlassian account.
Vendor references
- Create an API token, checked 2026-10-16.
- Using API tokens, checked 2026-10-16.
- API token permissions, checked 2026-10-16.
- Using access tokens, checked 2026-10-16.
- Bitbucket Cloud transitions to API tokens: app password deprecation, checked 2026-10-16.
- Bitbucket Cloud changelog (app password brownouts and final removal), checked 2026-10-16.
- Bitbucket Cloud REST API specification, checked 2026-10-16.
GitLab
Connect GitLab.com or a self-managed GitLab to Safeguard. The scopes and roles each token needs, which token types work, and step-by-step setup.
Azure DevOps
Connect Azure Repos in an Azure DevOps organization to Safeguard. The personal access token scopes Safeguard needs, which token types work, service hooks, and step-by-step setup.