diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 432d6c3ad56c0b78205fab52c22532a88deb8012..019371e51fc1604da8172258509392d3969bbcef 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -15,7 +15,7 @@ stages:
     - analyze
     - integration-test
     - build-release
-    - deploy
+    - publish
     - .post
 
 include:
diff --git a/.gitlab/ci/.mk-docs-deploy.yml b/.gitlab/ci/.mk-docs-deploy.yml
index 6973aff9d993117108126c910b372ce6294b4ac7..62895a1e7cc80ea309977d6e94b4938cab9133d7 100644
--- a/.gitlab/ci/.mk-docs-deploy.yml
+++ b/.gitlab/ci/.mk-docs-deploy.yml
@@ -1,11 +1,20 @@
-image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/python:latest
-pages:
-  stage: deploy
+image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/python:3.9.15
+cache:
+  # keep artifacts from previous builds
+  paths:
+    - public
+documentation:
+  stage: publish
   script:
     - pip install mkdocs-material
-    - mkdocs build --site-dir public
+    - mkdocs build --site-dir public/$CI_COMMIT_BRANCH
+  needs: []
   artifacts:
+    name: "$CI_COMMIT_BRANCH"
     paths:
       - public
+    expire_in: 1 week
   rules:
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+      # run only for protected branches; in our case this should be master and
+      # develop.
+    - if: $CI_COMMIT_REF_PROTECTED == "true"