docs/dev-manual/gitlab.rst

   1 GitLab
   2 ======
   3
   4 |Gromacs| is transitioning to GitLab for source code management, issue tracking,
   5 and integrated automation for testing and documentation.
   6
   7 The repository contains DockerFiles and GitLab Runner configuration
   8 files to support automated testing and documentation builds.
   9 General information on configuring GitLab CI pipelines can be found
  10 in the official `Gitlab documentation <https://docs.gitlab.com/ee/ci/yaml/>`_.
  11
  12 The GitLab CI configuration entry point is the :file:`.gitlab-ci.yml` file
  13 at the root of the source tree.
  14 Configuration templates are found in the files in the
  15 :file:`admin/ci-templates/` directory.
  16
  17 Docker images used by GitLab Runner are available on `Docker Hub <https://hub.docker.com/u/gromacs>`__.
  18 Images are (re)built manually from DockerFiles in :file:`admin/dockerfiles`.
  19
  20 This documentation is incomplete, pending resolution of :issue:`3275`.
  21
  22 ..  todo:: Expand this documentation to resolve :issue:`3275`
  23
  24 Pipeline execution
  25 ------------------
  26
  27 .. todo:: Discuss the distinct characteristics of |Gromacs| CI pipelines to relevant to job configuration.
  28
  29 .. todo:: Comment on the number of pipelines that can be or which are likely to be running at the same time.
  30
  31 Configuration files
  32 ~~~~~~~~~~~~~~~~~~~
  33
  34 At the root of the repository, :file:`.gitlab-ci.yml` defines the stages and
  35 some default parameters, then includes files from :file:`admin/gitlab-ci/` to
  36 define jobs to be executed in the pipelines.
  37
  38 Note that job names beginning with a period (``.``) are
  39 `"hidden" <https://docs.gitlab.com/ee/ci/yaml/#hidden-keys-jobs>`_.
  40 Such jobs are not directly eligible to run, but may be used as templates
  41 via the `*extends* job property <https://docs.gitlab.com/ee/ci/yaml/#extends>`_.
  42
  43 Job parameters
  44 ~~~~~~~~~~~~~~
  45
  46 Refer to https://docs.gitlab.com/ee/ci/yaml for complete documentation on
  47 GitLab CI job parameters, but note the following GROMACS-specific conventions.
  48
  49 .. glossary::
  50
  51     before_script
  52         Used by several of our templates to prepend shell commands to
  53         a job *script* parameter.
  54         Avoid using *before-script* directly, and be cautious
  55         about nested *extends* overriding multiple *before_script* definitions.
  56
  57     cache
  58         There is no global default, but jobs that build software will likely
  59         set *cache*. To explicitly unset *cache* directives, specify a job
  60         parameter of ``cache: {}``.
  61         Refer to `GitLab docs <https://docs.gitlab.com/ee/ci/yaml/#cache>`__
  62         for details. In particular, note the details of cache identity according
  63         to `cache:key <https://docs.gitlab.com/ee/ci/yaml/#cachekey>`__
  64
  65     image
  66         Part of the tool chain configuration. Instead of setting *image*
  67         directly, *extend* a *.use_<toolchain>* template from
  68         :file:`admin/gitlab-ci/global.gitlab-ci.yml`
  69
  70     rules
  71     only
  72     except
  73     when
  74         *Job* parameters for controlling the circumstances under which jobs run.
  75         (Some key words may have different meanings when occurring as elements
  76         of other parameters, such as *archive:when*, to which this note is not
  77         intended to apply.)
  78         Instead of setting any of these directly in a job definition, try to use
  79         one of the pre-defined behaviors (defined as ``.rules:<something>`` in
  80         :file:`admin/gitlab-ci/global.gitlab-ci.yml`).
  81         Errors or unexpected behavior will occur if you specify more than one
  82         *.rules:...* template, or if you use these parameters in combination
  83         with a *.rules...* template.
  84         To reduce errors and unexpected behavior, restrict usage of these controls
  85         to regular job definitions (don't use in "hidden" or parent jobs).
  86
  87     variables
  88         Many job definitions will add or override keys in *variables*.
  89         Refer to `GitLab <https://docs.gitlab.com/ee/ci/yaml/#variables>`__
  90         for details of the merging behavior. Refer to :ref:`variables` for local usage.
  91
  92 Schedules and triggers
  93 ~~~~~~~~~~~~~~~~~~~~~~
  94
  95 Pipeline `schedules <https://gitlab.com/help/ci/pipelines/schedules>`__ are
  96 configured through the GitLab web interface.
  97 Scheduled pipelines may provide different variable definitions through the
  98 environment to jobs that run under the ``schedules``
  99 `condition <https://gitlab.com/help/ci/pipelines/schedules#using-only-and-except>`__.
 100
 101 Nightly scheduled pipelines run against ``master`` and *release* branches in
 102 the GROMACS repository.
 103
 104 Global templates
 105 ~~~~~~~~~~~~~~~~
 106
 107 In addition to the templates in the main job definition files,
 108 common "mix-in" functionality and behavioral templates are defined in
 109 :file:`admin/gitlab-ci/global.gitlab-ci.yml`.
 110
 111 Jobs beginning with ``.use-`` provide mix-in behavior, such as boilerplate for
 112 jobs using a particular tool chain.
 113
 114 Jobs beginning with a `parameter <https://docs.gitlab.com/ee/ci/yaml>`__
 115 name allow parameters to be set in a single place for common job characteristics.
 116 If providing more than a default parameter value, the job name should be suffixed
 117 by a meaningful descriptor and documented within
 118 :file:`admin/gitlab-ci/global.gitlab-ci.yml`
 119
 120 Job names
 121 ~~~~~~~~~
 122
 123 Job names should
 124
 125 1. Indicate the purpose of the job.
 126 2. Indicate relationships between multi-stage tasks.
 127 3. Distinguish jobs in the same stage.
 128 4. Distinguish job definitions throughout the configuration.
 129
 130 Jobs may be reassigned to different stages over time, so including the stage
 131 name in the job name is not helpful, generally. If tags like "pre" and "post,"
 132 or "build" and "test" are necessary to distinguish phases of, say, "webpage,"
 133 then such tags can be buried at the end of the job name.
 134
 135 Stylistically, it is helpful to use delimiters like ``:`` to distinguish the
 136 basic job name from qualifiers or details. Also consider
 137 `grouping jobs <https://docs.gitlab.com/ee/ci/pipelines/index.html#grouping-jobs>`__
 138
 139 .. _variables:
 140
 141 Variables
 142 ~~~~~~~~~
 143
 144 The GitLab CI framework, GitLab Runner, plugins, and our own scripts set and
 145 use several `variables <https://docs.gitlab.com/ee/ci/variables/README.html>`__.
 146
 147 Default values are available from the ``.variables:default`` definition in
 148 :file:`admin/gitlab-ci/global.gitlab-ci.yml`.
 149 Many of the mix-in / template jobs provide additional or overriding definitions.
 150 Other variables may be set when making final job definitions.
 151
 152 Variables may control the behvior of GitLab-CI (those beginning with ``CI_``),
 153 GitLab Runner and supporting infrastructure, or may be used by job definitions,
 154 or passed along to the environment of executed commands.
 155
 156 *variables* keys beginning with ``KUBERNETES_`` relate to the GitLab Runner
 157 `Kubernets executor <https://docs.gitlab.com/runner/executors/kubernetes.html#the-kubernetes-executor>`__
 158
 159 Other important variable keys are as follows.
 160
 161 .. glossary::
 162     COMPILER_MAJOR_VERSION
 163         Integer version number provided by toolchain mix-in for convenience and
 164         internal use.
 165
 166     CMAKE_COMPILER_SCRIPT
 167         CMake command line options for a tool chain. A definition is provided by
 168         the mix-in toolchain definitions (e.g. ``.use-gcc8``) to be appended to
 169         :command:`cmake` calls in a job's *script*.
 170
 171     CMAKE_MPI_OPTIONS
 172         Provide CMake command line arguments to define GROMACS MPI build options.
 173
 174     GROMACS_RELEASE
 175         Read-only environment variable that can be checked to see if a job is
 176         executing in a pipeline for preparing a tagged release.
 177         Can be set when launching pipelines via the GitLab web interface.
 178         For example, see *rules* mix-ins in :file:`admin/gitlab-ci/global.gitlab-ci.yml`.
 179
 180     EXTRA_INSTALLS
 181         List additional OS package requirements. Used in *before_script* for some
 182         mix-in job definitions to install additional software dependencies. If
 183         using such a job with *extends*, override this variable key with a
 184         space-delimited list of packages (default: ``""``). Consider proposing a
 185         patch to the base Docker images to include the dependency to reduce
 186         pipeline execution time.
 187
 188 .. todo:: Define common variables.
 189     ``BUILD_DIR``, ``INSTALL_DIR``, ``CACHE_FALLBACK_KEY``, ...