Set Up a Self-Hosted macOS Runner for GitHub Actions

MacMetro team ·

Register your Mac mini with GitHub Actions, then tell your workflow to run on it. You can start with an iOS Simulator build and add tests or signing once the build passes.

You’ll need an Apple silicon Mac, admin access to a private GitHub repository, and an iOS project with a shared Xcode scheme. The example assumes the project is at the root of the repository.

Get Xcode Ready

Install the Xcode version your project uses, then open it to finish setup and install iOS platform support. If you have more than one Xcode installed, select the right copy in Xcode → Settings → Locations. In Terminal, run xcodebuild -version to check which version your runner will use. See Apple’s Xcode setup instructions for the platform components.

Register the Mac With GitHub

In the repository, open Settings → Actions → Runners. Click New self-hosted runner, choose macOS and ARM64, and run the commands GitHub gives you on the Mac. Keep the default labels when the setup script asks. The registration token expires after an hour. See GitHub’s runner registration steps.

From the runner directory, run ./run.sh and leave it running while you try the workflow. GitHub should show the runner as Idle when it’s ready for a job.

Run Your First iOS Build

Save this as .github/workflows/ios-build.yml on the default branch. Replace MyApp with the name of your shared scheme. If your project uses a workspace, add -workspace YourApp.xcworkspace to the build command.

name: iOS Simulator Build
on: workflow_dispatch
permissions:
  contents: read
jobs:
  build:
    runs-on: [self-hosted, macOS, ARM64]
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - name: Build for iOS Simulator
        run: >-
          xcodebuild -scheme MyApp
          -destination 'generic/platform=iOS Simulator'
          CODE_SIGNING_ALLOWED=NO build

Open Actions → iOS Simulator Build → Run workflow. The three runs-on labels send the job to a self-hosted Apple silicon Mac. If it stays queued, check that the runner is online and that all three labels appear next to it. See GitHub’s guide to runner labels.

Keep the Runner Available

Once the build passes, stop ./run.sh with Control-C. Run ./svc.sh install, then ./svc.sh start from the same directory so you can close the terminal. GitHub documents how to manage the runner service on macOS.

Need a Mac for CI? See Mac mini plans or compare a dedicated Mac with Xcode Cloud and GitHub-hosted runners.