# 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). For any other instance you get "GitLab sign-in isn't set up on this server": 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. "Token rejected — check the URL and key." means the URL or token is wrong, or the token lacks access. 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.

AI CodeOps doesn't register webhooks on your projects or comment on merge requests.

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