.. _monitorgating:

Pagure Dist Git Interactions With Monitor Gating
================================================

`Monitor Gating <https://pagure.io/fedora-ci/monitor-gating>`_ is a set of scripts that
is used to test if `Fedora CI Gating <https://docs.fedoraproject.org/en-US/ci/gating/>`_
is working as expected. It essentially follows a typical workflow of cloning a package
from dist-git, rebuild it in koji, create a update in bodhi, then checks that the CI
runs, and the build is gated appropriately.

Possible Interactions
---------------------

The following are a set of documented interactions possible between Pagure Dist Git and
Monitor Gating.

git and fedpkg CLI
~~~~~~~~~~~~~~~~~~

**cloning a repo**
    Monitor Gating uses ``fedpkg clone`` to clone a repo from dist-git.

    `utils.py#_107
    <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_107>`_

**adding a remote**
    Monitor Gating uses ``git remote add`` to add a fork on dist-git as a remote on a
    cloned dist-git repo.

    `utils.py#_136
    <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_136>`_

**switching branches**
    Monitor Gating uses ``fedpkg switch-branch`` to switch branches on a dist-git cloned
    repo.

    `utils.py#_149
    <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_149>`_

**git pull, push, commit**
    Monitor Gating uses ``git commit``, ``git pull```, and ``git push`` to get and make
    changes to a dist-git repo.

    `utils.py#_175-212
    <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_175-212>`_

dist-git (pagure) API
~~~~~~~~~~~~~~~~~~~~~

**CI status**
    Monitor gating currently gets the status of the CI run(s) on a pull request using
    the get PR flags endpoint (``api/0/<namespace>/<name>/pull-request/<pr-id>/flag``).

    `utils.py#_636
    <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_636>`_

**open pull request**
    Monitor Gating opens new Pull Requests on dist-git using the pagure API
    (``api/0/<namespace>/<name>/pull-request/new``)

    `utils.py#_214
    <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_214>`_

**merge pull request**
    Monitor Gating merges Pull Requests on dist-git using the pagure API
    (``api/0/<namespace>/<name>/pull-request/<pr-id>/merge``)

    `utils.py#_691
    <https://pagure.io/fedora-ci/monitor-gating/blob/production/f/monitor_gating/utils.py#_691>`_

Changes proposed
----------------

In order to switch out Pagure Dist Git for an alternative that provides a relatively
compatible API pattern, the following changes must be made in the places mentioned
below.

Necessary
~~~~~~~~~

- The changes made to the Continuous Integration component with regards to the reporting
  of CI status need to be updated in monitor gating. Currently dist-git uses the pagure
  flags system.
- Monitor Gating will need to be updated to support Opening and Merging pull requests on
  the new solution

Unnecessary
~~~~~~~~~~~

- No changes should be needed for the basic git / fedpkg commands. (this is based on the
  assumption the new solution is based on git)