diff --git a/delete-inactive-environments.sh b/.ci-scripts/delete-inactive-environments.sh
similarity index 98%
rename from delete-inactive-environments.sh
rename to .ci-scripts/delete-inactive-environments.sh
index 53ee4362d09020bc9bfcf0b9efd37610aa1e20e9..58ec57bb8134ec50a2b953816dea95fd08911e1d 100644
--- a/delete-inactive-environments.sh
+++ b/.ci-scripts/delete-inactive-environments.sh
@@ -8,6 +8,7 @@ PROJECT_ID=14957
 ACTIVE_BRANCHES=$(curl --header "PRIVATE-TOKEN: $API_TOKEN" "https://gitlab.gwdg.de/api/v4/projects/${PROJECT_ID}/repository/branches" | jq '.[].name')
 ACTIVE_BRANCHES=$(echo $ACTIVE_BRANCHES | sed -E "s/[^0-9a-z[:space:]\"]/-/g")
 
+# get environments
 ENVIRONMENTS=$(curl --header "PRIVATE-TOKEN: $API_TOKEN" "https://gitlab.gwdg.de/api/v4/projects/${PROJECT_ID}/environments")
 ENV_NAMES=$(echo $ENVIRONMENTS | jq -r '.[].name')
 
diff --git a/remove-old-artifacts.sh b/.ci-scripts/remove-old-artifacts.sh
similarity index 84%
rename from remove-old-artifacts.sh
rename to .ci-scripts/remove-old-artifacts.sh
index f781c72e81512bd2116f64dadaf4dae72f12f962..00f7908bab7053c8b316d45025adae8e8ca1a11b 100644
--- a/remove-old-artifacts.sh
+++ b/.ci-scripts/remove-old-artifacts.sh
@@ -1,5 +1,8 @@
 #!/bin/bash
 
+# This script removes all data that belongs to branches that have been closed.
+# This way we ensure that the artifacts don't get too big.
+
 PROJECT_ID=14957
 
 # get active branches
diff --git a/.ci-scripts/set-path-base.sh b/.ci-scripts/set-path-base.sh
new file mode 100755
index 0000000000000000000000000000000000000000..5c814c0271b1b114ed909327c2b0a3d38b7d3197
--- /dev/null
+++ b/.ci-scripts/set-path-base.sh
@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# This script sets the base path for vuepress according to the branch we're on.
+# Since our environments always have their respective branch name in the URL,
+# the base path has to be adjusted to that. Otherwise the files of the environment
+# will not be found.
+
+if [[ $1 == "main" ]]; then
+    sed -i "s|base:\s*'/'|base: '/ahiqar/website/'|" src/.vuepress/config.js
+else
+    sed -i "s|base:\s*'/'|base: '/ahiqar/website/$1/'|" src/.vuepress/config.js
+fi
\ No newline at end of file
diff --git a/update-artifacts.sh b/.ci-scripts/update-artifacts.sh
similarity index 79%
rename from update-artifacts.sh
rename to .ci-scripts/update-artifacts.sh
index d91fd5ed8ea97406c8c6e0a3b2f348771263e0df..7072f8614b0cf700ee9abe4e67b7ed2887bbd349 100644
--- a/update-artifacts.sh
+++ b/.ci-scripts/update-artifacts.sh
@@ -1,5 +1,9 @@
 #!/bin/bash
 
+# This script gets the old artifacts containing the data for all active environments and
+# adds the current branch's data to them.
+# This way we can preserve the old environments and have the new one, too.
+
 DIST_DIR=src/.vuepress/dist
 PROJECT_ID=14957
 
@@ -14,7 +18,8 @@ unzip -u old-artifact.zip
 
 # we want the main branch to be available at https://subugoe.pages.gwdg.de/ahiqar/website/ while
 # the environments of the feature branches should be available at 
