diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 019371e51fc1604da8172258509392d3969bbcef..432d6c3ad56c0b78205fab52c22532a88deb8012 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -15,7 +15,7 @@ stages:
     - analyze
     - integration-test
     - build-release
-    - publish
+    - deploy
     - .post
 
 include:
diff --git a/.gitlab/ci/.mk-docs-deploy.yml b/.gitlab/ci/.mk-docs-deploy.yml
index 62895a1e7cc80ea309977d6e94b4938cab9133d7..1fe2613ede37eb436370544b74956fddcedea2f2 100644
--- a/.gitlab/ci/.mk-docs-deploy.yml
+++ b/.gitlab/ci/.mk-docs-deploy.yml
@@ -1,20 +1,45 @@
-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/$CI_COMMIT_BRANCH
-  needs: []
-  artifacts:
-    name: "$CI_COMMIT_BRANCH"
-    paths:
-      - public
-    expire_in: 1 week
-  rules:
-      # run only for protected branches; in our case this should be master and
-      # develop.
-    - if: $CI_COMMIT_REF_PROTECTED == "true"
+build-mkdocs:
+    image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/python:3.9.15-slim-bullseye
+    stage: build
+    before_script:
+        - pip install mkdocs-material
+    script:
+        - mkdocs build --site-dir mkdocs-built
+    artifacts:
+        paths:
+            - mkdocs-built
+    rules:
+        # run only for protected branches (this should be master and develop).
+        - if: $CI_COMMIT_REF_PROTECTED == "true"
+
+.pages-options: &pages-options
+    image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/python:3.9.15-slim-bullseye
+    stage: deploy
+    script:
+        - mv mkdocs-built public
+    needs:
+        - job: build-mkdocs
+          artifacts: true
+    artifacts:
+        paths:
+            - public
+
+pages-develop:
+    <<: *pages-options
+    environment:
+        name: docs-develop
+        deployment_tier: development
+        url: "https://danet.h-da.io/-/gosdn/-/jobs/$CI_JOB_ID/artifacts/public/index.html"
+    rules:
+        # run only on development branch (this should be develop).
+        - if: $CI_COMMIT_BRANCH == "develop"
+
+pages:
+    <<: *pages-options
+    environment:
+        name: docs-master
+        deployment_tier: production
+        url: https://danet.h-da.io/gosdn
+    rules:
+        # run only on default branch (this should be master).
+        - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH