Bitbucket Cloud
Connector maturity: Beta. See Connector maturity.
Description
The Bitbucket Cloud connector reads the names of the Bitbucket Pipelines variables stored in Bitbucket Cloud through the Bitbucket Cloud REST API 2.0, so credentials that live in pipelines instead of your vault can be found. It reads workspace variables, repository variables and deployment environment variables. It does not scan Bitbucket's users or groups.
Each workspace or repository that has at least one variable appears as a Non-Human account named bitbucket-pipelines:<workspace> or bitbucket-pipelines:<workspace>/<repository>, holding its variables as CI/CD secret credentials; a deployment environment's variables belong to its repository's account. The variables are also compared with your vault on the Secrets Outside Vault page, and the credential KRIs and credential policy rules apply to them.
System Type Classification
| Field | Value |
|---|---|
| System Type | Application |
| Default Scan Priority | 500 |
Version Support
| OrbisID Edition | Supported |
|---|---|
| Community | No |
| Pro | Yes |
| Enterprise | Yes |
Bitbucket Cloud is covered. Bitbucket Data Center is not.
Supported Protocol
| Protocol | Port | Notes |
|---|---|---|
| REST API (HTTPS) | 443 TCP | An API token (HTTP Basic with the account email) or an access token (Bearer) |
What OrbisID Discovers
| Data | Source |
|---|---|
| Workspace variables | GET /2.0/workspaces/{workspace}/pipelines-config/variables |
| Repositories the token administers | GET /2.0/repositories/{workspace}?role=admin |
| Repository variables | GET /2.0/repositories/{workspace}/{repo}/pipelines_config/variables |
| Deployment environments and their variables | GET .../{repo}/environments and .../deployments_config/environments/{uuid}/variables |
By default only variables marked secured are reported. Turn on the system attribute Include Plain Variables (bitbucketIncludeAllVariables) to report every variable; a secret stored as a plain variable is otherwise missed. Bitbucket returns the value of every variable that is not secured. OrbisID discards it as soon as the response is read and never stores or logs it. Bitbucket reports no dates for variables, so none is recorded: an unknown date is not treated as "never".
The workspaces to read are named in the Workspaces attribute, because a token's workspaces are not listed. At most 1,000 repositories per workspace are read. A repository or workspace that cannot be read is skipped with a warning, and variables already recorded are kept rather than removed. If nothing at all can be read, the scan fails instead of reporting that there are no secrets.
Connection Requirements
Required Permissions
Use either:
- an API token of an Atlassian account (put the account email in the credential's Username), or
- a workspace or repository access token (leave the Username empty)
with the Pipelines: read scope (read:pipeline:bitbucket) and Repositories: read. Bitbucket shows pipeline variables to users with admin rights on the repository (and the workspace), so only repositories the token administers are listed.
Credential Mapping
| OrbisID Field | Value |
|---|---|
credential.username | The Atlassian account email address for an API token; empty for an access token |
credential.password | The API token or access token |
system.hostname | api.bitbucket.org (bitbucket.org is mapped to it) |
| Workspaces (system attribute) | The workspace slugs to read, separated by commas |
Network Requirements
The OrbisID server must have HTTPS access to api.bitbucket.org on port 443.
Configuration Steps
- In Bitbucket create an API token or an access token with the scopes above
- Create a Credential in OrbisID (the email as Username for an API token, the token as Password)
- Navigate to Systems → Add System
- Fill in the fields:
| Field | Value |
|---|---|
| Name | Descriptive name (for example Bitbucket - acme) |
| OS Type | Bitbucket Cloud |
| System Type | Application |
| Hostname | api.bitbucket.org |
| Workspaces (attribute) | Your workspace slug or slugs |
| Credential | The token credential |
- Click Test Connection
- Click Save
Troubleshooting
| Symptom | Likely Cause | Resolution |
|---|---|---|
Name the Bitbucket workspace or workspaces to read | The Workspaces attribute is empty | Set it |
Authentication failed - check the Bitbucket token | A wrong or expired token, or an API token without the account email as Username | Check the token and the Username |
Bitbucket refused ... (403) | Missing Pipelines read scope, or no admin rights | Add the scope, or use a token that administers the repositories |
Bitbucket could not find ... (404) | A wrong workspace slug | Check the slug in the workspace URL |
| Repositories are missing | The token does not administer them | Use a token with admin rights |
| Variables appear without dates | Bitbucket reports no dates for variables | Expected |