Skip to content

How to Set Up a GitHub Actions Self-Hosted Runner on Mac Mini M4

Step-by-step guide to setting up a GitHub Actions self-hosted runner on a dedicated Mac Mini M4. Faster iOS builds, Apple Silicon native, and up to 6.7x cheaper than GitHub-hosted macOS runners.

CI/CD 30 min read Updated October 2026

Why Use a Self-Hosted Mac Runner?

GitHub-hosted macOS runners are convenient, but they bill by the minute, so the cost grows with your build volume. At $0.062 per minute (GitHub's standard macOS runner rate as of October 2026), a team running 75 hours of builds per month pays around $279. GitHub does not bill minutes on self-hosted runners, so a dedicated Mac mini M4 from My Remote Mac costs a flat $85/month (USD, excl. tax) with no per-minute billing, giving you the same (or better) hardware for a fraction of the cost.

Why Use a Self-Hosted Mac Runner?
My Remote Mac Self-Hosted GitHub-Hosted Runner
Cost $85/mo (no per-minute billing) $0.062/min (~$279/mo for 75h)
Architecture Apple M4, physical Mac allocated 1:1 Apple M1 VM, 3 cores, 7 GB RAM (standard runner)
Build Speed ~4 min (same project) ~12 min (medium project)
Persistent Cache Yes (persistent disk) No (ephemeral)
Custom Software Full root access Limited
Concurrent Jobs 1 job per runner; add runners or Macs to scale 5 (Free, Pro, Team) / 50 (Enterprise)

My Remote Mac prices in USD, excluding tax. GitHub-hosted figures: standard macOS runner at $0.062 per minute, from GitHub's pricing documentation, as of October 2026.

Key Benefit: Because the runner is persistent, DerivedData, SPM caches, and CocoaPods are preserved between builds. This alone can cut build times by 50-70% compared to ephemeral GitHub-hosted runners that start from scratch every time.

Prerequisites

Before you begin, make sure you have the following:

  • A dedicated Mac mini M4 build server from My Remote Mac (from $85/mo, USD, excl. tax)
  • A GitHub account with admin access to your repository or organization
  • SSH access to your Mac Mini (provided with your My Remote Mac subscription)
  • An Apple Developer account (for code signing and provisioning profiles)
  • Basic familiarity with YAML and terminal commands

Step 1: SSH into Your Mac Mini and Check Xcode

First, connect to your Mac Mini M4 via SSH. You will have received your credentials when you set up your My Remote Mac server.

Connect via SSH

# Connect to your Mac Mini M4
ssh admin@your-server-ip

# Verify you're on Apple Silicon
uname -m
# Expected output: arm64

# Check the macOS version
sw_vers

Check the Xcode Command Line Tools

# Xcode and its Command Line Tools come preinstalled
xcode-select -p
# /Applications/Xcode.app/Contents/Developer

# Accept the Xcode license if it asks
sudo xcodebuild -license accept

# Homebrew is preinstalled too (used below to add xcodes):
# put it on your PATH once per account
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
brew --version

Check Xcode and Add Other Versions

Xcode, its Command Line Tools and Homebrew come preinstalled on every My Remote Mac server. Check the active version, and install other releases side by side with xcodes if your project needs them:

# Check the preinstalled Xcode
xcodebuild -version
# Xcode 27.2

# Optional: add other Xcode releases side by side with the xcodes CLI
brew install xcodes

# List available Xcode versions
xcodes list

# Install an older release next to the preinstalled one (asks for your Apple Account)
xcodes install 26.6

# Show the installed versions and their paths
xcodes installed
# e.g. /Applications/Xcode.app and /Applications/Xcode-26.6.0.app

# Set the active Xcode (interactive SSH session: sudo asks for your password)
# preinstalled Xcode; for another version, use the path from xcodes installed
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

Install iOS Simulators

# Install the iOS simulator runtime that matches your Xcode
xcodebuild -downloadPlatform iOS

# Verify simulator availability
xcrun simctl list runtimes
xcrun simctl list devices available

Step 2: Install the GitHub Actions Runner

Now let's download and configure the GitHub Actions runner agent. Navigate to your repository on GitHub, go to Settings > Actions > Runners > New self-hosted runner, and select macOS + ARM64.

Download and Configure

# Create a directory for the runner
mkdir -p ~/actions-runner && cd ~/actions-runner

# Download the latest runner package (macOS ARM64). The same commands, with the
# current version and its checksum, are shown on Settings > Actions > Runners >
# New self-hosted runner
RUNNER_VERSION=$(curl -fsSL https://api.github.com/repos/actions/runner/releases/latest \
  | sed -n 's/.*"tag_name": *"v\([^"]*\)".*/\1/p')
curl -o "actions-runner-osx-arm64-${RUNNER_VERSION}.tar.gz" -L \
  "https://github.com/actions/runner/releases/download/v${RUNNER_VERSION}/actions-runner-osx-arm64-${RUNNER_VERSION}.tar.gz"

# Extract the package
tar xzf "actions-runner-osx-arm64-${RUNNER_VERSION}.tar.gz"

# Configure the runner
# Replace YOUR_TOKEN with the token from GitHub Settings
./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO \
  --token YOUR_TOKEN \
  --name "mac-mini-m4-runner" \
  --labels "self-hosted,macOS,ARM64,M4" \
  --work "_work"

# Test the runner interactively first
./run.sh

Install as a Persistent launchd Service

Running the agent interactively is fine for testing, but for production you need it to start automatically and restart if it crashes. GitHub provides a built-in service installation script for macOS:

# Install as a launchd service (a LaunchAgent; no sudo on macOS)
cd ~/actions-runner
./svc.sh install

# Start the service
./svc.sh start

# Check the service status
./svc.sh status

# View the launchd plist (for reference)
cat ~/Library/LaunchAgents/actions.runner.*.plist

The service now starts whenever the runner user's session starts, and restarts the runner if the process dies. A LaunchAgent does not start at boot on its own: on a headless Mac, turn on automatic login for that user (System Settings > Users & Groups; not available while FileVault is on) so the runner comes back online after a reboot. You can verify the runner appears as "Idle" in your GitHub repository's Settings > Actions > Runners page.

Configure Runner for Multiple Repositories (Organization-Level)

# For an organization-level runner, use the organization URL:
./config.sh --url https://github.com/YOUR_ORG \
  --token YOUR_ORG_TOKEN \
  --name "mac-mini-m4-org-runner" \
  --labels "self-hosted,macOS,ARM64,M4" \
  --runnergroup "Default" \
  --work "_work"

# This allows ALL repositories in your organization to use this runner

Step 3: Create Your iOS Build Workflow

Create a workflow file in your repository at .github/workflows/ios-build.yml. This workflow will run on your self-hosted Mac Mini M4 runner.

name: iOS Build & Test

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: [self-hosted, macOS, ARM64, M4]

    # bash -eo pipefail: a failing xcodebuild fails the step even when piped to xcbeautify
    defaults:
      run:
        shell: bash

    env:
      SCHEME: "MyApp"
      # Any device listed by: xcrun simctl list devices available
      DESTINATION: "platform=iOS Simulator,name=iPhone 17,OS=latest"
      # Pick the Xcode for this job without sudo
      # (preinstalled Xcode; for another version, use the path from xcodes installed)
      DEVELOPER_DIR: /Applications/Xcode.app/Contents/Developer
      # Caches sit next to the checkout: actions/checkout cleans the checkout
      # (git clean -ffdx) on every run, but not its parent folder
      DERIVED_DATA: ${{ github.workspace }}/../DerivedData
      SPM_CACHE: ${{ github.workspace }}/../SourcePackages

    steps:
      - name: Checkout code
        uses: actions/checkout@v7

      - name: Show the selected Xcode
        run: xcodebuild -version

      - name: Resolve Swift Package Dependencies
        run: |
          xcodebuild -resolvePackageDependencies \
            -scheme "$SCHEME" \
            -clonedSourcePackagesDirPath "$SPM_CACHE"

      - name: Install xcbeautify
        run: command -v xcbeautify >/dev/null || brew install xcbeautify

      - name: Build the app
        run: |
          xcodebuild build \
            -scheme "$SCHEME" \
            -destination "$DESTINATION" \
            -clonedSourcePackagesDirPath "$SPM_CACHE" \
            -derivedDataPath "$DERIVED_DATA" \
            | xcbeautify

      - name: Run unit tests
        run: |
          xcodebuild test \
            -scheme "$SCHEME" \
            -destination "$DESTINATION" \
            -clonedSourcePackagesDirPath "$SPM_CACHE" \
            -derivedDataPath "$DERIVED_DATA" \
            -resultBundlePath TestResults.xcresult \
            | xcbeautify

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: test-results
          path: TestResults.xcresult

Add Code Signing for Release Builds

For TestFlight or App Store deployments, add code signing steps. Store your certificates and provisioning profiles as GitHub Secrets:

  deploy:
    needs: build
    runs-on: [self-hosted, macOS, ARM64, M4]
    if: github.ref == 'refs/heads/main'

    env:
      # Same Xcode as the build job (App Store Connect requires Xcode 26 or later)
      DEVELOPER_DIR: /Applications/Xcode.app/Contents/Developer

    steps:
      - name: Checkout code
        uses: actions/checkout@v7

      - name: Install certificate and provisioning profile
        env:
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.BUILD_PROVISION_PROFILE_BASE64 }}
          KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
        run: |
          # Create a temporary keychain
          KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
          security create-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
          security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
          security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH

          # Import certificate
          CERTIFICATE_PATH=$RUNNER_TEMP/build_certificate.p12
          echo -n "$BUILD_CERTIFICATE_BASE64" | base64 --decode -o $CERTIFICATE_PATH
          security import $CERTIFICATE_PATH -P "$P12_PASSWORD" \
            -A -t cert -f pkcs12 -k $KEYCHAIN_PATH
          security list-keychain -d user -s $KEYCHAIN_PATH

          # Install provisioning profile (the folder Xcode 16 and later read)
          PP_PATH=$RUNNER_TEMP/build_pp.mobileprovision
          echo -n "$BUILD_PROVISION_PROFILE_BASE64" | base64 --decode -o $PP_PATH
          mkdir -p ~/Library/Developer/Xcode/UserData/Provisioning\ Profiles
          cp $PP_PATH ~/Library/Developer/Xcode/UserData/Provisioning\ Profiles

      - name: Build for distribution
        run: |
          xcodebuild archive \
            -scheme "MyApp" \
            -archivePath DerivedData/MyApp.xcarchive \
            -destination "generic/platform=iOS" \
            CODE_SIGN_STYLE=Manual

      - name: Export IPA
        run: |
          xcodebuild -exportArchive \
            -archivePath DerivedData/MyApp.xcarchive \
            -exportOptionsPlist ExportOptions.plist \
            -exportPath DerivedData/Export

      - name: Upload to TestFlight
        env:
          APP_STORE_CONNECT_API_KEY: ${{ secrets.APP_STORE_CONNECT_API_KEY }}
          APP_STORE_CONNECT_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}
        run: |
          # altool reads the key from ~/.appstoreconnect/private_keys/AuthKey_<KEY_ID>.p8
          xcrun altool --upload-app \
            -f DerivedData/Export/MyApp.ipa \
            -t ios \
            --apiKey $APP_STORE_CONNECT_API_KEY \
            --apiIssuer $APP_STORE_CONNECT_ISSUER_ID

      # The runner is persistent: remove the signing files at the end of every job
      - name: Clean up keychain and provisioning profile
        if: ${{ always() }}
        run: |
          security delete-keychain $RUNNER_TEMP/app-signing.keychain-db || true
          rm -f ~/Library/Developer/Xcode/UserData/Provisioning\ Profiles/build_pp.mobileprovision

