GitLab Integration Guide

What the Integration Does

The integration uses a dedicated GitLab access token to read data from your GitLab instance. All access is read-only. No data is written, updated, or deleted in your GitLab instance.

Data is extracted incrementally based on timestamps, so only new or modified records are pulled after the initial sync.

Step 1: Choose an Access Token Type

GitLab supports several token types. Choose the one that best fits your organization's security policy:

Token Type	Scope	Best For
Group Access Token	All projects within a group and its subgroups	Most deployments — scoped to a group hierarchy
Project Access Token	A single project	Narrow access to one repository
Personal Access Token	All projects the user has access to	Quick setup, but tied to an individual account

Recommendation: Use a Group Access Token scoped to the top-level group that contains the projects DevGrid needs to access. This keeps the token scoped appropriately and not tied to any individual's account.

Step 2: Create the Access Token

Option A: Group Access Token (Recommended)

Navigate to your group in GitLab
Go to Settings > Access Tokens
Click Add new token
Fill in:
- Token name: DevGrid Integration (or your preferred name)
- Expiration date: Set per your security policy (recommended: 1 year, with a calendar reminder to rotate)
- Role: Reporter
- Scopes: See the table in Step 3
Click Create group access token
Copy the token immediately — it will not be shown again

Option B: Project Access Token

Navigate to the project in GitLab
Go to Settings > Access Tokens
Follow the same configuration as above, with role Reporter

Option C: Personal Access Token

Navigate to User Settings > Access Tokens (or Preferences > Access Tokens in newer versions)
Follow the same configuration as above
The token inherits the user's project access, so ensure the user has at least Reporter access to the relevant projects

Note for self-managed GitLab: Group and project access tokens require a GitLab Premium or Ultimate license. If you are on GitLab Free (self-managed), use a Personal Access Token attached to a dedicated service account user.

Step 3: Required Token Scopes

The following scopes are required:

Scope	Required	Why
`read_api`	Yes	Read access to all API endpoints (projects, issues, merge requests, pipelines, jobs, groups, users, vulnerabilities, security findings)
`read_repository`	Yes	Read access to repository commits and file contents
`read_user`	Recommended	Read access to user profile and group membership information

At minimum, read_api and read_repository are required. Without read_repository, commit, file-level, and dependency discovery data will not be available.

Step 4: Required Role Permissions

The token (or the user behind it) needs at least Reporter access to the groups and projects that DevGrid will sync. Here's what each data type requires:

Data	Minimum Role	GitLab API Used
Groups	Reporter	`GET /groups`
Projects	Reporter	`GET /projects`
Issues	Reporter	`GET /projects/:id/issues`
Merge Requests	Reporter	`GET /projects/:id/merge_requests`
MR Comments	Reporter	`GET /projects/:id/merge_requests/:iid/notes`
MR File Diffs	Reporter	`GET /projects/:id/merge_requests/:iid/diffs`
MR Commits	Reporter	`GET /projects/:id/merge_requests/:iid/commits`
Pipelines	Reporter	`GET /projects/:id/pipelines`
Jobs	Reporter	`GET /projects/:id/jobs`
Commits	Reporter	`GET /projects/:id/repository/commits`
Commit File Diffs	Reporter	`GET /projects/:id/repository/commits/:sha/diff`
Users / Members	Reporter	`GET /groups/:id/members/all`
Dependencies (SBOM)	Reporter	`GET /projects/:id/dependencies`
Vulnerabilities	Developer	`GET /projects/:id/vulnerabilities`
Vulnerability Findings	Developer	`GET /projects/:id/vulnerability_findings`
Secret Detection Results	Developer	`GET /projects/:id/vulnerability_findings?scanner=secret_detection`

Note on Security Features: Vulnerability, secret detection, and SAST/DAST findings require GitLab Ultimate with the relevant scanners enabled. If unavailable, the integration gracefully skips these tables — no errors will occur.

Note on Dependencies: The dependency list endpoint requires Dependency Scanning or Container Scanning to be enabled. If unavailable, it is also skipped gracefully.

Step 5: Data We Collect

The integration reads from the following 13 GitLab resources. All access is read-only.

Groups, Projects & Users

Resource	Description
Groups	Group hierarchy and metadata
Projects	Project metadata (non-archived, membership-scoped)
Users	User accounts visible via group membership

Issues & Merge Requests

Resource	Description
Issues	Project issues
Merge Requests	Merge request metadata and status
MR Comments	Review comments and discussion notes on merge requests
MR File Diffs	File-level changes in merge requests
MR Commits	Commits included in each merge request

