Mac Mini M4 で CircleCI セルフホストランナーを構築する方法

1. なぜ Mac でセルフホスト CircleCI ランナーを使うのか？

CircleCI はクラウドベースの macOS 実行環境を提供していますが、それには相応のコストと制約が伴います。CircleCI 上の macOS リソースはクレジットベースの仕組みを使っており、macOS エグゼキュータでの各分は、リソースクラスに応じて 50〜100 クレジットを消費します。頻繁に iOS ビルドを実行するチームでは、これがすぐに月額$300〜$500以上に膨れ上がることがあります。

MyRemoteMac の専用 Mac Mini M4 上のセルフホストランナーなら、分単位の課金を完全になくせます。永続的なストレージ、ウォームキャッシュ、完全な root アクセスを備えた専用の Apple Silicon マシンを、月額$85からの定額で利用できます。以下に詳しい比較を示します。

2. 前提条件

始める前に、次のものが揃っていることを確認してください。

• MyRemoteMac の Mac Mini M4 サーバー（月額$85から）
• Performance、Scale、または Server プランの CircleCI アカウント（セルフホストランナーには有料プランが必要です）
• Mac Mini への SSH アクセス（MyRemoteMac のサブスクリプションに付属します）
• Apple Developer アカウント（コード署名とプロビジョニングプロファイル用）
• YAML、CircleCI の設定、ターミナルコマンドの基本的な知識

3. ステップ 1: Mac Mini に SSH 接続して依存関係をインストールする

まず、Mac Mini M4 に SSH で接続します。MyRemoteMac サーバーをセットアップした際に認証情報を受け取っているはずです。CircleCI ランナーを設定する前に、iOS ビルドに必要な Xcode とツールをインストールする必要があります。

SSH で接続する

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

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

# Check macOS version
sw_vers
# ProductName:    macOS
# ProductVersion: 15.2
# BuildVersion:   24C101

Homebrew と Xcode Command Line Tools をインストールする

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Add Homebrew to PATH
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# Install Xcode Command Line Tools
xcode-select --install

# Accept the license agreement
sudo xcodebuild -license accept

Xcode（フルバージョン）をインストールする

iOS ビルドには Xcode アプリケーションの完全版が必要です。ヘッドレスサーバーにインストールする最も速い方法は xcodes を使うことです。

# Install xcodes CLI tool
brew install xcodes

# List available Xcode versions
xcodes list

# Install the latest stable Xcode
xcodes install 16.2

# Set it as the active Xcode
sudo xcode-select -s /Applications/Xcode-16.2.app/Contents/Developer

# Verify installation
xcodebuild -version
# Xcode 16.2
# Build version 16C5032a

iOS シミュレーターとビルドツールをインストールする

# Install the iOS 18 simulator runtime
xcodebuild -downloadPlatform iOS

# Verify simulator availability
xcrun simctl list runtimes
# == Runtimes ==
# iOS 18.2 (18.2 - 22C150) - com.apple.CoreSimulator.SimRuntime.iOS-18-2

# Install additional build tools
brew install xcbeautify fastlane swiftlint

4. ステップ 2: CircleCI ランナーエージェントをインストールする

CircleCI は、Mac Mini を CircleCI プラットフォームに接続するためにマシンランナーエージェントを使用します。マシンランナーは CircleCI からジョブを受け取り、macOS ホスト上で直接実行します。これはコンテナランナー（Linux でのみ動作）とは異なります。

ランナー用の専用ユーザーを作成する

セキュリティ上の分離のため、CircleCI エージェントを実行する専用ユーザーを作成することをおすすめします。

# Create a circleci user (optional but recommended)
sudo dscl . -create /Users/circleci
sudo dscl . -create /Users/circleci UserShell /bin/zsh
sudo dscl . -create /Users/circleci RealName "CircleCI Runner"
sudo dscl . -create /Users/circleci UniqueID 550
sudo dscl . -create /Users/circleci PrimaryGroupID 20
sudo dscl . -create /Users/circleci NFSHomeDirectory /Users/circleci
sudo mkdir -p /Users/circleci
sudo chown circleci:staff /Users/circleci

