GitLab

GitLab is connected to a workspace the same way as GitHub: once, and repositories are then picked in projects.

What it gives you

• commits with Quiel-Task: {key} land in the task;
• the merge request shows on the task card, and merging triggers auto-acceptance;
• pipelines and jobs show the build status on the task;
• deployments and previews appear on the card.

It works with gitlab.com and with a self-hosted server, version 16.0 or newer. Older servers cannot be connected: Quiel refuses plainly rather than working halfway.

Connecting with a token

1. In GitLab create a token with the api scope (read_api is not enough, webhooks must be created) and the Maintainer role.
2. A service account (any plan, GitLab 18.11 and later), a group or project token (Premium and above) or a personal access token (available everywhere) will do.
3. "Integrations" → "GitLab" → "Connect GitLab" → token. For a self-hosted server, enter its address.

A token expires. The expiry date is shown on "Integrations"; an error appears there after a failed call to GitLab or a manual "Check". Press "Replace token" and paste a new one.

A token whose permissions cannot be checked is not accepted: better to ask for another token than to accept one that cannot create a webhook.

Connecting through GitLab (OAuth)

• gitlab.com: "Connect GitLab" → "With GitLab" → "gitlab.com", one click. It works only if the Quiel server administrator has set GITLAB_OAUTH_CLIENT_ID and GITLAB_OAUTH_CLIENT_SECRET (see docs/DEPLOY.md); otherwise connect with a token.
• Self-hosted: register an application in your own GitLab (Admin → Applications, or group settings), enable the api scope, and set the Redirect URI to https://<your quiel>/api/v1/gitlab/oauth/callback. Then enter the Application ID and Secret in "Connect GitLab" → "With GitLab" → "Own server".

Actions are performed on behalf of the person who connected. If they leave the GitLab group or lose access, the connection breaks, which shows as an error on the card.

Project repository

"Repositories" → "GitLab" → pick a project from the list. The webhook is created automatically.

One GitLab project can be connected to several Quiel projects. There is still one webhook per GitLab project and connection, and events are fanned out to every binding.

Two modes of working with git

Set in the project settings.

For the platform to open an MR, the repository must be connected from the GitLab list ("Repositories" → "GitLab") and the connection must be working. An address typed by hand does not qualify: there is nothing to open an MR with.

• If an MR for the branch already exists, the platform reuses it instead of creating a second one: resubmitting after edits does not pile up MRs.
• If the project has both GitHub and GitLab repositories (or several repositories), the task must have a repository chosen. Otherwise the platform refuses (ambiguous_repo): it will not guess where the code goes.
• If the connection is disabled or broken, the server has no SECRETS_ENCRYPTION_KEY, or GitLab is temporarily unavailable, the agent gets scm_unavailable. The work is not lost: it is in the branch, and the MR can be opened later or by hand.
• If GitLab refuses to create the MR (for example, missing permissions), the agent gets scm_failed with the reason.

On the task card the MR is labelled "MR !N", GitLab links (merge request, commit, pipeline) are recognized, and the card itself is titled "GitLab". Hints for the agent on GitLab repositories talk about GitLab pipelines and glab, not gh.

Linking commits to tasks

A commit is linked to a task by a line at the end of its message:

Quiel-Task: ATL-42

The client adds it itself. After the push the commit shows up on the task card. A repeated delivery of the same event does not duplicate the link.

In an MR description the platform puts the Quiel-Task line last, and anything that came from the agent (a title, paths of conflicting files) is reduced to a single line, so GitLab commands (quick actions) cannot get into the description. A merge request from a fork (a different GitLab project) is not linked to tasks automatically: no link, no review, no acceptance on merge, and the task title is not published in it. Link it by hand, see Tasks.

GitLab sends at most 20 commits in one push, and a push to several branches at once sometimes sends no event at all. So the platform fetches long pushes through a branch comparison and picks up what was missed every 15 minutes (see "What the platform does in the background").

Checks and acceptance (pipelines and jobs)

On the task card, under the result, there is a GitLab card: the merge request with its state and branch, and below it the pipeline and its jobs with an "x of y" summary. Jobs of merge request pipelines (their ref looks like refs/merge-requests/<number>/head) are attached to the task by the MR number.

A failed job with allow_failure: true counts as neutral, not red: GitLab itself does not treat such a pipeline as failed. External statuses (stage external) show up as checks.

Deployments with an environment and its url land on the card as a preview or production; a finished production deployment triggers the deployed event.

The project settings "Require green checks" and "Return the task to the agent if checks fail" work with GitLab checks the same way as with GitHub checks: checks belong to the task, wherever they came from.

Stacked MRs

An MR on top of another task's branch is a working technique. GitLab retargets dependent MRs itself only if "Delete source branch" is on at merge time, and it is off by default. When the base MR is merged, the platform reminds you: a note stays in the task feed, and project managers get a notification listing what needs retargeting (if a dependent MR still points at the merged branch). The platform does not retarget MRs itself.

Auto-acceptance on merge

Auto-acceptance is switched on in the project settings: when the MR is merged, the task moves to "Done" by itself. Turn it on if review already happens in GitLab; otherwise you get two acceptances in a row.

What the platform does in the background

Every 15 minutes the platform runs GitLab maintenance:

• reprocessing of events that failed to be handled, up to 5 attempts each; the journal of received events is purged after 14 days;
• webhooks, hourly per repository: a missing hook is recreated, one disabled by GitLab is re-enabled; on GitLab 19.1 and newer a hook created with a secret token is recreated with a signature only;
• tokens, every 6 hours: if a token stops working, administrators get a notification (once per breakage); for token connections, expiry reminders at 30, 7 and 1 days (one per threshold);
• push backfill for branches of tasks that are In progress or In review over the last 24 hours.

If the Quiel server was unavailable, maintenance is skipped until the next run. A webhook is processed after the response (GitLab gets 200 right away), so a slow API does not get the hook disabled.

If events do not arrive

1. In GitLab open the project's Settings → Webhooks: there should be a hook with an address like https://<domain>/api/v1/webhooks/gitlab/<connection id>. It is named quiel only on GitLab 17.1 and newer; on older servers look for it by the address /api/v1/webhooks/gitlab/….
2. GitLab disables a hook by itself after a run of delivery errors. Re-enable it in GitLab (Settings → Webhooks → the hook → enable, or send a test event). "Check" on "Integrations" validates only the token and does not re-enable hooks. If the hook is gone, disconnect GitLab and connect it again (hooks are recreated on reconnect) or bind the repository again.
3. For a self-hosted server, the Quiel address must be reachable from that server's network.

Signing: on GitLab 19.1 and newer the webhook carries only the HMAC signature, on 19.0 both signature and secret token, on older versions the secret token.