セルフホステッド ランナー リファレンス

セルフホステッド ランナーの設定と使用について説明します。

この記事で

セルフホステッド ランナーマシンに対する要求

以下の要求を満たしていれば、コンピューターをセルフホステッド ランナーとして使用できます。

  • マシン上にセルフホステッド ランナーアプリケーションをあなたがインストールして実行できること。 「サポートされているオペレーティング システム」および「サポートされているプロセッサ アーキテクチャ」を参照してください。
  • そのマシンがGitHub Actionsと通信できる。
  • そのマシンが、実行しようとしている種類のワークフローに対して十分なハードウェアリソースを持っていること。 セルフホステッド ランナーアプリケーションそのものは、最小限のリソースしか必要としません。
  • Dockerコンテナアクションあるいはサービスコンテナを使うワークフローを実行したいなら、Linuxのマシンを使い、Dockerがインストールされていなければなりません。

サポートされるオペレーティング システム

Linux

  • Red Hat Enterprise Linux 8 以降
  • CentOS 8 以降
  • Oracle Linux 8 以降
  • Fedora 29以降
  • Debian 10 以降
  • Ubuntu 20.04 以降
  • Linux Mint 20 以降
  • openSUSE 15.2 以降
  • SUSE Enterprise Linux (SLES) 15 SP2以降

Windows

  • Windows 10 (64 ビット)
  • Windows 11 64 ビット
  • Windows Server 2016 64 ビット
  • Windows Server 2019 64 ビット
  • Windows Server 2022 64 ビット

macOS

  • macOS 11.0 (Big Sur) 以降

サポートされているプロセッサ アーキテクチャ

  •         `x64` – Linux、macOS、Windows。

  •         `ARM64` – Linux、macOS、Windows (現在は パブリック プレビュー 段階)。

  •         `ARM32` – Linux。

セルフホステッド ランナーのルーティングの優先順位

ジョブをセルフホステッド ランナーにルーティングする際に、GitHub はジョブの runs-on ラベルおよびグループと一致するランナーを探します。

  • GitHub がジョブの runs-on ラベルおよびグループと一致するオンラインでアイドルのランナーを見つけると、ジョブがそのランナーに割り当てられ、送信されます。
    • 割り当てられたジョブをランナーが 60 秒以内に取得しない場合、新しいランナーが受け入れることができるように、ジョブはキューに再格納されます。
  • GitHub がジョブの runs-on ラベルおよびグループと一致するオンラインでアイドルのランナーを見つけられない場合、ランナーがオンラインになるまで、ジョブはキューに格納されたままになります。
  • 24時間以上にわたってキューに残っていたジョブは失敗します。

自動スケール

自動スケールを使用すると、必要に応じてセルフホステッド ランナーの数を動的に調整できます。 これにより、リソース使用率を最適化し、ピーク時に十分なランナー容量を確保しながら、アクティビティが少ない期間中のコストを削減できます。 セルフホステッド ランナーの自動スケールを実装するには、複雑さ、信頼性、応答性の点でトレードオフが異なる複数の方法があります。

Actions Runner Controller

GitHubホストランナーは、本質的にニーズに基づいて自動スケーリングします。 GitHubホストランナーは、自動スケール ソリューションの開発または実装に代わる、メンテナンスが少ないコスト効率の高い方法です。 詳しくは、「GitHub ホステッド ランナー」をご覧ください。

Actions Runner Controller(ARC) は、GitHubのスケール セット API と、セルフホステッド ランナーの自動スケーリングに推奨される Kubernetes ベースのソリューションの参照実装です。 ARC は、Kubernetes 環境で GitHub Actions を実行しているチーム向けに、完全な実稼働対応の自動スケール ソリューションを提供します。

GitHub は、Kubernetes インフラストラクチャを持つ組織と、Kubernetes の専門知識を持つチームに ARC を推奨します。 ARC は、プロビジョニングからジョブの実行、クリーンアップまで、クラスター内のランナーの完全なライフサイクルを処理します。

詳細については、「アクション ランナー コントローラー」および「Actions ランナー コントローラーのサポート」を参照してください。

GitHub Actions ランナースケールセットクライアント

GitHub Actions Runner Scale Set Client は、プラットフォーム チーム、インテグレーター、インフラストラクチャ プロバイダーが、Windows、Linux、macOS プラットフォームをサポートする VM、コンテナー、オンプレミス インフラストラクチャ、クラウド サービス全体の GitHub Actions ランナー用のカスタム自動スケール ソリューションを構築できるようにするスタンドアロンの Go ベースのモジュールです。

