1 GitLab CI Pipeline Execution
2 ============================
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/>`_.
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.
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`.
17 This documentation is incomplete, pending resolution of :issue:`3275`.
19 .. todo:: Expand this documentation to resolve :issue:`3275`
21 .. todo:: Discuss the distinct characteristics of |Gromacs| CI pipelines to relevant to job configuration.
22 (:issue:`3472` and :issue:`3617`)
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`)
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.
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.
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>`_.
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.
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.
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>`__
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!
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
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.
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`
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.
111 Schedules and triggers
112 ----------------------
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>`__.
120 Nightly scheduled pipelines run against ``master`` and *release* branches in
121 the GROMACS repository.
123 Running post-merge-acceptance pipelines
124 """""""""""""""""""""""""""""""""""""""
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.
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`).
141 Jobs beginning with ``.use-`` provide mix-in behavior, such as boilerplate for
142 jobs using a particular tool chain.
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`
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.
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.
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>`__
171 Updating regression tests
172 -------------------------
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.
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.
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>`__.
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.
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.
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>`__
204 Other important variable keys are as follows.
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.
213 COMPILER_MAJOR_VERSION
214 Integer version number provided by toolchain mix-in for convenience and
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`.
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*.
233 Provide CMake command line arguments to define GROMACS MPI build options.
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`.
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.
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.
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
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`.
265 .. todo:: Define common variables.
266 ``BUILD_DIR``, ``INSTALL_DIR``, ``CACHE_FALLBACK_KEY``, ...
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