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
- Prüfen Sie Workflow-Dateien im Editor und in einem Pre-Commit-Hook.
- Kopieren Sie Schritte aus funktionierenden Workflows, statt die Struktur aus dem Gedächtnis zu tippen.
- Halten Sie Workflows klein und lagern Sie gemeinsame Logik in wiederverwendbare Workflows oder Composite Actions aus.
- 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.
Verwandt
- GitHub App darf Workflow nicht aktualisieren: LösungBehebung von „refusing to allow a GitHub App to create or update workflow without workflows permission“: PAT oder App-Token mit Schreibrecht nutzen.
- Was ist ein wiederverwendbarer Workflow in GitHub Actions?Ein wiederverwendbarer Workflow ist ein GitHub-Actions-Workflow, den andere Workflows mit Inputs und Secrets aufrufen. So funktioniert workflow_call.
- Was ist workflow_dispatch in GitHub Actions?workflow_dispatch ist der GitHub-Actions-Trigger, mit dem Sie einen Workflow manuell mit Inputs starten. Syntax, CLI- und API-Nutzung sowie Fallstricke.
- Cache Service Responded With 429: So beheben Sie den FehlerFix "Failed to restore: Cache service responded with 429" in GitHub Actions: zu viele Cache-Anfragen. actions/cache aktualisieren, einmal wiederherstellen, einmal speichern.