ワークフローについて
ワークフローとは、1 つ以上のジョブを実行する構成可能な自動化プロセスです。 ワークフローは、リポジトリにチェックインされる YAML ファイルによって定義され、リポジトリ内のイベントによってトリガーされたときに実行されます。また、手動でトリガーしたり、定義されたスケジュールでトリガーしたりすることもできます。
ワークフローは、リポジトリ内の .github/workflows
ディレクトリで定義されます。 1 つのリポジトリで複数のワークフローを使用でき、それぞれで次のような異なるタスクのセットを実行できます。
- pull request のビルドとテスト。
- リリースが作成される度にアプリケーションをデプロイ。
- 新しい問題が開かれる度にラベルを追加。
ワークフローの基本
ワークフローには、次の基本的なコンポーネントが含まれている必要があります。
- ワークフローをトリガーする 1 つ以上の イベント 。
- 1 つ以上の ジョブ。それぞれが ランナー マシンで実行され、一連の 1 つ以上の _ステップ_が実行されます。
- 各ステップは、ユーザーが定義したスクリプトか、アクションを実行でき、ワークフローを簡略化できる再利用可能な拡張機能です。
これらの基本的なコンポーネントについて詳しくは、「GitHub Actions を理解する」をご覧ください。
ワークフローのトリガー
ワークフロー トリガーは、ワークフローの実行を引き起こすイベントです。 次のようなイベントがあります。
- ワークフローのリポジトリ内で発生するイベント
- GitHub Enterprise Cloud の外部で発生し、GitHub Enterprise Cloud で
repository_dispatch
イベントをトリガーするイベント - スケジュールされた時刻
- マニュアル
たとえば、リポジトリの既定のブランチに対してプッシュが行われたときや、リリースが作成されたとき、またはイシューが開かれたときに実行するようにワークフローを構成できます。
詳しくは、「ワークフローのトリガー」をご覧ください。すべてのイベントの一覧については、「ワークフローをトリガーするイベント」をご覧ください。
ワークフロー構文
ワークフローは YAML を使って定義されます。 ワークフローを作るための YAML 構文の完全な説明については、「GitHub Actions のワークフロー構文」をご覧ください。
ワークフロー実行の再実行、取り消し、削除など、ワークフロー実行の管理について詳しくは、「ワークフローの実行と展開の管理」をご覧ください。
ワークフロー テンプレートの使用
GitHub には、独自のワークフローを作成するためにそのまま使える、もしくはカスタマイズできる事前構成済みのワークフロー テンプレートが用意されています。 GitHub Enterprise Cloud はコードを分析し、自分のリポジトリに役立つ可能性のあるワークフロー テンプレートを表示します。 たとえばリポジトリにNode.jsのコードが含まれているなら、Node.jsプロジェクトのためのサジェッションが提示されます。
これらのワークフロー テンプレートは、すぐに起動して実行できるように設計されており、次のようなさまざまな構成が提供されます。
- CI: 継続的インテグレーション ワークフロー
- デプロイ: デプロイ ワークフロー
- 自動化: 自動ワークフロー
- コード スキャン: Code スキャン ワークフロー
- ページ: ページ ワークフロー
これらのワークフローを、カスタム ワークフローの構築の出発点として使用するか、そのまま利用します。 ワークフロー テンプレートの詳細な一覧は、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 ホステッド ランナーの使用」をご覧ください。
ワークフローの再利用
ワークフローを公開または非公開で自分の組織と共有するために、あるワークフローを別のワークフロー内から呼び出すことができます。 このようにすると、ワークフローを再利用し、重複を回避し、ワークフローのメンテナンスを簡単にすることができます。 詳しくは、「ワークフローの再利用」を参照してください。
ワークフローのセキュリティ強化
GitHubは、ワークフローのセキュリティを強化するために使用できるセキュリティ機能が用意されています。 GitHubのビルトイン機能を使用し、実行するアクションの脆弱性に関する通知を受け取ったり、ワークフロー内のアクションを最新の状態に保つプロセスを自動化したりできます。 詳しくは、「GitHub のセキュリティ機能を使用して GitHub Actions の使用をセキュリティで保護する」を参照してください。
環境の使用
保護ルールとシークレットを使って環境を構成し、ワークフローでのジョブの実行を制御できます。 ワークフロー中の各ジョブは、1つの環境を参照できます。 その環境を参照するジョブがランナーに送信される前に、その環境に設定された保護ルールはパスしなければなりません。 詳しくは、「デプロイに環境の使用」を参照してください。