Contents
GitHub リポジトリでセルフホストランナーを登録する手順
GitHub の UI から簡単にランナー登録画面へ遷移できます。ここでは必要な権限と操作の流れをまとめ、実際に画面を開くまでのステップをご紹介します。
UI から登録画面へアクセスする方法
以下の手順で「New self‑hosted runner」ボタンが表示されます。
| 手順 | 操作内容 |
|---|---|
| 1 | リポジトリページ右上の Settings をクリック |
| 2 | 左サイドメニューから Actions → Runners を選択 |
| 3 | ページ下部にある New self‑hosted runner ボタンを押す |
| 4 | OS（Linux・macOS・Windows）を選び、表示されたダウンロード URL とトークン取得コマンドを確認 |
この画面でランナー名とタグを自由に設定でき、ワークフローでは runs-on: [self-hosted, linux] のように指定できます。必要な権限はリポジトリの 管理者以上 です。
ランナー本体の取得と初期設定
最新バージョンを常に利用できるよう、ハードコードされたバージョン番号ではなく GitHub API から動的に取得する手順をご説明します。
最新リリースの取得方法（API 利用）
GitHub の公式リポジトリ actions/runner の最新リリース情報は次のコマンドで取得できます。
|
1 2 3 4 5 6 7 8 9 |
# 最新リリースタグ (例: v2.332.0) を取得 LATEST_TAG=$(curl -s https://api.github.com/repos/actions/runner/releases/latest | jq -r .tag_name) # OS とアーキテクチャに合わせたダウンロード URL を組み立て RUNNER_URL="https://github.com/actions/runner/releases/download/${LATEST_TAG}/actions-runner-linux-x64-${LATEST_TAG}.tar.gz" # ダウンロード実行 curl -L -o actions-runner.tar.gz "$RUNNER_URL" |
ポイント：
jqがインストールされていない環境はgrep/sedでも代替可能です。
設定スクリプトの実行（Linux/macOS）
ダウンロードしたアーカイブを展開し、GitHub UI で取得した Token と Repository URL を用いて設定します。
|
1 2 3 4 5 6 7 8 9 |
mkdir -p myrunner && tar xzf actions-runner.tar.gz -C myrunner cd myrunner ./config.sh \ --url https://github.com/<owner>/<repo> \ --token <TOKEN_FROM_UI> \ --name $(hostname)-runner \ --labels linux,ci |
Windows の場合は同様に config.cmd にオプションを渡します。
設定が完了するとランナーは GitHub と接続され、次のステップへ進めます。
OS 別サービス化（永続稼働）
ランナーをバックグラウンドで常駐させるには、各 OS のサービス管理機構に登録します。ここでは代表的な 3 プラットフォームの設定例を示します。
systemd (Linux) の具体的手順
svc.sh が提供するインストールコマンドで systemd ユニットを作成し、起動・自動有効化します。
|
1 2 3 4 5 6 7 8 9 10 |
# サービス登録 ./svc.sh install # 起動と永続化 sudo systemctl start actions.runner.<repo>.service sudo systemctl enable actions.runner.<repo>.service # ログ確認例 journalctl -u actions.runner.<repo>.service -f |
launchd (macOS) の具体的手順
launchd 用の plist を作成し、ロードするだけで自動起動が可能です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
cat <<'EOF' > /Library/LaunchDaemons/com.github.actions.runner.plist <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key><string>com.github.actions.runner</string> <key>ProgramArguments</key> <array> <string>/path/to/actions-runner/run.sh</string> </array> <key>RunAtLoad</key><true/> <key>KeepAlive</key><true/> <key>StandardOutPath</key><string>/var/log/github-runner.log</string> <key>StandardErrorPath</key><string>/var/log/github-runner.err</string> </dict> </plist> EOF sudo launchctl load -w /Library/LaunchDaemons/com.github.actions.runner.plist |
NSSM (Windows) の具体的手順
NSSM（Non‑Sucking Service Manager）を利用して run.cmd をサービス化します。
|
1 2 3 4 |
# NSSM がパスに通っている前提 nssm install GitHubRunner "C:\actions-runner\run.cmd" nssm start GitHubRunner # デフォルトで自動起動が有効になる |
AWS EC2 上でのベストプラクティス
大量のランナーをクラウドで運用する際は、最小権限の IAM ロール と 適切なセキュリティグループ を組み合わせることがコストとセキュリティの両面で重要です。
最小権限 IAM ポリシー例
ランナー自体は GitHub との通信にトークンを使用するため、EC2 側に必要なのはパラメータ取得とインスタンス管理だけです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ssm:GetParameter", "ec2:DescribeInstances", "ec2:TerminateInstances" ], "Resource": "*" } ] } |
上記ポリシーに加えて、AmazonEC2RoleforSSM（または AmazonSSMManagedInstanceCore）をアタッチすれば SSM エージェント経由でパラメータ取得が可能です。
セキュリティグループ設定の指針
- インバウンド：SSH (TCP 22) は管理者 IP のみ許可、HTTPS (TCP 443) は全開放（GitHub への通信はアウトバウンドで OK）。
- アウトバウンド：すべてのポート・プロトコルを許可し、GitHub API/Runner ダウンロードに必要な 443 を必ず通す。
Auto Scaling と Lambda による自動登録／削除フロー
- Auto Scaling Group (ASG) の
desired = 0で待機状態にします。 - ジョブがキュー（例：SQS）に入ったら Lambda がトリガーされ、EC2 を起動します。
- 起動後の User Data または Cloud‑Init スクリプトで
config.shを実行し、ランナーを自動登録します。 - ジョブが完了したら同じ Lambda が
./config.sh removeを呼び出して GitHub からランナーを削除し、インスタンスを終了させます。
このサイクルによりスポットインスタンスも安全に利用でき、コストを最大限抑えつつスパイク時の処理能力を確保できます。
運用・保守のポイント
ランナーは常に稼働し続けるため、トークン管理や定期的なバイナリ更新、ログ監視が欠かせません。以下に実践的な手順をまとめます。
トークンの安全な保管方法
一時的トークンは AWS Secrets Manager または Parameter Store に保存し、ランナー起動時に環境変数で参照します。
|
1 2 3 4 5 6 7 8 9 |
export RUNNER_TOKEN=$(aws secretsmanager get-secret-value \ --secret-id GitHubRunnerToken \ --query SecretString --output text) ./config.sh --url https://github.com/<owner>/<repo> \ --token "$RUNNER_TOKEN" \ --name $(hostname) \ --labels aws,ci |
Secrets Manager の自動ローテーション機能を有効にすれば、トークン更新作業も手間なく実行できます。
定期的なランナー本体のアップデートスクリプト（例：Ubuntu）
6 時間ごとに最新リリースを確認し、必要なら自動更新します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
#!/usr/bin/env bash set -euo pipefail RUNNER_DIR="/opt/github-runner" cd "$RUNNER_DIR" # 最新タグ取得 LATEST=$(curl -s https://api.github.com/repos/actions/runner/releases/latest | jq -r .tag_name) CURRENT=$("$RUNNER_DIR/run.sh" --version | awk '{print $2}') if [[ "$LATEST" != "$CURRENT" ]]; then echo "Updating runner: $CURRENT → $LATEST" ./svc.sh stop curl -L -o actions-runner.tar.gz \ "https://github.com/actions/runner/releases/download/${LATEST}/actions-runner-linux-x64-${LATEST}.tar.gz" tar xzf actions-runner.tar.gz --overwrite # 再登録は別途トークン取得ロジックを呼び出す（例: Secrets Manager） ./svc.sh install ./svc.sh start fi |
cron に 0 */6 * * * /usr/local/bin/update-runner.sh を登録しておくと、手動介入なしで常に最新状態が保たれます。
ログ監視と代表的な障害対応
| 症状 | 主な原因 | 推奨対策 |
|---|---|---|
Failed to connect to GitHub |
IAM ポリシー不足、SG のアウトバウンドブロック | ロールに ssm:GetParameter と ec2:DescribeInstances を付与、SG で TCP 443 を許可 |
Permission denied while fetching repository |
リポジトリへのアクセス権がランナーに付与されていない | Organization → Settings → Actions → Runners の「Allowed actions」設定を確認 |
| ディスク容量不足（ビルドアーティファクト残存） | /tmp や ~/.cache が肥大化 |
runner.cleanup スクリプトで定期削除、EBS サイズ自動拡張の CloudWatch アラートを設定 |
ログは systemd のジャーナル (journalctl -u actions.runner.*) と CloudWatch Logs エージェント に転送すれば、一元管理が可能です。
まとめ
- リポジトリ側登録：Settings → Actions → Runners → 「New self‑hosted runner」から開始。管理者権限が必要です。
- 最新バイナリ取得：GitHub API を利用して動的にダウンロード URL を生成し、ハードコードを排除。
- 設定スクリプト実行：
config.sh/config.cmdにトークン・URL・名前・タグを渡すだけで接続完了。 - サービス化：systemd、launchd、NSSM のいずれかで永続起動し、ログは標準出力/CloudWatch に集約。
- AWS ベストプラクティス：最小権限 IAM ロールと適切な SG、Auto Scaling + Lambda で自動登録・削除を実装し、スポットインスタンスでコスト最適化。
- 運用保守：Secrets Manager にトークン保存、定期的なバイナリ更新スクリプト、ログ監視と障害対応手順をドキュメント化しておくことで安全・安定した CI 環境が実現できます。
以上の手順に沿って設定すれば、GitHub Actions のセルフホストランナー を最新かつスケーラブルに運用できるようになります。ぜひ実際のプロジェクトで試し、得られた知見をチーム内で共有してください。