docs,marge_queue: document the tool usage

This marge_tool wasn't yet described in the documentation. It has links to the
resource utilization, and it is a satellite tool for crnm.

Signed-off-by: Sergi Blanch Torne <sergi.blanch.torne@collabora.com>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/37395>

1 files changed, 27 insertions, 2 deletions

diff --git a/docs/ci/index.rst b/docs/ci/index.rst
index 9472f3973d2..991a40e2ce3 100644
--- a/docs/ci/index.rst
+++ b/docs/ci/index.rst
@@ -23,8 +23,15 @@ The CI runs a number of tests, from trivial build-testing to complex GPU renderi
 A typical run takes between 20 and 30 minutes, although it can go up very quickly
 if the GitLab runners are overwhelmed, which happens sometimes. When it does happen,
 not much can be done besides waiting it out, or cancel it.
-You can do your part by only running the jobs you care about by using `our
-tool <#running-specific-ci-jobs>`__.
+
+It is a good practice to check the ``Marge`` 
+`queue <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests?assignee_username=marge-bot>`__ 
+to evaluate if it is the right moment to trigger some testing jobs. ``Marge`` 
+is configured to pick the MRs by assignment time, and this sort option is not 
+available in the Web UI. The `marge_queue <#marge-queue>`__ CLI tool 
+provides the list sorted by assignment time. The recommended way to manage the 
+trigger of those jobs is using our :abbr:`crnm (bin/ci/ci_run_n_monitor.sh)` 
+`cli tool <#running-specific-ci-jobs>`__.
 
 Due to limited resources, we currently do not run the CI automatically
 on every push; instead, we only run it automatically once the MR has
@@ -338,6 +345,24 @@ scope permissions.
     and select the ``api`` scope. The token will only be shown once after creation,
     so make sure you store it securely.
 
+Marge queue
+-----------
+
+You can use ``bin/ci/marge_queue.sh`` to check how long the Marge queue is. As
+mentioned, the merge flow is to assign MR to the ``Marge`` bot, to serialize
+the verification and merge. Looking at the
+`merge requests assigned to Marge <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests?assignee_username=marge-bot>`__
+you can evaluate the size of the queue, since the ``marge_queue`` tool provides
+sorted and summarized information about those MR in queue.
+
+The tool requires a GitLab token as described in the
+`crnm <#running-specific-ci-jobs>`__ section. It outputs the current queue
+sorted by the ``assigned at`` to ``Marge``. It can also be used as an active
+wait for another action in a pipe, using the ``--wait`` until the queue is
+empty. The return code corresponds to the number of MRs in the queue, so when
+it returns ``0``, one can, for example, start the ``crnm`` tool on a certain
+pipeline.
+
 Conformance Tests
 -----------------