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

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

この記事の内容

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

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

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

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

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

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

自動スケール

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

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

GitHub ホストランナーは、本質的にニーズに基づいて自動スケーリングされます。 GitHub ホストランナーは、自動スケール ソリューションの開発または実装に対する低メンテナンスでコスト効率の高い代替手段となる可能性があります。 詳しくは、「GitHub ホステッド ランナー」をご覧ください。

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

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

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

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

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

警告

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

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

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

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

メモ

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

または、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 リポジトリでリリースの通知にサブスクライブすることもできます。 詳しくは、「通知を設定する」をご覧ください。

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

警告

メジャー リリース、マイナー リリース、パッチ リリースなどソフトウェアに対してリリースされたすべての更新プログラムは利用可能な更新プログラムと見なされます。 30 日以内にソフトウェアを更新しないと、GitHub Actions サービスはランナーへのジョブをキューに入れなくなります。 さらに、重要なセキュリティ更新プログラムが必要な場合、GitHub Actions サービスは、更新されるまで、ランナーへのジョブをキューに入れません。

自動スケーリング用 Webhook

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

認証の要件

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

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

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

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

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

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

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

通信

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

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

GitHub との通信の要件

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

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

メモ

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

重要な操作に必要:

Shell
github.com
api.github.com
*.actions.githubusercontent.com

ダウンロード アクションに必要:

Shell
codeload.github.com
pkg.actions.githubusercontent.com

変更できないアクションの公開に必要:

Shell
ghcr.io

ジョブサマリー、ログ、ワークフロー アーティファクトのアップロード/ダウンロードに必要:

Shell
results-receiver.actions.githubusercontent.com
*.blob.core.windows.net

ランナー バージョンの更新に必要:

Shell
objects.githubusercontent.com
objects-origin.githubusercontent.com
github-releases.githubusercontent.com
github-registry-files.githubusercontent.com

OIDC トークンを取得するために必要:

Shell
*.actions.githubusercontent.com

パッケージまたはコンテナーを GitHub パッケージにダウンロードまたは発行するために必要です。

Shell
*.pkg.github.com
pkg-containers.githubusercontent.com
ghcr.io

Git Large File Storage に必要

Shell
github-cloud.githubusercontent.com
github-cloud.s3.amazonaws.com

Dependabot updates のジョブに必要です

Shell
dependabot-actions.githubapp.com

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

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