Versuchsdurchführung

Einrichten einer Pipeline in Gitlab

Einrichten eines Runners

Gitlab Runner funktionieren nach dem Server-Modell. Der Gitlab-Server auf dem das Repo gehostet ist fungiert als Server, der an die Runner Aufgaben verteilt. Ein Runner agiert dann als Client, der die Skripte einer Pipeline ausführt.

Setup

VM beantragen
Docker auf VM installieren
GitLab Runner mit docker compose starten

services:
  gitlab-runner:
    image: gitlab/gitlab-runner:latest
    volumes:
        - data:/etc/gitlab-runner
        - /var/run/docker.sock:/var/run/docker.sock
    deploy:
      update_config:
        order: start-first
      restart_policy:
        condition: on-failure

volumes:
    data:

Um den Gitlab-Runner mit dem Repo zu verknüpfen, muss dieser mit docker exec -it gitlab-runner gitlab-runner register registriert werden.
Im Registrierungsprozess den Host https://gitlab.informatik.hs-augsburg.de angeben
Im Repo unter Settings > CI/CD > Runners einen neuen Runner hinzufügen
Den dabei entstandenen Auth-Token in den Registrierungs-Prozess kopieren
Dem Runner einen einzigartigen ❄️ Namen geben
Executor Typ angeben, in unserem Fall wollen wir die Skripte in einem Docker auführen.
Der Runner ist registriert, es kann mit dem Schreiben von Pipelines fortgefahren werden 🎉

Pipeline

Um die Pipeline übersichtlich zu gestalten, wird diese für jeden einzelnen Task in eigene Dateien gesplittet. Im “Hauptfile” der Pipeline werden die für eine Pipeline typischsten Phasen definiert.

stages:
  - check
  - build
  - leak
  - deploy
  - test

include:
  - .gitlab/pipelines/docs.yml
  - .gitlab/pipelines/changelog.yml
  - .gitlab/pipelines/leaks.yml

Pipeline zum Veröffentlichen der Dokumentation

Unsere Dokumentation soll natürlich automatisch im Web veröffentlicht werden. Die Website zu bauen und dann zu veröffentlichen ist für einen Menschen viel zu repetetiv und gut automatisierbar.

Dazu müssen ein paar Variablen unter Settings > CI/CD > Variables angelegt werden, um die Pipeline zu authorisieren auf den Webserver kopieren zu dürfen.

Variablen

# Jobs to automate the docs building and publishing
build-docs:  # Generieren der HTML-Dateien aus Markdown
  stage: build
  image: node:latest
  script:
    - cd docs/
    - npm ci
    - npm run build
  artifacts:
    paths:
      - docs/dist/
    expire_in: 1 week
  cache:
    # Javascript Pakete cachen um schnellere Folgeinstallationen zu haben
    paths:
      - docs/node_modules/
  rules:
    # Nur ausführen wenn auf den main Branch gepusht wurde und sich Dateien in
    # ./docs verändert haben
    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
      changes:
        - docs/**/*
      when: on_success


deploy-docs:  # Kopieren der HTML-Dateien auf einen Server
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache rsync openssh-client base64
    - eval $(ssh-agent -s)
    # Für die Pipeline ist es notwendig einen SSH-Key zu generieren, der dann
    # anstatt eines Passworts zur Authentifizierung verwendet wird.
    - echo "$SSH_PRIVATE_KEY" | base64 -d | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
    - ssh-keyscan $DEPLOY_HOST >> ~/.ssh/known_hosts
  script:
    # Da $DEPLOY_PATH über nfs automount eingebunden ist muss dies zuerst getriggert werden
    # rsync alleine löst keinen automount aus
    - ssh $DEPLOY_USER@$DEPLOY_HOST "mkdir -p $DEPLOY_PATH"
    - rsync -avz --delete docs/dist/* $DEPLOY_USER@$DEPLOY_HOST:$DEPLOY_PATH
  rules:
    - if: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE == "push"
      changes:
        - docs/**/*
      when: on_success

Pipeline zum Erstellen eines CHANGELOG

Mit dem Tool git-cliff kann aus dem Commit-Verlauf eines Repos eine schöne Changelog-Datei für Releases erstellt werden.