Step 4: Optimize Performance

One of the biggest advantages of a self-hosted runner is persistent caching. Here are key optimizations to get the most out of your Mac Mini M4.

Enable DerivedData Caching

Since the runner is persistent, DerivedData is preserved between builds. Use a consistent DerivedData path:

# In your workflow, keep DerivedData next to the checkout (job env, as above):
#   DERIVED_DATA: ${{ github.workspace }}/../DerivedData
#   ... -derivedDataPath "$DERIVED_DATA"
# Each repository then gets ~/actions-runner/_work/<repo>/DerivedData

# On the runner, remove the DerivedData of repositories not built for 7 days
# (cron job every Sunday at 03:00, keeps your existing crontab entries)
(crontab -l 2>/dev/null; echo '0 3 * * 0 find "$HOME"/actions-runner/_work/*/DerivedData -maxdepth 0 -type d -mtime +7 -exec rm -rf {} +') \
  | crontab -

Cache SPM Packages

# Use clonedSourcePackagesDirPath to keep SPM packages on disk
# (SPM_CACHE points outside the checkout, as in the workflow above)
xcodebuild build \
  -scheme "MyApp" \
  -clonedSourcePackagesDirPath "$SPM_CACHE" \
  -derivedDataPath "$DERIVED_DATA"

