Short answer
Install Xcode on the Mac mini, then in your GitHub repository or organization open Settings → Actions → Runners → New self-hosted runner, choose macOS, and run the download and configure commands GitHub shows you over SSH. Install the runner as a service so it starts on boot, then use runs-on: self-hosted in your workflows. The commands below mirror GitHub’s documentation; the exact download URL and token come from your own GitHub settings page.
Before you start
- A Mac mini you can reach over SSH (connection details are in your MacMiniNode dashboard once it is ready)
- Admin rights on the GitHub repository or organization where the runner will be registered
- An Apple ID for downloading Xcode, and an Apple Developer Program membership if the workflow signs or uploads builds
- A decision on scope: GitHub advises against self-hosted runners on public repositories because forks can run code on your machine
1. Install Xcode and the command-line tools
Connect over remote desktop and install Xcode from the Mac App Store, or download a specific version from Apple Developer downloads. Then over SSH select it and accept the license: sudo xcode-select -s /Applications/Xcode.app followed by sudo xcodebuild -license accept. Run xcodebuild -runFirstLaunch once so the first workflow does not stall on component installation.
Install Homebrew if you want it for fastlane, xcbeautify, or other tools; the runner inherits whatever is on the machine.
2. Create the runner in GitHub
Open the repository (or organization) on GitHub → Settings → Actions → Runners → New self-hosted runner → macOS, architecture ARM64. GitHub shows four commands: create a folder, download the runner archive, extract it, and run ./config.sh with your repository URL and a one-time registration token. Copy them exactly; the token expires after an hour. Full reference: Adding self-hosted runners.
During configuration, give the runner a name and labels such as macos, xcode-16, or m6, so workflows can target it precisely.
3. Run it as a service so it survives reboots
From the runner folder: ./svc.sh install then ./svc.sh start. This installs a launchd agent that starts the runner at login. Check it with ./svc.sh status. GitHub documents the service commands in Configuring the self-hosted runner application as a service.
On a hosted Mac that nobody logs into interactively, make sure the account the service runs under logs in automatically after a reboot, or the agent will not start. Ask MacMiniNode support if you are unsure how the machine was prepared.
4. Point a workflow at it
In .github/workflows/ios.yml set runs-on: [self-hosted, macos] (or your labels) and run your usual steps: xcodebuild -scheme App -destination "platform=iOS Simulator,name=iPhone 16" test. Caches persist between jobs automatically because it is the same machine; you can drop the cache actions you needed on hosted runners.
5. Keep it healthy and secure
- Update the runner agent when GitHub flags a new version;
./svc.sh stop, update,./svc.sh start - Keep macOS and Xcode current; schedule a monthly check
- Store certificates and API keys in GitHub Secrets and import them per job (fastlane match or a keychain step), then clean up
- Prune derived data and old simulator runtimes periodically; the SSD is 256GB
- Rotate the runner registration if a team member with admin access leaves
What we did not test here
This guide follows GitHub’s published procedure and standard macOS commands. We have not published timing benchmarks or screenshots from a specific machine; when we do, they will carry the configuration and date they were captured. If a step differs on your Mac mini, open a ticket and we will update the guide.
Is MacMiniNode the right option?
A MacMiniNode Mac mini works well as a single dedicated macOS runner for steady daily CI. Teams needing many parallel macOS jobs on demand are better served by hosted minutes or several machines.