Skip to main content

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​

FieldValue
System TypeApplication
Default Scan Priority500

Version Support​

OrbisID EditionSupported
CommunityNo
ProYes
EnterpriseYes

Bitbucket Cloud is covered. Bitbucket Data Center is not.

Supported Protocol​

ProtocolPortNotes
REST API (HTTPS)443 TCPAn API token (HTTP Basic with the account email) or an access token (Bearer)

What OrbisID Discovers​

DataSource
Workspace variablesGET /2.0/workspaces/{workspace}/pipelines-config/variables
Repositories the token administersGET /2.0/repositories/{workspace}?role=admin
Repository variablesGET /2.0/repositories/{workspace}/{repo}/pipelines_config/variables
Deployment environments and their variablesGET .../{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 FieldValue
credential.usernameThe Atlassian account email address for an API token; empty for an access token
credential.passwordThe API token or access token
system.hostnameapi.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​

  1. In Bitbucket create an API token or an access token with the scopes above
  2. Create a Credential in OrbisID (the email as Username for an API token, the token as Password)
  3. Navigate to Systems → Add System
  4. Fill in the fields:
FieldValue
NameDescriptive name (for example Bitbucket - acme)
OS TypeBitbucket Cloud
System TypeApplication
Hostnameapi.bitbucket.org
Workspaces (attribute)Your workspace slug or slugs
CredentialThe token credential
  1. Click Test Connection
  2. Click Save

Troubleshooting​

SymptomLikely CauseResolution
Name the Bitbucket workspace or workspaces to readThe Workspaces attribute is emptySet it
Authentication failed - check the Bitbucket tokenA wrong or expired token, or an API token without the account email as UsernameCheck the token and the Username
Bitbucket refused ... (403)Missing Pipelines read scope, or no admin rightsAdd the scope, or use a token that administers the repositories
Bitbucket could not find ... (404)A wrong workspace slugCheck the slug in the workspace URL
Repositories are missingThe token does not administer themUse a token with admin rights
Variables appear without datesBitbucket reports no dates for variablesExpected