自動スケーリングについて
特定のラベルで受信した Webhook イベントに応答して、環境内のセルフホステッド ランナーの数を自動的に増減できます。 たとえば、queued アクティビティを含む workflow_job Webhook イベントを受信するたびに、新しいセルフホステッド ランナーを追加するオートメーションを作成できます。このイベントは、新しいジョブが処理できる状態であることを通知します。 Webhook のペイロードにはラベル データが含まれているため、ジョブが要求しているランナーの種類を識別できます。 ジョブが完了したら、workflow_job の completed アクティビティに応答してランナーを削除するオートメーションを作成できます。
推奨される自動スケーリング ソリューション
GitHub は、ランナーの自動スケーリングに使用できる 2 つのオープンソース プロジェクトを推奨し、それらと密接に連携しています。 ニーズに応じて、一方または両方のソリューションが適している可能性があります。
これらの自動スケーラーを設定する詳しい手順については、次のリポジトリをご覧ください。
- actions/actions-runner-controller - GitHub Actions のセルフホステッド ランナー用の Kubernetes コントローラー。
- philips-labs/terraform-aws-github-runner - アマゾン ウェブ サービス上のスケーラブルな GitHub Actions ランナー用の Terraform モジュール。
各ソリューションには、考慮すべき重要な特定の詳細が含まれる場合があります。
| actions-runner-controller | terraform-aws-github-runner | |
|---|---|---|
| ランタイム | Kubernetes | Linux と Windows VM |
| サポートされているクラウド | Azure、アマゾン ウェブ サービス、Google Cloud Platform、オンプレミス | アマゾン ウェブ サービス |
| ランナーをスケーリングできる場所 | Enterprise、Organization、リポジトリのレベル。 ランナー ラベルとランナー グループ別。 | Organization とリポジトリのレベル。 ランナー ラベルとランナー グループ別。 |
| ランナーをスケーリングする方法 | Webhook イベント、スケジュール、プル ベース | Webhook イベント、スケジュール (Organization レベルのランナーのみ) |
自動スケーリングにエフェメラル ランナーを使用する
GitHub は、エフェメラル セルフホステッド ランナーで自動スケーリングを実装することをお勧めします。永続的なセルフホステッド ランナーでの自動スケーリングはお勧めしません。 特定のケースでは、GitHub は、ジョブがシャットダウン中に永続的ランナーに割り当てられないことを保証できません。 エフェメラル ランナーであれば、GitHub はランナーに 1 つのジョブしか割り当てないため、これを保証できます。
この方法では、オートメーションを使ってジョブごとにクリーンな環境を提供できるため、ランナーをエフェメラル システムとして管理できます。 これは、以前のジョブから機密リソースが公開されるのを制限する役に立ち、侵害されたランナーが新しいジョブを受け取るリスクを軽減するのにも役立ちます。
環境にエフェメラル ランナーを追加するには、config.sh を使ってランナーを登録するときに --ephemeral パラメーターを指定します。 たとえば次のような点です。
./config.sh --url https://github.com/octo-org --token example-token --ephemeral
その後、ランナーが 1 つのジョブを処理すると、GitHub Actions サービスによって自動的に登録解除されます。 その場合、登録解除後にランナーをワイプする独自のオートメーションを作成できます。
注: ジョブに特定の種類のランナー用のラベルが付いていて、その種類に一致するものを使用できない場合、ジョブがキューに入れられてすぐに失敗することはありません。 そうではなく、24 時間のタイムアウト期間が切れるまで、ジョブはキューに残ります。
または、REST API を使って、エフェメラル Just-In-Time ランナーを作成することもできます。 詳しくは、「アクション」を参照してください。
セルフホステッド ランナーでランナー ソフトウェアの更新を制御する
既定では、ランナー ソフトウェアの新しいバージョンが利用可能になると、セルフホステッド ランナーは自動的にソフトウェアの更新を実行します。 コンテナーでエフェメラル ランナーを使用している場合は、新しいランナー バージョンがリリースされたときに、ソフトウェアの更新が繰り返される可能性があります。 自動更新をオフにすると、コンテナー イメージのランナー バージョンを独自のスケジュールで直接更新できます。
ソフトウェアの自動更新をオフにして、ソフトウェアの更新プログラムを自分でインストールするには、config.sh を使ってランナーを登録するときに、--disableupdate フラグを指定します。 たとえば次のような点です。
./config.sh --url https://github.com/YOUR-ORGANIZATION --token EXAMPLE-TOKEN --disableupdate
自動更新を無効にした場合でも、自分でランナーのバージョンを定期的に更新する必要があります。 GitHub Actions に新機能がある場合は、GitHub Actions サービスとランナー ソフトウェアの 両方 で変更する必要があります。 ソフトウェアを更新しないと、GitHub Actions の新機能を利用するジョブをランナーで正しく処理できない場合があります。
自動更新を無効にする場合は、ランナーの新しいバージョンが利用可能になってから 30 日以内に、バージョンを更新する必要があります。 actions/runner リポジトリでリリースの通知にサブスクライブすることもできます。 詳しくは、「通知を設定する」を参照してください。
ランナーの最新バージョンをインストールする方法については、最新リリースのインストール手順をご覧ください。
注: 30 日以内にソフトウェアを更新しないと、GitHub Actions サービスはランナーへのジョブをキューに入れなくなります。 さらに、重要なセキュリティ更新プログラムが必要な場合、GitHub Actions サービスは、更新されるまで、ランナーへのジョブをキューに入れません。
自動スケーリングに Webhook を使用する
workflow_job Webhook から受信したペイロードを使って、独自の自動スケーリング環境を作成できます。 この Webhook は、リポジトリ、Organization、Enterprise のレベルで使用でき、このイベントのペイロードには、ワークフロー ジョブのライフサイクルのステージに対応する action キーが含まれています (たとえば、ジョブが queued、in_progress、completed のとき)。 その場合、これらの Webhook ペイロードに応答して独自のスケーリング オートメーションを作成する必要があります。
workflow_jobWebhook について詳しくは、「Webhook のイベントとペイロード」をご覧ください。- Webhook の使用方法については、「webhookの作成」をご覧ください。
認証の要件
API を使って、リポジトリと Organization のセルフホステッド ランナーを登録および削除できます。 自動スケーリングの実装で、API の認証を行うには、アクセス トークンまたは GitHub アプリを使用できます。
アクセス トークンには、次のスコープが必要です。
- プライベート リポジトリの場合は、
repoスコープでアクセス トークンを使います。 - パブリック リポジトリの場合は、
public_repoスコープでアクセス トークンを使います。 - Organization の場合は、
admin:orgスコープでアクセス トークンを使います。
GitHub アプリを使って認証を行うには、次のアクセス許可を割り当てる必要があります。
- リポジトリの場合は、
administrationアクセス許可を割り当てます。 - Organization の場合は、
organization_self_hosted_runnersアクセス許可を割り当てます。
API を使って、Enterprise のセルフホステッド ランナーを登録および削除できます。 自動スケーリングの実装で API の認証を行うには、アクセス トークンを使用できます。
アクセス トークンには、manage_runners:enterprise スコープが必要です。