できない.dev

GitHub Actions の if 条件どおりにステップを実行できない

if が効かないときは、前ステップ失敗時に暗黙で付く success() 条件、文字列 'false' を真と評価する型の取り違え、! で始まる式のクオート漏れを順に疑う。
failure() / always() の明示と式の ${{ }} 囲みで大半は解決する。

公開: 更新:

症状できない
act push -W .github/workflows/ifcond.yml
…
[ifcond/demo]   ❌  Failure - Main 失敗するステップ [86.5717ms]
[ifcond/demo] ⭐ Run Main if always()
[ifcond/demo]   | B: always() なので実行される
[ifcond/demo]   ✅  Success - Main if always() [78.2239ms]

2026-09-26 に local host (Windows 11 Home, Docker 29.8.0)(Node.js 22.14.0 / npm 10.9.2) で実際に打って取った出力。検証環境の詳細

要約

GitHub Actions の if 条件が効かない原因は大きく 3 つだ。
(1) status 関数を含まない if には success() が暗黙で AND されるため、前のステップが失敗すると条件を満たしても実行されない。
(2) ! で始まる式はクオートか ${{ }} で囲まないと YAML として壊れる。
(3) 式の評価では空文字以外の文字列はすべて真なので、'false' という文字列も真になる。
式の評価規則は式の公式ドキュメント(新しいタブで開く)にまとまっている。

実行例

失敗するステップの後ろに if の無いステップ A、if: always() の B、if: failure() の C を並べて act で動かすと、A は実行行すら出ないまま飛ばされた。
走ったのは B と C の 2 つだけで、ジョブは失敗で終わった。

$ act push -W .github/workflows/ifcond.yml
[ifcond/demo] ⭐ Run Main 失敗するステップ
[ifcond/demo]   | ここで落とす
[ifcond/demo]   ❌  Failure - Main 失敗するステップ [86.5717ms]
[ifcond/demo] ⭐ Run Main if always()
[ifcond/demo]   | B: always() なので実行される
[ifcond/demo]   ✅  Success - Main if always() [78.2239ms]
[ifcond/demo] ⭐ Run Main if failure()
[ifcond/demo]   | C: failure() なので実行される
[ifcond/demo]   ✅  Success - Main if failure() [79.9384ms]
[ifcond/demo] 🏁  Job failed

— 2026-09-26 時点の出力

検証環境Node.js 22.14.0 / npm 10.9.2 / Git 2.48.1.windows.1 / 2026-09-26 検証(ほか 1 件)
検証日
実行環境
local host (Windows 11 Home, Docker 29.8.0)
バージョン
  • Node.js 22.14.0
  • npm 10.9.2
  • Git 2.48.1.windows.1
  • Docker 29.8.0

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 失敗時にも動かす条件を明示する

steps:
  - name: Notify on failure
    if: failure()
    run: ./notify.sh
  - name: Cleanup
    if: always()
    run: ./cleanup.sh

2. 式全体を ${{ }} で囲む

  - name: Build (except tags)
    if: ${{ !startsWith(github.ref, 'refs/tags/') }}
    run: npm run build

クオートで if: "!startsWith(...)" と書いても同じ効果がある。

3. 文字列は明示的に比較する

  - name: Deploy
    if: ${{ inputs.dry_run == 'false' }}
    run: ./deploy.sh

fromJSON(inputs.dry_run) で真偽値へ変換する方法もある。
型の扱いはワークフロー構文のリファレンス(新しいタブで開く)に整理されている。

よくある原因

  1. 暗黙の success() が付いている。
    if: github.event_name == 'push' のような条件だけを書くと、直前までのステップがすべて成功していることが前提条件として追加される。
  2. ! で始まる式をクオートしていない。
    YAML では行頭の ! がタグ記法と解釈されるので、if: !startsWith(...) はパースに失敗するか、意図しない動作になる。
  3. 文字列と真偽値を取り違えている。
    workflow_dispatch の inputs や outputs 経由の値は文字列で渡ることが多く、if: inputs.dry_run は値が 'false' でも真になる。
  4. job レベルの if で env を参照している。
    env コンテキストはジョブレベルの if では利用できず、Unrecognized named-value: 'env' のエラーでワークフロー自体が無効になる(ジョブがスキップされるのではない)。
  5. ref の形式が違う。
    ブランチ判定は refs/heads/ プレフィックス込みで比較する必要がある。