This guide explains how to connect your Bitbucket repositories to Cranium for Detect AI and CodeSensor scans. For general information about VCS integrations, see Accessing a Private VCS.
Bitbucket Service Types
Cranium supports two types of Bitbucket deployments:
- Bitbucket Cloud is Atlassian's hosted solution available at bitbucket.org. Organizations using Bitbucket Cloud access their repositories through Atlassian's infrastructure and use organization names (workspaces) as identifiers. The API endpoints are standardized across all Bitbucket Cloud instances.
- Bitbucket Data Center is a self-hosted solution that organizations run on their own infrastructure. Because each organization hosts Bitbucket on their own domain, Cranium requires the full URL to locate and connect to your specific instance. This allows Cranium to direct API requests to your self-hosted Bitbucket server rather than to Atlassian's cloud infrastructure.
Integrating Bitbucket Cloud
Requirements
To integrate Bitbucket Cloud with Cranium, you need:
- Your Bitbucket workspace name (organization name)
- A Personal Access Token with the following permissions:
- Project Read
- Repository Read
Project Read lets Discovery list the projects in your workspace. It is required when the integration has project filters.
If the token has Repository Read only and the integration has no project filters, Discovery scans your workspace as a single project and includes every repository the token can access.
Integration Steps
- Navigate to Integrations > VCS Integrations in the Cranium navigation drawer
- Click the blue Add New VCS Integration button
- In the integration dialog, provide:
- Name: A descriptive name for this integration (e.g., "Production Bitbucket Cloud")
- Description: Optional notes about this integration's purpose
- Service: Select "Bitbucket" from the dropdown
- Organization Name: Enter your Bitbucket workspace name
- Paste your Personal Access Token into the Personal Access Token field
- Optionally add project filters to limit scanning to specific projects. For Bitbucket Cloud, enter project keys (see Project Filtering below)
- Click Save
Creating a Bitbucket Cloud Personal Access Token
- Log in to Bitbucket Cloud at bitbucket.org
- Click your profile avatar in the bottom left corner
- Select Personal Settings
- Under Access management, click App passwords
- Click Create app password
- Provide a label (e.g., "Cranium Integration")
- Select the Project Read and Repository Read permissions
- Click Create
- Copy the generated token immediately (you won't be able to see it again)
Integrating Bitbucket Data Center
Requirements
To integrate Bitbucket Data Center with Cranium, you need:
- The full URL to your Bitbucket Data Center instance (e.g., https://bitbucket.yourcompany.com)
- A Personal Access Token with the following permissions:
- Project Read
- Repository Read
Integration Steps
- Navigate to Integrations > VCS Integrations in the Cranium navigation drawer
- Click the blue Add New VCS Integration button
- In the integration dialog, provide:
- Name: A descriptive name for this integration (e.g., "Engineering Bitbucket Server")
- Description: Optional notes about this integration's purpose
- Service: Select "Bitbucket Data Center" from the dropdown
- Base URL: Enter the full URL to your Bitbucket Data Center instance (e.g., https://bitbucket.yourcompany.com)
- Paste your Personal Access Token into the Personal Access Token field
- Optionally add project filters to limit scanning to specific projects
- Click Save
Creating a Bitbucket Data Center Personal Access Token
- Log in to your Bitbucket Data Center instance
- Click your profile icon and select Manage account
- In the left sidebar, click Personal access tokens
- Click Create token
- Provide a name (e.g., "Cranium Integration")
- Set an appropriate expiration date
- Select the following permissions:
- Project Read
- Repository Read
- Click Create
- Copy the generated token immediately (you won't be able to see it again)
Project Filtering
For both Bitbucket Cloud and Bitbucket Data Center, you can optionally filter the integration to specific projects. This is useful when you want to limit Cranium's access to particular repositories or teams. When project filters are configured, Cranium only scans repositories within those specified projects.
The value you enter depends on your service type:
- Bitbucket Cloud: Enter the project key, not the project name. The key is the short code Bitbucket shows for the project, for example
PROJ. Bitbucket Cloud project filters require a token with Project Read. - Bitbucket Data Center: Enter the project name (not the full URL path).
To add project filters:
- In the integration form, look for the Projects section
- Click Add Project
- Enter the project key (Bitbucket Cloud) or the project name (Bitbucket Data Center)
Example (Bitbucket Data Center): If your project is named projectname, enter projectname in the Projects filter.
Example (Bitbucket Cloud): If your project is named Platform Services and Bitbucket shows its key as PROJ, enter PROJ in the Projects filter, not Platform Services.
If you change a project filter, run Discovery again so the integration picks up the change.
Note: Bitbucket Cloud project filters match project keys only. If a filter entry holds a project name, Discovery skips that entry. If every entry is a name, Discovery fails. Edit the filter to use project keys and run Discovery again.
Troubleshooting
- Integration fails to save
- Verify your Base URL (for Data Center) follows the correct format for your deployment type and that your Personal Access Token has the required permissions.
- Detect AI cannot access repositories
- Ensure your Personal Access Token has permission to access the specific repositories you want to scan. For project-filtered integrations, verify that Bitbucket Cloud filters use project keys and Bitbucket Data Center filters use project names.
- Bitbucket Cloud Discovery Status shows Failed
- Check that every project filter entry is a project key, not a project name. Check that the token has Project Read and Repository Read and has not expired or been revoked. Edit the integration and run Discovery again.
- Some Bitbucket Cloud projects are missing from Discovery
- A filter entry that holds a project name matches nothing, and Discovery skips it with no message. Replace the name with the project key and run Discovery again.
- Token expired
- Personal Access Tokens can expire based on the expiration date you set during creation. Generate a new token and update the integration by editing it through the three-dot menu on the integration record.