# Or simply use your existing admin user (simpler setup)

ランナーエージェントをダウンロードしてインストールする

# Create a directory for the runner
sudo mkdir -p /opt/circleci

# Download the latest CircleCI machine runner for macOS ARM64
# Check https://circleci.com/docs/runner-installation-mac/ for latest version
curl -o /tmp/circleci-runner.pkg \
  https://circleci-binary-releases.s3.amazonaws.com/circleci-runner/1.0/circleci-runner_darwin_arm64.pkg

# Install the runner package
sudo installer -pkg /tmp/circleci-runner.pkg -target /

# Verify the installation
circleci-runner --version

ランナーエージェントを設定する

ランナーの設定ファイルを作成します。CircleCI ダッシュボードから取得したランナー認証トークンが必要です（ステップ 3 で説明します）。今のところは、設定ファイルの構造だけを作成しておきます。

# Create the configuration directory
sudo mkdir -p /opt/circleci/config

# Create the runner configuration file
sudo tee /opt/circleci/config/runner-agent-config.yaml << 'EOF'
api:
  auth_token: YOUR_RUNNER_TOKEN_HERE

runner:
  name: mac-mini-m4-runner
  working_directory: /opt/circleci/workdir
  cleanup_working_directory: true
  max_run_time: 5h

  # Optional: limit concurrent tasks
  # command_prefix: ["nice", "-n", "10"]

logging:
  file: /opt/circleci/logs/runner.log
EOF

# Create required directories
sudo mkdir -p /opt/circleci/workdir
sudo mkdir -p /opt/circleci/logs

# Set permissions (adjust user if using dedicated circleci user)
sudo chown -R admin:staff /opt/circleci

永続化のための macOS Launch Agent を作成する

ランナーが起動時に自動的に開始し、クラッシュしても再起動するようにするには、macOS の LaunchDaemon を作成します。

# Create the LaunchDaemon plist
sudo tee /Library/LaunchDaemons/com.circleci.runner.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.circleci.runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/circleci/circleci-runner</string>
        <string>machine</string>
        <string>--config</string>
        <string>/opt/circleci/config/runner-agent-config.yaml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/opt/circleci/logs/runner-stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/opt/circleci/logs/runner-stderr.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>
</dict>
</plist>
EOF

# Load and start the service
sudo launchctl load /Library/LaunchDaemons/com.circleci.runner.plist

# Verify the service is running
sudo launchctl list | grep circleci
# Expected: PID listed with com.circleci.runner

# Check the logs
tail -f /opt/circleci/logs/runner.log

5. ステップ 3: CircleCI ダッシュボードでランナーを設定する

次に、CircleCI の Web インターフェースでランナーを登録し、認証トークンを生成する必要があります。これにより、Mac Mini が CircleCI の組織に接続されます。

リソースクラスを作成する

CircleCI では、セルフホストランナーはリソースクラスごとに整理されます。リソースクラスは、.circleci/config.yml を特定のランナーの集合に対応付けるラベルです。

1. CircleCI ダッシュボード → Organization Settings → Self-Hosted Runners に移動します
2. 「Create Resource Class」をクリックします
3. Namespace を組織名（例: your-org）に設定します
4. リソースクラス名を分かりやすい名前（例: mac-runner）に設定します
5. これにより、リソースクラス識別子 your-org/mac-runner が作成されます

ランナー認証トークンを生成する

1. リソースクラスを作成したら、「Create New Token」をクリックします
2. トークンに分かりやすい名前（例: mac-mini-m4-token）を付けます
3. 生成されたトークンをすぐにコピーします — 一度しか表示されません

ランナー設定をトークンで更新する

# SSH back into your Mac Mini
ssh admin@your-server-ip

# Update the runner configuration with your real token
sudo nano /opt/circleci/config/runner-agent-config.yaml

# Replace YOUR_RUNNER_TOKEN_HERE with the actual token:
# api:
#   auth_token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

