github-runner

セルフホスト型 GitHub Actions ランナー

CI/CD ワークフローのジョブを実行するマシンである、セルフホスト型 GitHub Actions ランナーをデプロイして管理します。セルフホスト型ランナーを使うと、ハードウェア、OS、ツールチェーンを自由に選べますが、環境の保守が必要になります。

使用するタイミング

トリガー	対応方法
「プロジェクトの CI を設定したい」、「[repo/org] 用にセルフホスト型ランナーをデプロイしたい」	deployment を読みます — systemd、Docker、ARC から選択します
「ランナーが登録されない／失敗し続ける」、「ランナーが 404 を返す」、「登録トークンの期限が切れた」	management を読みます — ACCESS_TOKEN と RUNNER_TOKEN、グループを確認します
「ランナーを自動的にスケールする方法」、「ランナーを自動スケーリングしたい」、「キューに入ったジョブが多すぎる」	scaling を読みます — ARC、Scale Set Client、エフェメラルを確認します
「セルフホスト型ランナーを保護したい」、「ランナーを強化したい」、「ランナーのセキュリティ」、「パブリックリポジトリのリスク」	security を読みます — パブリックリポジトリのリスク、エフェメラル、JIT、グループを確認します
「カスタムランナーイメージを作りたい」、「ランナー用の Dockerfile をビルドしたい」、「Python を備えたカスタムランナーが欲しい」	custom-images を読みます — Dockerfile、ARC のコンテナーモードを確認します
「ランナーが接続する必要のあるドメインは？」、「ランナーのファイアウォールルール」、「ランナーのネットワーク設定」	network を読みます — ファイアウォールルール、TLS、プロキシを確認します
「ルーティングにはラベルとグループのどちらを使うべき？」、「特定のランナーを指定する方法」	management を読みます — ラベルとグループのセクションを確認します
「ランナーの問題を監視／トラブルシューティングしたい」、「ランナーがオフライン」、「ランナーがジョブを取得しない」	management を読みます — 監視とトラブルシューティングのセクションを確認します

クイックリファレンス

デプロイ方法の比較

方法	複雑さ	自動スケーリング	最適な用途
systemd サービス	低	手動	単一マシン、シンプルな CI
Docker コンテナー	中	手動レプリカ	ホームラボ、小規模チーム
ARC（Kubernetes）	高	組み込み	K8s の専門知識を持つチーム
Scale Set Client	高	カスタム	Kubernetes を使わないプラットフォームチーム

重要：ACCESS_TOKEN と RUNNER_TOKEN

これはセットアップで最もよくある失敗です。myoung34/github-runner の Docker エントリーポイントは、起動時に RUNNER_TOKEN のエクスポートを解除します。これは登録解除にのみ使用されます。登録には ACCESS_TOKEN（GitHub PAT）が必要です。

トークン	用途	有効期限
ACCESS_TOKEN	登録 — GitHub API 経由で新しいトークンを生成します	長期間有効（PAT）
RUNNER_TOKEN	登録解除のみ — 初回登録には使用しません	60 分

PAT のスコープ：

• リポジトリレベル：repo
• 組織レベル：admin:org
• エンタープライズレベル：manage_runners:enterprise

ラベル戦略

デフォルトのラベル：self-hosted + OS（linux／windows／macOS）+ アーキテクチャ（x64／ARM／ARM32／ARM64）

一般的な慣例：self-hosted,<hostname>,<os>,<arch>,<project>。ワークフローでは：

runs-on: [self-hosted, linux, x64, gpu]

すべてのラベルが一致する必要があります（AND ロジック）。--no-default-labels を使うと、OS／アーキテクチャの自動ラベルを削除できます。

主な注意点

問題	原因	解決策
runner-registration への POST で 404 が発生する	ACCESS_TOKEN の代わりに RUNNER_TOKEN を使用している	PAT を使った ACCESS_TOKEN に切り替えます
「Could not find any self-hosted runner group named 'Default'」	組織で別のグループ名を使用している	gh api でグループを確認し、RUNNER_GROUP を設定します
必要ないのに「Ephemeral option is enabled」と表示される	EPHEMERAL=0 は bash では真として扱われる	EPHEMERAL=false（文字列）を使用します
docker compose down -v で認証情報が消える	名前付きボリュームが削除される	ACCESS_TOKEN を使っていれば自動的に復旧します
ランナーからホストのファイルシステムパスが見えない	ランナーが Docker コンテナー内で動作している	ワークフロー内にデプロイ設定を直接記述します
Hugo ビルド：「Go not found」	Ubuntu 20.04 のランナーに Go がない	hugo mod vendor を実行し、_vendor/ をコミットします
GHCR のプルで「unauthorized」	デプロイジョブで Docker レジストリ認証を行っていない	docker/login-action@v4 を追加します
ランナーが 14 日を超えてオフラインになっている	GitHub によって自動削除された	新しいランナーを登録します

順次ワークフロー

1. デプロイ方法を選択する

デプロイを読み、systemd、Docker、ARC、または Scale Set Client を選択します。

2. 必要なランナーのスコープを確認する

• リポジトリレベル：単一のリポジトリに限定されたランナーです。管理者アクセス権が必要です
• 組織レベル：組織内の複数のリポジトリで共有するランナーです。組織のオーナーアクセス権が必要です
• エンタープライズレベル：エンタープライズ内の複数の組織で共有するランナーです。エンタープライズアクセス権が必要です

3. ランナーを登録する

登録の流れについては、アーキテクチャのリファレンスを読みます。

4. ジョブをランナーにルーティングする

ラベルと、必要に応じてグループを指定してruns-onを使用します。管理のラベルのセクションを読みます。

5. 監視とトラブルシューティングを行う

問題が発生した場合は、管理のトラブルシューティングのセクションを読みます。

6. セキュリティとスケーリングを計画する

本番環境へのデプロイについては、セキュリティとスケーリングを読みます。

テンプレート

• templates/docker-compose.yml — myoung34/github-runnerを使用するDockerランナー
• templates/custom-runner.Dockerfile — ARC用のカスタムランナーイメージ

リファレンスファイル

ファイル	読み込むタイミング
references/architecture.md	登録の流れ、ジョブのライフサイクル、またはランナーの通信について理解する必要がある場合
references/deployment.md	systemd、Docker、ARC、または Scale Set Client を使ってランナーをデプロイする必要がある場合
references/security.md	ランナーのセキュリティ強化、一時的なランナー／JIT の設定、グループの構成が必要な場合
references/scaling.md	ARC、Scale Set Client、または Webhook 駆動の自動スケーリングが必要な場合
references/management.md	グループ、ラベル、監視、トラブルシューティング、またはクリーンアップが必要な場合
references/custom-images.md	カスタムランナーのDockerfileや、ARCのKubernetesモードが必要な場合
references/network.md	ファイアウォールルールやプロキシ設定が必要な場合、または接続の問題をトラブルシューティングする場合