# GitLab

## Overview

GitLab is a DevOps platform for source control, CI/CD, and project planning. Integrate with GitLab to automate developer workflows from Suger — browse projects and groups, read and write repository files, branches, and commits, manage issues and merge requests, and drive CI/CD pipelines, jobs, and releases.

### Org-Level vs User-Level

> **Org-Level**: Organization-wide access via a GitLab **access token** — a service-account personal access token (preferred) or a Group Access Token. Best for shared, company-wide automation, and supports **self-managed** GitLab instances.
>
> **User-Level**: Personal GitLab.com access via OAuth. Use when you want to connect your own account and repositories.

## Create Integration (Org-Level)

### Prerequisites

- A GitLab **access token** with the `api` scope. Options, in order of preference:
  - a **service account** personal access token (Premium/Ultimate),
  - a **Group Access Token** (Premium/Ultimate), or
  - a personal access token (any tier, including Free).
- The token's identity must be a **member** of the groups and projects you want to access.
- For **self-managed** GitLab, your instance host name (e.g. `gitlab.example.com`).

### Create a service-account access token (recommended)

A service account is a machine user that isn't tied to a person, so the integration keeps working through staff changes. Setting one up is two steps:

1. **Create the service account** — as a group Owner, create a service account under your top-level group (**Group → Settings → Service accounts**, or via the API).
2. **Create an access token for it** — generate an access token for that service account with the `api` scope, and set an **expiration date** (GitLab caps this — typically 1 year).

Then add the service account as a **member** of the groups and projects you want Suger to access (any role — it does not need to be Owner).

:::warning
Access tokens expire. Note the expiration date, **rotate the token before it lapses**, and **reconnect the integration** with the new token — otherwise GitLab calls start failing once it expires.
:::

### Authenticate

1. Navigate to Settings > Integrations
2. Click **Connect GitLab**
3. Paste your GitLab **access token**
4. For self-managed GitLab, enter your instance host name (GitLab.com is used by default)
5. Submit — the integration is verified automatically and its status updates to `verified`

:::note
For a Group Access Token or a personal access token instead, create it under **Group → Settings → Access Tokens** or **GitLab → User Settings → Access Tokens** — both need the `api` scope and both expire, so the rotation note above applies. See [GitLab access tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens/).
:::

:::warning
An access token can only see resources whose group or project its identity is a **member** of. If lists come back empty, add the service account (or the token's bot user) as a member of the target group — creating a service account *under* a group does not by itself grant access to it.
:::

## Create User Integration

Use user-level integration when you want to connect your personal GitLab.com account.

1. Click `Connect Now` button in the User Integrations section
2. You will be redirected to GitLab to authorize
3. Grant Suger access to your GitLab account
4. Return to Suger — the integration is connected and verified automatically

## Suger AI Tools

When GitLab is connected, the Suger AI agent can automate GitLab through Suger's built-in tools (45 actions). Capabilities are grouped below.

> **Org-level and user-level**: Both are supported; user-level takes precedence when both are connected.

| Capability | What the agent can do |
|------------|-----------------------|
| **Projects & groups** | Create and manage projects and groups (e.g. `create-project`, `list-groups`) |
| **Repository files** | Read and write repository files (e.g. `get-file`, `create-file`, `update-file`) |
| **Branches & commits** | Manage branches and commits (e.g. `create-branch`, `create-commit`, `list-commits`) |
| **Merge requests** | Full merge-request lifecycle (e.g. `create-merge-request`, `update-merge-request`) |
| **Issues** | Issue CRUD (e.g. `create-issue`, `update-issue`) |
| **CI/CD** | Drive pipelines and jobs and publish releases (e.g. `create-pipeline`, `retry-job`, `create-release`) |

## Edit Integration

Editing is not supported. Delete and recreate.

## Delete Integration

Deleting removes the integration and revokes the stored credentials from Suger.

:::warning
This does not delete any GitLab data. You may also want to revoke the access token in GitLab (**User Settings → Access Tokens**, or the group's **Settings → Access Tokens**).
:::