# Restart the runner service to apply the new token
sudo launchctl unload /Library/LaunchDaemons/com.circleci.runner.plist
sudo launchctl load /Library/LaunchDaemons/com.circleci.runner.plist

# Verify the runner connects successfully
tail -20 /opt/circleci/logs/runner.log
# Look for: "Runner is ready to receive jobs"

接続されると、ランナーは CircleCI ダッシュボードの Self-Hosted Runners の下に「Online」として表示されます。60 秒以内に表示されない場合は、ログファイルでエラーメッセージを確認してください。

CircleCI CLI を使う（代替手段）

CircleCI CLI からランナーを管理することもできます。

# Install the CircleCI CLI
brew install circleci

# Authenticate with CircleCI
circleci setup

# Create a resource class via CLI
circleci runner resource-class create your-org/mac-runner \
  "Mac Mini M4 Runner" --generate-token

# List your runners
circleci runner instance list your-org/mac-runner

6. ステップ 4: iOS ビルド用の .circleci/config.yml を作成する

リポジトリのルートに .circleci/config.yml ファイルを作成します。標準的な CircleCI 設定との主な違いは、セルフホストランナーを対象とするために machine: true とカスタムの resource_class を使う点です。

version: 2.1

jobs:
  build-and-test:
    machine: true
    resource_class: your-org/mac-runner

    environment:
      SCHEME: "MyApp"
      DESTINATION: "platform=iOS Simulator,name=iPhone 16 Pro,OS=18.2"
      DERIVED_DATA_PATH: "DerivedData"
      SPM_CACHE_PATH: ".spm-cache"

    steps:
      - checkout

      - run:
          name: Select Xcode version
          command: |
            sudo xcode-select -s /Applications/Xcode-16.2.app/Contents/Developer
            xcodebuild -version

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

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

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

      - store_test_results:
          path: TestResults.xcresult

      - store_artifacts:
          path: TestResults.xcresult
          destination: test-results

workflows:
  ios-pipeline:
    jobs:
      - build-and-test:
          filters:
            branches:
              only:
                - main
                - develop

7. ステップ 5: キャッシュと並列化で最適化する

セルフホストランナーの最大の利点の 1 つは、永続的なキャッシュです。ランナーのファイルシステムが永続的であるため、CircleCI のクラウドリソースのようにキャッシュをアップロード・ダウンロードする必要がありません。とはいえ、ビルド速度を最大化するための追加の最適化もあります。

永続的な DerivedData を活用する

ランナーのディスクはビルド間で永続化されるため、DerivedData はすでに自動的にキャッシュされています。一貫したパスを使用してください。

# In your config.yml steps, always use a consistent DerivedData path:
- run:
    name: Build with persistent cache
    command: |
      xcodebuild build \
        -scheme "$SCHEME" \
        -destination "$DESTINATION" \
        -derivedDataPath ~/DerivedData/"$SCHEME" \
        -clonedSourcePackagesDirPath ~/spm-cache \
        | xcbeautify

# Periodically clean old DerivedData on the runner (cron job):
# 0 3 * * 0 find ~/DerivedData -maxdepth 1 -mtime +7 -exec rm -rf {} +

ジョブ間でワークスペースを永続化する

同じワークフロー内のジョブ間で成果物を受け渡すには、CircleCI のワークスペースを使用します。

jobs:
  build:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Build
          command: |
            xcodebuild build \
              -scheme "MyApp" \
              -destination "generic/platform=iOS" \
              -derivedDataPath DerivedData
      - persist_to_workspace:
          root: .
          paths:
            - DerivedData

  test:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - attach_workspace:
          at: .
      - run:
          name: Run tests
          command: |
            xcodebuild test \
              -scheme "MyApp" \
              -destination "platform=iOS Simulator,name=iPhone 16 Pro,OS=18.2" \
              -derivedDataPath DerivedData \
              | xcbeautify

workflows:
  build-test:
    jobs:
      - build
      - test:
          requires:
            - build

テストの並列実行

