This guide explains how to connect your GitLab repositories to Cranium for Detect AI and CodeSensor scans. For general information about VCS integrations, see Accessing a Private VCS.

GitLab Service Types

Cranium supports two types of GitLab deployments:

• GitLab refers to GitLab's cloud-hosted service available at gitlab.com. This is GitLab's SaaS platform where organizations create groups and projects under GitLab's centralized infrastructure. Since all GitLab.com instances share the same API endpoints, Cranium only needs your group or organization name to identify which repositories to access.
• GitLab Self-Managed is a self-hosted solution that organizations run on their own infrastructure. Each organization hosts GitLab on their own domain, which means Cranium needs both the full URL to locate your instance and the organization name to identify which groups and projects to scan within that instance. This dual requirement allows Cranium to first connect to your specific GitLab server, then navigate to the correct organizational structure within it.

Integrating GitLab (gitlab.com)

Requirements

To integrate GitLab with Cranium, you need:

• Your GitLab group or organization name
• A Personal Access Token with the following permissions:
• • read_user
  • read_repository
  • read_virtual_registry
  • read_api

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 GitLab")
   2. Description: Optional notes about this integration's purpose
   3. Service: Select "GitLab" from the dropdown
   4. Organization Name: Enter your GitLab group or organization name
5. Paste your Personal Access Token into the Personal Access Token field
6. Click Save

Creating a GitLab Personal Access Token

1. Log in to GitLab at gitlab.com
2. Click your profile avatar in the top right corner
3. Select Edit profile
4. In the left sidebar, click Access Tokens
5. Click Add new token
6. Provide a token name (e.g., "Cranium Integration")
7. Set an appropriate expiration date (optional, but recommended for security)
8. Select the following scopes:
9. 1. read_user
   2. read_repository
   3. read_virtual registry
   4. read_api
10. Click Create personal access token
11. Copy the generated token immediately (you won't be able to see it again)

Why GitLab Requires Only an Organization Name

GitLab.com uses a standardized API endpoint structure where all organizations and groups are accessed through the same base URL. When you provide an organization name, Cranium automatically constructs the correct API paths to access your group's repositories. The organization name serves as both an identifier and a filter, ensuring Cranium only accesses repositories within your specified group.

Integrating GitLab Self-Managed

Requirements

To integrate GitLab Self-Managed with Cranium, you need:

• The full URL to your GitLab Self-Managed instance (e.g., https://gitlab.yourcompany.com)
• Your GitLab group or organization name
• A Personal Access Token with the following permissions:
• • read_user
  • read_repository
  • read_virtual_registry
  • read_api

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 GitLab Server")
   2. Description: Optional notes about this integration's purpose
   3. Service: Select "GitLab Self-Managed" from the dropdown
   4. Base URL: Enter the full URL to your GitLab Self-Managed instance (e.g., https://gitlab.yourcompany.com)
   5. Organization Name: Enter your GitLab group or organization name
5. Paste your Personal Access Token into the Personal Access Token field
6. Click Save

Creating a GitLab Self-Managed Personal Access Token

1. Log in to your GitLab Self-Managed instance
2. Click your profile avatar in the top right corner
3. Select Edit profile
4. In the left sidebar, click Access Tokens
5. Click Add new token
6. Provide a token name (e.g., "Cranium Integration")
7. Set an appropriate expiration date (optional, but recommended for security)
8. Select the following scopes:
9. 1. read_user
   2. read_repository
   3. read_virtual_registry
   4. read_api
10. Click Create personal access token
11. Copy the generated token immediately (you won't be able to see it again)

Why GitLab Self-Managed Requires Both URL and Organization Name

GitLab Self-Managed instances run on infrastructure you control, meaning each installation has a unique domain where the GitLab instance is deployed. Cranium first needs the Base URL to locate and connect to your specific GitLab server. Once connected, Cranium then uses the Organization Name (a separate identifier configured within your GitLab instance) to navigate to the correct group or organizational structure.

This two-part addressing system is necessary because:

1. The URL identifies where your GitLab instance is deployed: Without it, Cranium wouldn't know where to send API requests.
2. The Organization Name identifies your scope within that instance: A single GitLab Self-Managed instance can host multiple top-level groups and organizations, each with its own separate identifier configured in GitLab. The Organization Name tells Cranium which organizational hierarchy to access.

This differs from GitLab.com, where the server location is always know (gitlab.com), and only the organizational identifier is needed.

Troubleshooting

• Integration fails to save
• • Verify your Base URL (for Self-Managed) follows the correct format for your deployment type and that your Personal Access Token has all required permissions.
• Detect AI cannot access repositories
• • Ensure your Personal Access Token has permission to access the specific repositories you want to scan. Verify that your Organization Name correctly matches your GitLab group name.
• Token expired
• • Personal Access Tokens 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.
• Cannot find organization
• • Verify your Organization Name exactly matches your GitLab group name. Organization names in GitLab are case-sensitive. For Self-Managed instances, also verify your Base URL is correct.