Invalid Workflow File: YAML構文エラーの修正方法
最終更新:
Invalid workflow fileは、GitHubがワークフローのYAMLを解析または検証できなかったため、ジョブが一切実行されなかったことを意味します。実行結果には失敗を示す赤いマークが表示され、ステップは表示されず、メッセージにはファイル名と、通常は行番号が含まれます。原因のほとんどは、インデントの誤り、値の配置ミス、または不正な式です。このページでは、よくあるメッセージと、プッシュ前にそれらを検出する方法を説明します。
表示される正確なメッセージ
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
行番号は、パーサーが問題に気付いた位置を示します。実際の誤りは、その前の行にあることが多いです。
原因1:インデント
YAMLではタブを使わず、常にスペースを使用します。ステップのキーの深さが誤っていると、runがstepsと同じ階層のキーとして扱われてしまいます。
# Wrong
steps:
- uses: actions/checkout@v4
run: npm test
# Right
steps:
- uses: actions/checkout@v4
- run: npm test
原因2:引用符で囲んでいない値の中のコロンや特殊文字
: を含む値や、*、&、!、{、%で始まる値は、引用符で囲む必要があります。
# Wrong
- name: Build: release
# Right
- name: "Build: release"
コロンを含むrun:のコマンドは、ブロック形式で記述すれば問題ありません。
- run: |
echo "status: ok"
原因3:必須キーの欠落または不明なキー
各ジョブにはruns-on(再利用可能なワークフローの場合はuses)とstepsが必要です。キーは大文字と小文字を区別し、step:やruns_on:のようなタイプミスがあると失敗します。needs:には、同じファイル内に存在するジョブ名を指定する必要があります。
原因4:式
閉じられていない${{、余分な単一引用符、または存在しない関数があると、ファイル全体が失敗します。if:内の式は${{ }}の有無のどちらでも記述できますが、!で始まる式は、YAMLが先頭の!をタグとして解釈するため、必ずラップする必要があります。
if: ${{ !cancelled() }}
式内の文字列には単一引用符を使用します。例:${{ github.ref == 'refs/heads/main' }}。
原因5:on:トリガーの誤り
on:キーには、名前、リスト、またはマップを指定できます。branchesなどのフィルターは、イベントの下に記述します。
on:
push:
branches: [main]
pull_request:
同じイベントに対してbranchesとbranches-ignoreを併用することはできません。
原因6:使用箇所で利用できないコンテキスト
一部のコンテキストは特定の場所でのみ利用できます。たとえば、envはjobs.<id>.ifでは使用できず、secretsはジョブレベルのif式で直接使用できません。エラーメッセージには「Unrecognized named-value」と表示され、該当するコンテキスト名が示されます。
プッシュ前に検出する
ローカルでワークフローのリンターを実行してください。actionlintは、スキーマ、シェルのスニペット、式を理解します。
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
または、Homebrewでインストール(brew install actionlint)し、actionlintを実行してください。ワークフローファイルの変更時にCIで実行することもできます。
- uses: actions/checkout@v4
- run: bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash) && ./actionlint -color
YAML拡張機能とGitHubのワークフロー用スキーマを導入したエディターでは、入力中にエラーがハイライトされます。
予防方法
- エディターとpre-commitフックの両方で、ワークフローファイルをリントしてください。
- 構造を記憶から書き起こすのではなく、動作しているワークフローからステップをコピーしてください。
- ワークフローは小さく保ち、共通のロジックは再利用可能なワークフローや複合アクションに移してください。
- ワークフローの変更はプルリクエストでレビューしてください。プルリクエストでは、マージ前に実行の失敗が明確に表示されます。
よくある質問
ワークフローがまったく実行されなかったのはなぜですか?
無効なファイルがあると、どの実行も開始されません。Actionsタブで、ファイル名が示された失敗した実行を確認するか、コミット上のアノテーションを確認してください。
GitHubが間違った行を指摘するのはなぜですか?
パーサーは、解析を断念した位置を報告します。その上の行と、インデントを確認してください。
一般的なYAMLリンターでYAMLを検証できますか?
構文エラーは検出しますが、runs-on の欠落のような GitHub 固有のルールは検出できません。それらには actionlint を使用してください。
ファイルは有効なのにジョブがスキップされるのはなぜですか?
これは別の問題です。トリガーフィルター、パスフィルター、またはif:条件が原因の可能性があります。ジョブがスキップされるのではなく停止している場合は、ランナーの待機を参照してください。
関連記事
- GitHub Appによるワークフローの更新を拒否される:修正方法「refusing to allow a GitHub App to create or update workflow without workflows permission」の修正方法:ワークフローへの書き込み権限を持つPATまたはAppトークンを使用してください。
- GitHub Actionsの再利用可能なワークフローとは再利用可能なワークフローとは、他のワークフローが入力とシークレットを渡して呼び出せるGitHub Actionsのワークフローです。workflow_callの構文と、よくある誤りを学びましょう。
- GitHub Actionsのworkflow_dispatchとはworkflow_dispatchは、入力を指定してワークフローを手動で開始できるGitHub Actionsのトリガーです。構文、CLIやAPIでの利用方法、注意点を学びましょう。
- Cache Service Responded With 429: 修正方法GitHub Actions の「Failed to restore: Cache service responded with 429」を修正します。キャッシュへのリクエストが多すぎる場合の対処法です。actions/cache を更新し、復元は何度行っても構いませんが、保存は一度だけにしてください。