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:
• • Repository Read

Integration Steps

1. Navigate to Settings > Integrations in the Cranium navigation drawer
2. Click the blue Add New VCS Integration button
3. In the integration dialog, provide:
4. 1. Name: A descriptive name for this integration (e.g., "Production Bitbucket Cloud")
   2. Description: Optional notes about this integration's purpose
   3. Service: Select "Bitbucket" from the dropdown
   4. Organization Name: Enter your Bitbucket workspace name
5. Paste your Personal Access Token into the Personal Access Token field
6. Optionally add project filters to limit scanning to specific projects
7. Click Save

Creating a Bitbucket Cloud Personal Access Token

1. Log in to Bitbucket Cloud at bitbucket.org
2. Click your profile avatar in the bottom left corner
3. Select Personal Settings
4. Under Access management, click App passwords
5. Click Create app password
6. Provide a label (e.g., "Cranium Integration")
7. Select the Repository Read permission
8. Click Create
9. 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

1. Navigate to Settings > Integrations in the Cranium navigation drawer
2. Click the blue Add New VCS Integration button
3. In the integration dialog, provide:
4. 1. Name: A descriptive name for this integration (e.g., "Engineering Bitbucket Server")
   2. Description: Optional notes about this integration's purpose
   3. Service: Select "Bitbucket Data Center" from the dropdown
   4. Base URL: Enter the full URL to your Bitbucket Data Center instance (e.g., https://bitbucket.yourcompany.com)
5. Paste your Personal Access Token into the Personal Access Token field
6. Optionally add project filters to limit scanning to specific projects
7. Click Save

Creating a Bitbucket Data Center Personal Access Token

1. Log in to your Bitbucket Data Center instance
2. Click your profile icon and select Manage account
3. In the left sidebar, click Personal access tokens
4. Click Create token
5. Provide a name (e.g., "Cranium Integration")
6. Set an appropriate expiration date
7. Select the following permissions:
8. 1. Project Read
   2. Repository Read
9. Click Create
10. 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.

To add project filters:

1. In the integration form, look for the Projects section
2. Click Add Project
3. Enter the project name (not the full URL path)

Example: If your repository URL is https://bitbucket.org/myorg/projectname/repo, enter projectname in the Projects filter.

When project filters are configured, Cranium will only scan repositories within those specified projects.

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 project names are entered correctly.
• 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.