ワークフローについて

ワークフローとは、1 つ以上のジョブを実行する構成可能な自動化プロセスです。ワークフローは、リポジトリにチェックインされる YAML ファイルによって定義され、リポジトリ内のイベントによってトリガーされたときに実行されます。また、手動でトリガーしたり、定義されたスケジュールでトリガーしたりすることもできます。

ワークフローは、リポジトリ内の .github/workflows ディレクトリで定義されます。 1 つのリポジトリで複数のワークフローを使用でき、それぞれで次のような異なるタスクのセットを実行できます。

pull request のビルドとテスト。
リリースが作成される度にアプリケーションをデプロイ。
新しい問題が開かれる度にラベルを追加。

ワークフローの基本

ワークフローには、次の基本的なコンポーネントが含まれている必要があります。

ワークフローをトリガーする 1 つ以上の イベント 。
1 つ以上の ジョブ。それぞれが ランナー マシンで実行され、一連の 1 つ以上の _ステップ_が実行されます。
各ステップは、ユーザーが定義したスクリプトか、アクションを実行でき、ワークフローを簡略化できる再利用可能な拡張機能です。

これらの基本的なコンポーネントについて詳しくは、「GitHub Actions を理解する」をご覧ください。

ランナー 1 をトリガーしてジョブ 1 を実行し、それによってランナー 2 がジョブ 2 の実行をトリガーするイベントの図。各ジョブは複数のステップに分割されています。

ワークフローのトリガー

ワークフロートリガーは、ワークフローの実行を引き起こすイベントです。次のようなイベントがあります。

ワークフローのリポジトリ内で発生するイベント
GitHub の外部で発生し、GitHub で repository_dispatch イベントをトリガーするイベント
スケジュールされた時刻
マニュアル

たとえば、リポジトリの既定のブランチに対してプッシュが行われたときや、リリースが作成されたとき、またはイシューが開かれたときに実行するようにワークフローを構成できます。

詳しくは、「ワークフローのトリガー」をご覧ください。すべてのイベントの一覧については、「ワークフローをトリガーするイベント」をご覧ください。

ワークフロー構文

ワークフローは YAML を使って定義されます。ワークフローを作るための YAML 構文の完全な参照については、「GitHub Actions　のワークフロー構文」をご覧ください。

ワークフロー実行の再実行、取り消し、削除など、ワークフロー実行の管理について詳しくは、「ワークフローの実行と展開の管理」をご覧ください。

ワークフローテンプレートの使用

GitHub には、独自のワークフローを作成するためにそのまま使える、もしくはカスタマイズできる事前構成済みのワークフローテンプレートが用意されています。 GitHub はコードを分析し、自分のリポジトリに役立つ可能性のあるワークフローテンプレートを表示します。たとえばリポジトリにNode.jsのコードが含まれているなら、Node.jsプロジェクトのためのサジェッションが提示されます。

これらのワークフローテンプレートは、すぐに起動して実行できるように設計されており、次のようなさまざまな構成が提供されます。

これらのワークフローを、カスタムワークフローの構築の出発点として使用するか、そのまま利用します。ワークフローテンプレートの詳細な一覧は、actions/starter-workflows リポジトリで参照できます。詳しくは、「ワークフローテンプレートの使用」を参照してください。

高度なワークフロー機能

このセクションでは、より複雑なワークフローの作成に役立つ GitHub Actions のいくつかの高度な機能について簡単に説明します。

シークレットの保存

ワークフローでパスワードや証明書などの機密データを使用する場合は、これらを GitHub に シークレット として保存し、それらをワークフロー内で環境変数として使用できます。つまり、機密性の高い値をワークフローの YAML ソースに直接埋め込むことなく、ワークフローを作成して共有できます。

この例のジョブでは、既存のシークレットを環境変数として参照し、それをパラメーターとしてサンプルコマンドに送信する方法を示します。

jobs:
  example-job:
    runs-on: ubuntu-latest
    steps:
      - name: Retrieve secret
        env:
          super_secret: ${{ secrets.SUPERSECRET }}
        run: |
          example-command "$super_secret"

