Skip to Content

Changes for page GitLab Erklärungen

Last modified by Sebastian Beyer on 2026/10/13 10:43
From version 162.2
edited by Sebastian Beyer
on 2026/10/13 10:27
Change comment: Auto-saved during real-time collaboration
To version 162.3
edited by Sebastian Beyer
on 2026/10/13 10:35
Change comment: Auto-saved during real-time collaboration

Summary

Details

Page properties
Content
... ... @@ -252,11 +252,14 @@
252 252  
253 253  == Pipeline im Basisprojekt v2 ==
254 254  
255 -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.
256 256  
257 -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.
258 -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.
259 259  
259 +=== Aufbau der Pipeline ===
260 +
261 +Zunächst werden in der //.gitlab-ci.yml //die beiden Stages definiert:
262 +
260 260  {{code language="yaml"}}
261 261  stages:
262 262   - verify
... ... @@ -263,64 +263,79 @@
263 263   - deploy
264 264  {{/code}}
265 265  
266 -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"//).
267 -Im Script-Abschnitt wird dann mvn clean verify ausgeführt. Maven verify baut das Projekt und führt die Tests im Projekt aus.
268 -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:
269 269  
270 -{{code language="yaml"}}
271 -verify-job:
272 - stage: verify
273 - image: eclipse-temurin:21-jdk-alpine
274 - script:
275 - - "./mvnw clean verify"
276 - rules:
277 - - if: $CI_PIPELINE_SOURCE == "schedule"
278 - when: always
279 - allow_failure: true
280 - - when: always
281 - 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
282 282  {{/code}}
283 283  
284 -(((
285 - 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.
286 -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.
287 -Im Script-Bereich wird erst git installiert und dann die Projekete zur Erfassung und Visualisierung der Daten installiert.
288 -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.
289 -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.
290 290  
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 +
291 291  {{code language="yaml"}}
292 -deploy_stats_pages:
293 - stage: deploy
294 - image: maven:3.9.9-amazoncorretto-21-al2023
295 - variables:
296 - DEVELOPMENT_BRANCH_NAME: "development"
297 - FETCH_MULTITHREAD: "true" #options are true/false
298 - LOGLEVEL: "SHORT" #options are OFF, SHORT, LONG. Has an effect on the amount of logging when data is being added
299 - #TIME_FRAMES: "01.01.2025,31.03.2025,40,Zeitraum01;01.04.2025,31.05.2025,35" #Format start,end,minHours[,name];anotherTimeframe;anotherTimeframe;...
300 - script:
301 - - yum install -y git rsync
302 - - git clone https://gitlab.swl.informatik.uni-oldenburg.de/GA/gitlab2data.git
303 - - cd gitlab2data
304 - - mvn clean package
305 - - java -jar target/GitLab2Data-1.0-SNAPSHOT-jar-with-dependencies.jar
306 - - cd ..
307 - - mkdir -p public/data
308 - - rm -f public/data/*.json
309 - - cp gitlab2data/*.json public/data/
310 - - git clone https://gitlab.swl.informatik.uni-oldenburg.de/GA/data4visual.git repo
311 - - rsync -av --exclude='data/' --exclude='.git' --exclude='.gitignore' repo/ public/
312 - artifacts:
313 - paths:
314 - - public
315 - pages:
316 - path_prefix: "stats" #to allow for parallel deployments of the projects own page don't make the stats site the main deployment
317 - expire_in: never
318 - rules:
319 - - if: $CI_PIPELINE_SOURCE == "schedule"
320 - when: always
321 - - when: never
331 +needs:
332 + - job: verify-job
333 + artifacts: true
322 322  {{/code}}
323 323  
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 +
324 324  ----
325 325  
326 326  = GitLab Pages (Einsehen der erfassten Projektdaten) =