Mac mini GitHub Actions セルフホスト Runner 本番ガイド（launchd + CI分離｜2026）

GitHub Actions セルフホスト Runner とは（Mac mini 版）

Mac mini GitHub Actions セルフホスト Runner は、ローカルまたはクラウド Mac mini で workflow Job を実行する自前 CI 環境です。

Mac mini で Runner を動かす 5 つの利点：

• ✔ ビルドキャッシュ永続（DerivedData / CocoaPods / SPM）
• ✔ Xcode 版固定（Golden Image）
• ✔ CI コスト固定（分課金なし）
• ✔ iOS ビルド大幅短縮（ホット 5–6 分帯）
• ✔ 企業級分離（専用 ci ユーザー + Keychain 分離）

iOS CI に Mac mini セルフホスト Runner が必須な理由

GitHub ホステッド Runner の 3 つのボトルネック

結論

GitHub ホステッド = ステートレス
Mac mini Runner = 記憶ある CI

iOS CI 性能差の本質です。関連：Flutter iOS CI 最適化：28 分→9 分.

Mac mini CI Runner 本番三層アーキテクチャ

全体モデル

┌──────────────────────────────┐
│ Layer 1: launchd daemon      │  ← reliability (auto-restart / crash recovery)
├──────────────────────────────┤
│ Layer 2: ci user isolation   │  ← security (Keychain / permission boundary)
├──────────────────────────────┤
│ Layer 3: label routing       │  ← maintainability (workflow → Runner)
└──────────────────────────────┘

第 1 層 — launchd 常駐（安定性の核）

launchd = macOS の systemd。自動再起動・再起動後復帰・クラッシュ復帰・デーモン級実行。

必須 plist 3 項目：

• RunAtLoad = true — ログイン後自動起動
• KeepAlive = true — クラッシュ後自動再起動
• WorkingDirectory — 必須（オフライン最多原因）

LaunchAgents を使用（LaunchDaemons 不可）— iOS CI はコード署名にユーザー Keychain が必要。macOS 自動ログインで ci セッション復帰。

第 2 層 — CI ユーザー分離（セキュリティの核）

管理者アカウントはなぜダメ？

• sudo 可能 → 攻撃面無限
• Keychain 読取 → 証明書漏洩
• fork PR 悪意スクリプト → 全機侵害

推奨：専用 ci ユーザー

• ❌ sudo なし・管理者グループ外
• ✅ 独立 Keychain（/Users/ci/Library/Keychains/）
• ✅ _developer グループ（xcodebuild / simctl）

sudo dscl . -create /Users/ci UserShell /bin/zsh
sudo dscl . -create /Users/ci RealName "CI Runner"
sudo dscl . -create /Users/ci UniqueID 505
sudo dscl . -create /Users/ci PrimaryGroupID 20
sudo dscl . -create /Users/ci NFSHomeDirectory /Users/ci
sudo createhomedir -c -u ci
sudo passwd ci
sudo dscl . -append /Groups/_developer GroupMembership ci

第 3 層 — Runner ラベルルーティング

ラベル体系 = CI スケジューラ。三層構造推奨：

runs-on: [self-hosted, macOS, ARM64, flutter-ios, xcode-16, m4]
           ┌──────────────┐  ┌───────────────────┐  ┌──────────────┐
           │ Platform     │  │ Workload          │  │ Hardware     │
           │ self-hosted  │  │ flutter-ios       │  │ m4, 16gb     │
           │ macOS, ARM64 │  │ xcode-16          │  │ region:tokyo │
           └──────────────┘  └───────────────────┘  └──────────────┘

ラベルはAND 一致；workflow は完全一致；同一ラベル複数機 = 自動負荷分散。

Mac mini Runner 本番インストール手順

ステップ 1 — Runner インストール

# Run as ci user
mkdir -p ~/actions-runner && cd ~/actions-runner
curl -fsSL -O https://github.com/actions/runner/releases/download/v2.316.1/actions-runner-osx-arm64-2.316.1.tar.gz
tar xzf actions-runner-osx-arm64-2.316.1.tar.gz

ステップ 2 — 登録

./config.sh \
  --url https://github.com/your-org/your-repo \
  --token YOUR_REGISTRATION_TOKEN \
  --name "$(hostname -s)" \
  --labels "self-hosted,macOS,ARM64,flutter-ios,xcode-16,m4,16gb" \
  --work _work \
  --replace \
  --unattended

ステップ 3 — launchd 設定（重要）

