> ## Documentation Index
> Fetch the complete documentation index at: https://help.nops.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GitLab

> Connect GitLab.com subscription, seat, and usage data to nOps

## 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 is a **cost and usage integration**. It is separate from **GitLab Issues**
in the recommendation workflow, which uses an organization connection and a
project destination. Connecting this card does not enable issue creation.

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.

<Note>
  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.
</Note>

## What token and access do I need?

| Requirement | Value | Why |
| - | - | - |
| **Token scope** | **`read_api`** (least-privilege) or `api` | Read-only access to all the group, member, seat, and usage-quota endpoints nOps calls. GitLab has no billing-specific scope. |
| **Role** | **Owner** on the **top-level group** | Seat / billable-member and usage-quota endpoints require the **Owner** role and work on **top-level groups only**. A Maintainer token returns `403`. |
| **Token type** | **Group access token** (recommended) or personal access token from a group Owner | A group access token is scoped to the one group and isn't tied to a person. |

<Warning>
  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.
</Warning>

<Note>
  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`.
</Note>

<Note>
  Only nOps **admins** and **owners** can connect, re-validate, or disconnect. **Members** see **Admin Only** on connectable cards.
</Note>

## Cost inputs (collected at connect time)

<Warning>
  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.
</Warning>

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:

| Field | Required | Notes |
| - | - | - |
| **Plan** | auto | Detected from your namespace (`free` / `premium` / `ultimate`); confirm or override. |
| **Price per seat** | recommended | Your negotiated price per billable user. This is the main cost driver. |
| **Billing term** | recommended | `monthly` or `annual`. Annual prices are normalized to a monthly figure (÷12). |
| **Currency** | optional | Defaults to `USD`. |
| **Contracted seats** | optional | If your contract fixes a seat count; otherwise nOps uses the live billable-members count. |
| **Included compute minutes / overage rate** | optional | Per month. Defaults to the plan allotment; overage is usually \$0. |
| **Included storage GB / overage rate** | optional | Overage is usually \$0 within the plan allotment. |
| **Invoice total + period** | optional | If supplied, nOps stores it as the actual (EffectiveCost) figure for invoice tie-out. |

<Note>
  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.
</Note>

## Create the token

### Group access token (recommended)

1. Sign in to [GitLab.com](https://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](https://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](https://docs.gitlab.com/user/profile/personal_access_tokens/) and [group access tokens](https://docs.gitlab.com/user/group/settings/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

* [GitLab REST API authentication](https://docs.gitlab.com/api/rest/authentication/)
* [Personal access token scopes](https://docs.gitlab.com/user/profile/personal_access_tokens/#personal-access-token-scopes)
* [Group access tokens](https://docs.gitlab.com/user/group/settings/group_access_tokens/)
* [List billable members of a group](https://docs.gitlab.com/api/group_members/#list-all-billable-group-members)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.