📝 Add GitLab CI/CD examples

* GitLab Pages
* npm deployment with rsync
* Multi-Arch-Images with Buildah

Author: veit

docs/productive/envs/uv/cicd.rst

@@ -6,8 +6,9 @@ CI/CD-Pipelines
 GitLab CI/CD
 ------------
 
-Für :doc:`GitLab CI/CD-Pipelines </productive/git/advanced/gitlab/ci-cd>` gibt
-es verschiedene Docker-Images mit vorinstalliertem ``uv``: `Available images
+Für :doc:`GitLab CI/CD-Pipelines </productive/git/advanced/gitlab/ci-cd/index>`
+gibt es verschiedene Docker-Images mit vorinstalliertem ``uv``: `Available
+images
 <https://docs.astral.sh/uv/guides/integration/docker/#available-images>`_.
 
 .. code-block:: yaml

docs/productive/git/advanced/gitlab/buildah.rst

@@ -0,0 +1,95 @@
+.. SPDX-FileCopyrightText: 2022–2025 Veit Schiele
+..
+.. SPDX-License-Identifier: BSD-3-Clause
+
+Multi-Arch-Images mit Buildah
+=============================
+
+`Buildah <https://buildah.io>`_ erlaubt euch, Container-Images zu erstellen ohne
+dass ihr eine vollständige Container-Runtime benötigt. Buildah ist ein
+Open-Source-Tool auf Linux-Basis, das `Docker <https://www.docker.com>`_- und
+`Kubernetes <https://kubernetes.io>`_-kompatible Images erstellen kann. Zudem kann Buildah nicht nur funktionierende Container von Grund auf neu erstellen,
+sondern auch aus einer bereits vorhandenen Dockerdatei. Schließlich lässt es
+sich leicht in Skripte und Build-Pipelines einbinden.
+
+Erste Schritte
+--------------
+
+#. Umgebungsvariablen einrichten
+
+   ``DEPLOY_USER``
+       Name des Accounts.
+   ``DEPLOY_KEY_FILE``
+       Pfad zu einem privaten SSH-Schlüssel, der zur Authentifizierung gegenüber
+       dem Server verwendet werden soll.
+   ``DEPLOY_HOST``
+       Hostname oder IP-Adresse des Servers, auf den verteilt werden soll.
+
+#. Einrichten der CI/CD-Pipeline
+
+   .. code-block:: yaml
+      :caption: .gitlab-ci.yml
+      :linenos:
+
+      stages:
+        - build
+        - deploy
+
+      build_docker:
+        stage: build
+        variables:
+          DOCKER_STEM: $CI_REGISTRY_IMAGE
+        image: quay.io/buildah/stable:v1.27
+        script:
+          - apk add --no-cache openssh
+          - chmod 0600 "$DEPLOY_KEY_FILE"
+          - ./build.sh
+
+      deploy_app:
+        stage: deploy
+        image: alpine
+        environment:
+          name: app
+          deployment_tier: staging
+        when: manual
+        script:
+          - apk add --no-cache openssh
+          - chmod 0600 "$DEPLOY_KEY"
+          - ./deploy.sh
+
+#. Bauen des Docker-Containers
+
+   .. code-block:: sh
+      :caption: build.sh
+      :linenos:
+      :emphasize-lines: 2, 5, 8
+
+      # Registry login
+      echo "$CI_REGISTRY_PASSWORD" | buildah login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
+
+      # Set docker tag
+      if [ "$CI_COMMIT_BRANCH" == main ]; then export DOCKER_TAG="latest"; else export DOCKER_TAG="${CI_COMMIT_TAG:-$CI_COMMIT_REF_SLUG}"; fi; export DOCKER_TAG_FULL="$DOCKER_STEM:$DOCKER_TAG"; echo "DOCKER_TAG_FULL=$DOCKER_TAG_FULL"
+
+      # Build and push
+      buildah build --isolation chroot --storage-driver vfs --jobs 2 --platform linux/amd64,linux/arm/v7 --manifest "$DOCKER_TAG_FULL" && buildah --storage-driver vfs images && buildah manifest push --storage-driver vfs --format v2s2 --all "$DOCKER_TAG_FULL" "docker://$DOCKER_TAG_FULL"
+
+   Zeile 2
+       meldet sich bei der :doc:`../package-registry` an.
+   Zeile 5
+       kennzeichnet die Images anhand ihrer Branch- oder Tag-Namen mit Ausnahme
+       von ``main``, der mit ``latest`` gekennzeichnet wird.
+   Zeile 8
+       baut die Images und stellt sie mit dem `VFS
+       <https://docs.docker.com/engine/storage/drivers/vfs-driver/>`_-Treiber
+       bereit.
+
+#. Bereitstellen
+
+   .. code-block:: sh
+      :caption: deploy.sh
+      :linenos:
+
+      # Set docker tag
+      if [ "$CI_COMMIT_BRANCH" == main ]; then export DOCKER_TAG="latest"; else export DOCKER_TAG="${CI_COMMIT_TAG:-$CI_COMMIT_REF_SLUG}"; fi; export DOCKER_TAG_FULL="$DOCKER_STEM:$DOCKER_TAG"; echo "DOCKER_TAG_FULL=$DOCKER_TAG_FULL"
+
+      echo "$CI_REGISTRY $DEPLOY_USER $DEPLOY_PASSWORD MYAPP $DOCKER_TAG" | ssh -o 'BatchMode yes' -o 'StrictHostKeyChecking accept-new' -i "$DEPLOY_KEY" root@$DEPLOY_HOST

