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

# GitLab

> Connect GitLab.com or self-hosted GitLab to CloudThinker for repository, merge request, and pipeline context, and to power Review

Connect your GitLab account to let CloudThinker agents read repositories, merge requests, and failing pipelines — and to run [Review](/guide/code-review/setup) on the projects you select. GitLab.com authenticates with **OAuth**; self-hosted GitLab uses a **project or group access token**.

## Prerequisites

* A **GitLab account** with access to the projects you want CloudThinker to reach.
* For OAuth: permission to authorize CloudThinker for your GitLab.com account.
* For access tokens: permission to create a **project or group access token**; self-hosted instances need GitLab **version 12.0 or above**.

## Setup

Navigate to **Connections → GitLab** in your CloudThinker workspace, click **Connect**, then pick an authentication method.

<Tabs>
  <Tab title="OAuth (GitLab.com)">
    <Steps>
      <Step title="Start the OAuth flow">
        Click **Connect to GitLab**. CloudThinker redirects you to GitLab's authorization page.
      </Step>

      <Step title="Authorize CloudThinker">
        Sign in to the GitLab account that can access the projects you want CloudThinker to use, then approve access.
      </Step>

      <Step title="Return to CloudThinker">
        After authorization, CloudThinker stores the OAuth tokens and shows a **Connected** status.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Access token">
    <Steps>
      <Step title="Create an access token in GitLab">
        Go to your project or group → **Settings → Access Tokens** and click **Add new token**:

        * **Role**: `Developer` or higher
        * **Scope**: `api`
        * **Expiration date**: set one (recommended)

        Copy the generated token.
      </Step>

      <Step title="Enter the connection details">
        In CloudThinker, switch to the access token tab and enter:

        * **GitLab URL**: `https://gitlab.com`, or your self-hosted instance URL (e.g. `https://gitlab.example.com`)
        * **Token Type**: **Project Access Token** (one project) or **Group Access Token** (all projects in a group)
        * **Access Token**: the token you just created
      </Step>

      <Step title="Validate and connect">
        Click **Validate Token** to confirm access, then click **Connect**. CloudThinker shows a **Connected** status.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Note>
  Review needs one extra step on GitLab: a manual webhook in your project or group. Follow [Configure webhooks](/guide/code-review/provider-auth#configure-webhooks).
</Note>

## Connection details

| Field            | Description                                                 | Example              |
| ---------------- | ----------------------------------------------------------- | -------------------- |
| **GitLab URL**   | Instance URL — token flow only                              | `https://gitlab.com` |
| **Token Type**   | Project or group access token — token flow only             | Project Access Token |
| **Access Token** | The GitLab access token — token flow only                   | —                    |
| **OAuth tokens** | Issued by GitLab and stored automatically — OAuth flow only | —                    |

## Required permissions

* **OAuth** inherits the access of the authorizing GitLab account.
* **Access tokens** need the `api` scope and the `Developer` role or higher — Guest and Reporter roles cannot post comments on merge requests.
* **Write operations** such as branch and merge request changes additionally require explicit [approval](/guide/approval) in CloudThinker.

<Tip>
  Prefer a project or group access token over a personal one: comments appear from a bot user, the token stays scoped to the projects you pick, and revoking it touches nothing else.
</Tip>

## Repository access

On top of what your OAuth account or access token can reach, the connection carries a CloudThinker-side repository policy. Open the connection's detail panel and find **Repository access** under **Settings**:

| Mode         | Behavior                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| **All**      | Every project the credential can reach is listed and readable; new projects are included automatically |
| **Selected** | Only the projects you pick are listed and readable; new projects are excluded until you add them       |

The policy only ever narrows what the credential already grants, and it is separate from choosing which projects run [Review](/guide/code-review/setup). Switching from **Selected** to **All** and back restores your previous selection.

## Agent capabilities

Once connected, agents can:

| Capability         | Description                                                               |
| ------------------ | ------------------------------------------------------------------------- |
| **Repositories**   | List and inspect the projects the connection can reach                    |
| **Merge requests** | Review open merge requests, their discussions, and what is needed to ship |
| **Pipelines**      | Investigate failing pipelines                                             |
| **Changes**        | Branch and merge request changes — **requires approval**                  |

### Verify the connection

```text theme={null}
@alex list the GitLab projects CloudThinker can reach and summarize their open merge requests
```

### Example prompts

```text theme={null}
@alex #report which open merge requests across our GitLab projects are blocked
@alex #recommend a fix for the failing pipeline on the api project
@alex #report this week's merged merge requests across the platform group
```

## Write access

Reads run without approval. Any change to a branch or a merge request is approval-gated: CloudThinker states the effect and the exact inputs, then waits for your confirmation before touching the project.

## Troubleshooting

<Accordion title="Token validation fails">
  The token is expired, lacks the `api` scope, or its role is below `Developer`. Create a new project or group access token with the `api` scope and the `Developer` role or higher, then validate again.
</Accordion>

<Accordion title="Self-hosted instance not reachable">
  Check the **GitLab URL** — use the bare instance URL without a trailing path, and confirm the instance is reachable from the internet. CloudThinker supports self-hosted GitLab version 12.0 and above.
</Accordion>

<Accordion title="Agent cannot find an expected project">
  A project token reaches one project; a group token reaches only that group's projects. Reconnect with a group token for the owning group, or with an account that has access to the missing project.
</Accordion>

<Accordion title="Reviews are not posting on merge requests">
  GitLab requires a manual webhook for Review. Add it in your project or group under **Settings → Webhooks** following [Configure webhooks](/guide/code-review/provider-auth#configure-webhooks).
</Accordion>

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Scoped tokens** — a project or group access token limits CloudThinker to exactly the projects you pick and posts as a bot user.
- **Set expirations** — give tokens an expiration date and rotate them before they lapse.

## Related

<CardGroup cols={2}>
  <Card title="Review Setup" icon="gear" href="/guide/code-review/setup">
    Turn on automated AI code reviews for your GitLab projects
  </Card>

  <Card title="Provider Authentication" icon="key" href="/guide/code-review/provider-auth">
    Authentication and webhook details for every Review provider
  </Card>
</CardGroup>