Skip to main content

ワークフローについて

トリガー、構文、高度な機能など、GitHub Actions のワークフローの概要について説明します。

ワークフローについて

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

ワークフローはリポジトリ内の .github/workflows ディレクトリで定義され、リポジトリには複数のワークフローを含めることができます。各ワークフローは、それぞれ異なる一連のタスクを実行できます。 たとえば、あるワークフローでは、pull request をビルドしてテストし、別のワークフローでは、リリースが作成されるたびにアプリケーションをデプロイし、さらに別のワークフローでは、新しい issue が開かれるたびにラベルを追加することができます。

ワークフローの基本

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

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

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

ワークフローの概要

ワークフローのトリガー

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

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

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

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

ワークフロー構文

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

サンプルワークフローを作成する

GitHub Actions では、YAML 構文を使用してワークフローを定義します。 各ワークフローは、コード リポジトリ内の .github/workflows という名前のディレクトリに個別の YAML ファイルとして格納されます。

コードがプッシュされるたびに一連のコマンドを自動的にトリガーするサンプルワークフローをリポジトリに作成できます。 このワークフローでは、GitHub Actions がプッシュされたコードをチェックアウトし、bats テスト フレームワークをインストールし、bats バージョンを出力する基本コマンド bats -v を実行します。

  1. 自身のリポジトリで、ワークフロー ファイルを格納するための .github/workflows/ ディレクトリを作成します。

  2. .github/workflows/ ディレクトリで、learn-github-actions.yml という名前の新しいファイルを作成し、次のコードを追加します。

    YAML
    name: learn-github-actions
    run-name: ${{ github.actor }} is learning GitHub Actions
    on: [push]
    jobs:
      check-bats-version:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v3
          - uses: actions/setup-node@v3
            with:
              node-version: '14'
          - run: npm install -g bats
          - run: bats -v
  3. これらの変更をコミットして、GitHub リポジトリにプッシュします。

これで、新しい GitHub Actions ワークフローファイルがリポジトリにインストールされ、別のユーザがリポジトリに変更をプッシュするたびに自動的に実行されます。 ワークフローの実行履歴に関する詳細については、「ワークフロー実行時のアクティビティを見る」を参照してください。

ワークフローファイルを理解する

YAML 構文を使用してワークフローファイルを作成する方法を理解しやすくするために、このセクションでは、導入例の各行について説明します。

name: learn-github-actions
省略可能 - GitHub リポジトリの [アクション] タブに表示されるワークフローの名前。
run-name: ${{ github.actor }} is learning GitHub Actions

"省略可能" - ワークフローから生成されたワークフロー実行の名前。これは、リポジトリの [アクション] タブのワークフロー実行の一覧に表示されます。この例では、github コンテキストの式を使って、ワークフロー実行をトリガーしたアクターのユーザー名を表示します。 詳細については、GitHub Actions のワークフロー構文に関するページを参照してください。

on: [push]
このワークフローのトリガーを指定します。 この例では、push イベントを使用しているため、変更がリポジトリにプッシュされるか、pull request がマージされるたびに、ワークフロー実行がトリガーされます。 これは、すべてのブランチへのプッシュによってトリガーされます。特定のブランチ、パス、またはタブへのプッシュでのみ実行される構文の例については、「GitHub Actions のワークフロー構文」を参照してください。
jobs:
learn-github-actions ワークフローで実行されるすべてのジョブをグループ化します。
check-bats-version:
check-bats-version という名前のジョブを定義します。 子キーは、ジョブのプロパティを定義します。
  runs-on: ubuntu-latest
Ubuntu Linux ランナーの最新バージョンで実行されるようにジョブを構成します。 これは、ジョブが GitHub によってホストされている新しい仮想マシンで実行されるということです。 他のランナーを使う構文例については、「GitHub Actions のワークフロー構文」を参照してください。
  steps:
check-bats-version ジョブで実行されるすべてのステップをグループ化します。 このセクションで入れ子になった各項目は、個別のアクションまたはシェル スクリプトです。
    - uses: actions/checkout@v3
