GitLab Pipelines · Workshop Lektion 9 / parallel:matrix

parallel:matrix – einmal schreiben, vielfach laufen

Tests über mehrere Python-Versionen, ohne den Job zu kopieren.

Warum das zählt
Unsere Tasks-API soll auf Python 3.11, 3.12 und 3.13 laufen. Den Test-Job dreimal zu kopieren ist fehleranfällig. Eine Matrix erzeugt aus einem Job automatisch mehrere parallele Varianten – derselbe Trick für Browser, OS-Versionen oder Datenbank-Versionen.

Kurzer Rückruf

Welche Variable taugt am besten als Image-Tag?

Die Idee: ein Job, viele Wertekombinationen

parallel: matrix nimmt eine Liste von Variablen-Sätzen. Für jede Kombination erzeugt GitLab eine eigene Job-Instanz, die gleichzeitig läuft. Die Matrix-Variable kannst du überall im Job verwenden – auch im image. 

test:
  stage: test
  image: python:$PYTHON_VERSION-slim   # Matrix-Variable im Image!
  script:
    - python --version
    - pip install -r requirements.txt pytest
    - pytest -q
  parallel:
    matrix:
      - PYTHON_VERSION: ["3.11", "3.12", "3.13"]

Daraus werden drei Jobs: test: [3.11], test: [3.12], test: [3.13] – parallel, jeder im passenden Python-Image.

Mehrere Achsen = Kreuzprodukt

  parallel:
    matrix:
      - PYTHON_VERSION: ["3.12", "3.13"]
        DB: ["postgres:15", "postgres:16"]

Zwei Python-Versionen × zwei DB-Versionen = vier parallele Jobs. Die Matrix wächst schnell – ein bewusster Punkt für den Workshop.

Dein Win Eine Versionsabdeckung, die mitwächst: neue Python-Version testen? Ein Listeneintrag, kein neuer Job.

Besonderheiten & Stolperfallen

Kombinatorische Explosion Drei Achsen mit je vier Werten sind schon 64 Jobs. Das frisst Runner-Kapazität und Minuten. Matrizen klein halten – nur die Kombinationen testen, die wirklich zählen.
Jede Variante ist ein eigener Job Jede Matrix-Instanz hat eigenes Log, eigene Artifacts, eigenen Erfolg/Fehler. Du siehst sofort, welche Kombination rot ist – nicht nur „der Test-Job".
Mit needs auf einzelne Instanzen zeigen Ein späterer Job kann gezielt von einer Matrix-Variante abhängen, z. B. needs: [{ job: test, parallel: { matrix: [{ PYTHON_VERSION: "3.13" }] } }]. (Mehr zu needs in Lektion 11.)
Runner-Kapazität ist endlich „Parallel" heisst nur parallel, wenn genug Runner frei sind. Sonst stehen Instanzen in der Warteschlange – die Matrix wird nicht schneller als die verfügbare Kapazität.

Übung für Teilnehmende

Übung 1 · Rechnen

Frage: PYTHON_VERSION hat 3 Werte, OS hat 2 Werte in derselben Matrix-Zeile. Wie viele Jobs entstehen?

Lösung anzeigen

3 × 2 = 6 parallele Jobs (Kreuzprodukt aller Werte einer Matrix-Zeile).

Übung 2 · Selbst schreiben

Aufgabe: Baue eine Matrix, die pytest für Python 3.12 und 3.13 ausführt und die Version im Image verwendet.

Lösung anzeigen 
test:
  image: python:$PY-slim
  script: [pip install pytest, pytest -q]
  parallel:
    matrix:
      - PY: ["3.12", "3.13"]
Übung 3 · Abwägen

Frage: Jemand will 5 Python- × 4 DB- × 3 OS-Versionen testen. Was ist das Problem und was wäre pragmatisch?

Lösung anzeigen

5×4×3 = 60 Jobs – teuer und langsam. Pragmatisch: alle Python-Versionen gegen eine DB/OS testen und nur die wichtigste Python-Version gegen die DB/OS-Varianten – nicht das volle Kreuzprodukt.

Kurz prüfen (aus dem Kopf)

Was erzeugt parallel: matrix aus einem Job?

Was ist die Hauptgefahr grosser Matrizen?

Primärquelle zum Lesen GitLab Docs – parallel:matrix.
Frag deinen Teacher. Unklar, wie needs auf eine einzelne Matrix-Instanz zeigt? Frag im Chat.
← Lektion 8 Lektion 10 · Environments & Deployments →