# This avoids re-downloading packages on every build

Parallel Test Execution

# Run tests in parallel across multiple simulators
# (devices from: xcrun simctl list devices available)
set -o pipefail
xcodebuild test \
  -scheme "MyApp" \
  -destination "platform=iOS Simulator,name=iPhone 17,OS=latest" \
  -destination "platform=iOS Simulator,name=iPhone 18 Pro,OS=latest" \
  -parallel-testing-enabled YES \
  -maximum-parallel-testing-workers 4 \
  -derivedDataPath "$DERIVED_DATA" \
  | xcbeautify

Install xcbeautify for Better Logs

# xcbeautify formats Xcode output for CI environments
brew install xcbeautify

# Use it by piping xcodebuild output (pipefail keeps xcodebuild's exit status):
set -o pipefail && xcodebuild build -scheme "MyApp" | xcbeautify

Troubleshooting Common Issues

Runner shows as "Offline" in GitHub

This usually means the launchd service is not running. Check the service status and logs:

# Check service status
./svc.sh status

# View logs
cat ~/actions-runner/_diag/Runner_*.log | tail -50

# Restart the service
./svc.sh stop
./svc.sh start

Code signing fails with "No signing certificate"

The launchd service runs under a different user context. Make sure the keychain is accessible:

# Ensure the login keychain is unlocked for the runner user
security unlock-keychain -p "YOUR_PASSWORD" ~/Library/Keychains/login.keychain-db