CI/CD

Resource	Description
Pipelines	CI/CD pipeline runs and status
Jobs	Individual CI/CD job executions

Repository & Code

Resource	Description
Commits	Repository commit history
Commit File Diffs	File-level changes per commit
Repository Files	File contents from the default branch, including package manifest files (e.g., `package.json`, `go.mod`, `requirements.txt`) for dependency discovery and `devgrid.yml` configuration files

Security & Compliance

Resource	Description
Dependencies	Software dependency list / SBOM via GitLab's Dependency Scanning (requires GitLab Ultimate)
Vulnerabilities	Vulnerability records from SAST, DAST, Container Scanning, and Dependency Scanning (requires GitLab Ultimate)
Vulnerability Findings	Detailed security findings including severity, location, and remediation status
Secret Detection Results	Detected secrets and credentials in source code (requires GitLab Ultimate with Secret Detection enabled)

Step 6: Provide Credentials to DevGrid

Share the following with your DevGrid contact:

Item	Example
GitLab Instance URL	`https://gitlab.com` or `https://gitlab.yourcompany.com`
Access Token	`glpat-xxxxxxxxxxxxxxxxxxxx`
Token Type	Group / Project / Personal
Scope	Which group(s) or project(s) the token covers

Use a secure method to transmit the access token (password manager share, encrypted message, etc.). Never send tokens over email.

Step 7: Verify Access

Before handing off the token, verify it can access the expected resources.

Quick Test via cURL

# Test basic API access
curl -s --header "PRIVATE-TOKEN: YOUR_TOKEN" \
  "https://YOUR_GITLAB/api/v4/projects?membership=true&per_page=5" | jq '.[].name_with_namespace'

# Test group access
curl -s --header "PRIVATE-TOKEN: YOUR_TOKEN" \
  "https://YOUR_GITLAB/api/v4/groups?per_page=5" | jq '.[].full_path'

# Test commit access (replace PROJECT_ID with a real project ID)
curl -s --header "PRIVATE-TOKEN: YOUR_TOKEN" \
  "https://YOUR_GITLAB/api/v4/projects/PROJECT_ID/repository/commits?per_page=1" | jq '.[].title'

A successful response returns HTTP 200 with JSON data. If you get HTTP 401, the token is invalid. If you get HTTP 403, the token lacks permissions for that resource.

Network & Firewall Considerations

The integration connects outbound from DevGrid infrastructure to your GitLab instance over HTTPS (port 443).

GitLab.com: No firewall changes needed.
Self-managed GitLab: If your instance restricts inbound connections by IP, contact your DevGrid representative for the list of source IP addresses to allowlist.

API Usage & Rate Limiting

The integration is designed to be respectful of your GitLab instance:

Read-only: no writes, updates, or deletes
Paginated requests: fetches records in pages (up to 100 per request, GitLab's maximum)
Rate-limit aware: honors Retry-After and RateLimit-Remaining headers; automatically backs off when rate limits are approached
Incremental: after the initial sync, only new/modified records are fetched
Concurrent but controlled: limited parallel requests (default 3 concurrent table syncs)

For GitLab.com, the default rate limit is 2,000 requests per minute for authenticated users. The integration stays well within this limit under normal operation.

Token Rotation

When you need to rotate the access token:

Create a new token following Step 2
Send the new token to your DevGrid contact via a secure channel
DevGrid will update the configuration (can be done with zero downtime)
Revoke the old token in GitLab

Tip: Set a calendar reminder before the token's expiration date. Expired tokens will cause sync failures until replaced.

Frequently Asked Questions

Q: Does the integration write any data to our GitLab instance?
A: No. All access is strictly read-only.

Q: Can we limit which projects are synced?
A: Yes. Using a Group Access Token automatically limits scope to that group's projects. Additional filtering (by project name, path, or other criteria) can be configured on the DevGrid side.

Q: Does this work with GitLab self-managed?
A: Yes. Provide your instance URL (e.g., https://gitlab.yourcompany.com) instead of https://gitlab.com.

Q: What GitLab versions are supported?
A: The integration uses the GitLab REST API v4, which is available on GitLab 12.0 and newer. All currently supported GitLab versions are compatible.

Q: What if we don't have GitLab Ultimate?
A: The security tables (vulnerabilities, vulnerability findings, secret detection, dependencies) require GitLab Ultimate with the relevant scanners enabled. If unavailable, those tables are automatically skipped. All other tables work on any GitLab tier.

Support

If you have questions about the integration or need help configuring access, contact your DevGrid representative or reach out to [email protected].