Skip to main content

​
Overview

nOps uses a GitLab.com access token (with the read_api scope) plus your top-level group to pull subscription, seat, and usage-quota data into Inform. The token is stored securely, validated before save, and is not shown again after you connect. This integration targets GitLab.com SaaS (https://gitlab.com). nOps reads:
  • Subscription & plan — namespace plan tier and billable member count.
  • Seats — billable members (paid seats) and per-member seat usage / last activity.
  • Usage quotas — CI/CD compute minutes and storage (repository, LFS, artifacts, packages, container registry) at the group and project level.
Unlike some vendors, GitLab’s API returns usage quantities and seat counts, not billed dollar amounts — there is no per-line USD billing feed. nOps derives cost from your plan and reports seats, compute minutes, and storage; dollar figures come from your subscription pricing, not the API.

​
What token and access do I need?

The read_api scope alone is not enough — the token owner (or the group access token) must have the Owner role on the top-level group. Seats and usage quotas are not readable at Maintainer level or on subgroups.
GitLab is rolling out fine-grained personal access tokens, but the standard, broadly-supported choice for read-only reporting is a classic token (personal or group) with read_api.
Only nOps admins and owners can connect, re-validate, or disconnect. Members see Admin Only on connectable cards.

​
Cost inputs (collected at connect time)

GitLab has no public billing API. Its REST and GraphQL APIs return usage quantities and seat counts only — never dollars (the invoice lives in the Customers Portal / internal CustomersDot API, which a customer token cannot reach). To report cost, nOps needs a few pricing inputs from you. Provide them once at connect time; nOps derives cost from your seat count, compute minutes, and storage.
The connect form collects the following (stored securely in Secrets Manager alongside your token). Only price per seat is important — GitLab bills are roughly seats × price, so that one number drives most of the cost:
Without a price per seat, nOps still ingests seats, compute minutes, and storage as usage (cost $0). Add the seat price to turn on dollar reporting. All values can be updated later by re-connecting.

​
Create the token

  1. Sign in to GitLab.com as an Owner of your top-level group.
  2. Go to your group’s Settings → Access tokens.
  3. Create a token: set the role to Owner, select the read_api scope, and set an expiration.
  4. Create the token and copy it immediately — it is shown only once.

​
Personal access token (alternative)

  1. Sign in to GitLab.com as a user who is an Owner of the top-level group.
  2. Go to Edit profile → Access → Personal access tokens.
  3. Select the read_api scope, set an expiration, and generate the token.
  4. Copy the token immediately — it is shown only once.
See GitLab personal access tokens and group access tokens for details.

​
Connect in nOps

​
Where to open GitLab

  • To connect for the first time — go to Settings → Integrations and click the GitLab card.
  • To manage an existing connection — go to Settings → Account Status → Connected apps and click the GitLab chip to re-validate or disconnect.

​
Connect steps

  1. Click the GitLab card or chip.
  2. Paste your access token (group access token or personal access token).
  3. Enter your top-level group path (for example my-company) or numeric group ID.
  4. Click Connect.
nOps validates the token against the GitLab.com API before storing it, then uses the group to read seats and usage quotas.

​
Manage your connection

Administrators can Re-validate or Disconnect from the modal. Rotate the token in GitLab before expiry and reconnect in nOps after rotation.

​
Troubleshooting

  • Invalid token — confirm the token has the read_api scope and has not expired.
  • No seat or usage data / 403 — the token needs the Owner role on the top-level group; a Maintainer token or a subgroup token cannot read seats or usage quotas.
  • Wrong group — use the full top-level namespace path (for example my-company) or the numeric group ID; subgroups are not supported for billing/usage.
  • No dollar amounts — expected: GitLab’s API returns usage and seat counts, not billed USD. nOps derives cost from your plan.
  • No data in Inform — allow up to 24 hours after connecting for the first sync.

​
Security

Do not share the token or store it in public repositories. Prefer a group access token with read_api scoped to a single top-level group. Rotate before expiration and disconnect in nOps when rotating.

​
Reference