クライアントは、 GitHub スケール セットの API 対話を調整しながら、インフラストラクチャのプロビジョニングを任せることができます。 ランナーの作成方法、スケーリング方法、破棄方法を定義し、柔軟なジョブ ルーティングとターゲット設定のために複数のラベルを持つランナーを構成します。 これにより、組織はランナー のライフサイクル管理と、ジョブ実行のためのリアルタイム テレメトリをきめ細かく制御できます。

クライアントは、基本的な構成ですぐに使用できるように設計されているため、チームは自動スケールをすばやく実装できます。 ただし、その真の力は柔軟性にあります。クライアントは、各組織の特定のインフラストラクチャ要件、コンプライアンスの制約、運用ワークフローを満たすように拡張およびカスタマイズされるように構築されています。 単純なスケーリング ロジックが必要な場合でも、複雑なマルチ環境プロビジョニング戦略が必要な場合でも、クライアントはニーズに適応します。

GitHub Actions ランナー スケール セット クライアントはオープンソースプロジェクトです。 actions/scaleset リポジトリには、完全なソース コード、包括的なドキュメント、および開始に役立つ実用的な例が含まれています。 実装ガイド、さまざまなインフラストラクチャ シナリオのサンプル構成、およびクライアントをさまざまなプロビジョニング システムと統合する方法を示す参照アーキテクチャがあります。 リポジトリには、クライアントの拡張や自動スケール パターンのコミュニティとの共有に関心があるチーム向けの投稿ガイドラインも含まれています。

          **メモ：** Runner Scale Set Client はActions Runner Controller (ARC) に代わるものではありません。これは、スケール セット API の参照実装と、ランナーの自動スケールに推奨される Kubernetes ソリューションのままです。 代わりに、クライアントは、Kubernetes の外部でカスタム自動スケール ソリューションを構築するために、同じスケール セット API とやり取りするための補完的なツールです。

自動スケール対象のエフェメラル ランナー

GitHub は、エフェメラル セルフホステッド ランナーで自動スケーリングを実装することをお勧めします。永続的なセルフホステッド ランナーでの自動スケーリングはお勧めしません。 特定のケースでは、GitHub は、ジョブがシャットダウン中に永続的ランナーに割り当てられないことを保証できません。 エフェメラル ランナーであれば、GitHub はランナーに 1 つのジョブしか割り当てないため、これを保証できます。

この方法では、オートメーションを使ってジョブごとにクリーンな環境を提供できるため、ランナーをエフェメラル システムとして管理できます。 これは、以前のジョブから機密リソースが公開されるのを制限する役に立ち、侵害されたランナーが新しいジョブを受け取るリスクを軽減するのにも役立ちます。

警告

エフェメラル ランナーのランナー アプリケーション ログ ファイルは、トラブルシューティングや診断のために外部ログ ストレージ ソリューションに転送する必要があります。 エフェメラルランナーのデプロイには必須ではありませんが、GitHub では、本番環境でエフェメラル ランナーの自動スケール ソリューションを導入する前に、ランナー ログが外部に転送されて保存されるようにすることを推奨しています。 詳しくは、「自己ホストランナーのモニタリングとトラブルシューティング」をご覧ください。

環境にエフェメラル ランナーを追加するには、--ephemeral を使ってランナーを登録するときに config.sh パラメーターを指定します。 次に例を示します。

./config.sh --url https://github.com/octo-org --token example-token --ephemeral

その後、ランナーが 1 つのジョブを処理すると、GitHub Actions サービスによって自動的に登録解除されます。 その場合、登録解除後にランナーをワイプする独自のオートメーションを作成できます。

メモ

ジョブに特定の種類のランナー用のラベルが付いていて、そのタイプに一致するものを使用できない場合、ジョブがキューに入れられてすぐに失敗することはありません。 そうではなく、24 時間のタイムアウト期間が切れるまで、ジョブはキューに残ります。

あるいは、REST API を使用して、エフェメラルなジャストインタイム ランナーを作成することもできます。 詳しくは、「セルフホステッド ランナーの REST API エンドポイント」をご覧ください。

セルフホステッド ランナーのランナー ソフトウェアの更新

既定では、ランナー ソフトウェアの新しいバージョンが利用可能になると、セルフホステッド ランナーは自動的にソフトウェアの更新を実行します。 コンテナーでエフェメラル ランナーを使用している場合は、新しいランナー バージョンがリリースされたときに、ソフトウェアの更新が繰り返される可能性があります。 自動更新をオフにすると、コンテナー イメージのランナー バージョンを独自のスケジュールで直接更新できます。

