Zum Inhalt springen

Ungültige Workflow-Datei: YAML-Syntaxfehler beheben

Zuletzt aktualisiert am

Invalid workflow file bedeutet, dass GitHub die YAML-Datei Ihres Workflows nicht lesen oder prüfen konnte, weshalb überhaupt keine Jobs gestartet wurden. Der Lauf zeigt einen roten Fehler ohne Schritte, und die Meldung nennt die Datei und meist eine Zeile. Die Ursache liegt fast immer in der Einrückung, einem Wert an der falschen Stelle oder einem fehlerhaften Ausdruck. Diese Seite listet die häufigen Meldungen auf und zeigt, wie Sie sie vor dem Push erkennen.

Die genaue Meldung

Invalid workflow file: .github/workflows/ci.yml#L12
You have an error in your yaml syntax on line 12
The workflow is not valid. .github/workflows/ci.yml (Line: 14, Col: 9): Unexpected value 'run'
The workflow is not valid. .github/workflows/ci.yml (Line: 8, Col: 5): Required property is missing: runs-on

Die Zeilennummer markiert die Stelle, an der der Parser das Problem bemerkt hat. Der eigentliche Fehler steht oft in der Zeile davor.

Ursache 1: Einrückung

YAML verwendet Leerzeichen, niemals Tabulatoren. Ein Schlüssel für einen Schritt auf der falschen Ebene lässt run wie ein Geschwister von steps aussehen:

# Wrong
steps:
  - uses: actions/checkout@v4
  run: npm test

# Right
steps:
  - uses: actions/checkout@v4
  - run: npm test

Ursache 2: Doppelpunkt oder Sonderzeichen in einem unquotierten Wert

Ein Wert, der : enthält oder mit *, &, !, { oder % beginnt, muss in Anführungszeichen stehen.

# Wrong
- name: Build: release
# Right
- name: "Build: release"

Ein run:-Befehl mit Doppelpunkt ist in Ordnung, wenn er als Block geschrieben wird:

- run: |
    echo "status: ok"

Ursache 3: Ein fehlender Pflichtschlüssel oder ein unbekannter Schlüssel

Jeder Job braucht runs-on (oder uses für einen wiederverwendbaren Workflow) und steps. Schlüssel unterscheiden Groß- und Kleinschreibung, und ein Tippfehler wie step: oder runs_on: führt zum Fehler. needs: muss auf einen Job verweisen, der in derselben Datei existiert.

Ursache 4: Ausdrücke

Ein nicht geschlossenes ${{, ein überflüssiges einfaches Anführungszeichen oder eine nicht existierende Funktion lässt die ganze Datei fehlschlagen. Ausdrücke in if: können mit oder ohne ${{ }} geschrieben werden, aber ein Ausdruck, der mit ! beginnt, muss eingeschlossen werden, weil YAML ein führendes ! als Tag liest:

if: ${{ !cancelled() }}

Zeichenketten in Ausdrücken stehen in einfachen Anführungszeichen: ${{ github.ref == 'refs/heads/main' }}.

Ursache 5: Fehler beim Auslöser on:

Der Schlüssel on: akzeptiert einen Namen, eine Liste oder eine Zuordnung. Filter wie branches gehören unter das Ereignis:

on:
  push:
    branches: [main]
  pull_request:

Die Verwendung von branches und branches-ignore für dasselbe Ereignis ist nicht erlaubt.

Ursache 6: Kontext an der verwendeten Stelle nicht verfügbar

Manche Kontexte gibt es nur an bestimmten Stellen: env kann nicht in einem jobs.<id>.if verwendet werden, und secrets kann direkt in einem if-Ausdruck auf Job-Ebene nicht verwendet werden. Die Meldung lautet "Unrecognized named-value" und nennt den Kontext.

So erkennen Sie den Fehler, bevor Sie pushen

Führen Sie einen Workflow-Linter lokal aus. actionlint kennt das Schema, Shell-Snippets und Ausdrücke:

docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color

oder installieren Sie ihn mit Homebrew (brew install actionlint) und führen Sie actionlint aus. Sie können ihn auch in der CI bei Änderungen an Workflow-Dateien laufen lassen:

- uses: actions/checkout@v4
- run: bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) && ./actionlint -color

Editoren mit der YAML-Erweiterung und dem Workflow-Schema von GitHub markieren Fehler außerdem schon während der Eingabe.

So verhindern Sie den Fehler

  1. Prüfen Sie Workflow-Dateien im Editor und in einem Pre-Commit-Hook.
  2. Kopieren Sie Schritte aus funktionierenden Workflows, statt die Struktur aus dem Gedächtnis zu tippen.
  3. Halten Sie Workflows klein und lagern Sie gemeinsame Logik in wiederverwendbare Workflows oder Composite Actions aus.
  4. Prüfen Sie Workflow-Änderungen in einem Pull Request, wo der Lauf vor dem Merge sichtbar fehlschlägt.

FAQ

Warum wurde mein Workflow gar nicht ausgeführt?

Eine ungültige Datei verhindert jeden Lauf. Schauen Sie im Tab Actions nach einem fehlgeschlagenen Lauf mit dem Dateinamen oder in die Annotation am Commit.

Warum zeigt GitHub auf die falsche Zeile?

Der Parser meldet, wo er aufgegeben hat. Prüfen Sie die Zeile darüber und die Einrückung.

Kann ich YAML mit einem allgemeinen YAML-Linter validieren?

Er findet Syntaxfehler, aber keine GitHub-spezifischen Regeln wie ein fehlendes runs-on. Verwenden Sie dafür actionlint.

Meine Datei ist gültig, aber der Job wird übersprungen. Warum?

Das ist ein anderes Problem: ein Filter für Auslöser, ein Pfadfilter oder eine if:-Bedingung. Siehe Warten auf einen Runner, falls der Job hängt statt übersprungen zu werden.