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 Variables
  32 ~~~~~~~~~
  33
  34 The GitLab CI framework, GitLab Runner, plugins, and our own scripts set and
  35 use several variables (usually as a key under a *variables* parameter in
  36 the YAML configuration).
  37
  38 Some default values are specified for all jobs in :file:`.gitlab-ci.yml`.
  39 Many of the mix-in / template jobs in :file:`admin/gitlab-ci/global.gitlab-ci.yml`
  40 provide additional or overriding definitions.
  41 Other variables may be set when making final job definitions.
  42
  43 Variables may control the behvior of GitLab-CI (those beginning with ``CI_``),
  44 GitLab Runner and supporting infrastructure, or may be used by job definitions,
  45 or passed along to the environment of executed commands.
  46
  47 *variables* keys beginning with ``KUBERNETES_`` relate to the GitLab Runner
  48 `Kubernets executor <https://docs.gitlab.com/runner/executors/kubernetes.html#the-kubernetes-executor>`__
  49
  50 Other important variable keys are as follows.
  51
  52 .. glossary::
  53     CMAKE_MPI_OPTIONS
  54         Provide CMake command line arguments to define GROMACS MPI build options.
  55
  56 .. todo:: Define common variables.
  57     ``BUILD_DIR``, ``INSTALL_DIR``, ``CACHE_FALLBACK_KEY``, ...