diff --git a/doc/source/examples/pipelines/gitlab-reference-pipelines.yaml b/doc/source/examples/pipelines/gitlab-reference-pipelines.yaml new file mode 100644 index 0000000000..8acf8b9005 --- /dev/null +++ b/doc/source/examples/pipelines/gitlab-reference-pipelines.yaml @@ -0,0 +1,27 @@ +- pipeline: + name: gitlab-check + description: | + Newly uploaded patchsets enter this pipeline to receive an + initial +/-1 Verified vote. + manager: independent + 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 + sqlreporter: + failure: + gitlab.com: + comment: true + sqlreporter: + start: + gitlab.com: + comment: true + sqlreporter: diff --git a/doc/source/reference/drivers/gitlab.rst b/doc/source/reference/drivers/gitlab.rst new file mode 100644 index 0000000000..b0514a9969 --- /dev/null +++ b/doc/source/reference/drivers/gitlab.rst @@ -0,0 +1,167 @@ +:title: GitLab Driver + +.. _gitlab_driver: + +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. + +.. note:: 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/api/connection//payload`` +- "Merge request events" set to "on" +- "Comments" set to "on" +- Define a "Secret Token" + +Connection Configuration +------------------------ + +The supported options in ``zuul.conf`` connections are: + +.. attr:: + + .. attr:: driver + :required: + + .. value:: gitlab + + The connection must set ``driver=gitlab`` for GitLab connections. + + .. attr:: api_token + + The user's API token. + + .. attr:: webhook_token + + The project's webhook secret token. + + .. attr:: server + :default: gitlab.com + + Hostname of the GitLab server. + + .. attr:: canonical_hostname + + The canonical hostname associated with the git repos on the + GitLab server. Defaults to the value of :attr:`.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. + + .. attr:: baseurl + :default: https://{server} + + Path to the GitLab web and API interface. + + .. attr:: 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. + +.. attr:: pipeline.trigger. + + The dictionary passed to the GitLab pipeline ``trigger`` attribute + supports the following attributes: + + .. attr:: event + :required: + + The event from GitLab. Supported events are: + + .. value:: gl_merge_request + + .. attr:: action + + A :value:`pipeline.trigger..event.gl_merge_request` + event will have associated action(s) to trigger from. The + supported actions are: + + .. value:: opened + + Merge request opened. + + .. value:: changed + + Merge request synchronized. + + .. value:: comment + + Comment added to merge request. + + .. attr:: 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. + +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. + +.. attr:: pipeline.. + + To report to GitLab, the dictionaries passed to any of the pipeline + :ref:`reporter` attributes support the following + attributes: + + .. attr:: comment + :default: true + + Boolean value that determines if the reporter should add a + comment to the pipeline status to the GitLab Merge Request. + + +Requirements Configuration +-------------------------- + +As described in :attr:`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. + +This driver does not support requirements. + + +Reference pipelines configuration +--------------------------------- + +Here is an example of standard pipelines you may want to define: + +.. literalinclude:: /examples/pipelines/gitlab-reference-pipelines.yaml + :language: yaml diff --git a/doc/source/reference/drivers/index.rst b/doc/source/reference/drivers/index.rst index 4413f4f049..27baa3da0d 100644 --- a/doc/source/reference/drivers/index.rst +++ b/doc/source/reference/drivers/index.rst @@ -21,6 +21,7 @@ Zuul includes the following drivers: gerrit github pagure + gitlab git mqtt smtp