Im **Root deines Repos**, genau **`.gitlab-ci.yml`** (mit fuehrendem Punkt). GitLab greift sie automatisch auf. Du kannst auch unter Project Settings -> CI/CD -> General Pipelines eine externe Datei referenzieren, Konvention ist aber die Datei im Repo-Root, mit dem Rest des Codes versioniert.

Was ist der Unterschied zwischen Stages und needs?

**Stages** definieren eine harte Reihenfolge: jeder Job in Stage 1 beendet, bevor ein Job in Stage 2 startet. **needs** erlaubt diese Reihenfolge zu umgehen: ein Job mit `needs: [setup]` startet, sobald `setup` fertig ist, auch wenn andere Jobs in frueheren Stages noch laufen. Nutze `needs` fuer **Fan-out-Parallelitaet** in spaeten Stages, wo manche Pfade frueher starten koennen, als die strikte Stage-Reihenfolge erlauben wuerde.

Warum scheitert meine "needs"-Referenz in der Validierung?

Zwei haeufige Gruende. **Eins:** der Abhaengigkeits-Job ist in einer **spaeteren Stage** als dieser Job, das ist nicht erlaubt (du kannst nur Jobs referenzieren, die schon liefen). Der Builder flaggt das. **Zwei:** der Job-Name ist falsch geschrieben. Der Builder nutzt Chips, damit du nicht falsch schreiben kannst, importierst du aber bestehendes YAML, pruefe jeden `needs:`-Eintrag zeichenweise gegen die echten Job-Keys.

rules vs only/except, was sollte ich nutzen?

**rules:** ist die moderne Syntax (seit GitLab 12.3) und das, was GitLab empfiehlt. **only/except** funktioniert noch, ist aber im Maintenance-Modus: keine neuen Features. Neue Projekte sollten ausschliesslich `rules:` nutzen. Dieser Builder schreibt `rules:`. Typische Regel: `if: $CI_COMMIT_BRANCH == "main"` mit `when: on_success`, laeuft nur auf main, bei erfolgreichen Vorgaenger-Stages.

Was ist der Unterschied zwischen artifacts und cache?

**[[artifacts||Dateien an spaetere Stages weitergereicht und aus der GitLab-UI fuer konfigurierbare Zeit downloadbar]]** sind **Outputs**: von einem Job produziert, an spaetere Stages weitergereicht, fuer die in `expire_in` gesetzte Zeit aufbewahrt (Default 30 Tage), aus der GitLab-UI downloadbar. Fuer Build-Outputs, Test-Reports, Coverage. **[[cache||Dateien, die ueber Pipeline-Runs derselben Branch wiederverwendet werden, wie node_modules oder pip-Wheels]]** ist **Scratch-Space**, ueber Pipeline-Runs wiederverwendet, um Dinge zu beschleunigen: `node_modules`, `.gradle`, `.npm`. Cache hat einen Key (meist nach Branch); Artifacts werden ueber Job-Abhaengigkeit weitergereicht.

Wie funktionieren CI-Variablen?

Drei Ebenen. **Eins:** `variables:` oben in der Datei sind global, in jedem Job sichtbar. **Zwei:** `variables:` in einem Job sind auf den Job beschraenkt. **Drei:** echte Secrets (Tokens, Passwoerter) kommen in **Project Settings -> CI/CD -> Variables**, nie ins YAML. Protected Variables sind nur fuer Jobs auf protected Branches sichtbar; Masked Variables werden in Logs versteckt. In Skripten als `$NAME` oder `${NAME}` referenzieren.

Wofuer ist allow_failure gut?

**allow_failure: true** laesst einen gescheiterten Job als Warnung erscheinen, **blockt aber den Rest der Pipeline nicht**. Typische Nutzungen: optionale Linter und Security-Scanner, die du sehen, aber nicht als Deploy-Gate willst, experimentelle Jobs in fruehen Entwicklungsphasen, Jobs, die von flaky externen Services abhaengen. Kombiniert mit `when: manual` ein gutes Pattern fuer "weiche" manuelle Jobs, die optional passieren und nicht blockieren sollen.

Wie debugge ich eine scheiternde Pipeline lokal?

GitLab Runner kann einen einzelnen Job lokal laufen lassen: `gitlab-runner exec docker ` mit der Datei auf Disk. Braucht Docker und installierten Runner, reproduziert aber das exakte Runner-Verhalten ohne CI-Minuten zu verbrennen. Fuer kuerzeres Feedback **`only:` / `rules:`** nutzen, um einen temporaeren Debug-Branch zu scopen, dorthin pushen und iterieren. Debug-Regeln vor dem Merge immer entfernen.

