Skip to main content

Bitbucket

Connect your Bitbucket Cloud account to Ciphrix using a scoped user API token for automated compliance monitoring of your repositories and default-branch security settings.

Capabilities​

The Bitbucket integration provides the following capabilities:

✅ Compliance Checks​

Automatically verify security configurations and compliance controls across your Bitbucket Cloud repositories including:

  • Repository privacy: repositories are not publicly accessible
  • Default-branch protection against unrestricted direct pushes
  • Default-branch protection against force pushes and branch deletion
  • At least one pull request approval required, with merge checks enforced

🔄 Import Asset​

Import and track Bitbucket Cloud workspaces and repositories as assets in your Ciphrix inventory.

How to Connect Bitbucket​

Prerequisites​

Before connecting Bitbucket, ensure you have:

  • A Bitbucket Cloud account with access to the workspaces and repositories you want to monitor
  • Permission to create a scoped API token for your Atlassian account
  • Repository administrator access to read branch restrictions for the repositories you want fully assessed
  • All four token scopes listed below

Bitbucket Premium is needed to enforce merge checks and satisfy the pull request approval check. You can connect other Bitbucket Cloud plans, but an advisory approval check alone does not satisfy that control.

Important API Token Notes​

Ciphrix uses the Bitbucket Cloud REST API for this integration.

  • Use a user API token with scopes, created in your Atlassian account with Bitbucket selected as the app.
  • Do not use a repository, project, or workspace access token.
  • Do not use an app password or a Bitbucket Data Center personal access token.
  • Ciphrix requires the token only; there is no email or username credential field.
  • Ciphrix discovers all workspaces and repositories accessible to the token owner.
  • The Connection Identifier and Credential Name are labels in Ciphrix. They do not restrict the scan to a particular workspace.
  • Branch checks use each repository's actual default branch, which does not have to be named main or master.

:::warning Atlassian limitation: administrator scope required

Atlassian's Bitbucket Cloud API requires the admin:repository:bitbucket scope and repository administrator access to read branch restrictions, even for read-only checks. This limitation affects the following Ciphrix checks:

  • CPX-CHK-BTBK-002 — Default Branch Protected
  • CPX-CHK-BTBK-003 — Force Push and Branch Deletion Blocked
  • CPX-CHK-BTBK-004 — PR Approvals Required

If you are not comfortable granting this scope, you can choose not to connect Bitbucket to Ciphrix. You can still provide evidence manually: take screenshots of the repository's branch restriction and merge-check settings and upload them as evidence to the corresponding test in Ciphrix.

For help identifying the settings to capture or the test to attach them to, contact support@ciphrix.com.

:::

Connection Instructions​

Step 1: Create a Bitbucket Cloud User API Token​

  1. Log in to Bitbucket Cloud

    • Go to https://bitbucket.org
    • Sign in with the account that has access to the repositories you want Ciphrix to monitor

  2. Open Atlassian Account Security

    • Open your profile menu and select Account settings
    • On the Atlassian Account page, open Security
    • Select Create and manage API tokens
    • You can also open Atlassian API Token Settings directly

  3. Create a Token with Scopes

    • Select Create API token with scopes
    • Enter a descriptive name such as Ciphrix Compliance Monitoring
    • Choose an expiration date and click Next
    • Select Bitbucket as the app and click Next

  4. Select the Required Scopes

    • Select all four scopes:
      • read:user:bitbucket
      • read:workspace:bitbucket
      • read:repository:bitbucket
      • admin:repository:bitbucket
    • Click Next
    • Review the permissions and click Create token

  5. Copy and Store the Token Securely

    • Copy the token value immediately
    • Atlassian only shows the token value once
    • Store it securely until you add it to Ciphrix

Step 2: Initiate Bitbucket Connection in Ciphrix​

You have two options to initiate the Bitbucket connection:

  1. Navigate to Integration Library

    • Log in to ciphrix.app
    • Go to Integrations in the sidebar
    • Go to the Integration Library tab
    • Search for or browse to Bitbucket

  2. Connect Bitbucket

    • Click the Connect button on the Bitbucket integration tile
    • A connection form will appear
Option B: From Create Connection​

  1. Navigate to Create Connection

    • Log in to ciphrix.app
    • Go to Integrations in the sidebar
    • Click Create Connection

  2. Select Bitbucket

    • From the connection provider dropdown, select Bitbucket
    • A connection form will appear

Step 3: Fill Connection Details​

  1. Enter Connection Information

    • Connection Name: Enter a friendly name for this connection
      • Example: "Engineering Bitbucket"
      • Example: "Production Code Repositories"
    • Connection Identifier: Enter a clear label for this Bitbucket connection
      • Example: engineering-bitbucket
      • This label does not limit which workspaces or repositories are scanned
    • Credential Name: Enter a name to identify the saved credential
      • Example: "Ciphrix Bitbucket Token"
    • Access Token: Paste the scoped Bitbucket user API token created in Step 1
    • Select Items: Keep Bitbucket Checks selected. Select Bitbucket Assets if you want to import asset information

  2. Create Connection

    • Click Create Connection
    • Wait for the credentials to be saved and the connection to be created

