# Connect GitLab

> Connect GitLab.com or a self-managed GitLab instance to AI CodeOps with OAuth or a personal access token, and see how merge requests are opened for you.

Source: https://aicodeops.dev/docs/git/gitlab

AI CodeOps works with GitLab.com and with self-managed GitLab instances. Connect an account once; sessions then write changes on a new branch and open a merge request for review.

## Before you start

- A GitLab account with at least Developer access to the projects you want to use, so it can push branches and open merge requests.
- For a self-managed instance: its public **https** address, for example `https://gitlab.example.com`. The platform has to reach it over the internet. Addresses on private networks, `localhost`, and `.local` or `.internal` names are refused.

## Connect with OAuth

1. In your workspace, open **Configure → Settings** and scroll to **Git Providers**.
2. On the **GitLab** card, leave **Instance URL (blank for gitlab.com)** empty for GitLab.com.
3. Choose **Connect via OAuth** and approve the request on GitLab.

AI CodeOps asks for the `api` and `read_user` scopes. `api` lets it read repositories, push branches and create and merge merge requests; `read_user` shows which account is connected.

OAuth only works against the GitLab server the platform's OAuth app is registered on (GitLab.com by default). The card offers it only for that server. For any other instance, use a token.

## Connect with a personal access token

This is the usual path for a self-managed instance.

1. In GitLab, create a personal access token (**User settings → Access tokens**) with the `api` scope. A project or group access token also works if it has `api` and the Developer role or higher.
2. On the GitLab card in AI CodeOps, enter your **Instance URL** (or leave it blank for GitLab.com).
3. Paste the token into **or access token** and choose **Connect with token**.

AI CodeOps checks the token against your instance before saving it. If it can't connect, the message says which part to fix: GitLab didn't recognise the token, the token lacks the `api` scope, or no GitLab API answered at the address. Tokens are not refreshed: when one expires in GitLab, disconnect and connect again with a new one.

## What AI CodeOps does with the repository

- **Browse:** **Develop → Repositories** lists your projects with their branches, files and merge requests.
- **Branches and merge requests:** when a change is approved and passes its [quality gates](https://aicodeops.dev/docs/quality-gates), AI CodeOps pushes a branch named `codeops/run-<id>` and opens a merge request into the project's default branch. Commits are authored as "AI CodeOps".
- **Merge:** a merge request the console opened can be merged from the console. The release gate runs again first.

Sessions don't register webhooks on your projects, and AI CodeOps doesn't comment on merge requests. A project you connect under **Build & Test → Builds** is the exception: it gets a webhook, so a push or a merge request can start a build, and a commit status with each build's result.

## Your token and your access

- A connection belongs to you, not the workspace. Workspace roles still decide what each member can do.
- Tokens are encrypted at rest (AES-256-GCM). OAuth tokens are refreshed before they expire.
- To remove access, choose **Disconnect** next to the account, or revoke the token in GitLab.

## Next steps

- [Create a project](https://aicodeops.dev/docs/projects) from a GitLab repository.
- [Run your first session](https://aicodeops.dev/docs/sessions).
- Using Gitea or Forgejo too? See [Connect Gitea](https://aicodeops.dev/docs/git/gitea) and [Connect Forgejo](https://aicodeops.dev/docs/git/forgejo).