# Or use a dedicated keychain in your workflow (recommended)
security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
security default-keychain -s build.keychain
security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain

Simulator fails to boot

Simulators sometimes get stuck. Reset them between builds:

# Shutdown all running simulators
xcrun simctl shutdown all

# Erase all simulator data (nuclear option)
xcrun simctl erase all

# Boot a specific simulator
xcrun simctl boot "iPhone 17"

Disk space running low

Xcode builds generate a lot of data. Set up automatic cleanup:

# Clean old DerivedData
rm -rf ~/Library/Developer/Xcode/DerivedData/*

# Remove simulators whose runtime is no longer installed
xcrun simctl delete unavailable

# Clean Homebrew cache
brew cleanup --prune=7

# Remove old Xcode archives
rm -rf ~/Library/Developer/Xcode/Archives/*

Cost Analysis

Here is a detailed cost comparison for different team sizes and build volumes:

Cost Analysis
Team Size My Remote Mac Cost Builds/Month GitHub-Hosted Cost Monthly Savings
Solo Dev $85/mo 100 builds (10 min avg) $62/mo None (costs $23/mo more)
Small Team (5) $85/mo 500 builds (10 min avg) $310/mo $225/mo
Medium Team (15) $229/mo (M4 Pro) 1500 builds (10 min avg) $930/mo $701/mo
Enterprise (50+) $458/mo (2x M4 Pro) 5000+ builds $3,100+/mo $2,642+/mo

My Remote Mac prices in USD, excluding tax. GitHub-hosted figures: standard macOS runner at $0.062 per minute, from GitHub's pricing documentation, as of October 2026.

Bottom Line: For teams running more than ~140 builds per month, a self-hosted Mac Mini M4 pays for itself immediately. And because builds are faster on persistent hardware with warm caches, your team saves developer time too. At 100 builds a month, as in the Solo Dev row, GitHub-hosted runners cost $23/mo less; a solo developer may still prefer a dedicated Mac for its persistent caches, faster builds and no per-minute billing. If you only ship occasionally, the daily plan gives you a Mac for release day from $14 per 24 hours (USD, excl. tax): turn auto-renew off when you deploy and it stops after 24 hours, or switch to monthly on the same Mac.

Ready to Speed Up Your iOS Builds?

Deploy a dedicated Mac Mini M4 as your GitHub Actions runner. Starting at $85/month.

My Remote Mac prices in USD, excluding tax.

Looking for more detail?

Browse the full documentation for step-by-step setup, configuration references, and troubleshooting.

Open the documentation →