-# https://subugoe.pages.gwdg.de/ahiqar/website/${CI_COMMIT_REF_SLUG}/
+# https://subugoe.pages.gwdg.de/ahiqar/website/${CI_COMMIT_REF_SLUG}/.
+# this has to be considered in the directory structure.
 if [ ! ${CI_COMMIT_REF_SLUG} = 'main' ]; then
 	mkdir -p public/${CI_COMMIT_REF_SLUG}
     cp --recursive ${DIST_DIR}/* public/${CI_COMMIT_REF_SLUG}
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index cd89bd24b9370e844f2401e62032118cb29be594..0451a19c05688e99a74a5a6d6385b1cccbb5e43e 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -1,3 +1,12 @@
+# this file defines the CI/CD stages for the Ahiqar website.
+# in some cases they invoke scripts provided at .ci-scripts/ in order to
+# keep this file slim and clear. please have a look at these scripts for
+# information that goes beyond the documentation of the single stages.
+#
+# this config uses a custom Docker image to keep the pipelines fast.
+# see https://gitlab.gwdg.de/mrodzis/docker-images/-/tree/main/alpine for more 
+# info about it.
+
 cache:
   paths:
     - node_modules/
@@ -12,27 +21,23 @@ build_page:
   image: node:lts-alpine3.10
   stage: build
   script:
-    - ash set-path-base.sh ${CI_COMMIT_REF_SLUG}
+    - ash .ci-scripts/set-path-base.sh ${CI_COMMIT_REF_SLUG}
     - npm i
     - node_modules/.bin/vuepress build src
   artifacts:
     paths:
       - src/.vuepress/dist
 
+# this stage creates a new environment for the current branch.
 pages:
-  image: alpine:latest
+  image: docker.gitlab.gwdg.de/mrodzis/docker-images/alpine
   stage: pages
   needs:
     - job: build_page
       artifacts: true
-  before_script:
-    - apk add curl
-    - apk add jq
-    - apk add unzip
-    - apk add zip
   script:
-    - ash update-artifacts.sh
-    - ash remove-old-artifacts.sh
+    - ash .ci-scripts/update-artifacts.sh
+    - ash .ci-scripts/remove-old-artifacts.sh
   environment:
     name: ${CI_COMMIT_REF_SLUG}
     url: https://subugoe.pages.gwdg.de/ahiqar/website/${CI_COMMIT_REF_SLUG}/
@@ -41,10 +46,9 @@ pages:
     paths:
       - public
 
+# preserves the current as well as all the old artifacts for the environments.
 pushback:
-  before_script:
-    - apk add zip
-  image: alpine:latest
+  image: docker.gitlab.gwdg.de/mrodzis/docker-images/alpine
   stage: preserve-pages
   needs:
     - job: pages
@@ -56,11 +60,9 @@ pushback:
     paths:
       - updated-artifact.zip
 
+# removes the environments that are no longer needed.
 remove_envs:
-  before_script:
-    - apk add curl
-    - apk add jq
-  image: alpine:latest
+  image: docker.gitlab.gwdg.de/mrodzis/docker-images/alpine
   stage: remove_unused_envs
   needs:
     - job: build_page
@@ -73,4 +75,4 @@ remove_envs:
     - if: '$CI_COMMIT_BRANCH == "main"'
     - if: '$CI_COMMIT_MESSAGE =~ "Merge"'
   script:
-    - ash delete-inactive-environments.sh
+    - ash .ci-scripts/delete-inactive-environments.sh
diff --git a/set-path-base.sh b/set-path-base.sh
deleted file mode 100755
index 16e24354dc19e65576e8b0da598ccb6e43d1bbcb..0000000000000000000000000000000000000000
--- a/set-path-base.sh
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/bin/bash
-
-if [[ $1 == "main" ]]; then
-    sed -i "s|base:\s*'/'|base: '/ahiqar/website/'|" src/.vuepress/config.js
-else
-    sed -i "s|base:\s*'/'|base: '/ahiqar/website/$1/'|" src/.vuepress/config.js
-fi
\ No newline at end of file