Bitbucket Integration

KvantumCI supports Bitbucket Cloud (bitbucket.org) as a platform for security and DevSecOps verification runs. Once connected, you can select any Bitbucket repository and branch, execute verification scans, and review security findings, pipeline posture, and Bill of Materials (BOM) data directly in the KvantumCI platform.

Bitbucket Cloud Only

KvantumCI supports Bitbucket Cloud. Bitbucket Data Center and Bitbucket Server are not supported. All API requests are securely routed to Bitbucket Cloud (api.bitbucket.org).

Read-Only & Lightweight

The Bitbucket integration is lightweight and strictly read-only. KvantumCI never modifies customer repositories or CI/CD pipelines, never commits code, and does not perform automated remediation.

Connection methods

To set up a new integration, navigate to Integrations in the left sidebar menu, select Add Integration → Bitbucket Cloud, and provide a configuration name.

KvantumCI supports all three Bitbucket Cloud credential types. Choose the one that fits your plan and security policy. Every method is read-only and uses the same workspace ID, which you can paste as a slug or a bitbucket.org URL:

Method	Best for	Requirement
OAuth client (recommended)	Shared workspaces without personal tokens	Any Bitbucket Cloud plan; workspace admin
Workspace access token	A workspace-owned token with no dependency on a person	Bitbucket Premium plan; workspace admin
Atlassian API token	A scoped token issued to a user or service account	Dedicated Atlassian account with read access to the workspace repositories

---

OAuth client (recommended)

An OAuth client (consumer) configured with client credentials is the recommended connection method. It is owned directly by the workspace rather than tied to an individual team member, and KvantumCI automatically requests short-lived access tokens for each verification scan.

Choose an OAuth client when:

• You are on any Bitbucket Cloud plan, including Free and Standard.
• You want credentials that do not stop working when a team member leaves.
• You prefer short-lived tokens that KvantumCI requests for each scan.

1. Create an OAuth client in Bitbucket

1. As a Bitbucket workspace administrator, go to Workspace settings → Apps and features → OAuth clients.
2. Click Create OAuth client.
3. Under Details, enter a descriptive name (e.g. KvantumCI-Scanner).
4. Under Authorization, select Client credentials only.
5. Under Scopes, grant the following read-only permissions:
   • Account: Read
   • Projects: Read
   • Pipelines: Read (Bitbucket automatically includes Email: Read and Repositories: Read)
   Least privilege

   Do not check any write, admin, or delete permissions. KvantumCI requires only read access.

6. Click Save.
7. From the dialog that opens, copy the Client ID (Consumer Key) and click Show secret to copy the Secret (Consumer Secret). Bitbucket only displays the secret once.

2. Configure the integration in KvantumCI

1. In KvantumCI, open Integrations in the left sidebar menu and click Add Integration.
2. Select Bitbucket Cloud as the provider.
3. Keep OAuth client selected as the connection method.
4. Enter a Name for this configuration (e.g. My Workspace - Bitbucket).
5. In the Workspace field, enter your Bitbucket workspace slug or full URL (e.g. my-workspace or https://bitbucket.org/my-workspace).
6. Enter the Client ID.
7. Paste the Client secret.
8. Click Create.

KvantumCI validates the credentials and workspace access, then confirms the connection.

---

Workspace access token

A workspace access token is owned by the workspace rather than a person. It stops working when it expires or is revoked.

Plan requirement

Workspace access tokens require a Bitbucket Premium plan. On Free or Standard, use an OAuth client instead.

1. Generate a workspace access token in Bitbucket

1. As a workspace administrator, open Workspace settings → Security → Access tokens.
2. Click Create.
3. Enter a descriptive name (e.g. kvantumci-scanner).
4. Set an expiration date according to your security policy.
5. Select the following read-only scopes:
   • Account: Read
   • Repositories: Read
   • Projects: Read
   • Pipelines: Read
6. Click Create token and copy the generated token immediately (Bitbucket will not display it again).

2. Configure the integration in KvantumCI

1. In KvantumCI, open Integrations → Add Integration.
2. Select Bitbucket Cloud and choose Workspace access token.
3. Enter a configuration name.
4. Enter your Bitbucket Workspace slug or URL.
5. Paste your token into the Access token field.
6. Click Create.

---

Atlassian API token

An Atlassian API token is a scoped token issued to a user account. It stops working when that user loses access or the token expires.

Use a dedicated account

Create the token from a dedicated Atlassian account with read access to the workspace repositories, so the integration does not stop when a person leaves.

1. Generate an API Token in Atlassian

1. Signed in as your dedicated service account, open Atlassian Account → Security → API tokens.
2. Click Create API token with scopes.
3. Enter a label and set an expiration date.
4. Under application, choose Bitbucket.
5. Select only the required read scopes:
   • read:repository:bitbucket
   • read:workspace:bitbucket
   • read:project:bitbucket
   • read:pipeline:bitbucket
   • read:user:bitbucket
6. Click Create and copy the token.

2. Configure the integration in KvantumCI

1. In KvantumCI, open Integrations → Add Integration.
2. Select Bitbucket Cloud and choose API token.
3. Enter a configuration name.
4. Enter your Bitbucket Workspace slug or URL.
5. Paste your token into the API token field.
6. Click Create.

---

Validation and error handling

When creating or updating a Bitbucket integration, KvantumCI immediately validates your credentials and reports actionable feedback:

• Workspace verification: Confirms the workspace exists and that credentials have permission to read workspace metadata and list repositories. If the workspace is not found or inaccessible, an error message is surfaced.
• Required scopes: Validates that required read permissions are present. If a scope is missing, KvantumCI identifies the missing scope so you can update the credential in Bitbucket.
• Least-privilege warnings: If a credential has permissions beyond read access (for example, write or admin), KvantumCI accepts the connection and shows a warning recommending a read-only credential.
• Credential mismatch detection: If an Atlassian API token is entered into the OAuth client form (or vice versa), KvantumCI detects the type mismatch and prompts you to select the matching connection method.
• Temporary failures: Bitbucket rate limits and outages are reported as retryable, so you can try again later.

---

Token expiration and rotation

• OAuth client: Access tokens are short-lived and automatically renewed by KvantumCI. Rotate the client secret in Bitbucket and update the integration in KvantumCI when required by your security policy.
• Workspace access tokens and API tokens: Rotate tokens before their expiration date. In KvantumCI, open Integrations, edit your Bitbucket integration, and enter the new token. Leaving the secret field blank keeps the stored one.
• Cleanup: When deleting an integration in KvantumCI, remember to delete the OAuth client or revoke the access token in Bitbucket.

For step-by-step instructions on setting up your first project with Bitbucket, see our Getting started guide.