uses キーワードは、このステップが actions/checkout アクションの v3 を実行することを指定します。 これは、リポジトリをランナーにチェックアウトするアクションであり、コードに対してスクリプトまたは他のアクション (ビルド ツールやテスト ツールなど) を実行できます。 チェックアウト アクションは、リポジトリのコードに対してワークフローが実行されるたびに使用する必要があります。
    - uses: actions/setup-node@v3
      with:
        node-version: '14'
このステップでは、actions/setup-node@v3 アクションを使用して、指定されたバージョン (この例では、v14 を使用) の Node.js をインストールします。 これにより、nodenpm の両方のコマンドが PATH にプッシュされます。
    - run: npm install -g bats
run キーワードは、ランナーでコマンドを実行するようにジョブに指示します。 この場合は、npm を使用して bats ソフトウェア テスト パッケージをインストールします。
    - run: bats -v
最後に、ソフトウェアのバージョンを出力するパラメーターを指定して bats を実行します。

ワークフローファイルの視覚化

この図では、作成したワークフローファイルと、GitHub Actions コンポーネントが階層にどのように整理されているかを確認できます。 各ステップでは、単一のアクションまたはシェル スクリプトが実行されます。 ステップ 1 と 2 ではアクションが実行され、ステップ 3 と 4 ではシェル スクリプトが実行されます。 ワークフローの事前構築済みアクションの詳細については、「Finding and customizing actions」 (アクションの検出とカスタマイズ) を参照してください。

ワークフローの概要

ワークフロー実行のアクティビティの表示

ワークフローがトリガーされると、 ワークフローを実行するワークフロー実行 が作成されます。 ワークフロー実行の開始後に、実行の進行状況を示す視覚化グラフが表示され、GitHub での各ステップのアクティビティを表示できます。

  1. GitHub.com で、リポジトリのメイン ページへ移動します。

  2. リポジトリ名の下にある [アクション] をクリックします。

    リポジトリに移動

  3. 左サイドバーで、表示するワークフローをクリックします。

    ワークフロー結果のスクリーンショット

  4. [Workflow runs] で、表示する実行の名前をクリックします。

    ワークフロー実行のスクリーンショット

  5. [ジョブ] の下、または視覚化グラフ内で、表示するジョブをクリックします。

    ジョブを選択

  6. 各ステップの結果を表示します。

    ワークフロー実行の詳細のスクリーンショット

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

スターター ワークフローを使用する

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

スターター ワークフローの完全な一覧については、actions/starter-workflows リポジトリ を参照してください。

スターター ワークフローの使用と作成について詳しくは、「スターター ワークフローの使用」と「Organization のスターター ワークフローを作成する」をご覧ください。

高度なワークフロー機能

このセクションでは、より複雑なワークフローの作成に役立つ 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"

詳細については、「暗号化されたシークレット」を参照してください。

依存ジョブを作成する

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

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

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: [12, 14, 16]
    steps:
      - uses: actions/setup-node@v3
        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:10.18-jessie
    services:
      postgres:
        image: postgres
    steps:
      - name: Check out repository code
        uses: actions/checkout@v3
      - 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 ホステッド ランナーのラベルについて詳しくは、「サポートされているランナーとハードウェア リソース」をご覧ください。

ワークフローの再利用

ワークフローを公開または非公開で自分の組織と共有するために、あるワークフローを別のワークフロー内から呼び出すことができます。 このようにすると、ワークフローを再利用し、重複を回避し、ワークフローのメンテナンスを簡単にすることができます。 詳細については、「ワークフローの再利用」を参照してください。

環境の使用

保護ルールとシークレットを使って環境を構成し、ワークフローでのジョブの実行を制御できます。 ワークフロー中の各ジョブは、1つの環境を参照できます。 その環境を参照するジョブがランナーに送信される前に、その環境に設定された保護ルールはパスしなければなりません。 詳細については、「デプロイに環境を使用する」を参照してください。