# Jobs to automate the docs building and publishing
build-changelog:  # Generieren der Changelog
  stage: build
  image:
    name: orhunp/git-cliff:latest
    entrypoint: [""]
  variables:
    GIT_STRATEGY: clone
    GIT_DEPTH: 0
  script:
    - git-cliff -r . > CHANGELOG.md
  artifacts:
    paths:
      - CHANGELOG.md
  rules:
    - if: $CI_COMMIT_TAG
      when: on_success


deploy-changelog:  # Changelog in Repo commiten
  stage: deploy
  image: alpine:latest
  needs: [build-changelog]
  variables:
    GIT_STRATEGY: clone
  before_script:
    - apk add --no-cache git
    - git config --global user.name "GitLab CI"
    - git config --global user.email "gitlab-ci@example.com"
    - git remote set-url origin "https://oauth2:${GIT_PUSH_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
  script:
    - git add CHANGELOG.md
    - git commit -m "Update CHANGELOG.md [skip ci]" || echo "No changes to commit"
    - git push origin HEAD:${CI_COMMIT_REF_NAME}
  rules:
    - if: $CI_COMMIT_TAG
      when: on_success

Pipeline um Geheimnisse in Commits zu entdecken

Vorbereitung

CI/CD-Plattform: GitLab
Tool: Gitleaks
Konfiguration: .gitleaksconfig.toml im Repository vorhanden
Ziel: Anhand verschiedener Patterns erkennen, ob versehentlich Geheimnisse in einem Repo commited wurden.

Durchführung

1. Gitleaks-Job zur .gitlab-ci.yml hinzufügen

Füge folgenden Job in deine GitLab CI/CD-Pipeline ein, um das Projektverzeichnis auf Geheimnisse zu scannen:

# Job to scan the directory for leaked secrets
gitleaks:
  stage: leak
  image:
    name: zricethezav/gitleaks:latest
    entrypoint: [""]
  script:
    - gitleaks dir -v -f json -r gitleaks-report.json --config  ./.gitleaksconfig.toml # --config .. is optional
  artifacts:
    paths:
      - gitleaks-report.json
    when: on_failure
    expire_in: 1 week
  rules:
    - if: $CI_PIPELINE_SOURCE == "push"
      changes:
        - "**/*"
      when: on_success
    - if: $CI_PIPELINE_SOURCE == "schedule"
      when: always

2. Konfigurationsdatei erstellen (Optional)

Lege im Repository eine Datei namens .gitleaksconfig.toml ab. Diese kann selbst erstellte Regeln enthalten, die von Gitleaks verwendet werden um Muster zu erkennen/ignorieren:

# This is a custom gitleaks configuration which extends the standard config.
title = "Custom Gitleaks configuration"

[extend] useDefault = true

# Add your custom rules here
[[rules]] id = "your-rule-id"
description = "An description for your rule"
regex = '''(?i)\b(your|rule|regex)\b'''

# Exception for this file, or else the pipeline fails.
[allowlist]
description = "Ignore custom config file"
paths = [ '''.gitleaksconfig\.toml''' ]

Ergebnis

Nach einem erfolgreichen Lauf sollte der Gitleaks-Job in der GitLab-Pipeline grün durchlaufen, sofern keine verdächtigen Inhalte gefunden wurden.

Im Fehlerfall (on_failure) erzeugt Gitleaks automatisch einen Report im JSON-Format (gitleaks-report.json), der als Artefakt gespeichert wird. Dieser kann direkt in GitLab heruntergeladen und überprüft werden.

Zusätzlich wird der Gitleaks-Job regelmäßig ausgeführt, vorausgesetzt man hat dies in GitLab eingestellt.

Probleme

Nur Arbeitsverzeichnis wird gescannt: Der Befehl gitleaks dir durchsucht nicht die Git-Historie. Vorschlag: Verwende stattdessen gitleaks git . um das gesamte Repository inklusive Commits zu analysieren.
Leaks werden erst spät erkannt: Gitleaks lokal als Pre-Commit Hook einrichten, um bereits vor dem Commit zu scannen und Probleme frühzeitig zu vermeiden.