.. _COMPETITORS:

Competing Solutions
###################

Each feature group has competitors solving a part of its task; none of them reads pipeline files and pipeline runs
into one model, which a Sphinx domain and the visualizations build on.

A pipeline becomes a trace by the :gh:`GitLab receiver
<open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/gitlabreceiver>` of the OpenTelemetry Collector,
fed by GitLab's webhooks.


.. _COMPETITORS/Files:

Pipeline Files
**************

No package on PyPI reads a :file:`.gitlab-ci.yml` into a Python object model. The packages below check a pipeline
file, or write one.

.. _COMPETITORS/Files/JSONSchema:

JSON Schema
===========

Source: GitLab's own `schema of a pipeline file
<https://gitlab.com/gitlab-org/gitlab/-/raw/master/app/assets/javascripts/editor/schema/ci.json>`__, which its pipeline
editor uses, checked by e.g. `check-jsonschema <https://pypi.org/project/check-jsonschema/>`__, compared to
:ref:`DATA/PipelineFile`.

.. rubric:: Disadvantages

* A file is validated against the schema. A program reading it gets nested dictionaries and lists.
* The schema knows neither the line of an element nor its parent, and doesn't resolve ``extends``, ``include`` or
  ``!reference``.

.. rubric:: Advantages

* The schema is GitLab's, so a file is checked the same way as in GitLab's pipeline editor.

.. _COMPETITORS/Files/Linters:

Linters
=======

Source: `gitlab-ci-verify <https://pypi.org/project/gitlab-ci-verify/>`__ and
`gitlab-lint <https://pypi.org/project/gitlab-lint/>`__, compared to :ref:`DATA/PipelineFile`.

.. rubric:: Disadvantages

* Command line programs reporting findings, not a model. gitlab-lint sends the file to GitLab's API to be checked;
  gitlab-ci-verify runs a compiled program installed from PyPI.

.. rubric:: Advantages

* gitlab-ci-verify checks a job's scripts with ShellCheck, and both check a file against GitLab itself.

.. _COMPETITORS/Files/Generators:

Pipeline Generators
===================

Source: `gcip <https://pypi.org/project/gcip/>`__ (the GitLab CI Python Library), compared to
:ref:`DATA/PipelineFile`.

.. rubric:: Disadvantages

* It writes a pipeline file from Python code, but doesn't read one.
* Five dependencies: ``boto3``, ``pyaml``, ``setuptools-git-versioning``, ``semver`` and ``python-gitlab``.

.. rubric:: Advantages

* A dynamic pipeline - e.g. for a child pipeline - is generated by a program instead of being written by hand.


.. _COMPETITORS/Runs:

Pipeline Runs
*************

.. _COMPETITORS/Runs/python-gitlab:

python-gitlab
=============

Source: :gh:`python-gitlab <python-gitlab/python-gitlab>`, on PyPI as
`python-gitlab <https://pypi.org/project/python-gitlab/>`__, compared to :ref:`DATA/PipelineRun` and
:ref:`VIS/PipelineTrace`.

.. rubric:: Disadvantages

* Two dependencies: ``requests`` and ``requests-toolbelt``; licensed under the LGPL-3.0.
* A pipeline's `jobs and bridges <https://python-gitlab.readthedocs.io/en/stable/gl_objects/pipelines_and_jobs.html>`__
  are flat lists of ``ProjectPipelineJob`` and ``ProjectPipelineBridge`` objects in the shape of the REST API's
  payloads. A matrix is only part of a job's name - ``test: [3.14, linux]`` -, a child pipeline is read with its own
  request, and a pipeline is not converted into a trace.

.. rubric:: Advantages

* The whole REST and GraphQL API, including writes like retrying a job or starting a pipeline.


.. _COMPETITORS/Domain:

Pipeline Documentation
**********************

.. _COMPETITORS/Domain/gitlab-ci-docs:

gitlab-ci-docs
==============

Source: :gh:`gitlab-ci-docs <martin356/gitlab-ci-docs>`, on PyPI as
`gitlab-ci-docs <https://pypi.org/project/gitlab-ci-docs/>`__, compared to the :ref:`glci domain <GLCI>`.

.. rubric:: Disadvantages

* A command line program writing an HTML table of the ``workflow`` section's variables into a :file:`README.md`, not
  a part of a Sphinx build.
* A variable's type, options and whether it is required are written as a comment of its own format behind the
  variable, not taken from GitLab's ``spec:inputs`` or a variable's ``description`` and ``options``.

.. rubric:: Advantages

* The :file:`README.md` is rendered by GitLab itself, next to the pipeline file.