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     image
  58         Part of the tool chain configuration. Instead of setting *image*
  59         directly, *extend* a *.use_<toolchain>* template from
  60         :file:`admin/gitlab-ci/global.gitlab-ci.yml`
  61
  62     variables
  63         Many job definitions will add or override keys in *variables*.
  64         Refer to `GitLab <https://docs.gitlab.com/ee/ci/yaml/#variables>`__
  65         for details of the merging behavior. Refer to :ref:`variables` for local usage.
  66
  67 In addition to the templates in the main job definition files,
  68 common "mix-in" functionality and behavioral templates are defined in
  69 :file:`admin/gitlab-ci/global.gitlab-ci.yml`.
  70
  71 .. _variables:
  72
  73 Variables
  74 ~~~~~~~~~
  75
  76 The GitLab CI framework, GitLab Runner, plugins, and our own scripts set and
  77 use several `variables <https://docs.gitlab.com/ee/ci/variables/README.html>`__.
  78
  79 Default values are available from the ``.variables:default`` definition in
  80 :file:`admin/gitlab-ci/global.gitlab-ci.yml`.
  81 Many of the mix-in / template jobs provide additional or overriding definitions.
  82 Other variables may be set when making final job definitions.
  83
  84 Variables may control the behvior of GitLab-CI (those beginning with ``CI_``),
  85 GitLab Runner and supporting infrastructure, or may be used by job definitions,
  86 or passed along to the environment of executed commands.
  87
  88 *variables* keys beginning with ``KUBERNETES_`` relate to the GitLab Runner
  89 `Kubernets executor <https://docs.gitlab.com/runner/executors/kubernetes.html#the-kubernetes-executor>`__
  90
  91 Other important variable keys are as follows.
  92
  93 .. glossary::
  94     CMAKE_MPI_OPTIONS
  95         Provide CMake command line arguments to define GROMACS MPI build options.
  96
  97 .. todo:: Define common variables.
  98     ``BUILD_DIR``, ``INSTALL_DIR``, ``CACHE_FALLBACK_KEY``, ...