Skip to Content

Changes for page GitLab Erklärungen

Last modified by Sebastian Beyer on 2026/10/13 10:43
From version 162.1
edited by Sebastian Beyer
on 2026/10/12 13:48
Change comment: There is no comment for this version
To version 162.4
edited by Sebastian Beyer
on 2026/10/13 10:36
Change comment: Auto-saved during real-time collaboration

Summary

Details

Page properties
Content
... ... @@ -244,15 +244,22 @@
244 244  
245 245  = GitLab Pipelines =
246 246  
247 -Eine GitLab Pipeline ist eine in //.gitlab-ci.yml// definierte Abfolge von Jobs. Jobs können dabei beispielsweise die automatische Ausführung von Tests sein.
247 +Eine GitLab Pipeline ist eine in der Datei //.gitlab-ci.yml// definierte Abfolge von Jobs. Diese Jobs können beispielsweise das Projekt automatisch bauen, Tests ausführen oder Berichte erstellen und veröffentlichen.
248 248  
249 +Die Jobs werden in sogenannten **Stages** (Phasen) organisiert. Jobs innerhalb einer Stage können parallel ausgeführt werden, sofern keine Abhängigkeiten festgelegt wurden. Die nächste Stage beginnt normalerweise erst, wenn die vorherige abgeschlossen ist.
250 +
251 +Schlägt ein Job fehl, wird die Pipeline normalerweise als fehlgeschlagen markiert und nachfolgende Stages werden nicht mehr ausgeführt. Über die Einstellung allow_failure kann jedoch festgelegt werden, dass bestimmte Jobs fehlschlagen dürfen, ohne die weitere Ausführung der Pipeline zu verhindern.
252 +
249 249  == Pipeline im Basisprojekt v2 ==
250 250  
251 -Die Pipeline im Basisprojekt ist auf zwei Stages mit jeweils einem Job aufgeteilt und wird im Folgenden Schritt für Schritt erklärt. Ihr dürft im Rahmen des Softwareprojekts, wenn nötig, die Pipeline um weitere Jobs oder Stages erweitern. **Die bestehenden Jobs sollten allerdings **(von Studierenden) **nicht geändert werden.**
255 +Die Pipeline im Basisprojekt besteht aus zwei Stages mit insgesamt drei Jobs. Sie überprüft automatisch euer Projekt und stellt verschiedene Berichte bereit.
252 252  
253 -In der //.gitlab-ci.yml //werden zunächst die Stages definiert. Eine Stage ist eine logische Gruppe von Jobs, die in einem bestimmten Abschnitt der Pipeline ausgeführt werden. Jobs in einer Stage werden parallel ausgeführt, es sei denn es wird eine Abhängigkeit in den Jobs definiert.
254 -Wenn alle Jobs in einer Stage (erfolgreich) abgeschlossen sind, startet die nächste Stage. Schlägt ein Job fehl wird die gesamte Pipeline gestoppt, außer es werden Jobs so markiert, dass sie fehlschlagen dürfen.
257 +Die Pipeline darf im Rahmen des Softwareprojekts bei Bedarf um weitere Jobs oder Stages **erweitert** werden. Die **bestehenden Jobs** sollten von Studierenden allerdings **nicht verändert werden**, da sie für die Überprüfung und Auswertung des Projekts benötigt werden.
255 255  
259 +=== Aufbau der Pipeline ===
260 +
261 +Zunächst werden in der //.gitlab-ci.yml //die beiden Stages definiert:
262 +
256 256  {{code language="yaml"}}
257 257  stages:
258 258   - verify
... ... @@ -259,70 +259,93 @@
259 259   - deploy
260 260  {{/code}}
261 261  
262 -Der //verify-job //ist der erste Job, der in der Pipeline definiert ist. Er wird in der //verify-//Stage ausgeführt. Das Image ist ein Docker-Image, welches schon mit einer Java 21 Umgebung eingerichtet ist. Dadurch wird sichergestellt, dass der Job immer die gleiche Umgebung hat ("//but it works on my machine"//).
263 -Im Script-Abschnitt wird dann mvn clean verify ausgeführt. Maven verify baut das Projekt und führt die Tests im Projekt aus.
264 -Die Rules definieren, wann ein Job ausgeführt wird und ob das Fehlschlagen des Jobs erlaubt ist. Regeln werden von oben nach unten ausgewertet. //$CI_PIPELINE_SOURCE == "schedule" //sagt dass der Job bei automatischen Aufrufen über einen zeitgesteuerten Start der Pipeline mit besonderen Einschränkungen ausgeführt werden soll. //allow_failure// erlaubt in dem Fall, dass bei automatischer Ausführung die Pipeline nicht abgebrochen wird, falls sich euer Projekt nicht bauen lässt, damit darauffolgende Jobs weiterhin ausgeführt werden.
269 +(((
270 +Die Pipeline enthält folgende Jobs:
265 265  
266 -{{code language="yaml"}}
267 -verify-job:
268 - stage: verify
269 - image: eclipse-temurin:21-jdk-alpine
270 - script:
271 - - "./mvnw clean verify"
272 - rules:
273 - - if: $CI_PIPELINE_SOURCE == "schedule"
274 - when: always
275 - allow_failure: true
276 - - when: always
277 - allow_failure: false
272 +* **verify-job (Stage: verify):** Baut das Projekt, führt Tests und weitere Überprüfungen aus und erstellt Berichte zur Testabdeckung (JaCoCo) und zu möglichen Codeproblemen (SpotBugs).
273 +* **deploy_spotbugs_pages (Stage: deploy):** Veröffentlicht den zuvor erzeugten SpotBugs-Bericht als eigene GitLab-Pages-Seite.
274 +* **deploy_stats_pages (Stage: deploy):** Erfasst regelmäßig eure Projektarbeitsdaten, beispielsweise Stundenbuchungen, und veröffentlicht eine Visualisierung dieser Daten.
275 +
276 +Der verify-job führt die eigentlichen Überprüfungen durch. Die beiden Jobs der Deploy-Stage kümmern sich um die Veröffentlichung bzw. Bereitstellung der Berichte. Dabei wird der Statistik-Job nur bei zeitgesteuerten Pipelines ausgeführt.
277 +
278 +==== 1. Verify-Stage: Projekt überprüfen ====
279 +
280 +Der erste Job der Pipeline heißt verify-job. Er wird in der Stage verify ausgeführt.
281 +
282 +Für diesen Job wird das Docker-Image maven:3.9.9-eclipse-temurin-21 verwendet. Es stellt eine Umgebung mit Maven und Java 21 bereit. Dadurch wird sichergestellt, dass das Projekt bei jeder Pipeline-Ausführung unter vergleichbaren Bedingungen überprüft wird und nicht von den lokal installierten Entwicklungswerkzeugen abhängig ist.
283 +
284 +Die eigentliche Überprüfung erfolgt durch folgenden Maven-Befehl:
285 +
286 +{{code}}
287 +./mvnw clean verify jacoco:report
278 278  {{/code}}
279 279  
280 -(((
281 - Der //deploy_stats_pages// Job ist der erste Job, der in der //deploy//-Stage ausgeführt wird. Der Job erfasst eure Projektarbeitsdaten (bspw. eure Stundenbuchungen) und veröffentlicht diese, nur für euch in GitLab sichtbar, in eurem Projekt.
282 -Die Variablen sind Umgebungsvariablen, die zum Erfassen der Daten benötigt werden. **Die //TIME_FRAMES// Variable ist auskommentiert und sollte durch euren projektverantwortlichen Betreuer:in (Tutor:in) angepasst werden.** Durch die //TIME_FRAMES// Variable können die [[Einschätzungszeiträume>>https://xwiki.swl.informatik.uni-oldenburg.de/xwiki/bin/view/Main/Bewertung/#HEinschE4tzungszeitrE4ume]] sowie die "Soll-Zeit" pro Zeitraum gesetzt und für die Visualisierung verwendet werden.
283 -Im Script-Bereich wird erst git installiert und dann die Projekete zur Erfassung und Visualisierung der Daten installiert.
284 -Der Artifakt-Bereich definiert welche Dateien nach Ausführung des Jobs behalten werden. Der Public Ordner wird verwendet, um statische Websiten zu veröffentlichen. In diesem Fall die Visualisierung der erfassten Daten.
285 -Im Gegensatz zum //verify-job// wird der //deploy_stats_pages//-Job **nur** ausgeführt, wenn die Pipeline zeitgesteuert gestartet wird.
290 +Mit diesem Befehl wird das Projekt neu gebaut, die konfigurierten Tests und Maven-Überprüfungen werden ausgeführt und die Erstellung der JaCoCo-Berichte angestoßen.
286 286  
292 +Zusätzlich verarbeitet der Job die SpotBugs-Ergebnisse. Dazu werden zwei bereitgestellte Python-Skripte verwendet. Diese bereiten die gefundenen Probleme auf und erzeugen eine übersichtliche HTML-Seite.
293 +
294 +Die erzeugten Berichte werden anschließend im Ordner public gesammelt und als sogenannte **Artifacts** gespeichert. Artifacts sind Dateien, die nach der Ausführung eines Jobs erhalten bleiben und beispielsweise von weiteren Jobs verwendet werden können.
295 +
296 +===== **JaCoCo: Testabdeckung** =====
297 +
298 +JaCoCo ist ein Werkzeug zur Messung der Testabdeckung. Es zeigt euch, welche Teile eures Java-Codes bei der Ausführung der Tests durchlaufen wurden.
299 +
300 +So könnt ihr erkennen, welche Klassen oder Methoden bereits durch Tests abgedeckt sind und an welchen Stellen möglicherweise noch Tests fehlen.
301 +
302 +Der verify-job erstellt einen zusammengefassten JaCoCo-Bericht für das Projekt und veröffentlicht ihn über GitLab Pages. Dadurch könnt ihr die Ergebnisse direkt im Browser ansehen.
303 +
304 +**Wichtig:** Eine hohe Testabdeckung bedeutet nicht automatisch, dass alle Tests sinnvoll sind oder dass das Projekt fehlerfrei ist. Sie hilft euch aber dabei, bisher ungetestete Bereiche zu erkennen.
305 +
306 +===== **SpotBugs: Mögliche Codeprobleme erkennen** =====
307 +
308 +Neben JaCoCo wird auch SpotBugs verwendet. SpotBugs untersucht Java-Code auf typische Fehlermuster und mögliche Programmierfehler.
309 +
310 +Die gefundenen Probleme werden in verschiedenen Formaten bereitgestellt:
311 +
312 +* **HTML-Bericht:** Eine übersichtliche Darstellung der gefundenen Probleme mit zusätzlichen Erklärungen.
313 +* **XML-Berichte:** Die ursprünglichen SpotBugs-Ergebnisse der einzelnen Module.
314 +* **GitLab Code Quality:** Die Ergebnisse werden in ein Format umgewandelt, das GitLab zur Darstellung von Codequalitätsproblemen verwenden kann.
315 +
316 +Die HTML-Berichte helfen euch, mögliche Fehler schneller zu verstehen und im eigenen Code nachzuvollziehen.
317 +
318 +Die SpotBugs-Ergebnisse werden zunächst vom verify-job erstellt und anschließend durch einen eigenen Job veröffentlicht.
319 +
320 +==== 2. Deploy-Stage: Berichte veröffentlichen ====
321 +
322 +In der zweiten Stage deploy werden die erzeugten Berichte bereitgestellt.
323 +
324 +===== **SpotBugs-Berichte veröffentlichen (deploy_spotbugs_pages)** =====
325 +
326 +Der Job deploy_spotbugs_pages übernimmt die SpotBugs-Dateien aus dem vorherigen verify-job und veröffentlicht sie über GitLab Pages.
327 +
328 +Hierfür verwendet der Job die folgende Einstellung:
329 +
287 287  {{code language="yaml"}}
288 -deploy_stats_pages:
289 - stage: deploy
290 - image: maven:3.9.9-amazoncorretto-21-al2023
291 - variables:
292 - DEVELOPMENT_BRANCH_NAME: "development"
293 - FETCH_MULTITHREAD: "true" #options are true/false
294 - LOGLEVEL: "SHORT" #options are OFF, SHORT, LONG. Has an effect on the amount of logging when data is being added
295 - #TIME_FRAMES: "01.01.2025,31.03.2025,40,Zeitraum01;01.04.2025,31.05.2025,35" #Format start,end,minHours[,name];anotherTimeframe;anotherTimeframe;...
296 - script:
297 - - yum install -y git rsync
298 - - git clone https://gitlab.swl.informatik.uni-oldenburg.de/GA/gitlab2data.git
299 - - cd gitlab2data
300 - - mvn clean package
301 - - java -jar target/GitLab2Data-1.0-SNAPSHOT-jar-with-dependencies.jar
302 - - cd ..
303 - - mkdir -p public/data
304 - - rm -f public/data/*.json
305 - - cp gitlab2data/*.json public/data/
306 - - git clone https://gitlab.swl.informatik.uni-oldenburg.de/GA/data4visual.git repo
307 - - rsync -av --exclude='data/' --exclude='.git' --exclude='.gitignore' repo/ public/
308 - artifacts:
309 - paths:
310 - - public
311 - pages:
312 - path_prefix: "stats" #to allow for parallel deployments of the projects own page don't make the stats site the main deployment
313 - expire_in: never
314 - rules:
315 - - if: $CI_PIPELINE_SOURCE == "schedule"
316 - when: always
317 - - when: never
331 +needs:
332 + - job: verify-job
333 + artifacts: true
318 318  {{/code}}
319 319  
336 +Dadurch wird festgelegt, dass der Job die Ergebnisse des verify-job benötigt und dessen gespeicherte Artifacts verwendet.
337 +
338 +Anschließend werden die SpotBugs-Dateien in den Ordner public kopiert. GitLab Pages verwendet diesen Ordner, um die Berichte als Webseite bereitzustellen.
339 +
340 +Für jeden Branch wird eine eigene SpotBugs-Seite veröffentlicht. Dadurch könnt ihr die Ergebnisse eures aktuellen Entwicklungsbranches unabhängig von denen anderer Branches ansehen.
341 +
342 +==== 3. Wann werden die Jobs ausgeführt? ====
343 +
344 +Die Pipeline unterscheidet zwischen normalen Ausführungen, beispielsweise nach einem Push, und zeitgesteuerten Ausführungen (Schedules).
345 +
346 +Die Regeln für den verify-job und den deploy_spotbugs_pages-Job werden zentral unter .report_rules definiert und von beiden Jobs gemeinsam verwendet.
347 +
348 +Dabei
349 +
320 320  ----
321 321  
322 322  = GitLab Pages (Einsehen der erfassten Projektdaten) =
323 323  )))
324 324  
325 - Wie im vorherigen Abschnitt beschrieben, werden im Softwareprojekt mit Hilfe der Pipeline Daten erfasst. Diese Daten können dann aus GitLab eingesehen werden. Für die Gruppen-Stats könnt ihr rechts bei den Projekt Informationen das Badge für "Stat Report" anklicken. Den Jacoco Report findet ihr unter Environments -> reports -> jacoco-(Branch-Name). Neben dem JaCoCo Bericht findet ihr dort auch generierte SpotBugs Berichte. Um diese Berichte zu öffnen, drückt ihr einfach auf den "Open"-Button. Dann sollte der jeweilige Bericht in einem neuen Tab geöffnet werden.
355 + Wie im vorherigen Abschnitt beschrieben, werden im Softwareprojekt mit Hilfe der Pipeline Daten erfasst. Diese Daten können dann aus GitLab eingesehen werden. Für die Gruppen-Stats könnt ihr rechts bei den Projekt Informationen das Badge für "Stat Report" anklicken. Den Jacoco Report findet ihr unter Operate->Environments -> reports -> jacoco-<Branch-Name>. Neben dem JaCoCo Bericht findet ihr dort auch generierte SpotBugs Berichte. Um diese Berichte zu öffnen, drückt ihr einfach auf den "Open"-Button. Dann sollte der jeweilige Bericht in einem neuen Tab geöffnet werden.
326 326  
327 327  [[image:1791805037500-827.png]][[image:1791805272506-124.png||height="282" width="1112"]]
328 328