GitLab¶
The GitLab driver supports sources, triggers, and reporters. It can interact with the public GitLab.com service as well as site-local installations of GitLab.
Configure GitLab¶
Zuul needs to interact with projects by:
receiving events via web-hooks
performing actions via the API
web-hooks¶
Projects to be integrated with Zuul needs to send events using webhooks. This can be enabled at Group level or Project level in “Settings/Webhooks”
“URL” set to
http://<zuul-web>/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”
API¶
In order to manage multiple projects using a single connection, Zuul needs a global access to projects, which can only be achieved by creating a specific Zuul user. This user counts as a licensed seat.
The API token must be created in user Settings, Access tokens. The Zuul user’s API token configured in zuul.conf must have the following ACL rights: “api”.
Connection Configuration¶
The supported options in zuul.conf
connections are:
-
<gitlab connection>¶
-
<gitlab connection>.driver (required)¶
- gitlab¶
The connection must set
driver=gitlab
for GitLab connections.
-
<gitlab connection>.api_token_name¶
The user’s personal access token name (Used if cloneurl is http(s)) Set this parameter if authentication to clone projects is required
-
<gitlab connection>.api_token¶
The user’s personal access token
-
<gitlab connection>.webhook_token¶
The webhook secret token.
-
<gitlab connection>.server¶
Default:gitlab.com
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>.sshkey¶
Path to SSH key to use (Used if cloneurl is ssh)
-
<gitlab connection>.cloneurl¶
Default:{baseurl}
Omit to clone using http(s) or set to
ssh://git@{server}
. If api_token_name is set and cloneurl is either omitted or is set without credentials, cloneurl will be modified to use credentials as this:http(s)://<api_token_name>:<api_token>@<server>
. If cloneurl is defined with credentials, it will be used as is, without modification from the driver.
-
<gitlab connection>.keepalive¶
Default:60
TCP connection keepalive timeout;
0
disables.
-
<gitlab connection>.disable_connection_pool¶
Default:false
Connection pooling improves performance and resource usage under normal circumstances, but in adverse network conditions it can be problematic. Set this to
true
to disable.
-
<gitlab connection>.driver (required)¶
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:
- gl_merge_request¶
- gl_push¶
-
pipeline.trigger.<gitlab source>.action¶
A gl_merge_request event will have associated action(s) to trigger from. The supported actions are:
- opened¶
Merge request opened.
- changed¶
Merge request synchronized.
- merged¶
Merge request merged.
- comment¶
Comment added to merge request.
- approved¶
Merge request approved.
- unapproved¶
Merge request unapproved.
- labeled¶
Merge request labeled.
-
pipeline.trigger.<gitlab source>.comment¶
This is only used for
gl_merge_request
andcomment
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>.labels¶
This is only used for
gl_merge_request
andlabeled
actions. It accepts a string or a list of strings that are that must have been added for the event to match.
-
pipeline.trigger.<gitlab source>.unlabels¶
This is only used for
gl_merge_request
andlabeled
actions. It accepts a string or a list of strings that are that must have been removed for the event to match.
-
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.
-
pipeline.trigger.<gitlab source>.event (required)¶
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.
-
pipeline.<reporter>.<gitlab source>.merge¶
Default:false
Boolean value that determines if the reporter should merge the Merge Request. To merge a Merge Request the Zuul user must be a Developer or Maintainer project’s member. In case of developer, the Allowed to merge setting in protected branches must be set to Developers + Maintainers.
-
pipeline.<reporter>.<gitlab source>.label¶
A string or list of strings, each representing a label name which should be added to the merge request.
-
pipeline.<reporter>.<gitlab source>.unlabel¶
A string or list of strings, each representing a label name which should be removed from the merge request.
-
pipeline.<reporter>.<gitlab source>.comment¶
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.
pipeline:
require:
gitlab:
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
orfalse
) that indicates whether the Merge Request must be open in order to be enqueued.
-
pipeline.require.<gitlab source>.merged¶
A boolean value (
true
orfalse
) that indicates whether the Merge Request must be merged or not in order to be enqueued.
-
pipeline.require.<gitlab source>.approved¶
A boolean value (
true
orfalse
) that indicates whether the Merge Request must be approved or not in order to be enqueued.
-
pipeline.require.<gitlab source>.labels¶
A list of labels a Merge Request must have in order to be enqueued.
-
pipeline.require.<gitlab source>.open¶
Reference pipelines configuration¶
Here is an example of standard pipelines you may want to define:
- pipeline:
name: check
manager: independent
require:
gitlab.com:
open: true
trigger:
gitlab.com:
- event: gl_merge_request
action: comment
comment: (?i)^\s*recheck\s*$
- event: gl_merge_request
action:
- opened
- changed
success:
gitlab.com:
comment: true
approval: true
failure:
gitlab.com:
comment: true
approval: false
start:
gitlab.com:
comment: true
approval: false
- pipeline:
name: gate
manager: dependent
require:
gitlab.com:
approved: true
open: true
labels:
- gateit
trigger:
gitlab.com:
- event: gl_merge_request
action:
- approved
- event: gl_merge_request
action:
- labeled
labels:
- gateit
success:
gitlab.com:
comment: true
approval: true
merge: true
failure:
gitlab.com:
comment: true
approval: false
start:
gitlab.com:
comment: true
approval: false
- pipeline:
name: promote
post-review: true
manager: supercedent
precedence: high
require:
gitlab.com:
merged: true
trigger:
gitlab.com:
- event: gl_merge_request
action: merged
success:
gitlab.com:
comment: true
failure:
gitlab.com:
comment: true
- pipeline:
name: post
post-review: true
manager: independent
trigger:
gitlab.com:
- event: gl_push
ref: ^refs/heads/.*$
- pipeline:
name: tag
post-review: true
manager: independent
trigger:
gitlab.com:
- event: gl_push
ref: ^refs/tags/.*$