:title: Pagure Driver

.. _pagure_driver:

Pagure
======

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

Configure Pagure
----------------

Pagure's project owner must give project Admin access to the Pagure's user
that own the API key defined in the Zuul configuration. The API key
must at least have the ``Modify an existing project`` access.

Furthermore Project owner must set the web hook target url in project settings
such as: ``http://<zuul-web>/zuul/api/connection/<conn-name>/payload``

Connection Configuration
------------------------

The supported options in ``zuul.conf`` connections are:

.. attr:: <pagure connection>

   .. attr:: driver
      :required:

      .. value:: pagure

         The connection must set ``driver=pagure`` for Pagure connections.

   .. attr:: api_token

      The user's API token with the ``Modify an existing project`` capability.

   .. attr:: server
      :default: pagure.io

      Hostname of the Pagure server.

   .. attr:: canonical_hostname

      The canonical hostname associated with the git repos on the
      Pagure server.  Defaults to the value of :attr:`<pagure
      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 Pagure 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 Pagure web and API interface.

   .. attr:: cloneurl
      :default: https://{baseurl}

      Path to the Pagure Git repositories. Used to clone.

Trigger Configuration
---------------------
Pagure webhook events can be configured as triggers.

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

.. attr:: pipeline.trigger.<pagure source>

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

   .. attr:: event
      :required:

      The event from Pagure. Supported events are:

      .. value:: pg_pull_request

      .. value:: pg_pull_request_review

      .. value:: pg_push

   .. attr:: action

      A :value:`pipeline.trigger.<pagure source>.event.pg_pull_request`
      event will have associated action(s) to trigger from. The
      supported actions are:

      .. value:: opened

         Pull request opened.

      .. value:: changed

         Pull request synchronized.

      .. value:: comment

         Comment added to pull request.

      .. value:: status

         Status set on pull request.

      A :value:`pipeline.trigger.<pagure
      source>.event.pg_pull_request_review` event will have associated
      action(s) to trigger from. The supported actions are:

      .. value:: thumbsup

         Positive pull request review added.

      .. value:: thumbsdown

         Negative pull request review added.

   .. attr:: comment

      This is only used for ``pg_pull_request`` ``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 pull request.

   .. attr:: status

      This is used for ``pg_pull_request`` and ``status`` actions. It
      accepts a list of strings each of which matches the user setting
      the status, the status context, and the status itself in the
      format of ``status``.  For example, ``success`` or ``failure``.

   .. attr:: ref

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

Reporter Configuration
----------------------
Zuul reports back to Pagure via Pagure API. Available reports include a PR
comment containing the build results, a commit status on start, success and
failure, and a merge of the PR itself. Status name, description, and context
is taken from the pipeline.

.. attr:: pipeline.<reporter>.<pagure source>

   To report to Pagure, the dictionaries passed to any of the pipeline
   :ref:`reporter<reporters>` attributes support the following
   attributes:

   .. attr:: status

      String value (``pending``, ``success``, ``failure``) that the
      reporter should set as the commit status on Pagure.

   .. attr:: status-url
      :default: web.status_url or the empty string

      String value for a link url to set in the Pagure status. Defaults to the
      zuul server status_url, or the empty string if that is unset.

   .. attr:: comment
      :default: true

      Boolean value that determines if the reporter should add a
      comment to the pipeline status to the Pagure Pull Request. Only
      used for Pull Request based items.

   .. attr:: merge
      :default: false

      Boolean value that determines if the reporter should merge the
      pull Request. Only used for Pull Request based items.


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.  To supply
requirements for changes from a Pagure source named ``pagure``, create a
configuration such as the following::

  pipeline:
    require:
      pagure:
        score: 1
        merged: false
        status: success

This indicates that changes originating from the Pagure connection
must have a score of *1*, a CI status *success* and not being already merged.

.. attr:: pipeline.require.<pagure source>

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

   .. attr:: score

      If present, the minimal score a Pull Request must reached.

   .. attr:: status

      If present, the CI status a Pull Request must have.

   .. attr:: merged

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

   .. attr:: open

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

Reference pipelines configuration
---------------------------------

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

  - pipeline:
      name: check
      manager: independent
      require:
        pagure.io:
          merged: False
      trigger:
        pagure.io:
          - event: pg_pull_request
            action: comment
            comment: (?i)^\s*recheck\s*$
          - event: pg_pull_request
            action:
              - opened
              - changed
      start:
        pagure.io:
          status: 'pending'
          comment: false
        sqlreporter:
      success:
        pagure.io:
          status: 'success'
        sqlreporter:
      failure:
        pagure.io:
          status: 'failure'
        sqlreporter:

  - pipeline:
      name: gate
      manager: dependent
      precedence: high
      require:
        pagure.io:
          score: 1
          merged: False
          status: success
        sqlreporter:
      trigger:
         pagure.io:
           - event: pg_pull_request
             action: status
             status: success
           - event: pg_pull_request_review
             action: thumbsup
      start:
        pagure.io:
          status: 'pending'
          comment: false
        sqlreporter:
      success:
        pagure.io:
          status: 'success'
          merge: true
          comment: true
        sqlreporter:
      failure:
        pagure.io:
          status: 'failure'
          comment: true
        sqlreporter:

  - pipeline:
      name: post
      post-review: true
      manager: independent
      precedence: low
      trigger:
        pagure.io:
          - event: pg_push
            ref: ^refs/heads/.*$
      success:
        sqlreporter:
