docs/dev-manual/gitlab.rst

   1 GitLab
   2 ======
   3
   4 The repository contains DockerFiles and GitLab Runner configuration
   5 files to support automated testing and documentation builds.
   6 General information on configuring GitLab CI pipelines can be found
   7 in the official `Gitlab documentation <https://docs.gitlab.com/ee/ci/yaml/>`_.
   8
   9 The GitLab CI configuration entry point is the :file:`.gitlab-ci.yml` file
  10 at the root of the source tree.
  11 Configuration templates are found in the files in the
  12 :file:`admin/ci-templates/` directory.
  13
  14 Docker images used by GitLab Runner are available on `Docker Hub <https://hub.docker.com/u/gromacs>`__.
  15 Images are (re)built manually using details in :file:`admin/containers`.
  16
  17 This documentation is incomplete, pending resolution of :issue:`3275`.
  18
  19 ..  todo:: Expand this documentation to resolve :issue:`3275`
  20
  21 Pipeline execution
  22 ------------------
  23
  24 .. todo:: Discuss the distinct characteristics of |Gromacs| CI pipelines to relevant to job configuration.
  25
  26 .. todo:: Comment on the number of pipelines that can be or which are likely to be running at the same time.
  27
  28 .. note::
  29
  30     Full automated testing is only available for merge requests originating from
  31     branches of the main https://gitlab.com/gromacs/gromacs repository.
  32     GitLab CI pipelines created for forked repositories will include fewer jobs
  33     in the testing pipeline. Non-trivial merge requests may need to be issued
  34     from a branch in the ``gromacs`` project namespace in order to receive
  35     sufficient testing before acceptance.
  36
  37 Configuration files
  38 ~~~~~~~~~~~~~~~~~~~
  39
  40 At the root of the repository, :file:`.gitlab-ci.yml` defines the stages and
  41 some default parameters, then includes files from :file:`admin/gitlab-ci/` to
  42 define jobs to be executed in the pipelines.
  43
  44 Note that job names beginning with a period (``.``) are
  45 `"hidden" <https://docs.gitlab.com/ee/ci/yaml/#hidden-keys-jobs>`_.
  46 Such jobs are not directly eligible to run, but may be used as templates
  47 via the `*extends* job property <https://docs.gitlab.com/ee/ci/yaml/#extends>`_.
  48
  49 Job parameters
  50 ~~~~~~~~~~~~~~
  51
  52 Refer to https://docs.gitlab.com/ee/ci/yaml for complete documentation on
  53 GitLab CI job parameters, but note the following GROMACS-specific conventions.
  54
  55 .. glossary::
  56
  57     before_script
  58         Used by several of our templates to prepend shell commands to
  59         a job *script* parameter.
  60         Avoid using *before-script* directly, and be cautious
  61         about nested *extends* overriding multiple *before_script* definitions.
  62
  63     cache
  64         There is no global default, but jobs that build software will likely
  65         set *cache*. To explicitly unset *cache* directives, specify a job
  66         parameter of ``cache: {}``.
  67         Refer to `GitLab docs <https://docs.gitlab.com/ee/ci/yaml/#cache>`__
  68         for details. In particular, note the details of cache identity according
  69         to `cache:key <https://docs.gitlab.com/ee/ci/yaml/#cachekey>`__
  70
  71     image
  72         Part of the tool chain configuration. Instead of setting *image*
  73         directly, *extend* a *.use_<toolchain>* template from
  74         :file:`admin/gitlab-ci/global.gitlab-ci.yml`
  75
  76     rules
  77     only
  78     except
  79     when
  80         *Job* parameters for controlling the circumstances under which jobs run.
  81         (Some key words may have different meanings when occurring as elements
  82         of other parameters, such as *archive:when*, to which this note is not
  83         intended to apply.)
  84         Instead of setting any of these directly in a job definition, try to use
  85         one of the pre-defined behaviors (defined as ``.rules:<something>`` in
  86         :file:`admin/gitlab-ci/rules.gitlab-ci.yml`).
  87         Errors or unexpected behavior will occur if you specify more than one
  88         *.rules:...* template, or if you use these parameters in combination
  89         with a *.rules...* template.
  90         To reduce errors and unexpected behavior, restrict usage of these controls
  91         to regular job definitions (don't use in "hidden" or parent jobs).
  92         Note that *rules* is not compatible with the older *only* and *except*
  93         parameters. We have standardized on the (newer) *rules* mechanism.
  94
  95     tags
  96         Jobs that can only run in the |Gromacs| GitLab CI Runner infrastructure
  97         should require the ``k8s-scilifelab`` tag.
  98         These include jobs that specify Kubernetes configuration variables or
  99         require special facilities, such as GPUs or MPI.
 100         Note that the *tag* controls which Runners are eligible to take a job.
 101         It does not affect whether the job is eligible for addition to a particular pipeline.
 102         Additional *rules* logic should be used to make sure that jobs with the
 103         ``k8s-scilifelab`` do not become eligible for pipelines launched outside
 104         of the |Gromacs| project environment.
 105         See, for instance, :term:`CI_PROJECT_NAMESPACE`
 106
 107     variables
 108         Many job definitions will add or override keys in *variables*.
 109         Refer to `GitLab <https://docs.gitlab.com/ee/ci/yaml/#variables>`__
 110         for details of the merging behavior. Refer to :ref:`variables` for local usage.
 111
 112 Schedules and triggers
 113 ~~~~~~~~~~~~~~~~~~~~~~
 114
 115 Pipeline `schedules <https://gitlab.com/help/ci/pipelines/schedules>`__ are
 116 configured through the GitLab web interface.
 117 Scheduled pipelines may provide different variable definitions through the
 118 environment to jobs that run under the ``schedules``
 119 `condition <https://gitlab.com/help/ci/pipelines/schedules#using-only-and-except>`__.
 120
 121 Nightly scheduled pipelines run against ``master`` and *release* branches in
 122 the GROMACS repository.
 123
 124 Global templates
 125 ~~~~~~~~~~~~~~~~
 126
 127 In addition to the templates in the main job definition files,
 128 common "mix-in" functionality and behavioral templates are defined in
 129 :file:`admin/gitlab-ci/global.gitlab-ci.yml`.
 130 For readability, some parameters may be separated into their own files, named
 131 according to the parameter (e.g. :file:`rules.gitlab-ci.yml`).
 132
 133 Jobs beginning with ``.use-`` provide mix-in behavior, such as boilerplate for
 134 jobs using a particular tool chain.
 135
 136 Jobs beginning with a `parameter <https://docs.gitlab.com/ee/ci/yaml>`__
 137 name allow parameters to be set in a single place for common job characteristics.
 138 If providing more than a default parameter value, the job name should be suffixed
 139 by a meaningful descriptor and documented within
 140 :file:`admin/gitlab-ci/global.gitlab-ci.yml`
 141
 142 Job names
 143 ~~~~~~~~~
 144
 145 Job names should
 146
 147 1. Indicate the purpose of the job.
 148 2. Indicate relationships between multi-stage tasks.
 149 3. Distinguish jobs in the same stage.
 150 4. Distinguish job definitions throughout the configuration.
 151
 152 Jobs may be reassigned to different stages over time, so including the stage
 153 name in the job name is not helpful, generally. If tags like "pre" and "post,"
 154 or "build" and "test" are necessary to distinguish phases of, say, "webpage,"
 155 then such tags can be buried at the end of the job name.
 156
 157 Stylistically, it is helpful to use delimiters like ``:`` to distinguish the
 158 basic job name from qualifiers or details. Also consider
 159 `grouping jobs <https://docs.gitlab.com/ee/ci/pipelines/index.html#grouping-jobs>`__
 160
 161 .. _variables:
 162
 163 Updating regression tests
 164 ~~~~~~~~~~~~~~~~~~~~~~~~~
 165
 166 Changes in |Gromacs| that require changes in regression-tests are notoriously hard,
 167 because a merge request that tests against the non-updated version of the
 168 regression tests will necessarily fail, while updating regression tests while
 169 the current change is not integrated into master, might cause other
 170 merge request pipelines to fail.
 171
 172 The solution is a new regression-test branch or commit, uploaded to gitlab.
 173 Then set that regression test branch with REGRESSIONTESTBRANCH or
 174 the specific commit with REGRESSIONTESTCOMMIT when
 175 running the specific pipeline that requires the regressiontest-update.
 176 See below on how to set variables for specific pipelines.
 177
 178 Variables
 179 ~~~~~~~~~
 180
 181 The GitLab CI framework, GitLab Runner, plugins, and our own scripts set and
 182 use several `variables <https://docs.gitlab.com/ee/ci/variables/README.html>`__.
 183
 184 Default values are available from the ``.variables:default`` definition in
 185 :file:`admin/gitlab-ci/global.gitlab-ci.yml`.
 186 Many of the mix-in / template jobs provide additional or overriding definitions.
 187 Other variables may be set when making final job definitions.
 188
 189 Variables may control the behvior of GitLab-CI (those beginning with ``CI_``),
 190 GitLab Runner and supporting infrastructure, or may be used by job definitions,
 191 or passed along to the environment of executed commands.
 192
 193 *variables* keys beginning with ``KUBERNETES_`` relate to the GitLab Runner
 194 `Kubernets executor <https://docs.gitlab.com/runner/executors/kubernetes.html#the-kubernetes-executor>`__
 195
 196 Other important variable keys are as follows.
 197
 198 .. glossary::
 199     CI_PROJECT_NAMESPACE
 200         Distinguishes pipelines created for repositories in the ``gromacs``
 201         GitLab project space. May be used to pre-screen jobs to determine
 202         whether |Gromacs| GitLab infrastructure is available to the pipeline
 203         before the job is created.
 204
 205     COMPILER_MAJOR_VERSION
 206         Integer version number provided by toolchain mix-in for convenience and
 207         internal use.
 208
 209     CMAKE_COMPILER_SCRIPT
 210         CMake command line options for a tool chain. A definition is provided by
 211         the mix-in toolchain definitions (e.g. ``.use-gcc8``) to be appended to
 212         :command:`cmake` calls in a job's *script*.
 213
 214     CMAKE_MPI_OPTIONS
 215         Provide CMake command line arguments to define GROMACS MPI build options.
 216
 217     GROMACS_RELEASE
 218         Read-only environment variable that can be checked to see if a job is
 219         executing in a pipeline for preparing a tagged release.
 220         Can be set when launching pipelines via the GitLab web interface.
 221         For example, see *rules* mix-ins in :file:`admin/gitlab-ci/global.gitlab-ci.yml`.
 222
 223     EXTRA_INSTALLS
 224         List additional OS package requirements. Used in *before_script* for some
 225         mix-in job definitions to install additional software dependencies. If
 226         using such a job with *extends*, override this variable key with a
 227         space-delimited list of packages (default: ``""``). Consider proposing a
 228         patch to the base Docker images to include the dependency to reduce
 229         pipeline execution time.
 230
 231     REGRESSIONTESTBRANCH
 232         Use this branch of the regressiontests rather than master to allow for
 233         merge requests that require updated regression tests with valid CI tests.
 234
 235     REGRESSIONTESTCOMMIT
 236         Use this commit to the regressiontests rather than the head on master to
 237         allow for merge requests that require updated regression tests with
 238         valid CI tests.
 239
 240
 241 .. todo:: Define common variables.
 242     ``BUILD_DIR``, ``INSTALL_DIR``, ``CACHE_FALLBACK_KEY``, ...
 243
 244 Setting variables
 245 ~~~~~~~~~~~~~~~~~
 246
 247 Variables for individual piplelines are set in the gitlab interface under
 248 ``CI/CD``; ``Pipelines``. Then chose in the top right corner ``Run Piplelines``.
 249 Under ``Run for``, the desired branch may be selected, and variables may be set
 250 in the fields below.