docs/productive/git/advanced/gitlab/ci-cd/buildah.rst

@@ -1,7 +1,12 @@
+.. SPDX-FileCopyrightText: 2024–2025 Veit Schiele
+..
+.. SPDX-License-Identifier: BSD-3-Clause
+
+
 Docker-Container bauen
 ======================
 
-Wir verwenden :doc:`ci-cd`, um unsere Python-Docker-Container zu erstellen.
+Wir verwenden :doc:`index`, um unsere Python-Docker-Container zu erstellen.
 
 #. Zunächst definieren wir die Python-Version in unserer
    :ref:`pyproject-toml`-Datei des Projekts:

docs/productive/git/advanced/gitlab/ci-cd-pipeline.png renamed to docs/productive/git/advanced/gitlab/ci-cd/ci-cd-pipeline.png

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: 2022 Veit Schiele
+.. SPDX-FileCopyrightText: 2022–2025 Veit Schiele
 ..
 .. SPDX-License-Identifier: BSD-3-Clause
 
@@ -17,11 +17,11 @@ Continuous Integration
     führt eine Reihe von Skripten sequentiell oder parallel aus, die eure
     Anwendung automatisch erstellt und testet, :abbr:`z.B. (zum Beispiel)` nach
     jedem ``git pull`` in einem :doc:`Feature-Branch
-    <../../workflows/feature-branches>`. Damit soll es weniger wahrscheinlich
+    <../../../workflows/feature-branches>`. Damit soll es weniger wahrscheinlich
     werden, dass ihr Fehler in eure Anwendung einbringt.
 
     Wenn die Überprüfungen wie erwartet funktionieren, könnt ihr einen
-    :doc:`Merge Request <merge-requests>` stellen; schlagen die Überprüfungen
+    :doc:`Merge Request <../merge-requests>` stellen; schlagen die Überprüfungen
     fehl, könnt ihr die Änderungen :abbr:`ggf. (gegebenenfalls)` zurücknehmen.
 
     .. seealso::
@@ -155,7 +155,7 @@ Pipelines anzeigen
 
 Ihr findet die aktuellen und historischen Pipeline-Runs auf der Seite
 :menuselection:`CI/CD --> Pipelines` eures Projekts. Ihr könnt auch auf Pipelines
-für einen :doc:`Merge-Request <merge-requests>` zugreifen, indem ihr zu deren
+für einen :doc:`Merge-Request <../merge-requests>` zugreifen, indem ihr zu deren
 Registerkarte :guilabel:`Pipelines` navigiert. Wählt eine Pipeline aus, um die
 Seite *Pipeline-Details* zu öffnen und die *Jobs* anzuzeigen, die für diese
 Pipeline ausgeführt wurde. Von hier aus könnt ihr eine laufende Pipeline
@@ -176,3 +176,12 @@ Pipeline löschen.
      <https://docs.gitlab.com/ee/ci/variables/index.html>`_
    * `GitLab Docs: Predefined variables reference
      <https://docs.gitlab.com/ee/ci/variables/predefined_variables.html>`_
+
+.. toctree::
+   :hidden:
+
+   pages
+   npm
+   docker
+   buildah
+   github-migration