- run:
    name: Run tests in parallel
    command: |
      xcodebuild test \
        -scheme "MyApp" \
        -destination "platform=iOS Simulator,name=iPhone 16 Pro,OS=18.2" \
        -destination "platform=iOS Simulator,name=iPhone 15,OS=17.5" \
        -parallel-testing-enabled YES \
        -maximum-parallel-testing-workers 4 \
        -derivedDataPath DerivedData \
        | xcbeautify

CircleCI のテスト分割

大規模なテストスイートには、CircleCI に組み込まれたテスト分割機能を使い、複数の並列ランナーにテストを分散させます。

jobs:
  test:
    machine: true
    resource_class: your-org/mac-runner
    parallelism: 3
    steps:
      - checkout
      - run:
          name: Split and run tests
          command: |
            # Generate test plan
            TESTS=$(circleci tests glob "**/*Tests.swift" | \
              circleci tests split --split-by=timings)

            # Run only this container's portion of tests
            xcodebuild test \
              -scheme "MyApp" \
              -destination "platform=iOS Simulator,name=iPhone 16 Pro,OS=18.2" \
              -only-testing:$TESTS \
              | xcbeautify

8. ワークフローの例

一般的な iOS の CI/CD シナリオ向けに、完全で本番運用に対応したワークフローの例を紹介します。

iOS のビルド、テスト、デプロイの完全なパイプライン

version: 2.1

jobs:
  lint:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Run SwiftLint
          command: swiftlint lint --reporter json > swiftlint-results.json || true
      - store_artifacts:
          path: swiftlint-results.json

  build-and-test:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Select Xcode
          command: sudo xcode-select -s /Applications/Xcode-16.2.app/Contents/Developer
      - run:
          name: Resolve dependencies
          command: |
            xcodebuild -resolvePackageDependencies \
              -scheme "MyApp" \
              -clonedSourcePackagesDirPath ~/spm-cache
      - run:
          name: Build and test
          command: |
            xcodebuild test \
              -scheme "MyApp" \
              -destination "platform=iOS Simulator,name=iPhone 16 Pro,OS=18.2" \
              -clonedSourcePackagesDirPath ~/spm-cache \
              -derivedDataPath ~/DerivedData/MyApp \
              -resultBundlePath TestResults.xcresult \
              -parallel-testing-enabled YES \
              | xcbeautify
      - store_test_results:
          path: TestResults.xcresult
      - store_artifacts:
          path: TestResults.xcresult

  deploy-testflight:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Select Xcode
          command: sudo xcode-select -s /Applications/Xcode-16.2.app/Contents/Developer
      - run:
          name: Install certificates with Fastlane Match
          command: |
            fastlane match appstore --readonly
      - run:
          name: Build and upload to TestFlight
          command: |
            fastlane beta
          environment:
            FASTLANE_USER: ${APPLE_ID}
            MATCH_PASSWORD: ${MATCH_PASSWORD}

workflows:
  ios-pipeline:
    jobs:
      - lint
      - build-and-test:
          requires:
            - lint
      - deploy-testflight:
          requires:
            - build-and-test
          filters:
            branches:
              only: main

Fastlane 連携の例

ビルドの自動化に Fastlane を使っている場合、CircleCI セルフホストランナーと連携させる方法は次のとおりです。

# Fastfile (fastlane/Fastfile)
default_platform(:ios)

platform :ios do
  desc "Run tests"
  lane :test do
    scan(
      scheme: "MyApp",
      device: "iPhone 16 Pro",
      derived_data_path: "~/DerivedData/MyApp",
      result_bundle: true,
      output_directory: "./test_output"
    )
  end

  desc "Build and push to TestFlight"
  lane :beta do
    match(type: "appstore", readonly: true)
    increment_build_number(
      build_number: ENV["CIRCLE_BUILD_NUM"]
    )
    gym(
      scheme: "MyApp",
      export_method: "app-store",
      derived_data_path: "~/DerivedData/MyApp"
    )
    pilot(skip_waiting_for_build_processing: true)
  end
end

# .circleci/config.yml using Fastlane
version: 2.1

