From 971c5673f1ae5cc8d07b9a56d80e117f112047c9 Mon Sep 17 00:00:00 2001
From: Michal Konecny <mkonecny@redhat.com>
Date: Nov 02 2023 15:52:16 +0000
Subject: Add CI doc for dist-git ARC investigation


This document describes the interactions between dist git and Fedora CI.

Signed-off-by: Michal Konecny <mkonecny@redhat.com>

---

diff --git a/docs/dist-git-move/ci.rst b/docs/dist-git-move/ci.rst
new file mode 100644
index 0000000..21c5783
--- /dev/null
+++ b/docs/dist-git-move/ci.rst
@@ -0,0 +1,69 @@
+.. _ci:
+
+Pagure Dist Git Interactions With Fedora CI
+====
+
+`Fedora CI <https://docs.fedoraproject.org/en-US/ci/>`_ is a service
+that handles Continuous Integration of packages in Fedora project.
+As that it interacts with dist-git.
+Fedora CI consists of multiple services:
+
+- Jenkins - Fedora hosted instance that runs the tests
+- `Greenwave <https://pagure.io/greenwave>`_ - service to evaluate
+  gating policies on test results
+- `ResultsDB <https://pagure.io/taskotron/resultsdb>`_ - stores
+  results of the tests
+- `WaiverDB <https://pagure.io/waiverdb>`_ - service for recording
+  waivers against test results
+
+Possible Interactions
+----
+
+The following are a set of documented interactions possible between Pagure Dist
+Git and Fedora CI.
+
+Rawhide gating
+^^^^
+
+- To configure rawhide gating rules for Greenwave user needs to add ``gating.yaml`` file
+  to package repository
+
+Notification about results
+^^^^
+
+- Notification about CI results is done by creating flags using API calls:
+
+  * ``/api/0/<package_name>/pull-request/<pr_id>/flag``
+  * ``/api/0/<package_name>/c/<commit_id>/flag``
+
+  Those flags are then visible on the corresponding commit or pull request.
+
+Triggering tests on pull requests
+^^^^
+
+- The automatic trigger of CI when creating pull request is done by emitting
+  message topic ``pull-request.new`` and it's consumed by Jenkins
+
+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
+^^^^
+
+- If URL for dist git is change it will need to be reflected in each component
+  that is part of Fedora CI and directly interacts with dist-git:
+
+  * `Greenwave <https://pagure.io/fedora-infra/ansible/blob/main/f/roles/openshift-apps/greenwave/templates/settings.py>`_ -
+    HTTP get request to the repository to check the ``gating.yaml``
+
+Unnecessary
+^^^^
+
+- In case message schema will change we would need to update the topics that
+  are consumed by Fedora CI. The
+  `configuration <https://github.com/fedora-ci/dist-git-build-trigger/blob/pull-request.new/Jenkinsfile>`_
+  for Jenkins is here.
diff --git a/docs/dist-git-move/index.rst b/docs/dist-git-move/index.rst
index 059970e..961f3c5 100644
--- a/docs/dist-git-move/index.rst
+++ b/docs/dist-git-move/index.rst
@@ -43,6 +43,7 @@ Index
 .. toctree::
     :maxdepth: 1
 
+    ci
     copr
     hotness
     notifications