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

自己ホストランナーマシンに対する要求

以下の要件を満たしているマシンをセルフホステッド ランナーとして使用できます。

• マシン上に自己ホストランナーアプリケーションをあなたがインストールして実行できること。 「サポートされているオペレーティング システム」と「サポートされているプロセッサ アーキテクチャ」を参照してください。
• そのマシンが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-bit
• Windows Server 2022 64 ビット

macOS

• macOS 11.0 (Big Sur) 以降

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

• x64 - Linux、macOS、Windows。
• ARM64 - Linux、macOS。
• ARM32 - Linux。

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

ジョブをセルフホステッド ランナーにルーティングすると、GitHub により、ジョブの runs-on ラベルやグループと一致するランナーが検索されます。

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

自動スケール

特定のラベルで受信した Webhook イベントに応答して、環境内のセルフホステッド ランナーの数を自動的に増減できます。

サポートされている自動スケール ソリューション

actions/actions-runner-controller (ARC) プロジェクトは、Kubernetes ベースのランナー オートスケーラーです。 GitHub では、デプロイするチームに Kubernetes の専門知識と経験がある場合は ARC が推奨されます。

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

自動スケーリング用のエフェメラル ランナー

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

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

環境にエフェメラル ランナーを追加するには、config.sh を使ってランナーを登録するときに --ephemeral パラメーターを指定します。 たとえば次のような点です。

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

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

または、REST API を使って、エフェメラル Just-In-Time ランナーを作成することもできます。 詳しくは、「セルフホステッド ランナーの REST API エンドポイント」をご覧ください。

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

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

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

./config.sh --url https://github.com/YOUR-ORGANIZATION --token EXAMPLE-TOKEN --disableupdate

自動更新を無効にした場合でも、自分でランナーのバージョンを定期的に更新する必要があります。 GitHub Actions に新機能がある場合は、GitHub Actions サービスとランナー ソフトウェアの 両方 で変更する必要があります。 ソフトウェアを更新しないと、GitHub Actions の新機能を利用するジョブをランナーで正しく処理できない場合があります。

自動更新を無効にする場合は、ランナーの新しいバージョンが利用可能になってから 30 日以内に、バージョンを更新する必要があります。 actions/runner リポジトリでリリースの通知にサブスクライブすることもできます。 詳しくは、「通知を設定する」をご覧ください。

ランナーの最新バージョンをインストールする方法については、最新リリースのインストール手順をご覧ください。

自動スケーリング用 Webhook

workflow_job Webhook から受信したペイロードを使って、独自の自動スケーリング環境を作成できます。 この Webhook は、リポジトリ、組織、エンタープライズのレベルで使用でき、このイベントのペイロードには、ワークフロー ジョブのライフサイクルのステージに対応する action キーが含まれています (たとえば、ジョブが queued、in_progress、completed のとき)。 その場合、これらの Webhook ペイロードに応答して独自のスケーリング オートメーションを作成する必要があります。

• workflow_job Webhook の詳細については、「Webhook のイベントとペイロード」を参照してください。
• Webhook の使用方法については、「Webhook ドキュメント」を参照してください。

認証の要件

API を使って、リポジトリと組織のセルフホステッド ランナーを登録および削除できます。 自動スケーリングの実装で、API の認証を行うには、アクセス トークンまたは GitHub アプリを使用できます。

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

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

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

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

API を使って、エンタープライズのセルフホステッド ランナーを登録および削除できます。 自動スケーリングの実装で API の認証を行うには、アクセス トークンを使用できます。

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

通信

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

GitHub Actionsランナーアプリケーションはオープンソースです。 ランナー リポジトリでイシューを投稿およびファイルできます。新しいバージョンがリリースされると、ランナー アプリケーションは 24 時間以内に自動的に更新されます。

お使いの GitHub Enterprise Server インスタンス との通信の要件

• GitHub Actions ジョブを受け入れて実行するには、セルフホステッド ランナー アプリケーションがホスト マシン上で動作している必要があります。
• GitHub Enterprise Server は、お使いの GitHub Enterprise Server インスタンス のホスト名と API サブドメインで、ランナーからの HTTP(S) 経由の受信接続を受け入れる必要があります。また、ランナーは お使いの GitHub Enterprise Server インスタンス のホスト名と API サブドメインへの HTTP(S) 経由の送信接続を許可する必要があります。
• キャッシュが機能するには、ランナーが BLOB ストレージと通信し、そこからコンテンツを直接ダウンロードできる必要があります。

GitHub.com との通信

GitHub Enterprise Server の GitHub.com アクションへの自動アクセスを有効にしている場合を除き、自己ホスト ランナーが GitHub.com に接続する必要はありません。 詳しくは、「Enterprise でのアクションの使用について」をご覧ください。

ランナーを GitHub.com に接続する場合、ホスト マシンはポート 80 経由の送信 HTTP 接続、またはポート 443 経由の HTTPS 接続を実行できる必要があります。 HTTPS 経由で確実に接続するには、GitHub Enterprise Server に対して TLS を構成します。 「TLSの設定」を参照してください。

GitHub.com アクションへの自動アクセスを有効にした場合、自己ホスト ランナーでは GitHub.com に直接接続してアクションをダウンロードします。 下記の GitHub の URL と通信するための適切なネットワークアクセスがマシンにあることを確認する必要があります。

github.com
api.github.com
codeload.github.com
pkg.actions.githubusercontent.com

github.com
api.github.com
codeload.github.com
pkg.actions.githubusercontent.com

REST API を使って GitHub に関するメタ情報 (GitHub サービスの IP アドレスやドメインの詳細など) を取得できます。 API の actions_inbound セクションは、完全修飾ドメインとワイルドカード ドメインの両方をサポートしています。 完全修飾ドメインには 1 つの完全なドメイン名 (例: example.github.com) を指定しますが、ワイルドカード ドメインは * を使って複数のサブドメインを表します (例: *.github.com)。 ワイルドカード ドメインを使うセルフホステッド ランナーの要件の例を以下に示します。 詳しくは、「メタデータ用 REST API エンドポイント」をご覧ください。

github.com
*.github.com
*.githubusercontent.com
ghcr.io

github.com
*.github.com
*.githubusercontent.com
ghcr.io