jobs:
  fastlane-test:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: bundle install
      - run:
          name: Run Fastlane tests
          command: bundle exec fastlane test
      - store_test_results:
          path: ./test_output
      - store_artifacts:
          path: ./test_output

  fastlane-deploy:
    machine: true
    resource_class: your-org/mac-runner
    steps:
      - checkout
      - run:
          name: Install dependencies
          command: bundle install
      - run:
          name: Deploy to TestFlight
          command: bundle exec fastlane beta

workflows:
  ios-workflow:
    jobs:
      - fastlane-test
      - fastlane-deploy:
          requires:
            - fastlane-test
          filters:
            branches:
              only: main

9. パフォーマンス比較

CircleCI クラウドの macOS リソースと、MyRemoteMac の専用 Mac Mini M4 との詳細なパフォーマンスおよびコスト比較を示します。

ビルド時間のベンチマーク

月間コスト分析

10. よくある問題のトラブルシューティング

# Check if the process is running
ps aux | grep circleci-runner

# Check the LaunchDaemon status
sudo launchctl list | grep circleci

# View the error logs
tail -50 /opt/circleci/logs/runner-stderr.log
tail -50 /opt/circleci/logs/runner.log

# Restart the service
sudo launchctl unload /Library/LaunchDaemons/com.circleci.runner.plist
sudo launchctl load /Library/LaunchDaemons/com.circleci.runner.plist

# If the token expired, generate a new one in CircleCI dashboard
# and update /opt/circleci/config/runner-agent-config.yaml

# Verify the exact resource class name in CircleCI dashboard:
# Organization Settings > Self-Hosted Runners > Resource Classes

# The resource_class in .circleci/config.yml must match exactly:
# resource_class: your-org/mac-runner  (case-sensitive!)

# Check your runner is online:
circleci runner instance list your-org/mac-runner

# Common mistakes:
# - Wrong namespace (org name vs personal namespace)
# - Typo in resource class name
# - Runner is offline or token is invalid
# - Using 'docker' executor instead of 'machine: true'

# Option 1: Use Fastlane Match (recommended)
# In your Fastfile:
match(type: "appstore", readonly: true)

# Option 2: Manual keychain management in your job steps
- run:
    name: Setup code signing
    command: |
      # Decode and import the certificate
      echo "$BUILD_CERTIFICATE_BASE64" | base64 --decode > /tmp/cert.p12

      # Create a temporary keychain
      security create-keychain -p "ci" /tmp/ci.keychain
      security set-keychain-settings -lut 21600 /tmp/ci.keychain
      security unlock-keychain -p "ci" /tmp/ci.keychain

      # Import the certificate
      security import /tmp/cert.p12 -P "$P12_PASSWORD" \
        -A -t cert -f pkcs12 -k /tmp/ci.keychain
      security list-keychain -d user -s /tmp/ci.keychain

      # Install provisioning profile
      mkdir -p ~/Library/MobileDevice/Provisioning\ Profiles
      echo "$PROVISIONING_PROFILE_BASE64" | base64 --decode \
        > ~/Library/MobileDevice/Provisioning\ Profiles/profile.mobileprovision

# Add a pre-build step to clean simulators
- run:
    name: Reset simulators
    command: |
      xcrun simctl shutdown all 2>/dev/null || true
      xcrun simctl erase all 2>/dev/null || true

# If a specific runtime is missing, reinstall it:
xcodebuild -downloadPlatform iOS

# List available simulators
xcrun simctl list devices available

# Check available disk space
df -h /

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

# Remove old simulator runtimes
xcrun simctl runtime delete all

# Clean Homebrew cache
brew cleanup --prune=7

# Remove old CircleCI working directories
find /opt/circleci/workdir -maxdepth 1 -mtime +3 -exec rm -rf {} +

# Set up a weekly cron job for automatic cleanup
(crontab -l 2>/dev/null; echo "0 4 * * 0 rm -rf ~/Library/Developer/Xcode/DerivedData/* && brew cleanup --prune=7") | crontab -

11. よくある質問

12. 関連ガイド