ワークフローについて
ワークフローは、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 構文を使用してワークフローファイルを作成する方法を理解しやすくするために、このセクションでは、導入例の各行について説明します。
|
省略可能 - GitHub リポジトリの [アクション] タブに表示されるワークフローの名前。 |
|
このワークフローのトリガーを指定します。 この例では、push イベントを使用しているため、変更がリポジトリにプッシュされるか、pull request がマージされるたびに、ワークフロー実行がトリガーされます。 これは、すべてのブランチへのプッシュによってトリガーされます。特定のブランチ、パス、またはタブへのプッシュでのみ実行される構文の例については、「GitHub Actions のワークフロー構文」を参照してく� さい。
|
|
learn-github-actions ワークフローで実行されるすべてのジョブをグループ化します。
|
|
check-bats-version という名前のジョブを定義します。 子キーは、ジョブのプロパティを定義します。
|
|
Ubuntu Linux ランナーの最新バージョンで実行されるようにジョブを構成します。 これは、ジョブが GitHub によってホストされている新しい仮想マシンで実行されるということです。 他のランナーを使う構文例については、「GitHub Actions のワークフロー構文」を参照してく� さい。 |
|
check-bats-version ジョブで実行されるすべてのステップをグループ化します。 このセクションで入れ子になった各� �目は、個別のアクションまたはシェル スクリプトです。
|
|
uses キーワードは、このステップが actions/checkout アクションの v3 を実行することを指定します。 これは、リポジトリをランナーにチェックアウトするアクションであり、コードに対してスクリプトまたは他のアクション (ビルド ツールやテスト ツールなど) を実行できます。 チェックアウト アクションは、リポジトリのコードに対してワークフローが実行されるたびに使用する必要があります。
|
|
このステップでは、actions/setup-node@v2 アクションを使用して、指定されたバージョン (この例では、v14 を使用) の Node.js をインストールします。 これにより、node と npm の両方のコマンドが PATH にプッシュされます。
|
|
run キーワードは、ランナーでコマンドを実行するようにジョブに指示します。 この� �合は、npm を使用して bats ソフトウェア テスト パッケージをインストールします。
|
|
最後に、ソフトウェアのバージョンを出力するパラメーターを指定して 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つの環境を参照できます。 その環境を参照するジョブがランナーに送信される前に、その環境に設定された保護ルールはパスしなければなりません。 詳細については、「デプロイに環境を使用する」を参照してく� さい。