GitLab triggers start a run from what happens in a project. All five are instant — GitLab tells Bizomate the moment it happens:

  • GitLab · New issue — When an issue is opened.
  • GitLab · New merge request — When a merge request is opened.
  • GitLab · Merge request merged — When a merge request is merged.
  • GitLab · Push to a branch — When commits are pushed.
  • GitLab · Pipeline finished — When a CI/CD pipeline finishes.

Publishing adds a webhook to the project for you, and nothing needs pasting — see How instant triggers work.

Who can do this

Workspace Admins and Editors, on every plan — GitLab is not a premium connection. Viewers see the trigger and its status but cannot change it.

In GitLab, the token's user must be a Maintainer or Owner of the project — for a project access token, made with one of those roles. Adding a webhook needs that.

Before you start

  • A GitLab connection with the api scope — see Connect GitLab.
  • For a GitLab of your own: it must be able to reach Bizomate over the internet, since it sends each event to Bizomate.

Steps

Set up the trigger:

  1. Open the workflow in the designer and open the trigger picker — Browse all triggers on an empty workflow, or select the trigger and Change how it starts.

  2. Under GitLab, select the event — New merge request, say. It reads GitLab · instant. Or type GitLab in Search triggers.

  3. In Connection, choose your GitLab connection — for example Consulace GitLab.

  4. In Project, choose the project — Projects the token reaches, as group/name. For example consulace/billing-service.

  5. For Push to a branch: optional, in Only this branch, a branch name — main. Empty takes every branch.

  6. For Pipeline finished: under When it, choose Finishes, Succeeds or Fails.

  7. The panel reads Publishing sets this up in GitLab, and every publish sets it up again. It stays while the workflow is published — switched off, what arrives is ignored — and is taken away when the workflow is deleted or starts another way.

  8. Add the steps, then Publish. Bizomate adds a webhook to the project for that event.

    The panel reads Waiting for the first event — Make one happen; it appears here within seconds.

Test with a real event:

  1. Make the event happen in the project — open an issue, push a commit, let a pipeline finish.
  2. Within seconds the panel reads Listening — instant — Last event 10:45 · New merge request · !42 Round GST per line.
  3. On Output, select Use the last event, then Test run.

What the trigger gives

Every GitLab trigger gives project — its path, consulace/billing-service.

New issue:

Field What it is
iid The issue's number in the project — what Update an issue and Add a note take.
id GitLab's id for it across the whole GitLab.
title, description Its title and description.
state opened.
url Its page in GitLab.
author The username of whoever opened it.
labels A list of its label names — bug, web.

New merge request and Merge request merged:

Field What it is
iid The merge request's number — !42 is 42 — what Accept a merge request takes.
title Its title.
state opened, or merged.
source, target The branch it comes from and the branch it goes into.
url Its page in GitLab.
author The username of whoever opened it — or, for Merge request merged, whoever merged it.
mergeStatus Whether GitLab can merge it.

Push to a branch:

Field What it is
branch The branch pushed to — main.
user The username of who pushed.
head The commit the branch now points at.
commitCount How many commits the push brought.
commits A list, each with id, message, author and url. GitLab sends at most 20; commitCount counts them all.

Pipeline finished: id, status (success, failed or canceled), ref (the branch), duration in seconds, and url, the pipeline's page.

Use them in later steps as {{ trigger.iid }}, {{ trigger.project }} and so on.

What happens next

  • Each event starts one run of the live version, in Production, named after it — New issue · #42 Invoice totals round wrongly, New merge request · !42 Round GST per line, Merge request merged · !42 Round GST per line, Push to main · 3 commits, Pipeline finished · main · failed.
  • Each workflow has its own webhook in the project, turned on for its one event only. You can see it in GitLab under the project's Settings › Webhooks.
  • Every publish sets the webhook up again: Bizomate deletes its old webhook and adds a new one. A webhook deleted in GitLab comes back the next time you publish.
  • Changing to another trigger, or another project, and publishing — or deleting the workflow — deletes the webhook from the project.

How Bizomate knows an event is GitLab's

When it adds the webhook, Bizomate gives it a secret token of its own, made for that webhook and kept encrypted. GitLab sends the token with every event (the X-Gitlab-Token header), and Bizomate compares it. An event without the right token is answered 401 — The signature does not match. — and starts nothing. The webhook is added with SSL verification on, so GitLab checks it is talking to Bizomate.

Which events start a run

  • New issue — only when an issue is opened. Editing, closing or reopening one does not. Confidential issues do not start a run.
  • New merge request — only when one is opened. Reopening or updating one does not.
  • Merge request merged — only when a merge request is merged. Closing without merging does not.
  • Push to a branch — every push to a branch, or only to the branch in Only this branch — the exact name, capitals included. Pushing a tag does not, and nor does deleting a branch.
  • Pipeline finished — when a pipeline ends. Succeeds takes only success; Fails takes only failed; Finishes takes success, failed and canceled. A pipeline that is still running, or was skipped, does not start a run.

Good to know

  • Merging a merge request is also a push to its target branch. Workflows on both triggers both run.
  • GitLab switches off a webhook that keeps failing. Publishing again adds a new one.
  • A call over 256 KB is not taken, so a very large push may not start a run.

If something goes wrong

What you see Why What to do
Not listening — GitLab would not take Bizomate's address: GitLab refused: 403 Forbidden. Check the connection's details on Connections. Fix it, then publish again. The token's user is not a Maintainer or Owner of the project. Give the user the Maintainer role, or make a project access token with it, then publish again.
Not listening — GitLab would not take Bizomate's address: GitLab refused: 401 Unauthorized. Check the connection's details on Connections. Fix it, then publish again. The token has ended or was revoked. Select Reconnect with a new token, then publish again.
Not listening — … GitLab refused: insufficient_scope. … The token lacks the api scope. Reconnect with a token that has api, then publish again.
Not listening — … GitLab refused: url is blocked: … Your own GitLab refuses to send to Bizomate's address — its outbound requests are limited. Ask your GitLab administrator to allow requests to Bizomate's address.
Waiting for the first event stays Nothing has happened yet, the event is not one that starts a run (see above), or your GitLab cannot reach Bizomate. Make the event happen. In GitLab, the webhook's Recent events show what was sent and Bizomate's answer.
Nothing has arrived yet — make one happen in GitLab, then try again. on Output No event has reached the trigger yet. Make one happen, wait for Listening — instant, then Use the last event.
A run did not start for an event the panel shows The workflow is switched off, or its workspace is archived. Switch it on — see Switch a workflow on or off. The missed event does not run later.