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