# GitLab

> Connect GitLab for the Coder: which access token to create, the scopes and role it needs, where to paste it, and how to fix the usual errors.

Connect GitLab and the Coder works on your projects the same way it does on GitHub: it reads the project, its merge requests, its issues, and its pipelines, copies the project into its own [workspace](/docs/workspaces/files), and hands you a merge request for review. When your [house rules](/docs/ceo/house-rules) allow it, it can also merge.

> [!IMPORTANT]
> Today you connect GitLab in the **StellarFirm desktop app**. On stellarfirm.ai you can browse [Integrations](https://stellarfirm.ai/app/integrations) and read what each tool does; connecting from the web is Coming soon.

## At a glance

| | |
| --- | --- |
| Category | Source control |
| Status | Available |
| Used by | Coder (available now) |
| Connect in | The StellarFirm desktop app, under Integrations |
| What you paste | One access token, starting with `glpat-` |
| Works with | Projects on gitlab.com, including projects in subgroups |

## What assistants can do

| Ability | How it runs | What the token needs |
| --- | --- | --- |
| Read projects, merge requests, and issues | Reads on its own | `api` scope |
| Read changed files and pipeline results | Reads on its own | `api` scope |
| Copy the project into its workspace | Reads on its own | `write_repository` scope (it includes reading) |
| Open an issue | Waits for your Approve | `api` scope |
| Push a branch with its work | Waits for your Approve | `write_repository` scope, and at least the Developer role |
| Open a merge request, a draft by default | Waits for your Approve | `api` scope, and at least the Developer role |
| Merge a merge request | Only as your [merge policy](/docs/ceo/house-rules#merge-policy) allows | `api` scope, and a role allowed to merge into the target branch (Maintainer for a protected branch) |

The Coder cannot create GitLab projects. Create the project yourself, then give it to the Coder.

## Pick a token

All three kinds take the same scopes. They differ in who they act as and what they can reach.

| Token | Acts as | Reaches | Where you can use it |
| --- | --- | --- | --- |
| Project access token | Its own project member | One project | Every self-managed tier; on gitlab.com, Premium and Ultimate |
| Group access token | Its own group member | Every project in one group | Every self-managed tier; on gitlab.com, Premium and Ultimate |
| Personal access token | You | Every project you can reach | Every tier |

A project token keeps access narrowest, and its merge requests show the token's own name rather than yours. On the gitlab.com Free tier, use a personal token, ideally on an account that only belongs to the projects the Coder should touch.

## Create a project access token

1. In GitLab, open the project, then **Settings**, **Access tokens**.
2. Choose **Add new token**.
3. **Token name**: something you will recognise, such as "StellarFirm Coder".
4. **Expiration date**: GitLab sets one within a year. When it expires, the Coder stops as **Blocked** and asks you for a new one.
5. **Select a role**: **Developer**. Choose **Maintainer** only if your merge policy lets the Coder merge into a protected branch such as `main`.
6. **Select scopes**: tick **api** and **write_repository**.
7. Choose **Create project access token** and copy it. GitLab shows it once.

A group access token is the same, from the group's **Settings**, **Access tokens**.

## Create a personal access token

1. In GitLab, open your avatar, then **Edit profile**, **Access**, **Personal access tokens**.
2. Choose **Add new token**. If GitLab asks which kind, choose **Legacy token**: it offers the scopes below.
3. Name it, such as "StellarFirm Coder", and pick an **Expiration date**.
4. Tick **api** and **write_repository**.
5. Choose **Create token** (or **Generate token**) and copy it. GitLab shows it once.

The token can do anything your account can do in those projects, so your own role decides whether it may push and merge.

## Connect it in StellarFirm

1. Open the StellarFirm desktop app and sign in.
2. Open **Integrations** and pick **GitLab**.
3. Paste the token into **Access token**.
4. Leave **Use live GitLab** on and press **Connect**.
5. The card shows **Connected**. Your token is saved on your computer by the desktop app, never shown back to you, and handed to one git command at a time.

## Tell the Coder where to work

The Coder needs a project path, written as `group/project` or `group/subgroup/project`.

- **In your message.** Name it, or paste its link: "Coder, in acme/platform/web, fix the login redirect."
- **For good, per Coder.** Open **Settings**, **Coders**, edit the Coder, and under **Repository and login** choose **GitLab** as source control and fill in **Repository** with the project path. See [several Coders](/docs/personas/coder#several-coders).

Each Coder can also act as its own GitLab member: choose **Its own login** and paste that member's token, with the same scopes and role as above.

## Good to know

- **Pushing and merging follow your house rules.** The Coder pushes to a new branch of its own, never to your default branch, and never force pushes. Pushing waits for your Approve. Merging follows your [merge policy](/docs/ceo/house-rules#merge-policy): review only by default, and never while the pipeline is failing or still running. Your protected branch rules on GitLab still apply.
- **Drafts.** A merge request the Coder opens starts with **Draft:** in its title. GitLab does not merge a draft, so choose **Mark as ready** before you ask the Coder to merge.
- **Merge method.** GitLab merges with your project's own merge method (merge commit, merge commit with semi-linear history, or fast-forward). Change it under the project's **Settings**, **Merge requests**.
- **If the clone fails**, the job stops as **Blocked** before any coding and says what to fix, usually that the token cannot read that project or has expired.
- **Several code hosts connected?** A link, the word GitLab, or "merge request" in your message picks GitLab.
- **Self-managed GitLab** is not connected from the app yet. The Coder's workspace must also be allowed to reach your server. Ask [support](/support) if you need it.
- **Revoke at any time.** Revoke the token in GitLab and the Coder loses access straight away. Then choose **Turn off** on the GitLab card.

## Troubleshooting

| What you see | What it means | What to do |
| --- | --- | --- |
| Blocked: the Coder cannot clone the project | The token cannot see it, or has expired | Check the project path, the token's expiry, and that the token belongs to that project or group |
| 401 Unauthorized | The token was revoked or expired | Create a new token and paste it on the GitLab card |
| 403 Forbidden on a push | The role is too low, or the branch is protected | Give the token at least Developer; the Coder only pushes its own branch |
| 403 Forbidden on opening a merge request or issue | The `api` scope is missing | Create a token with `api` and `write_repository` |
| The merge is refused | The merge request is a draft, the pipeline is not green, or the role cannot merge into that branch | Mark it as ready, wait for the pipeline, or give the token Maintainer |
| You cannot find Access tokens on a project | Project tokens need Premium or Ultimate on gitlab.com | Use a personal access token instead |

## Prompts

```prompt title="Pick up a ticket"
Coder, GitLab is connected. Pick up the top open issue on [group]/[project], implement it, and open a merge request for review once I Approve.
```

```prompt title="Review a merge request"
Coder, read merge request [number] on [group]/[project], check its pipeline, and tell me what to fix before it merges.
```

```prompt title="Explain a failing pipeline"
Coder, the pipeline on [group]/[project] is failing. Read the latest results, tell me why, and propose the smallest fix.
```

## Next

- [Connect your code](/docs/getting-started/connect-your-code): the checklist for every code host.
- [House rules](/docs/ceo/house-rules) and [approvals](/docs/ceo/approvals): what waits for you.
- [GitHub](/docs/integrations/github) and [Bitbucket](/docs/integrations/bitbucket).

---

Source: https://stellarfirm.ai/docs/integrations/gitlab