Allow useful CI to run in forks

[alexxy/gromacs.git] / docs / dev-manual / gitlab.rst

diff --git a/docs/dev-manual/gitlab.rst b/docs/dev-manual/gitlab.rst
index 19894addcea4ae72e8a7d05bddd955dcc62e6216..8964a4b81cafc1307510b5950f5905e8fec06e8d 100644 (file)
--- a/docs/dev-manual/gitlab.rst
+++ b/docs/dev-manual/gitlab.rst
@@ -1,9 +1,6 @@
 GitLab
 ======
 
-|Gromacs| is transitioning to GitLab for source code management, issue tracking,
-and integrated automation for testing and documentation.
-
 The repository contains DockerFiles and GitLab Runner configuration
 files to support automated testing and documentation builds.
 General information on configuring GitLab CI pipelines can be found
@@ -15,7 +12,7 @@ Configuration templates are found in the files in the
 :file:`admin/ci-templates/` directory.
 
 Docker images used by GitLab Runner are available on `Docker Hub <https://hub.docker.com/u/gromacs>`__.
-Images are (re)built manually from DockerFiles in :file:`admin/dockerfiles`.
+Images are (re)built manually using details in :file:`admin/containers`.
 
 This documentation is incomplete, pending resolution of :issue:`3275`.
 
@@ -28,6 +25,15 @@ Pipeline execution
 
 .. todo:: Comment on the number of pipelines that can be or which are likely to be running at the same time.
 
+.. note::
+
+    Full automated testing is only available for merge requests originating from
+    branches of the main https://gitlab.com/gromacs/gromacs repository.
+    GitLab CI pipelines created for forked repositories will include fewer jobs
+    in the testing pipeline. Non-trivial merge requests may need to be issued
+    from a branch in the ``gromacs`` project namespace in order to receive
+    sufficient testing before acceptance.
+
 Configuration files
 ~~~~~~~~~~~~~~~~~~~
 
@@ -84,6 +90,13 @@ GitLab CI job parameters, but note the following GROMACS-specific conventions.
         To reduce errors and unexpected behavior, restrict usage of these controls
         to regular job definitions (don't use in "hidden" or parent jobs).
 
+    tags
+        By `default <https://docs.gitlab.com/ee/ci/yaml/#setting-default-parameters>`__,
+        jobs require the ``k8s-scilifelab`` tag, which identifies Runners in the
+        |Gromacs| infrastructure. A small number of jobs in the first pipeline
+        stage override the default with an empty tag list so that all GitLab
+        users can run basic tests in their forked project.
+
     variables
         Many job definitions will add or override keys in *variables*.
         Refer to `GitLab <https://docs.gitlab.com/ee/ci/yaml/#variables>`__
@@ -159,6 +172,12 @@ or passed along to the environment of executed commands.
 Other important variable keys are as follows.
 
 .. glossary::
+    CI_PROJECT_NAMESPACE
+        Distinguishes pipelines created for repositories in the ``gromacs``
+        GitLab project space. May be used to pre-screen jobs to determine
+        whether |Gromacs| GitLab infrastructure is available to the pipeline
+        before the job is created.
+
     COMPILER_MAJOR_VERSION
         Integer version number provided by toolchain mix-in for convenience and
         internal use.