Kann ich externe Dateien einbinden?

Ja. Das Top-Level-`include:`-Keyword zieht YAML aus anderen Dateien oder anderen Repos. Typische Patterns: `include: local: '.gitlab/templates/test.yml'`, um eine lange Pipeline in Dateien aufzuteilen, oder `include: project: 'group/templates' file: 'docker.yml'`, um zentrale Pipeline-Templates ueber viele Projekte wiederzuverwenden. Dieser Builder emittiert kein `include:` (jede Pipeline steht fuer sich), du kannst es aber manuell ergaenzen.

GitLab-CI-YAML-Builder - kostenlos

PresetsKlick, um eine Beispiel-Pipeline zu laden

Top-Level-Einstellungen

Standard-ImageWird von jedem Job genutzt, der nicht sein eigenes `image:` setzt. Z. B. `node:20-alpine`, `python:3.12`

Stages (eines pro Zeile)Reihenfolge zählt. Jeder Job muss auf eines dieser Stages verweisenGlobale Variablen (KEY=value)In jedem Job sichtbar. Secrets gehen nach Settings -> CI/CD -> Variables, nicht hierher

Jobs3 Job(s)

Job-Basics

Job-NameEinzigartig in der Datei. Wird in `needs:` und der Pipeline-UI verwendetStageMuss zu einem oben gelisteten Stages passen

Image-Override (optional)Leer lassen, um den Standard zu nutzenJob-Variablen (optional)`KEY=value`, eine pro Zeile. Nur in diesem Job sichtbarneeds (Cross-Stage-Abhängigkeiten)

Der Job startet, sobald die gelisteten Jobs fertig sind. Spätere Stages können nicht referenziert werden

allow_failure

Wenn aktiv, blockiert ein Fehlschlag nicht die Pipeline (nur Warnung)

Skripte

before_script (optional, Vorlauf-Skript)Befehle, die vor jedem script-Eintrag laufen. Ein Befehl pro ZeilescriptDie Befehle des Jobs. Ein Befehl pro Zeile. Kann Runner-Env-Variablen referenzieren

Artefakte und Cache

Artefakte: paths (eine pro Zeile)Zu behaltende Dateien/Ordner. Werden an spätere Stages weitergegebenArtefakte: expire_inLebensdauer, z. B. `1 hour`, `1 week`, `1 month`

Cache: keySchlüssel zum Teilen des Caches zwischen Pipelines. Standard: `${CI_COMMIT_REF_SLUG}`Cache: paths (eine pro Zeile)Ordner, die zwischen Pipelines erhalten bleiben, z. B. `node_modules/`, `.npm/`

Regeln

Bedingungen, wann der Job läuft. Jede Regel = `if:`-Ausdruck + `when:`-Entscheidung

.gitlab-ci.yml

Im Repo-Root speichern und committen

42 Zeilen

default:
  image: node:20-alpine

stages:
  - install
  - test
  - deploy

variables:
  CI_NODE_OPTIONS: --max-old-space-size=4096

install:
  stage: install
  script:
    - npm ci
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 hour
  cache:
    key: npm-${CI_COMMIT_REF_SLUG}
    paths:
      - .npm/
      - node_modules/

unit-test:
  stage: test
  script:
    - npm test
  cache:
    key: npm-${CI_COMMIT_REF_SLUG}
    paths:
      - .npm/
      - node_modules/

deploy:
  stage: deploy
  script:
    - npm run build
    - npm run deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Tipps

Secrets (Tokens, Passwörter) gehen immer nach Project Settings -> CI/CD -> Variables, nicht in die Datei
Cache-Key mit `${CI_COMMIT_REF_SLUG}` ergibt einen Cache pro Branch, was Cache-Poisoning verhindert
Fühlt sich die Pipeline langsam an, prüfe, ob `needs:` etwas serialisiert, das parallel laufen könnte

Was dieser Builder macht

Eine .gitlab-ci.yml lebt im Root deines GitLab-Repos und beschreibt die volle Pipeline: geordnete Stages (install, test, deploy), einzelne Jobs mit ihren Skripten, was gecacht und was als Artifact publiziert wird, und wann jeder Job tatsaechlich laeuft (nur auf main? nur bei Tags? nur wenn eine Datei sich aenderte?). Eine Datei, keine separate UI, mit dem Rest des Codes versioniert.

Dieser Builder schreibt sie fuer dich. Preset waehlen (Test + Deploy, Docker-Registry-Push, GitLab Pages), Stages und Jobs in Formularen bearbeiten, und das rechte Panel zeigt das exakte YAML, das du in `.gitlab-ci.yml` einfuegen kannst. Der Validator prueft die typischen Fallen: ein Job, der einen Job in einer spaeteren Stage braucht, ein Job, der eine nicht in `stages:` gelistete Stage referenziert, doppelte Job-Namen, Jobs ohne Script.

