docs/dev-manual/gitlab.rst

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