ワークフローの制御

このセクションでは、ワークフローの実行を制御する流れを説明します。今までは処理を単純に直列で実行していましたが、条件によって特定のステップやジョブを実行したり、ジョブ同士の依存関係によって実行順序を制御するなど、さまざまな制御方法があります。

1. 条件分岐(if)

条件分岐は、特定の条件に一致した場合にのみ処理を実行したいときに利用する記述です。ワークフローの中で、あるステップを実行するかどうかを条件によって切り替えるための仕組みです。

1.1 条件分岐のイメージ

まず、条件の例として「ブランチが main かどうか」を判定するケースがあります。処理が始まった後、現在実行されているブランチ名を確認し、それが main であれば処理を実行し、main でなければそのステップはスキップされます。このように、条件に適合したときだけ処理が進むという流れになります。

1.2 条件分岐の記載方法

GitHub Actions では、if という項目を使って条件を記述します。

steps:
  - name: mainブランチのみデプロイ
    if: github.ref == 'refs/heads/main'
    run: echo "mainブランチへのデプロイを実行します"

  - name: mainブランチ以外の処理
    if: github.ref != 'refs/heads/main'
    run: echo "このブランチではデプロイをスキップします"

if の条件が true であればステップは実行され、false の場合はスキップされます。

ここで押さえておきたい点として、GitHub Actions の if には else や else if といった構文は存在しません。条件に合わない場合は、そのステップが実行されずにスキップされる、という動作になります。上記のように、複数の条件分岐を行いたい場合は、条件ごとにステップを分けて記述する形になります。

このように、if を使うことで、ブランチ名やイベントの種類など、さまざまな条件に応じて柔軟に処理を切り替えることができます。

2. concurrency(同時実行制御)

同時実行制御は、ワークフローが同じタイミングで重複して実行されないようにするための仕組みです。特に、本番環境へのデプロイのように「同時に複数実行されると問題になる処理」を安全に管理する場面で役立ちます。

2.1 同時実行制御のイメージ

同じグループ名を与えられたワークフローは、同時に二つ以上動くことがありません。すでに一つが実行中であれば、新しく起動されたワークフローは制御されるようになります。この仕組みにより、例えば「同じデプロイ処理が並列で走ってしまう」といった事故を防ぐことができます。

また、動作の違いとして cancel-in-progress の設定があります。

cancel-in-progress を true にすると、すでに実行中のジョブを強制的にキャンセルし、新しくキューに入ったジョブが優先的に実行されます。コードが更新され続けるような環境では、この動きが適している場合があります。

一方で、cancel-in-progress を false に設定すると、現在実行中のジョブが終わるまで新しいジョブは待機します。落ち着いた運用で、毎回の実行結果を確実に残したい場合には、この設定が向いています。

2.2 同時実行制御の記載方法

これらの制御は、concurrency というブロックで指定します。

concurrency:
  group: deploy-production
  cancel-in-progress: true

group には制御したいグループ名を、cancel-in-progress には先ほど説明した動作を設定します。この例では、deploy-production というグループで同時実行を制御し、新しいワークフローが起動された際には実行中のものをキャンセルする設定になっています。

3. needs(ジョブ間依存)

ジョブ間依存は、複数のジョブが存在するワークフローの中で、どのジョブを先に実行し、どのジョブを後から実行するかを明確にするための仕組みです。特定のジョブを、ほかのジョブが終わるまで待機させたい場合に利用します。

3.1 ジョブ間依存のイメージ

まず、needs を指定しない場合の動きを考えます。ジョブを複数並べて記述しただけでは、それぞれは独立して実行されるため、実行順序は保証されません。極端な例では、build がまだ終わっていないのに deploy が先に実行されるといった状況が起きる可能性があります。

これに対して、needs を指定すると、依存先のジョブが確実に完了するまで次のジョブは実行されません。例えば deploy のジョブに needs: build と記載すると、deploy は build というジョブが正常に終わるまで待機し、完了後に実行されます。

3.2 ジョブ間依存の記載方法

needs の後に「依存したいジョブ名」をそのまま書くことで、ジョブ間の依存関係を定義できます。

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: echo "テストを実行"

  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo "ビルドを実行"

  deploy:
    needs: [test, build]
    runs-on: ubuntu-latest
    steps:
      - run: echo "デプロイを実行"

この例では、deploy ジョブに needs: [test, build] を指定しているため、test と build の両方が正常に完了した後に deploy が実行されます。このように、複数のジョブの完了を待ち、それらがすべて成功したタイミングで次のジョブを動かすことが可能です。

ジョブ間の実行順序を制御したい場合や、特定のジョブの成功が次の処理の前提になるようなワークフローでは、needs が非常に重要な役割を果たします。

4. そのほかの制御構文

他にもいくつか制御構文がありますが、利用頻度は上記と比べると少し低くなります。ここでは、簡単な紹介に留めておきます。

4.1 matrix

同じジョブを複数のパターンで繰り返し実行するための設定です。[項目, 項目, ・・・]のようにリスト形式で定義します。

複数バージョンの言語でテストを行いたい場合や、複数 OS に対して同じジョブを実行する場合に利用します。

下記は、actions/setup-python@v6のアクションを、3.10、3.11、3.12の複数パターンで実行したい場合のサンプルです。

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]
    steps:
      - uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}

matrix で指定できる項目数の上限や、include/exclude を使った組み合わせの絞り込みなどの仕様は、GitHub公式ドキュメントのRunning variations of jobs in a workflowに記載があります。

4.2 strategy

strategy は、matrix と組み合わせて複数のジョブを実行する際の動作を制御する設定です。

代表的なものに fail-fast があります。これは、どれか一つのパターンが失敗した時に、残りの並列実行を止めるかどうかを指定するものです。すべてのパターンを最後まで実行したい場合には false を指定します。

以下の例では、Ubuntu と macOS の2つの OS で並列テストを行うものの、どちらかが失敗しても残りは停止せず最後まで実行されます。

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
    steps:
      - run: echo "テストを実行"

4.3 continue-on-error

continue-on-error は、ジョブやステップが失敗してもワークフロー全体を失敗扱いにしないための設定です。

テスト結果の比較や、特定の OS だけ一時的に問題がある時など、「失敗しても他の処理は続けたい」場合に使います。

以下の例では、一部のステップが失敗してもジョブ自体は成功した扱いとなり、後続の処理が続きます。

steps:
  - name: 実験的な処理
    run: exit 1
    continue-on-error: true

4.4 timeout-minutes

timeout-minutes は、ジョブやステップが無限に実行され続けることを防ぐための設定で、実行できる最大時間を指定します。外部 API の応答が遅い場合や、デプロイに時間がかかりすぎる可能性がある時に便利です。

以下の例では、このジョブは最大 10 分まで実行でき、時間を過ぎると強制的に停止します。

jobs:
  deploy:
    timeout-minutes: 10
    steps:
      - run: ./deploy.sh

4.5 defaults

defaults は、すべてのステップに共通する設定をまとめて記述するための仕組みです。特定のシェルを毎回書くのが面倒な場合や、すべての run ステップに共通オプションを付けたい場合に使います。以下の例では、すべての run ステップが bash を使うようになります。

defaults:
  run:
    shell: bash

jobs:
  sample:
    steps:
      - run: echo "このステップは bash で実行されます"