詳しくは、「GitHub Actions でのシークレットの使用」をご覧ください。

依存ジョブを作成する

デフォルトでは、ワークフロー内のジョブはすべて同時並行で実行されます。別のジョブが完了した後でのみ実行する必要があるジョブがある場合は、needs キーワードを使ってこの依存関係を作成できます。ジョブの 1 つが失敗すると、依存するすべてのジョブがスキップされます。ただし、ジョブを続ける必要がある場合は、if 条件ステートメントを使ってこれを定義できます。

この例では、setup、build、test ジョブが連続して実行され、build と test は、それらに先行するジョブの正常な完了に依存します。

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - run: ./setup_server.sh
  build:
    needs: setup
    runs-on: ubuntu-latest
    steps:
      - run: ./build_server.sh
  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - run: ./test_server.sh

詳しくは、「ワークフローでジョブを使用する」をご覧ください。

マトリックスを使用する

マトリックス戦略を使用すると、1 つのジョブ定義で変数を使用して、変数の組み合わせに基づく複数のジョブ実行を自動的に作成できます。たとえば、マトリックス戦略を使用して、複数バージョンの言語または複数のオペレーティングシステムでコードをテストできます。マトリックスは、配列としてビルドオプションを受け取る strategy キーワードを使って作成します。たとえば、このマトリックスは、異なるバージョンの Node.js を使って、ジョブを複数回実行します。

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node: [14, 16]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}

詳しくは、「ワークフローでのジョブのバリエーションの実行」をご覧ください。

依存関係のキャッシング

ジョブで依存関係を定期的に再利用する場合は、これらのファイルをキャッシュしてパフォーマンスを向上させることを検討できます。キャッシュが作成されると、同じリポジトリ内のすべてのワークフローで使用できるようになります。

この例では、~/.npm ディレクトリをキャッシュする方法を示します。

jobs:
  example-job:
    steps:
      - name: Cache node modules
        uses: actions/cache@v3
        env:
          cache-name: cache-node-modules
        with:
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-

詳しくは、「依存関係をキャッシュしてワークフローのスピードを上げる」をご覧ください。

データベースとサービスコンテナの利用

ジョブにデータベースまたはキャッシュサービスが必要な場合は、services キーワードを使って一時コンテナーを作成し、サービスをホストすることができます。作成されたコンテナーは、そのジョブ内のすべてのステップで利用でき、ジョブが完了すると削除されます。この例では、ジョブで services を使って postgres コンテナーを作成した後、node を使ってサービスに接続する方法を示します。

jobs:
  container-job:
    runs-on: ubuntu-latest
    container: node:20-bookworm-slim
    services:
      postgres:
        image: postgres
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Connect to PostgreSQL
        run: node client.js
        env:
          POSTGRES_HOST: postgres
          POSTGRES_PORT: 5432

詳しくは、「コンテナー化されたサービスを使用する」をご覧ください。

ラベルを使用してワークフローを転送する

特定のタイプのランナーがジョブを処理するようにしたい場合は、ラベルを使用してジョブの実行場所を制御できます。セルフホステッドランナーには、既定のラベル self-hosted 以外のラベルを割り当てることができます。その後、YAML ワークフローでこれらのラベルを参照し、ジョブが予測可能な方法でルーティングされるようにすることができます。 GitHub-ホステッドランナーには、定義済みのラベルが割り当てられます。

この例は、ワークフローがラベルを使用して必要なランナーを指定する方法を示しています。

jobs:
  example-job:
    runs-on: [self-hosted, linux, x64, gpu]

ワークフローは、runs-on 配列内のすべてのラベルを持つランナーでのみ実行されます。ジョブは、指定されたラベルを持つアイドル状態のセルフホステッドランナーに優先的に移動します。使用できるものがなく、指定されたラベルを持つ GitHub ホステッドランナーが存在する場合、ジョブは GitHub ホステッドランナーに移動します。

自己ホストランナーのラベルについて詳しくは、「セルフホストランナーとのラベルの利用」をご覧ください。

GitHub ホストランナーのラベルについて詳しくは、「GitHub ホステッドランナーの使用」をご覧ください。

ワークフローについて

この記事の内容