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

# GitLab

> Connect gitlab.com or a self-hosted GitLab instance.

Nuphos connects to GitLab over **OAuth**: gitlab.com works out of the box, while
self-hosted instances need a one-time OAuth app you create. Once connected, the
agent can work with merge requests, pipelines, issues, and repository contents.

## Connect

### gitlab.com

<Steps>
  <Step title="Start the connection">
    In **Connectors → Connect → GitLab**, keep the host as `https://gitlab.com`
    and authorize. Your browser opens GitLab's consent screen.
  </Step>

  <Step title="Approve and return">
    Approve the requested scopes. GitLab redirects back to the desktop app (via a
    `nuphos://gitlab-callback` link) and the connection completes.
  </Step>
</Steps>

### Self-hosted GitLab

For a self-hosted instance you provide your own OAuth application:

<Steps>
  <Step title="Create an OAuth application on your GitLab">
    In your GitLab (Admin Area → Applications, or a group/user application),
    create an application with scopes **`api`**, **`read_user`**,
    **`read_repository`**, **`write_repository`**, and set the **redirect URI** to
    the value shown in the Nuphos dialog (it points at the Nuphos backend's
    `/gitlab-app/setup`).
  </Step>

  <Step title="Enter the host and app credentials in Nuphos">
    Set the **GitLab host** to your instance URL (e.g.
    `https://gitlab.example.com`) and paste the **Application ID** and **Secret**,
    then authorize as above.
  </Step>
</Steps>

<Note>
  Nuphos applies SSRF protections to the GitLab host — private, loopback, and
  cloud-metadata addresses are rejected. Use a real, reachable HTTPS host.
</Note>

## In the Nuphos app

Browse the connected namespace — merge requests, pipelines, and repository
contents — without leaving Nuphos.

## What the agent can do for you

With code and CI visible, the agent can connect what's deployed to where it came
from. Ask it things like:

* *"Did the deploy pipeline pass, and what went out in it?"* — it reads the
  pipeline and the commits behind it.
* *"Production broke after the last merge — what changed?"* — it correlates the
  incident window with merged MRs and reads the diff.
* *"File an issue for this and link the failing pipeline"* — a write, so it
  pauses for your approval first.

## Permissions & authorization

Two boundaries govern what happens through this connector:

* **Hard boundary — who can use it.** Only team **Administrators** can connect
  or remove the binding, and they can restrict it to specific members with a
  [member allow-list](/security/access-control). Within a session the agent only
  holds credentials you explicitly selected, re-checked on every request.
* **Soft boundary — what the agent may do with it.** Reading MRs, pipelines, and
  code is free-form; writes (issues, comments, MR changes) go through
  [plan approvals](/security/approvals) and
  [Auto-authorization](/security/auto-mode) unless you gave an explicit
  instruction.

The outer limit is the OAuth grant: the connection acts with the access of the
GitLab account that authorized it — authorize with an account whose reach
matches what you want the agent to have.

## Good to know

* For self-hosted instances, the OAuth app is created **once** per instance;
  after that, connecting works the same as gitlab.com.
* Tokens are stored encrypted and refreshed automatically.