Skip to main content
Connecting GitLab lets Traversal correlate incidents with recent code changes by pulling commits and merge requests, helping it explain “what changed” alongside telemetry evidence. Supports both gitlab.com and self-hosted GitLab instances.

​
What Traversal reads

  • Merge requests — recent MRs, diffs, and discussions
  • Commits — commit history and changed files
  • Code — file contents and code search results

​
Repository access during investigations

Traversal can combine GitLab API data with a temporary checkout of an allowed project. API access provides merge request metadata, diffs, discussions, and individual file contents. A checkout lets the investigation inspect the wider codebase with local search and analysis tools when it needs more context. Traversal can clone projects and inspect remote references using safe, read-only Git operations. GitLab API access—not a broad glab command surface—continues to provide merge request and code context beyond this focused repository checkout capability. The projects and groups available to an investigation remain limited by the GitLab integration’s configuration and credentials. Repository checkouts run in an ephemeral agent sandbox. Traversal isolates Git configuration for credentialed operations, provides credentials only for the sandbox operation, and redacts credential values from command output. For example, you can ask Traversal to:
  • “Inspect mygroup/service-api for the code path behind this error.”
  • “Compare the current implementation with the merge request linked to the incident.”
  • “Find where the affected service configures database connection timeouts.”
Private or self-hosted GitLab endpoints require a Traversal Connector that can reach the endpoint. The configured GitLab URL must be the HTTPS hostname root, such as https://gitlab.yourcompany.com, without a path prefix.

​
Setup

Choose a token based on where your repositories live:
  • One project: Use a project access token.
  • One group: Use a group access token for projects in that group.
  • Unrelated projects: Use a personal access token (PAT) from a dedicated account with membership only in those projects.
On self-managed GitLab, an internal account can also read projects marked Internal without being a member. If your dedicated PAT account must see only the projects you assign, ask a GitLab administrator to mark it External and grant it access to those projects. Project and group tokens created by internal users may also see Internal projects outside their project or group.
1

Create a token

Go to your GitLab project’s Settings > Access tokens and create a token with the Reporter role and read_api and read_repository scopes. Set an expiration date and copy the token immediately.
2

Configure in Traversal

Go to Company Knowledge > Integrations, select GitLab, choose Project Access Token, enter the numeric Project ID from project settings, and paste the token.

​
Self-hosted GitLab

For self-hosted instances, expand Self-Hosted Configuration and enter your GitLab host base URL (for example, https://gitlab.yourcompany.com). Do not include /api/v4. Traversal appends that path automatically.

​
Private network access

If the service endpoint is not directly reachable by Traversal (as is common with self-hosted services), deploy a Traversal Connector in a network that can reach it. When configuring the integration, select that connector under Network Access Needed. The service endpoint does not need public internet exposure. See Set up the Traversal Connector for deployment and network requirements.

​
Token permissions

  • Scopes: Grant read_api and read_repository for read-only access. This is the default, and all Traversal needs to investigate.
  • Write access (optional): Only if you want Traversal to open merge requests with fixes, grant the api scope and a role that can push branches, such as Developer. The api scope permits writes, so grant it only to a token scoped to the projects Traversal may change.
  • Access: Check which projects the token can read. Traversal’s Project IDs and Group ID fields do not restrict the token or on-demand reads.
  • Rotation: Rotate the token before it expires and update it in Traversal.

​
More information