The GitLab driver supports sources, triggers, and reporters. It can interact with the public service as well as site-local installations of GitLab.


The driver is not features complete compared to the other drivers provided with Zuul.

Configure GitLab

Zuul needs to interact with projects by:

  • receiving events via web-hooks

  • performing actions via the API

The Zuul user’s API token configured in zuul.conf must have the following ACL rights: “api”. The API token must be created in user Settings, Access tokens.

Each project to be integrated with Zuul needs in “Settings/Webhooks”:

  • “URL” set to http://<zuul-web>/zuul/api/connection/<conn-name>/payload

  • “Merge request events” set to “on”

  • “Push events” set to “on”

  • “Tag push events” set to “on”

  • “Comments” set to “on”

  • Define a “Secret Token”

Connection Configuration

The supported options in zuul.conf connections are:

<gitlab connection>
<gitlab connection>.driver (required)

The connection must set driver=gitlab for GitLab connections.

<gitlab connection>.api_token

The user’s API token.

<gitlab connection>.webhook_token

The project’s webhook secret token.

<gitlab connection>.server

Hostname of the GitLab server.

<gitlab connection>.canonical_hostname

The canonical hostname associated with the git repos on the GitLab server. Defaults to the value of <gitlab connection>.server. This is used to identify projects from this connection by name and in preparing repos on the filesystem for use by jobs. Note that Zuul will still only communicate with the GitLab server identified by server; this option is useful if users customarily use a different hostname to clone or pull git repos so that when Zuul places them in the job’s working directory, they appear under this directory name.

<gitlab connection>.baseurl
Default: https://{server}

Path to the GitLab web and API interface.

<gitlab connection>.cloneurl
Default: {baseurl}

Path to the GitLab Git repositories. Used to clone.

Trigger Configuration

GitLab webhook events can be configured as triggers.

A connection name with the GitLab driver can take multiple events with the following options.

pipeline.trigger.<gitlab source>

The dictionary passed to the GitLab pipeline trigger attribute supports the following attributes:

pipeline.trigger.<gitlab source>.event (required)

The event from GitLab. Supported events are:

pipeline.trigger.<gitlab source>.action

A gl_merge_request event will have associated action(s) to trigger from. The supported actions are:


Merge request opened.


Merge request synchronized.


Comment added to merge request.


Merge request approved.


Merge request unapproved.

pipeline.trigger.<gitlab source>.comment

This is only used for gl_merge_request and comment actions. It accepts a list of regexes that are searched for in the comment string. If any of these regexes matches a portion of the comment string the trigger is matched. comment: retrigger will match when comments containing ‘retrigger’ somewhere in the comment text are added to a merge request.

pipeline.trigger.<gitlab source>.ref

This is only used for gl_push events. This field is treated as a regular expression and multiple refs may be listed. GitLab always sends full ref name, eg. refs/heads/bar and this string is matched against the regular expression.

Reporter Configuration

Zuul reports back to GitLab via the API. Available reports include a Merge Request comment containing the build results. Status name, description, and context is taken from the pipeline.

pipeline.<reporter>.<gitlab source>

To report to GitLab, the dictionaries passed to any of the pipeline reporter attributes support the following attributes:

pipeline.<reporter>.<gitlab source>.comment
Default: true

Boolean value that determines if the reporter should add a comment to the pipeline status to the GitLab Merge Request.

pipeline.<reporter>.<gitlab source>.approval

Bolean value that determines whether to report approve or unapprove into the merge request approval system. To set an approval the Zuul user must be a Developer or Maintainer project’s member. If not set approval won’t be reported.

Requirements Configuration

As described in pipeline.require pipelines may specify that items meet certain conditions in order to be enqueued into the pipeline. These conditions vary according to the source of the project in question.

      open: true

This indicates that changes originating from the GitLab connection must be in the opened state (not merged yet).

pipeline.require.<gitlab source>

The dictionary passed to the GitLab pipeline require attribute supports the following attributes:

pipeline.require.<gitlab source>.open

A boolean value (true or false) that indicates whether the Merge Request must be open in order to be enqueued.

pipeline.require.<gitlab source>.merged

A boolean value (true or false) that indicates whether the Merge Request must be merged or not in order to be enqueued.

Reference pipelines configuration

Here is an example of standard pipelines you may want to define:

- pipeline:
    name: check
    description: |
      Newly uploaded patchsets enter this pipeline to receive an
      initial +/-1 Verified vote.
    manager: independent
        open: true
        - event: gl_merge_request
          action: comment
          comment: (?i)^\s*recheck\s*$
        - event: gl_merge_request
            - opened
            - changed
        comment: true
        approval: true
        comment: true
        approval: false
        comment: true
        approval: false

- pipeline:
    name: post
    post-review: true
    manager: independent
        - event: gl_push
          ref: ^refs/heads/.*$

- pipeline:
    name: tag
    post-review: true
    manager: independent
        - event: gl_push
          ref: ^refs/tags/.*$