docs/productive/git/advanced/gitlab/ci-cd-pipeline.png.license renamed to docs/productive/git/advanced/gitlab/ci-cd/ci-cd-pipeline.png.license

@@ -0,0 +1,116 @@
+.. SPDX-FileCopyrightText: 2025 Veit Schiele
+..
+.. SPDX-License-Identifier: BSD-3-Clause
+
+npm-Deployment mit rsync
+========================
+
+`npm <https://www.npmjs.com>`_ ist ein Paketmanager für die
+JavaScript-Laufzeitumgebung `Node.js <https://nodejs.org/en/>`_, und mit `rsync
+<https://rsync.samba.org>`_ können die Daten mit dem entfernten Server
+synchronisiert werden.
+
+Erste Schritte
+--------------
+
+#. Umgebungsvariablen einrichten
+
+   ``DEPLOY_DIR``
+       Verzeichnis auf dem entfernten Server, in das verteilt werden soll.
+   ``DEPLOY_HOST``
+       Hostname oder IP-Adresse des Servers, auf den verteilt werden soll.
+   ``DEPLOY_KEY_FILE``
+       Pfad zu einem privaten SSH-Schlüssel, der zur Authentifizierung gegenüber
+       dem Server verwendet werden soll.
+   ``DEPLOY_USER``
+       Name des SSH-Accounts.
+   ``KNOWN_HOSTS_FILE``
+       Pfad zu einer Datei mit vordefinierten :file:`known_hosts`-Einträgen, mit
+       denen die Verbindung überprüft werden soll.
+
+#. Einrichten der CI/CD-Pipeline
+
+   .. code-block:: yaml
+      :caption: .gitlab-ci.yml
+      :emphasize-lines: 13, 14, 15
+
+      stages:
+        - deploy
+
+      deploy-static-assets:
+        stage: deploy
+        rules:
+          - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+        environment:
+          name: prod
+          deployment_tier: production
+        image: node:alpine
+        script:
+          - apk add --no-cache git nodejs npm openssh-client-default rsync
+          - chmod 0600 "$DEPLOY_KEY_FILE"
+          - ./deploy.sh
+
+   Zeile 13
+       installiert die für das Bauen und Hochladen erforderlichen Pakete
+   Zeile 14
+       ändert die Zugriffsberechtigungen für den ssh-Schlüssel
+   Zeile 15
+       ruft die :file:`deploy.sh`-Datei auf
+
+#. Verschieben der statischen Dateien auf den Server
+
+   .. code-block:: sh
+      :caption: deploy.sh
+      :linenos:
+      :emphasize-lines: 7-13, 18, 19, 24, 25-31
+
+      #!/bin/sh
+      set -e
+
+      # Deploy static assets to a server via rsync.
+
+      # Create SSH config.
+      cat >deploy.ssh_config <<-END
+          Host deploy
+              HostName $DEPLOY_HOST
+              User $DEPLOY_USER
+              IdentityFile $DEPLOY_KEY_FILE
+              UserKnownHostsFile $KNOWN_HOSTS_FILE
+      END
+
+
+      # Build the JavaScript application & related files.
+      cd vite-app
+      npm ci
+      npx vite build
+
+      # Deploy the application and GeoJSON data.
+      rsync \
+          -rtlv \
+          --rsh 'ssh -F ../deploy.ssh_config' \
+          --rsync-path "mkdir -p \"$DEPLOY_DIR\" && rsync" \
+          ../data/cusy.geojson \
+          cusy.html \
+          dist/cusy-map.css \
+          dist/cusy-map.js \
+          dist/cusy-map.js.map \
+          "deploy:$DEPLOY_DIR"
+
+   Zeile 7–13
+       erstellt die ssh-Konfigurationsdatei
+
+   Zeile 18
+       installiert die Abhängigkeiten des Projekts aus der
+       :file:`vite-app/package.json`-Datei
+
+       .. seealso::
+          `npm-ci <https://docs.npmjs.com/cli/v9/commands/npm-ci>`_
+
+   Zeile 19
+       erstellt das `vite <https://vite.dev>`_-Projekt für die Produktion.
+
+   Zeile 24
+       verschiebt die ssh-Konfiguration auf den Server
+
+   Zeile 25–31
+       verschiebt die Anwendung und GeoJSON-Daten auf den Server