# Connect GitLab

> Watch GitLab on gitlab.com or a self-managed instance. A review request, a failed pipeline or a new to-do reaches your Mac's notch, and the alert shows the merge request with its description and comments, or the jobs that failed.

Source: https://coisland.app/docs/connect-gitlab/

## What you need

- **You need:** Personal access token, read_api, from Edit profile › Access › Personal access tokens
- **The form asks:** GitLab address, Connector name, Personal access token
- **You can watch:** Review requests, Merge requests and issues, Failed pipelines, New releases, To-do items
- **Access:** GET requests only, with a read_api token

CoIsland calls GitLab's REST API straight from your Mac: there is no CoIsland server and no CoIsland account. The token stays in your login Keychain, and every request the GitLab connector sends is a `GET`.

## Create a GitLab personal access token

1. In GitLab, select your avatar, then **Edit profile › Access › Personal access tokens**.
2. Select **Generate token › Legacy token**.
3. **Token name:** one you will recognize, such as `CoIsland`. **Expiration date:** GitLab asks for one (a year at most by default).
4. **Scopes:** `read_api` only. It reads every project you can see and writes nothing.
5. Select **Generate token** and copy it: it starts with `glpat-` and GitLab shows it only once.

### When your GitLab blocks tokens

- On a self-managed GitLab, an administrator can turn off access tokens for everyone (**Admin › Settings › General › Account and limit › Disable access tokens**).
- On gitlab.com, the owner of a group with enterprise users can turn off personal access tokens for those users.

Either way GitLab answers `401 Unauthorized`, and CoIsland says the token was refused, may have expired or been revoked, or that tokens were turned off. Ask your administrator.

## Connect GitLab in CoIsland

1. Open **Settings › Connectors**, click **+** (Add Connector) and choose **GitLab**.
2. Fill in the fields, then click **Test connector**, then **Add Connector**.

| Field | What to enter |
|---|---|
| GitLab address | Leave it as `gitlab.com`, or your GitLab's address, such as `gitlab.example.com` or `gitlab.example.com/gitlab`. https only |
| Connector name | What monitors call it. CoIsland suggests `gitlab`, or `gitlab_example` for your own |
| Personal access token | The token you copied |

**Test connector** calls `GET /api/v4/user` and `GET /api/v4/personal_access_tokens/self` and saves nothing. It shows your username, the token's scopes and its expiry, and warns when the token lacks `read_api`.

## Watch GitLab: the six monitor kinds

| Kind | What alerts | What CoIsland calls |
|---|---|---|
| Review requests | An open merge request asks for your review | `GET /merge_requests?scope=reviews_for_me` |
| Merge requests | A merge request assigned to you, yours, or a project's enters the state you pick | `GET /merge_requests`, or a project's |
| Issues | An issue assigned to you, yours, or a project's | `GET /issues`, or a project's |
| Failed pipelines | A pipeline of the last 7 days fails, or reaches the status you pick | `GET /projects/:project/pipelines` |
| New releases | A release, or with `is:tag` a tag, of the last 30 days | `GET /projects/:project/releases` or `/repository/tags` |
| To-do items | A pending to-do, such as a review requested or a mention | `GET /todos` |

```text
scope:reviews project:acme/api -is:draft
scope:assigned state:opened label:bug
project:acme/api ref:main source:push
project:gitlab-org/gitlab-runner is:tag
state:pending action:review_requested,mentioned type:merge_request
```

- `scope:all` needs a project: every open merge request of gitlab.com is not a question.
- Projects are full paths, subgroups included: `project:acme/web/shop`.
- Each request reads the newest 100. A result with more compares nothing: narrow it.
- Vulnerabilities are not watched: GitLab's vulnerability API needs Ultimate and is being deprecated.

Clicking a row in the notch opens the alert in CoIsland: a merge request shows its description as GitLab renders it, its branches, merge status, pipeline, reviewers and newest comments; a failed pipeline lists its failed jobs and why. **Open in GitLab** goes to the page.

## Troubleshooting GitLab connector errors

- **"GitLab refused the token…"** It expired, was revoked, or tokens were turned off by an administrator or group owner.
- **"The token lacks the scope this needs (api read_api)."** Create a token with `read_api`.
- **"acme/api: Not found, or not visible to this token. GitLab says: Project Not Found."** Check the project's full path and that you are a member.
- **"GitLab redirected the request; not followed."** Use your GitLab's https address.
- **"Rate limited; retry after 30."** gitlab.com allows 5,000 requests an hour per user on the Free plan; CoIsland waits, then retries.