Overview

Cranium integrates with cloud-hosted Version Control Systems to scan private repositories for AI components and vulnerabilities. Once connected, you can run Detect AI and CodeSensor scans across your organization's repositories to maintain AI Bills of Materials and assess security risks.

Supported Version Control Systems

Cranium supports the following VCS platforms:

• Azure DevOps
• BitBucket Cloud
• BitBucket Data Center
• GitHub & GitHub Enterprise Cloud
• GitHub Enterprise Server
• GitLab
• GitLab Self-Managed

Authentication Methods

Cranium uses two authentication methods depending on your VCS:

• Personal Access Token (PAT) - Supported by all VCS platforms. You generate a token with read permissions in your VCS platform and provide it to Cranium. Tokens require manual rotation when they expire.
• OAuth (GitHub App) - Available only for GitHub & GitHub Enterprise Cloud. Provides organization-level authentication with automatic token refresh, fine-grained permissions, and audit trails. Recommended for organizations requiring app-based authentication.

Creating a VCS Integration

Step 1: Navigate to Integrations

Open the navigation drawer and select Settings, then click Integrations. Click the blue Add New VCS Integration button above the integrations list.

Step 2: Complete Basic Details

In the Create VCS Integration dialog, provide:

• Name - A descriptive name for this integration (e.g., "Production GitHub" or "Engineering Azure DevOps")
• Description - Optional notes about this integration's purpose
• Service - Select your VCS platform from the dropdown
• Base URL - The root domain of your VCS instance. The Base URL must include an organization name for Azure DevOps, BitBucket Cloud, and GitHub (e.g., https://dev.azure.com/{org}). A BitBucket Data Center URL must include a domain (e.g., https://{domain}).

Step 3: Choose Authentication Method

Select your authentication method based on your VCS platform and requirements.

For GitHub & GitHub Enterprise Cloud:

You can choose either Personal Access Token or OAuth.

Choose OAuth if:

• Your organization requires app-based authentication
• You want automatic token refresh
• You need organization-level audit trails
• You want fine-grained permission management

Choose Personal Access Token if:

• You need individual user access
• Your account lacks organization admin permissions
• You prefer manual token management

For All Other VCS Platforms:

Personal Access Token is the only available option.

Step 4a: Authenticate with Personal Access Token

1. Select Personal Access Token from the Authentication Method dropdown
2. Generate a token in your VCS platform with the required permissions (see Permissions section below)
3. Paste the token into the Personal Access Token field
4. Optionally add project filters (see Project Filtering section below)
5. Click Save

Step 4b: Authenticate with OAuth (GitHub Only)

1. Select OAuth from the Authentication Method dropdown
2. Click the blue Connect to GitHub button
3. A new window opens showing the GitHub authorization screen
4. Review the requested permissions:
5. • Repository read access
   • Metadata read
   • Webhook management (if configuring webhooks)
6. Click Authorize to grant Cranium access

• • If you don't have Organization Owner permissions: GitHub will prompt you to request access. This sends an email to your organization owner for approval.

1. After authorization completes, the dialog displays "Connected to GitHub"
2. Optionally add project filters (see Project Filtering section below)
3. Click Save

Project Filtering (Optional)

Use the Projects filter to limit scans to specific projects within your VCS organization. If you add project names, Detect AI will only scan those projects and skip all others. If you leave this blank, Detect AI can attempt to scan all projects your authentication permits.

To add a project filter:

1. Click + Add under the Projects field
2. Enter the project name (not the full URL path)
3. Click Remove next to any project to delete it from the filter

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

Required Permissions by VCS Platform

Your authentication token or app must have read-only access to repositories and metadata. Specific permission requirements:

Azure DevOps

• Code (Read) - vso.code
• Project And Team (Read) - vso.project

BitBucket Cloud

• Repository Read

BitBucket Data Center

• Project Read
• Repository Read

GitHub (Personal Access Token)

• Repository Read
• Note: For GitHub Enterprise deployments, ensure your PAT has access to the organization and repositories you want to scan.

GitHub (OAuth/GitHub App)

• Permissions are automatically requested during the OAuth authorization flow. The Cranium GitHub App requests only the minimum permissions required for repository scanning and metadata access.

GitLab

• read_user
• read_repository
• read_virtual_registry
• read_api

Token generation guides:

• Azure DevOps - Use personal access tokens
• Bitbucket Cloud - Access Tokens
• Bitbucket Data Center - HTTP access tokens
• GitHub - Managing your personal access tokens
• GitLab - Personal access tokens

Managing Existing Integrations

Viewing Integrations

All configured VCS integrations appear in the VCS Integrations list under Settings > Integrations. The list shows:

• Integration name and description
• VCS service type
• Detect AI scan status and results
• SSH enabled status

Editing an Integration

Click the three-dot menu on the right side of any integration record and select Edit Integration to modify settings.

Deleting an Integration

Click the three-dot menu on the right side of any integration record and select Delete Integration. This removes the integration and stops future scans on connected repositories.

Continuous Monitoring

Cranium can automatically rescan a repository's BOM whenever code is pushed, using a webhook configured on your VCS Integration. To set up Continuous Monitoring, open the three-dot menu on the integration you want to use and select Get Webhook Details. This opens a modal displaying the Webhook URL and Tenant Secret for that integration. Use these to configure a webhook in your VCS platform.

Continuous Monitoring is supported for GitHub, GitHub Enterprise Cloud, GitLab, and GitLab Self-Managed. Azure DevOps, GitHub Enterprise Server, Bitbucket Cloud, and Bitbucket Data Center are not currently supported.

For full setup guidance, see the Continuous Monitoring Overview.

GitHub Authentication Migration

If you have existing GitHub integrations using Personal Access Tokens and want to migrate to GitHub App authentication:

1. Your existing PAT integrations continue working without any action required
2. GitHub App authentication is available for new integrations or voluntary migrations
3. To migrate an existing integration:
4. • Edit the integration
   • Change Authentication Method to OAuth
   • Complete the OAuth authorization flow
   • Save the integration
5. You can maintain both PAT and GitHub App integrations simultaneously for different repositories or organizations

Requirements for GitHub App authentication:

• Organization admin permissions for initial installation
• Re-authorization through OAuth flow when migrating from PAT

Troubleshooting

• Integration fails to save: Verify your Base URL follows the correct format for your VCS platform and that your authentication token has the required permissions.
• Detect AI cannot access repositories: Check that your PAT or GitHub App has permission to access the specific repositories you want to scan. For project-filtered integrations, verify project names are entered correctly.
• GitHub OAuth authorization fails: Ensure you have Organization Owner permissions or have requested access from an organization owner. Check that your organization allows third-party application access.