Mac mini GitHub Actions Self-Hosted Runner: Production CI Guide (launchd + CI Isolation | 2026)

What is a GitHub Actions self-hosted runner (Mac mini edition)

A Mac mini GitHub Actions self-hosted runner is a self-hosted CI execution environment that runs workflow jobs on a local or cloud Mac mini instance instead of GitHub-hosted macOS runners.

Five core advantages of running a runner on Mac mini:

• ✔ Long-lived build caches (DerivedData / CocoaPods / SPM)
• ✔ Full Xcode version control (Golden Image pinning)
• ✔ Fixed CI cost (not per-minute billing)
• ✔ Significantly faster iOS builds (hot builds in the 5–6 minute range)
• ✔ Enterprise-grade security isolation (dedicated ci user + Keychain separation)

Why iOS CI must use a Mac mini self-hosted runner

Three bottlenecks of GitHub-hosted runners

Core conclusion

GitHub-hosted runner = stateless machine
Mac mini runner = CI system with memory

That is the root cause of iOS CI performance gaps. Further reading: Flutter iOS CI tuning: from 28 minutes to 9 minutes.

Production three-layer Mac mini CI runner architecture

Overall architecture model

┌──────────────────────────────┐
│ 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)
└──────────────────────────────┘

Layer 1 — launchd daemon (core stability)

launchd = macOS systemd. Key capabilities: auto-restart Runner, recover after system reboot, relaunch after crashes, run at daemon level.

Three critical plist keys (all required):

• RunAtLoad = true — auto-start after user login
• KeepAlive = true — auto-relaunch after crash
• WorkingDirectory — must be set (top cause of offline runners)

Use LaunchAgents (not LaunchDaemons)—iOS CI needs user Keychain access for code signing. Pair with macOS auto-login so the ci user session returns after reboot.

Layer 2 — CI user isolation (security core)

Why not use an admin account?

• Can sudo → attack surface expands without bound
• Keychain readable → certificates may leak
• fork PR can run malicious scripts → full machine compromise

Recommended: dedicated ci user

• ❌ no sudo, not in admin group
• ✅ separate Keychain (/Users/ci/Library/Keychains/)
• ✅ member of _developer group (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

Layer 3 — Runner label routing (CI scheduling core)

Label taxonomy = your CI scheduler. Recommended three-tier structure:

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 │
           └──────────────┘  └───────────────────┘  └──────────────┘

Labels are AND matched; workflow must match exactly; multiple machines with same labels = automatic load balancing.

Mac mini runner full install flow (production-grade)

Step 1 — Install 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

Step 2 — Register runner

./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

Step 3 — launchd daemon config (critical)

Save to ~/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>

Step 4 — Start runner

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

Network and proxy (egress allowlist)

Runner must reach: *.github.com, api.github.com, *.actions.githubusercontent.com, objects.githubusercontent.com. Inject proxy in plist EnvironmentVariables (shell export https_proxy is not inherited). Full IP ranges: api.github.com/meta.

Production security hardening

The biggest risk for self-hosted runners is fork PRs on public repos. Enable three lines of defense:

1. Repo-level runner (not org-level)

Register as a repo-level runner to avoid org-wide lateral movement—if one repo is compromised, all repos' Keychains and Secrets are exposed.

2. Fork PR protection

GitHub repo → Settings → Actions → General, enable:

Require approval for all outside collaborators (fork pull request workflows)

Ensure fork PRs do not auto-run on self-hosted runners. See also cloud Mac CI security isolation (fork PR attack surface).

3. Secrets isolation

• ❌ do not store .p12 or .env in ci home
• ❌ do not hard-code API keys in workflows
• ✅ GitHub Secrets + runtime injection; certificates via Fastlane match + Keychain

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

CI performance tuning (iOS / Flutter)

A Mac mini self-hosted runner amplifies iOS CI optimization through local cache persistence:

Three-layer cache tuning

• CocoaPods cache (~/.cocoapods + ios/Pods)
• DerivedData cache (fixed -derivedDataPath)
• SPM / Flutter pub cache

Full cache strategy in the cluster article: iOS CI cache design (DerivedData / CocoaPods / SPM).

One-click runner rebuild (disaster recovery)

After macOS major upgrades, Golden Image drift, or a security incident, use rebuild_runner.sh to rebuild in about 5 minutes:

#!/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."

Verify runner is production-ready (checklist)

Before acceptance, confirm base environment is ready (cloud Mac onboarding checklist).

Level 1 — Runner online

• ✅ GitHub UI shows Idle
• ✅ launchctl list | grep github-runner shows healthy PID
• ✅ log contains Listening for Jobs

Level 2 — Empty job

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

• ✅ job assigned within 30 seconds (no long queue)
• ✅ output shows runner name and OS version

Level 3 — Toolchain verification

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

FAQ (long-tail keywords)

Can a Mac mini run a GitHub Actions runner?

Yes—and it is one of the most common production setups for iOS CI. With launchd, a Mac mini can run a GitHub Actions self-hosted runner (macOS) environment stably over long periods.

How much faster is a self-hosted runner vs GitHub-hosted?

Typically 30%–60% faster for iOS CI, mainly from CocoaPods and DerivedData cache persistence—GitHub-hosted runners start fresh every job and cannot retain local caches.

What is the difference between launchd and brew services?

launchd is macOS's system daemon framework (systemd equivalent); brew services is only a wrapper and is unsuitable for non-Homebrew GitHub Actions runners. Production should use a hand-written plist.

How do I troubleshoot an offline runner?

Check in priority order:

1. launchctl list | grep github-runner — process state
2. plist WorkingDirectory is set
3. workflow runs-on labels exactly match runner registration

How many runners can one Mac mini host?

16GB → recommend 1; 24GB → 1–2 (light jobs). xcodebuild easily fills memory—multiple instances need concurrency limits.