MacでBuildkiteエージェントを動かす方法

最初に必要なもの

• Buildkiteのクラスタと、そのエージェントトークンとキューを管理する権限。Organizationの管理者か、クラスタのメンテナーである必要があります。
• macOS 11以降のMac。これがBuildkiteの公表している最低要件です。Apple silicon、Homebrew、Xcode、管理者権限も必要です。
• エージェントがリポジトリのcloneに使えるSSH鍵。

1. キューとエージェントトークンを作成する

Buildkiteで「Agents」を選んで「Clusters」ページに移り、クラスタを選びます。「Queues」ページで「New Queue」を選びます。キーをmacosにし、「Self hosted」を選びます。次に「Agent Tokens」を開いて「New Token」を選び、説明を入力して作成します。値をコピーします。Buildkiteが表示するのは一度だけです。

トークンのフォームには「Allowed IP Addresses」の欄があります。MacRunでは空欄のままにしてください。当社のMacには固定のパブリックIPがないので、CIDRのルールを入れるとエージェントが締め出されます。

2. Homebrewでエージェントをインストールする

brew tap buildkite/buildkite
brew trust buildkite/buildkite
brew install buildkite/buildkite/buildkite-agent

2026年10月に当社のMacに入っていたHomebrew 7.0.7は、サードパーティのtapを信頼するまで、そこからformulaを読み込みません。それが真ん中の行です。formulaの名前は現在buildkite-agent@3ですが、Buildkiteのドキュメントにある古い名前も引き続きこれを指しています。

Apple siliconでは、ファイルは/opt/homebrewの下に置かれます。

• 設定：/opt/homebrew/etc/buildkite-agent/buildkite-agent.cfg
• フック：/opt/homebrew/etc/buildkite-agent/hooks
• ログ：/opt/homebrew/var/log/buildkite-agent.log

お使いのマシンでの正確なパスは、brew info buildkite-agentを実行して確認してください。

3. トークンとキューのタグを追加する

Buildkiteのドキュメントでは、sedでプレースホルダーのトークンを置き換えています。大文字の部分を自分のトークンに置き換えてください。

sed -i '' "s/xxx/INSERT-YOUR-AGENT-TOKEN-HERE/g" "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg
cat "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg | grep token

次に同じファイルを開いてtagsの行を設定し、エージェントをキューに参加させます。

tags="queue=macos"

エージェントは、クラスタ内の1つのセルフホストキューに属します。キューのタグがなければ、デフォルトのキューに参加します。クラスタにデフォルトのセルフホストキューがない場合、Buildkiteによるとエージェントは接続に失敗します。

4. テストしてから、サービスとして動かす

まずフォアグラウンドで一度起動します。クラスタのエージェント一覧に表示されるはずです。

buildkite-agent start

Control Cで止めます。Homebrewのformulaにはサービス定義が含まれています。上の設定でbuildkite-agent startを実行し、失敗したら再起動し、同じファイルにログを出力します。Macのデスクトップ上のターミナルから起動してください。

brew services start buildkite/buildkite/buildkite-agent@3
brew services list | grep buildkite

macOSでは、エージェントはlaunchdのサービスを起動したユーザーとして動きます。Xcodeと署名鍵を持っているアカウントで起動してください。

まずはMac 1台につきエージェント1つで始めてください。Buildkiteは、1つのサービスから複数のエージェントを動かすための、設定ファイルのspawn設定と--spawnフラグを記載しています。Xcodeのビルドを2つ同時に動かすと、同じコアとメモリを取り合います。16 GBのマシンでは、まず1つのエージェントで計測し、それから2つを試してください。

5. 再起動後も動くようにする

formula自身のインストール時の注記に、このユーザーで自動ログインするようMacを設定せよとあります。BuildkiteのtapのREADMEが、そのトレードオフを説明しています。LaunchAgentにはログインが必要ですが、そのおかげでテストがiOSシミュレータのようなGUIツールを使えます。「システム設定」の「ユーザとグループ」で自動ログインをオンにします。それからスリープをオフにし、再起動して、エージェント一覧を確認します。

sudo pmset -a sleep 0
sudo shutdown -r now

plistは、Homebrewが置く場所であるホームフォルダのLaunchAgentsに置いたままにしてください。macOS 27では、/Library/LaunchAgentsにplistがあると自動ログインが壊れることを確認しました。ヘッドレスMacでの自動ログインをご覧ください。

6. Mac用のパイプラインステップ

steps:
  - label: ":xcode: iOS tests"
    agents:
      queue: "macos"
    commands:
      - "rm -rf build/TestResults.xcresult"
      - "xcodebuild test -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.5' -resultBundlePath build/TestResults.xcresult"
      - "ditto -c -k --keepParent build/TestResults.xcresult build/TestResults.xcresult.zip"
    artifact_paths:
      - "build/TestResults.xcresult.zip"
    timeout_in_minutes: 30
    retry:
      automatic:
        - exit_status: -1
          limit: 2

exit_status: -1のリトライは、Buildkiteのコマンドステップの例から取りました。テストが失敗したときではなく、エージェント自体が失われたときにジョブをリトライします。

よくあるエラーと対処法

• launchctlがCould not find domain forと表示する。Buildkiteによると、Macにユーザーがログインしている必要があります。デスクトップでログインし、サービスをもう一度読み込んでください。
• Refusing to load formula ... from untrusted tap。brew trust buildkite/buildkiteを実行し、もう一度インストールします。
• エージェントが接続しない。トークンが間違っているか、tagsのキューのキーがこのクラスタに存在しません。
• エージェントがcloneできない。エージェントを動かすユーザーの~/.sshに鍵を置いてください。
• xcodebuild: error: Existing file at -resultBundlePath。ビルドはチェックアウトを再利用します。上の例のように、先にbundleを削除してください。

あとでアップグレードするには、brew update && brew upgrade buildkite/buildkite/buildkite-agent@3を実行します。

専用Macが役立つ理由

Buildkiteは自分のマシンで使う前提で作られていて、常設のMacはキャッシュを保持します。Xcode 26.6でWikipediaのiOSアプリを使った当社のベンチマークでは、小さな変更後のジョブがウォームなM6で27秒でした。新規のGitHubホスト型macos-26 runnerでは269秒でした。

Buildkiteのホスト型エージェントで足りる場合

Buildkiteはホスト型のmacOSエージェントも提供しています。2026年10月に読んだドキュメントによると、ホスト型のキューを作るときに選べます。面倒を見るマシンを持ちたくないなら、そのほうが簡単です。SLA、トークンのルール用の固定IP、複数のリージョンが必要な場合も、MacRunは向きません。

MacRun側についてはその他のCIシステムをご覧ください。ステップで何を実行するかは、iOS CI/CDパイプラインのガイドをご覧ください。