ソフトウェアの自動更新をオフにして、ソフトウェアの更新プログラムを自分でインストールするには、--disableupdate を使ってランナーを登録するときに、config.sh フラグを指定します。 次に例を示します。

./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`
          ](/webhooks-and-events/webhooks/webhook-events-and-payloads#workflow_job) Webhook から受信したペイロードを使って、独自の自動スケール環境を作成できます。 この Webhook は、リポジトリ、Organization、Enterprise のレベルで使用でき、このイベントのペイロードには、ワークフロー ジョブのライフサイクルのステージに対応する `action` キーが含まれています (たとえば、ジョブが `queued`、`in_progress`、`completed` のとき)。 その場合、これらの Webhook ペイロードに応答して独自のスケーリング オートメーションを作成する必要があります。

* workflow_job Webhook の詳細については、「Webhook のイベントとペイロード」を参照してください。

          **メモ：** このアプローチは、スケーリングの決定を行うために Webhook 配信のタイムラインに依存します。これにより、遅延と信頼性の問題が発生する可能性があります。 大規模なボリューム自動スケール のシナリオでは、アクション コントローラーまたはスケール セット クライアントの使用を検討してください。

認証の要件

          [API](/rest/actions/self-hosted-runners) を使って、リポジトリと Organization のセルフホステッド ランナーを登録および削除できます。 自動スケーリングの実装で、API の認証を行うには、アクセス トークンまたは GitHub アプリを使用できます。

アクセス トークンには、次のスコープが必要です。

  • プライベート リポジトリの場合は、repo スコープでアクセス トークンを使います。
  • パブリック リポジトリの場合は、public_repo スコープでアクセス トークンを使います。
  • Organizationは、admin:org スコープでアクセス トークンを使います。

GitHub アプリを使って認証を行うには、次のアクセス許可を割り当てる必要があります。

  • リポジトリの場合は、administration アクセス許可を割り当てます。

  • Organizationは、organization_self_hosted_runners アクセス許可を割り当てます。

            [API](/rest/actions/self-hosted-runners) を使って、Enterprise のセルフホステッド ランナーを登録および削除できます。 自動スケーリングの実装で API の認証を行うには、アクセス トークンを使用できます。

アクセス トークンには、manage_runners:enterprise スコープが必要です。

Communication

セルフホステッド ランナーは、ジョブの割り当てを受け取り、新しいバージョンのランナー アプリケーションをダウンロードするために、GitHub に接続します。

GitHub Actionsランナーアプリケーションはオープンソースです。 ランナー リポジトリでイシューを投稿およびファイルできます。 新しいバージョンがリリースされると、ランナー アプリケーションでは、ランナーにジョブが割り当てられたとき、またはジョブが割り当てられなかった場合はリリースから一週間以内に、それ自体を自動的に更新します。

GitHub との通信の要件

  • GitHub Actions ジョブを受け入れて実行するには、ホスト マシン上でセルフホステッド ランナー アプリケーションが実行されている必要があります。
  • ホスト マシンには、アップロードとダウンロードの速度が 70 キロビット/秒以上である適切なネットワーク アクセスが必要です。
  • ホスト マシンは、ポート 443 経由で送信 HTTPS 接続ができる必要があります。
  • セルフホステッド ランナーに割り当てられたワークフローの機能に応じて、ホスト マシンは以下に示す GitHub ドメインと通信できる必要があります。

機能別のアクセス可能なドメイン

メモ

一覧表示されているドメインの一部は、CNAME レコードを使用して構成されます。 ファイアウォールによっては、すべての CNAME レコードに対して規則を再帰的に追加する必要がある場合があります。 CNAME レコードは今後変更される可能性があり、一覧表示されているドメインのみが一定のままであることに注意してください。

データ再利用可能アクション.ランナー本質的コミュニケーション %}

さらに、ワークフローで他のネットワーク リソースへのアクセスが必要になる場合があります。

GitHub OrganizationあるいはEnterpriseアカウントでIPアドレス許可リストを使うなら、セルフホステッド ランナーのIPアドレスを許可リストに追加しなければなりません。 GitHub Enterprise Cloud ドキュメントの「Organization に対する許可 IP アドレスを管理する」または「Enterprise でセキュリティ設定のポリシーを適用する」を参照してください。