GitLab Integration Guide

What the Integration Does

The integration uses a dedicated GitLab access token (typically a service account personal 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. For third-party integrations, GitLab recommends a service account with a personal access token (often called a service account token / service access token). That is also DevGrid’s recommended approach.

Recommendation: Create a dedicated service account, add it as a Reporter member of the top-level group that contains the projects DevGrid should sync, then create a personal access token on that service account with the scopes in Step 3.

Grant access at the group level (not project-by-project). That way the integration keeps full visibility as projects and subgroups are added over time. Project-only membership will miss anything created after setup unless someone updates access again.

Why service accounts?

• Not tied to a human user (access survives employee changes)
• Do not consume a licensed seat
• GitLab’s recommended pattern for third-party integrations and automation
• Authenticate with the same API mechanism as other access tokens (PRIVATE-TOKEN)

Note: GitLab does not use a separate token type named “service access token.” A service account authenticates with a personal access token created for that service account. The token value still looks like glpat-… and is used the same way.

Step 2: Create the Access Token

Option A: Service Account + Personal Access Token (Recommended)

A1. Create the service account

GitLab.com / group-scoped service account

1. Navigate to the top-level group that owns the projects DevGrid will access
2. Go to Settings > Service accounts
3. Click Add service account
4. Enter a name (for example DevGrid Integration)
5. Click Create service account

GitLab Self-Managed / Dedicated (instance service account)

1. Sign in as an administrator (or a top-level group Owner if your instance allows group owners to create service accounts)
2. Go to Admin > Settings > Service accounts (instance) or the group Settings > Service accounts page
3. Create a service account as above

A2. Grant membership (required)

Service accounts have no useful project access until they are members of groups or projects.

DevGrid only syncs projects the token’s identity can access as a member (the integration requests projects with membership scoping). If the service account is not a member, those projects will not appear — and DevGrid cannot invent visibility it does not have.

Required for full visibility (entire group, including future projects):

1. Add the service account as a member of the top-level group DevGrid should sync
2. Assign role Reporter (minimum)
3. The account inherits access to existing subgroups/projects and to projects/subgroups created later under that group

Do not rely on adding the service account only to individual projects. That freezes the accessible set at setup time: any new project under the group will be invisible to DevGrid until membership is updated again.

A3. Create the personal access token for the service account

1. On the service accounts page, open the service account
2. Select Manage access tokens (or equivalent)
3. Click Add new token
4. Fill in:
   • Token name: devgrid-integration (or follow your org naming standard, e.g. api-read-devgrid-production)
   • Expiration date: Set per your security policy (GitLab typically defaults to and caps around 365 days unless your admins allow longer / non-expiring service-account tokens)
   • Scopes: See the table in Step 3
5. Click Create personal access token
6. Copy the token immediately — it will not be shown again

Optional (admin/policy dependent): Some GitLab instances allow service-account personal access tokens without an expiry date. Prefer a defined expiry plus rotation unless your security team explicitly requires non-expiring tokens.

Option B: Group Access Token

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

A group access token also covers the full group hierarchy, including projects added later (same full-visibility model as adding a service account at the top-level group). Prefer Option A when your organization wants a first-class service account identity; use Option B when group tokens are simpler for your policies or service accounts are unavailable.

Option C: Project Access Token

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

Option D: Personal Access Token (human user — last resort)

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

Prefer a first-class service account (Option A) over a human or ad-hoc bot user whenever possible.

Availability notes (token types)

If group/project access tokens are unavailable in your tier or disabled by policy, use Option A.

Step 3: Required Token Scopes

The following scopes are required:

Do not grant write scopes (api, write_repository, etc.). The integration is read-only.

Note on read_user: GitLab’s read_user scope is only available on personal access tokens (including service-account PATs) and is not required for this integration. Membership/user data is read via API endpoints covered by read_api.

Without read_repository, commit, file-level, and related repository data will not be available.

Step 4: Required Role Permissions

The token identity (service account, group/project bot, or user) needs at least Reporter access to the groups and projects that DevGrid will sync.

For service accounts, this means explicit group/project membership with role Reporter or higher.

Here's what each data type requires:

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

Issues & Merge Requests

CI/CD

Repository & Code

Security & Compliance

Step 6: Provide Credentials to DevGrid

Share the following with your DevGrid contact:

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

# Optional: confirm token identity (useful for service accounts)
curl -s --header "PRIVATE-TOKEN: YOUR_TOKEN" \
  "https://YOUR_GITLAB/api/v4/user" | jq '{id, username, name, bot: .bot}'

# 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.

If projects are missing from the membership-scoped project list, add the service account (or token identity) as a Reporter member of those groups/projects and re-test.

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:

1. Create a new token following Step 2 (for service accounts: rotate/create a new personal access token on the same service account so memberships do not need to be rebuilt)
2. Send the new token to your DevGrid contact via a secure channel
3. DevGrid will update the configuration (can be done with zero downtime)
4. 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 use a service access token / service account token?
A: Yes — that is the recommended approach. Create a GitLab service account, add it as a Reporter member of the top-level group to sync (so new projects under that group remain visible), then create a personal access token on that service account with read_api and read_repository.

Q: Why group-level access instead of project-by-project?
A: DevGrid can only sync what the token can see. Group-level access (service account on the top-level group, or a Group Access Token) includes projects created later. Project-only access will miss new projects until someone grants access again.

Q: Can we limit which projects are synced?
A: Prefer granting the token full group hierarchy access so nothing is missed at the source. If you still need a narrower dataset in DevGrid, 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.

Service accounts themselves require a sufficiently modern GitLab version/offering. If service accounts are unavailable, use a Group/Project access token or a dedicated non-human user PAT as a fallback.

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].