コンテンツへスキップ

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のワークフロー用スキーマを導入したエディターでは、入力中にエラーがハイライトされます。

予防方法

  1. エディターとpre-commitフックの両方で、ワークフローファイルをリントしてください。
  2. 構造を記憶から書き起こすのではなく、動作しているワークフローからステップをコピーしてください。
  3. ワークフローは小さく保ち、共通のロジックは再利用可能なワークフローや複合アクションに移してください。
  4. ワークフローの変更はプルリクエストでレビューしてください。プルリクエストでは、マージ前に実行の失敗が明確に表示されます。

よくある質問

ワークフローがまったく実行されなかったのはなぜですか?

無効なファイルがあると、どの実行も開始されません。Actionsタブで、ファイル名が示された失敗した実行を確認するか、コミット上のアノテーションを確認してください。

GitHubが間違った行を指摘するのはなぜですか?

パーサーは、解析を断念した位置を報告します。その上の行と、インデントを確認してください。

一般的なYAMLリンターでYAMLを検証できますか?

構文エラーは検出しますが、runs-on の欠落のような GitHub 固有のルールは検出できません。それらには actionlint を使用してください。

ファイルは有効なのにジョブがスキップされるのはなぜですか?

これは別の問題です。トリガーフィルター、パスフィルター、またはif:条件が原因の可能性があります。ジョブがスキップされるのではなく停止している場合は、ランナーの待機を参照してください。