ワークフローについて

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

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

ワークフローの基本

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

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

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

ワークフローの概要

ワークフローのトリガー

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

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

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

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

ワークフロー構文

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

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

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

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

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

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

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

これらの変更をコミットして、GitHub リポジトリにプッシュします。

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

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

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

`name: learn-github-actions`	省略可能 - GitHub リポジトリの [アクション] タブに表示されるワークフローの名前。
`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@v2`	`uses` キーワードは、このステップが `actions/checkout` アクションの `v3` を実行することを指定します。これは、リポジトリをランナーにチェックアウトするアクションであり、コードに対してスクリプトまたは他のアクション (ビルドツールやテストツールなど) を実行できます。チェックアウトアクションは、リポジトリのコードに対してワークフローが実行されるたびに使用する必要があります。
`- uses: actions/setup-node@v2 with: node-version: '14'`	このステップでは、`actions/setup-node@v2` アクションを使用して、指定されたバージョン (この例では、v14 を使用) の Node.js をインストールします。これにより、`node` と `npm` の両方のコマンドが `PATH` にプッシュされます。
`- run: npm install -g bats`	`run` キーワードは、ランナーでコマンドを実行するようにジョブに指示します。この� �合は、`npm` を使用して `bats` ソフトウェアテストパッケージをインストールします。
`- run: bats -v`	最後に、ソフトウェアのバージョンを出力するパラメーターを指定して `bats` を実行します。

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

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

ワークフローの概要

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

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

で、リポジトリのメインページへ移動します。
リポジトリ名の下にある [アクション] をクリックします。
左サイドバーで、表示するワークフローをクリックします。
[Workflow runs] で、表示する実行の名前をクリックします。
[ジョブ] の下、または視覚化グラフ内で、表示するジョブをクリックします。
各ステップの結果を表示します。

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

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

GitHub には、独自の継続的インテグレーションワークフローを作成するためにカスタマイズできる事前構成済みのスターターワークフローが用意されています。 GitHub Enterprise Server はコードを分析し、自分のリポジトリに役立つ可能性のある 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 条件ステートメントを使ってこれを定義できます。

この例では、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: [12, 14, 16]
    steps:
      - uses: actions/setup-node@v2
        with:
          node-version: ${{ matrix.node }}

詳しくは、「ジョブにマトリックスを使用する」をご覧く� さい。

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

ジョブにデータベースまたはキャッシュサービスが必要な� �合は、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@v2
      - 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 配列内のすべてのラベルを持つランナーでのみ実行されます。ジョブは、指定されたラベルを持つアイドル状態のセルフホステッドランナーに優先的に移動します。

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

環境の使用

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

ワークフローについて

この記事では、次の� �目が扱われます。