Git
GitLab
Report builds to GitLab merge requests as a commit status and a summary note, and review with commands.
The GitLab integration works with gitlab.com and self-managed GitLab. Each build of a linked project shows on the merge request as a commit status named CirCI / <build name>, and CirCI keeps one summary note on the merge request up to date. People approve, reject or rerun with /circi commands in a note.
It differs from GitHub in three ways: it uses an access token instead of an App, GitLab statuses have no Approve and Reject buttons, and you add the webhook on GitLab yourself.
| You get | Where |
|---|---|
| A commit status per build name | The merge request's pipeline and merge widget |
| One summary note per merge request | The merge request's discussion |
/circi approve, /circi reject, /circi rerun |
A note on the merge request |
| One help note when a command can't be used | The same discussion, edited in place |
Set up
Section titled “Set up”An owner or admin of the workspace does this under Workspace settings › Integrations › Add integration › GitLab.
- In GitLab, create an access token with the
apiscope. A project, group or personal access token works; use one whose account can see the repositories you want to report to and can post statuses and notes. - In CirCI, enter the GitLab address (
https://gitlab.comor your self-managed address) and the Access token (glpat-…), then connect. CirCI asks GitLab who the token belongs to and lists the projects it can read, so a wrong address, a rejected token or a token without theapiscope fails here with a message. - Add the webhook on GitLab (below).
- On the integration's page, choose the GitLab project each CirCI project reports to.
- To block merging, require the status to pass in the GitLab project's merge request settings.
A GitLab user on a given server can be connected in one workspace only. Connecting again with a new token replaces the credentials and clears a "needs attention" flag. A self-managed address must be public unless the instance sets WEBHOOK_ALLOW_PRIVATE_ADDRESSES (see Environment variables).
Add the webhook on GitLab
Section titled “Add the webhook on GitLab”CirCI only learns about merge requests and notes if GitLab calls it. On the GitLab integration's page, owners and admins see the address and the secret to use. In each GitLab project (or group) open Settings › Webhooks and add:
- URL:
PUBLIC_URL/webhooks/gitlab(the aliasPUBLIC_URL/api/integrations/gitlab/webhookalso works). - Secret token: the secret shown on the integration's page. It stays the same unless the instance secret changes.
- Trigger events: merge request events and comments.
GitLab sends the secret in the X-Gitlab-Token header. CirCI refuses deliveries without it.
Link a project to a GitLab project
Section titled “Link a project to a GitLab project”On the integration's page, choose the GitLab project each CirCI project reports to, written as the path with its namespace, for example acme/web or acme/team/web. The list comes from the repositories the token can read; you can also type the path. A project reports to one git host at a time.
What appears where
Section titled “What appears where”The commit status
Section titled “The commit status”One status per build name, CirCI / <build name>. Its description is the same title the GitHub check uses, and it links to the build.
| Situation | Status | Description |
|---|---|---|
| Processing | running |
Processing screenshots… |
| No changes | success |
No visual changes |
| Changes approved | success |
Changes approved (3 changed · 1 added) |
| Changes await review and the project doesn't block merging | success |
3 changed · 1 added: review required |
| Changes await review and merging is blocked | failed |
3 changed · 1 added: review required |
| Rejected | failed |
Changes rejected (3 changed · 1 added) |
| Some screenshots couldn't be read | failed, or success when merging isn't blocked |
1 screenshot couldn't be read, until the build is uploaded again |
| Processing failed | failed, or success when merging isn't blocked |
Processing failed |
The summary note
Section titled “The summary note”One note per merge request, edited in place, with a table of builds (status, changes, review) and any hosted sites for the newest commit. It has the same text as the GitHub summary comment: the heading CirCI visual tests, the columns Build, Status, Changes and Review, and a closing line that points to the dashboard and the /circi commands. A build with screenshots that couldn't be read says "1 screenshot couldn't be read" in its review cell.
Commands
Section titled “Commands”In a note on the merge request, put one of these on a line of its own:
| Command | What it does |
|---|---|
/circi approve |
Approves the newest build of each build name on the merge request |
/circi reject |
Rejects them |
/circi rerun |
Processes them again |
CirCI puts a thumbs-up reaction on the note when it acted. When it didn't, it reacts with a thumbs-down and writes the reason in one help note per merge request, which it finds again by a hidden marker and edits in place, so repeated mistakes don't pile up notes. The reasons are the ones on the GitHub page: no build yet, still processing, processing failed, or nothing to decide. For someone CirCI can't match to an account the note says "I couldn't tell who you are in CirCI. Sign in at PUBLIC_URL with GitLab (a member of this project's workspace), then try again." Edits of a note don't repeat the action.
Settings
Section titled “Settings”The Merge gate settings on the CirCI project page apply as they do for GitHub: Unreviewed changes block merging, Flaky-only changes block merging and Approve default-branch builds automatically. A build with screenshots that couldn't be read follows Unreviewed changes block merging too: it fails when that is on and passes, with the count in the description, when it's off.
A person may use commands when they have linked their GitLab account in the Signed in with section of their CirCI Profile and can see the project (a member, or an owner or admin of its workspace). CirCI matches the GitLab user ID, never the email.
The merge gate in CI
Section titled “The merge gate in CI”Pass --gate status to make GitLab's status the gate when the instance has no GitHub App configured: the server then can't tell that a GitLab-linked project reports to a git host. Who blocks the merge, GitLab's status or the CI job, is explained in How a build flows.
Troubleshooting
Section titled “Troubleshooting”| What you see | Why, and what to do |
|---|---|
| Connect fails with a message | The address isn't a GitLab server, the token was rejected, or it lacks the api scope. Create a new token with api |
| Statuses appear but commands do nothing | The webhook isn't added, or its secret token doesn't match the one on the integration's page. Check Recent events on GitLab's webhook page |
| Commands get a thumbs-down and the help note | Read the note: it names the reason. If it says it can't tell who you are, link GitLab in Profile |
| The integration shows needs attention | GitLab rejected the token. Connect again with a new token |
| A closed merge request still has review requests | Not handled: nothing happens when a merge request is closed |
What the webhook handles
Section titled “What the webhook handles”- Merge request opened or reopened: remembers the author and gives builds their merge request number. Other merge request updates aren't used.
- Note created on a merge request: the
/circicommands.
Not supported yet
Section titled “Not supported yet”- Approve and Reject buttons on the status (GitLab has none).
- GitLab events beyond merge request open, reopen and notes. For example, closing a merge request does nothing (GitHub closes its review requests).
- Reporting a project to more than one GitLab project.
Not yet verified against gitlab.com or a self-managed GitLab server.