Connect GitLab

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

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.