Alles laeuft im Browser. Kein Upload, kein Account, keine echte Pipeline wird hier gestartet. Der Output ist derselbe Text, den du von Hand schreiben wuerdest.

So benutzt du es

Ein Preset oben waehlen: Test + Deploy, Docker-Registry-Push oder GitLab Pages. Das Formular fuellt sinnvolle Defaults.

Das Default-Image setzen (von jedem Job genutzt, der es nicht ueberschreibt), die geordnete Liste der Stages und beliebige globale Variablen als `KEY=value`-Paare.

Jobs in Tabs ergaenzen. Pro Job setzen: eindeutiger Name, Stage (muss in der Stages-Liste vorkommen), optionales Image-Override, optionale Variablen und needs.

Das Script schreiben (ein Befehl pro Zeile). Optional ein before_script fuer Setup-Befehle, die mehrere Runs teilen.

artifacts setzen (Pfade und `expire_in`) fuer den Build-Output. cache mit Key und Pfaden setzen, um Wiederholungen zu beschleunigen.

rules mit `if:`-Ausdruecken ergaenzen, z. B. `$CI_COMMIT_BRANCH == "main"`. `on_success`, `always`, `manual` (braucht Klick zum Start) oder `never` waehlen.

allow_failure fuer Jobs toggeln, die die Pipeline beim Scheitern nicht blocken sollen (Linter, Security-Scanner, die advisory sind).

Im Vorschau-Panel Copy klicken oder Download zum Speichern als `.gitlab-ci.yml`, dann ins Root deines Repos committen. Der naechste Push triggert die Pipeline.

Wann das nuetzlich ist

Sieben konkrete Situationen, in denen ein GitLab-CI-Builder echte Zeit spart:

Erste Pipeline in einem neuen Projekt. "Test + Deploy" waehlen, den Test-Befehl aendern, committen. In zwei Minuten erledigt statt in der langen GitLab-Doku zu fischen.
Docker-Registry-Push an eine bestehende Pipeline anhaengen. Der Login-+-Tag-+-Push-Tanz ist eine bekannte Sequenz; der Builder schreibt sie, du fuellst nur den Image-Namen.
Deploy-Job, der nur auf main laeuft. Die `rules:`-Syntax mit `if:` ist der moderne Weg (ersetzt das alte `only:` / `except:`), und kleine Tippfehler kosten einen ganzen Pipeline-Run.
node_modules oder pip ueber Pipeline-Runs cachen. Die Cache-Stanza ist kurz, aber leicht falsch zu formatieren. Der Builder schreibt einen funktionierenden Cache mit Default-Key `$CI_COMMIT_REF_SLUG`.
Multi-Stage-Pipeline mit parallelen Jobs in test. Mehrere Jobs in der `test`-Stage laufen automatisch parallel. Der Builder macht die Struktur offensichtlich, damit du sie nicht versehentlich serialisierst.
Manueller Deploy-Gate. Die Regel des Deploy-Jobs auf `when: manual` setzen, nur ein expliziter Klick in der GitLab-UI startet den Deploy. Typisches Prod-Pattern.
GitLab-Pages-Site-Deploy. Der spezielle `pages`-Job muss als Artifact in `public/` publishen. Das "Pages Deploy"-Preset codiert die Konvention exakt.

Fragen und Antworten

GitLab CI ist GitLabs eingebautes CI/CD-System. Du legst eine Datei `.gitlab-ci.yml` ins Root deines Repos, GitLab greift sie automatisch auf, jeder Push startet die Pipeline. Jede Pipeline hat Stages (geordnete Gruppen: install, test, deploy), jede Stage hat Jobs, die parallel auf geteilten oder self-hosted Runnern laufen. Free-Tier beinhaltet GitLab-gehostete Runner mit Monatsminuten. Self-hosted-Runner sind kostenlos und unbegrenzt.

default: image: node:20-alpine stages: - install - test - deploy variables: CI_NODE_OPTIONS: --max-old-space-size=4096 install: stage: install script: - npm ci artifacts: paths: - node_modules/ expire_in: 1 hour cache: key: npm-${CI_COMMIT_REF_SLUG} paths: - .npm/ - node_modules/ unit-test: stage: test script: - npm test cache: key: npm-${CI_COMMIT_REF_SLUG} paths: - .npm/ - node_modules/ deploy: stage: deploy script: - npm run build - npm run deploy rules: - if: $CI_COMMIT_BRANCH == "main"