~/Library/LaunchAgents/com.kvmboot.github-runner.plist に保存：

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0"><dict>
  <key>Label</key><string>com.kvmboot.github-runner</string>
  <key>ProgramArguments</key>
  <array><string>/Users/ci/actions-runner/run.sh</string></array>
  <key>WorkingDirectory</key><string>/Users/ci/actions-runner</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
  </dict>
  <key>StandardOutPath</key><string>/Users/ci/Library/Logs/github-runner.log</string>
  <key>StandardErrorPath</key><string>/Users/ci/Library/Logs/github-runner.err</string>
</dict></plist>

ステップ 4 — 起動

launchctl load ~/Library/LaunchAgents/com.kvmboot.github-runner.plist
launchctl list | grep github-runner
tail -f ~/Library/Logs/github-runner.log   # expect: Listening for Jobs

ネットワーク・プロキシ（出口許可）

Runner は *.github.com、api.github.com、*.actions.githubusercontent.com、objects.githubusercontent.com へ到達必須。プロキシは plist EnvironmentVariables に注入。IP 一覧：api.github.com/meta.

本番セキュリティ強化

最大リスクは公開リポの fork PR。三道の防衛：

1. リポジトリ級 Runner（組織級禁止）

リポジトリ級で登録し組織横断権限拡散を防ぐ——1 リポ侵害で全 Keychain / Secrets 露出。

2. Fork PR 保護

GitHub リポ → Settings → Actions → General で有効化：

外部協力者の fork PR ワークフローに承認を要求

fork PR がセルフホスト Runner で自動実行されないこと。詳細：クラウド Mac CI セキュリティ分離（fork PR 攻撃面）.

3. Secrets 分離

• ❌ .p12 / .env を ci ホームに置かない
• ❌ workflow に API Key 直書きしない
• ✅ GitHub Secrets + 実行時注入；証明書は Fastlane match + Keychain

concurrency:
  group: flutter-ios-${{ github.ref }}
  cancel-in-progress: true

CI 性能最適化（iOS / Flutter）

Mac mini セルフホスト Runner はローカルキャッシュ永続で iOS CI 最適化 を増幅：

キャッシュ三層

• CocoaPods（~/.cocoapods + ios/Pods）
• DerivedData（固定 -derivedDataPath）
• SPM / Flutter pub

完全戦略：iOS CI キャッシュ設計（DerivedData / CocoaPods / SPM）.

ワンクリック Runner 再構築（DR）

macOS メジャーアップグレード・Golden Image ドリフト・セキュリティ事象後、rebuild_runner.sh で約 5 分再構築：

#!/usr/bin/env zsh
set -euo pipefail
CI_USER="ci"
PLIST_DEST="/Users/$CI_USER/Library/LaunchAgents/com.kvmboot.github-runner.plist"

sudo -u "$CI_USER" launchctl unload "$PLIST_DEST" 2>/dev/null || true
sudo -u "$CI_USER" bash -c "cd /Users/$CI_USER/actions-runner && ./config.sh remove --token \$(gh api -X POST /repos/your-org/your-repo/actions/runners/remove-token --jq '.token') 2>/dev/null || true"
sudo -u "$CI_USER" zsh /Users/$CI_USER/scripts/setup_runner.sh
sudo -u "$CI_USER" launchctl load "$PLIST_DEST"
echo "[OK] Runner rebuilt."

本番就绪検証（チェックリスト）

検収前に基盤環境を確認（クラウド Mac オンボーディングチェックリスト).

レベル 1 — Runner オンライン

• ✅ GitHub UI が Idle
• ✅ launchctl list | grep github-runner で健全 PID
• ✅ ログに Listening for Jobs

レベル 2 — 空 Job

runs-on: [self-hosted, macOS, flutter-ios]

• ✅ 30 秒以内に割当（長時間キューなし）
• ✅ Runner 名と OS 版を出力

レベル 3 — ツールチェーン

xcodebuild -version    # matches Golden Image
flutter --version
pod --version

FAQ（ロングテール）

Mac mini で GitHub Actions Runner は動く？

はい。iOS CI の定番本番構成の一つ。launchd で GitHub Actions セルフホスト Runner（macOS） を長期安定運用可能。

セルフホストは GitHub ホステッドよりどれくらい速い？

iOS CI で通常 30%–60% 短縮。CocoaPods / DerivedData 永続化が主因——ホステッドは毎 Job 新規環境。

launchd と brew services の違い？

launchd は macOS システムデーモン（systemd 相当）；brew services はラッパーで非 Homebrew Runner 管理に不向き。本番は plist 直書き。

Runner オフラインの排查？

優先順位：

1. launchctl list | grep github-runner
2. plist の WorkingDirectory
3. runs-on ラベル完全一致

1 台の Mac mini で何 Runner？

16GB → 1 推奨；24GB → 1–2（軽量）。xcodebuild はメモリ逼迫——複数は concurrency 必須。