# GitLab

Connect GitLab to link your repositories to iKanban projects, so agents work in them.

Everything happens on **Agent settings → Connections**, in the **Git providers** card.

## Connect and link (2 minutes)

1. Click **GitLab → Connect**, then **Authorize** on GitLab. iKanban asks only to read the API and your profile; it never writes to GitLab. The row then shows **Connected** and your GitLab username.
2. Click **GitLab → Configure**. Every project of your teams is listed. Click **Link** next to a project and pick a repository.
3. The project row now shows the repository with **Unlink**.

Each person connects their own GitLab account. Connecting doesn't give anyone else access to your repositories. GitLab's access lasts two hours at a time; iKanban renews it on its own, so you only connect once.

## Let this laptop reach the repository

Agents run on your laptop and clone the linked repository with **this laptop's own git sign-in**. Check it once:

```text
git ls-remote https://gitlab.com/<group>/<project>.git HEAD
```

A commit hash means you're ready. If git asks for a password or fails, pick one:

- **Personal access token (HTTPS):** GitLab avatar → **Edit profile → Access → Personal access tokens → Generate token → Legacy token** → scopes **read_repository** and **write_repository** → create (shown once). Run the command again: the username is `oauth2` and the password is the token. Your system keychain remembers it.
- **SSH key already on GitLab:** `git config --global url."git@gitlab.com:".insteadOf "https://gitlab.com/"` makes git use SSH for these repositories.

Prefer an agent to check it all? Use the [GitLab setup prompt](/docs/settings/gitlab-prompt), or `/ikanban-gitlab-setup` in Claude Code once This laptop is set up.

## Good to know

- **Merge requests:** agents can push a branch (they ask you first). iKanban doesn't open GitLab merge requests for you yet; open one from the branch in GitLab.
- **Needs reconnecting:** GitLab refused iKanban's access, for example after you revoked it. Click the row and authorize again.
- **Empty repository list:** you aren't a member of any GitLab project with that account, or you authorized a different one.
- **"Not set up on this server yet":** your iKanban server can't connect GitLab; ask your iKanban administrator.