Step 4: Verify Connection​

  1. Check Connection Status

    • Open the new connection in Integrations
    • Status should show Active after the credentials are saved
    • A successful scan confirms that the token has the required provider access

  2. Initial Scan

    • Ciphrix scans your environment once a week on its scheduled scan day
    • The first scheduled scan discovers accessible workspaces and repositories and runs the compliance checks
    • You can contact support@ciphrix.com to know your next scan date

  3. View Results

    • Navigate to Monitoring
    • Filter by Bitbucket to view check results and findings for your repositories
    • If asset import is enabled, navigate to Assets to view imported workspaces and repositories

Permissions and Data Access​

The Bitbucket user API token must include all four scopes:

ScopeRequired For
read:user:bitbucketRead the authenticated user's account context
read:workspace:bitbucketDiscover and read accessible workspaces
read:repository:bitbucketRead repository metadata and default-branch configuration
admin:repository:bitbucketRead repository branch restrictions

Repository administrator permission is also needed to read branch restrictions. Adding the scope does not grant the token owner access to repositories they cannot already administer.

Ciphrix uses this access to review:

  • Workspace and repository inventory and metadata
  • Repository public/private settings
  • The actual default branch
  • Direct-push, force-push, and branch-deletion restrictions
  • Approval requirements and merge-check enforcement
  • Effective branching-model configuration when needed to match a branch restriction

Ciphrix makes read-only API requests. It does not push code, create pull requests, change repository settings, or modify branch restrictions. The repository administration scope is required by Bitbucket to read restrictions, even though Ciphrix does not make write requests.

Managing the Integration​

Rotating the User API Token​

To rotate the token used by Ciphrix:

  1. Create a new Bitbucket user API token with all four required scopes
  2. Go to Integrations in Ciphrix
  3. Open the existing Bitbucket connection
  4. Replace the saved Access Token
  5. Click Update Credentials
  6. Revoke the old token in Atlassian after confirming a scan succeeds with the new token

Revoking Access​

To revoke Ciphrix's access to Bitbucket:

  1. Open Atlassian API Token Settings
  2. Find the token created for Ciphrix
  3. Revoke the token
  4. In Ciphrix, disable or delete the Bitbucket connection

Note: Revoking the user API token will prevent future Bitbucket scans from completing successfully.

Troubleshooting​

Connection Failed​

Issue: Credentials cannot be saved or Bitbucket scans cannot authenticate

  • Confirm you pasted a scoped Bitbucket Cloud user API token
  • Confirm Bitbucket was selected as the app when the token was created
  • Confirm the token has not expired or been revoked
  • Ensure there are no extra spaces when copying the token
  • Create a new token and update the connection if the value may have been copied incorrectly

Missing Scopes or HTTP 403 Errors​

Issue: A scan cannot discover workspaces or read repository settings

  • Confirm the token includes all four required scopes
  • Repository read and administration scopes alone are not enough; user and workspace read scopes are also required
  • Create a replacement token with the correct scopes and click Update Credentials in Ciphrix
  • Wait for a successful scan to confirm the new token's access

Branch Restriction Permission Errors​

Issue: Repository privacy can be checked, but branch protection checks show permission errors

  • Confirm the token includes admin:repository:bitbucket
  • Confirm the token owner has administrator access to the affected repositories
  • Ask a repository administrator to create the token if the current account cannot read branch restrictions

No Repositories Found​

Issue: The connection is active but expected repositories are missing

  • Confirm the token owner has access to the relevant Bitbucket Cloud workspaces and repositories
  • Confirm the token includes user, workspace, and repository read scopes
  • Changing the connection identifier does not grant access to another workspace

PR Approval Check Fails​

Issue: An approval requirement exists, but the check still fails

  • Confirm the approval rule applies to the repository's actual default branch
  • Require at least one approval before merging
  • Enforce merge checks so an unmet approval requirement blocks merging
  • Advisory checks alone do not pass this control; enforcement requires Bitbucket Premium

No Compliance Data Appearing​

Issue: Integration connected but no compliance data is visible for more than 7 days

  • Confirm the connection status is Active in Ciphrix
  • Confirm the Bitbucket token is still valid and has all required scopes
  • Contact Ciphrix Support at support@ciphrix.com

Token Was Exposed​

Issue: The Bitbucket user API token may have been shared or exposed

  • Revoke the token in Atlassian API Token Settings
  • Create a new token with all four required scopes
  • Update the Bitbucket connection in Ciphrix with the new token

Support​

Need help with Bitbucket integration?