diff --git a/README.md b/README.md
index ffa6ac4724defd075753a9bf909ed409a2bd3a17..139b1c281338009d4014e8b0293a9ebcd2a14236 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,10 @@ In the directory `install`, you'll find scripts and instructions related to the
 installation and maintenance of new build machines.
 
 In the directory `ci`, you'll find scripts that are used for our continuous
-integration builds.
+integration builds. These scripts are now deprecated
+
+In the directory `gitlab`, you'll find scripts that are used for our continuous
+integration builds. These correspond to the new generation scripts.
 
 In the directory `templates`, you will find useful information and templates
 for creating/updating packages in gitlab.
diff --git a/gitlab/README.md b/gitlab/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..59ea50aaabf1f09bcc282716b5fa65ae332af00e
--- /dev/null
+++ b/gitlab/README.md
@@ -0,0 +1,23 @@
+# Scripts for Continous Integration with Gitlab
+
+This directory contains scripts that are used by our continuous integration
+(CI) builds. There are various sets of scripts named as follows:
+
+* `before_<stage>.sh`
+* `<stage>.sh`
+* `after_<stage>.sh`
+
+Each of these sets correpond to one of the build stages inside the CI builds.
+
+The script `install.sh` contains a basic set of routines to install and update
+the scripts on the target host. If you add more scripts, it is sensible to
+add those in there.
+
+The script `functions.sh` contains a set of functions that are shared between
+all scripts. All scripts *source* `functions.sh` before anything is done.
+`functions.sh` also set important local and global (export) variables that are
+required by the build system.
+
+Before changing any script, try to understand the role of each of the stages by
+looking at our template CI yaml files (in the directory `../templates`) and
+then how to use the functions declared in `functions.sh`.