Set up your Mac mini as a self-hosted CI runner (GitHub Actions, GitLab, Jenkins, Buildkite)

Register your dedicated mini as a macOS build runner and keep it running as a service, so your queue is always covered.

A dedicated Mac mini makes an excellent macOS CI runner: warm caches, a pinned toolchain, one flat price, and it's yours between builds. This guide gets it registered and running as a background service on the big four CI systems. Do the first-hour setup first.

Prerequisites (all runners)

# run on: your Mac mini
xcode-select --install                 # command line tools
sudo xcodebuild -license accept        # accept the Xcode license
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install whatever your builds need — xcbeautify, fastlane, swiftlint, CocoaPods — now, so the runner starts warm.

GitHub Actions

In your repo (or org): Settings → Actions → Runners → New self-hosted runner → macOS. GitHub gives you a download and a token; run their commands on the mini, then install it as a service so it survives reboots:

# run on: your Mac mini (in the actions-runner folder)
./config.sh --url https://github.com/YOURORG/YOURREPO --token YOUR_TOKEN
./svc.sh install
./svc.sh start

Target it from a workflow with runs-on: [self-hosted, macOS].

GitLab Runner

# run on: your Mac mini
brew install gitlab-runner
gitlab-runner register        # choose the "shell" executor for native macOS builds
brew services start gitlab-runner

The shell executor runs jobs directly on macOS, which is what you want for Xcode.

Jenkins agent

Point your Jenkins controller at the mini as a permanent agent over SSH (Manage Jenkins → Nodes → New Node), or run the agent JAR under a launchd job so it reconnects on boot. Label the node macos and pin builds to it.

Buildkite

# run on: your Mac mini
brew install buildkite/buildkite/buildkite-agent
# add your agent token to the config, then:
brew services start buildkite-agent

Keep it healthy

• Run the runner as a service (the svc.sh / brew services steps above) so a reboot brings it back on its own — pair that with auto-restart-after-power-failure from the setup guide.
• Prune build artifacts on a schedule. Derived data and simulator runtimes fill a disk quietly; a weekly cleanup job saves you a 2 a.m. "no space left" failure.
• Pin macOS and Xcode to your target versions and update deliberately.
• Watch the queue depth. If one mini can't keep up, add a second — same rack, same network, one invoice — and register it with the same label.

Outgrowing one runner? We can rack additional minis on the same network and have them online fast. Tell us your build volume and we'll help you size the fleet.

See Mac mini plans or read dedicated mini vs. metered CI to check where the cost crossover lands for your team.