Bitbucket Pipelines macOS Runner：2026 企業導入基準

macOS Runnerのステップは、コンテナ内の一時環境ではなく、登録したMacのホスト上でBashを実行します。Atlassianの公式説明でも、macOS Runnerの設定と実行環境はホスト側の状態に依存します。macOS Runnerの実行方式を確認してください。

前のジョブが作成した常駐プロセス、グローバルなツール、作業ディレクトリ外の設定、Keychainの項目が残れば、次のジョブの結果に影響します。Runnerの画面がオンラインでも、環境の再現性や権限分離が成立したことにはなりません。

注意：外部コントリビューションを受け付けるリポジトリと、本番署名を行うジョブを同じMacプールへ送らないでください。清掃スクリプトだけで信頼境界を代替する設計は避けます。

最初に、次の証拠を記録します。

• ホスト上の作業ディレクトリ外へ書き込めない、または書き込みを検知できること
• ジョブ終了後にプロセス、派生データ、キャッシュ、テンポラリーファイルが消えること
• 署名用Keychain、環境変数、アーカイブが別プールから参照できないこと
• ノード停止やMac再起動後に、管理者の手作業なしで状態を確認できること
• 失敗時に対象ノードを隔離し、再利用前に再初期化できること

清掃対象を「リポジトリの作業フォルダー」だけに限定すると不十分です。XcodeのDerivedData、依存関係のキャッシュ、シミュレーター関連ファイル、ログ、テンポラリーファイル、バックグラウンドプロセスまで範囲を定義します。

特に危険なのは、ビルドスクリプトがグローバルなパッケージを追加したり、launchdなどで常駐処理を起動したりするケースです。次のタスクが同じホストを使えば、前の変更が見えない形でビルドへ影響します。

清掃を検証するときは、正常終了だけでなく、ジョブ取消、タイムアウト、署名処理の失敗も対象にします。Bitbucket側が自動的に扱う範囲と、チームが管理するMacホスト上の範囲を分けて記録してください。

Bitbucket Cloudでは、Runnerをリポジトリ単位で登録する方法と、ワークスペース単位で利用させる方法があります。Repository Runnerは対象リポジトリに限定しやすく、Workspace Runnerは複数リポジトリから呼び出せるため、権限の影響範囲が広くなります。Runnerの登録方法を基準に、利用範囲を台帳化してください。

Workspace Runnerを使う場合は、リポジトリごとの信頼レベルをタグだけで表現しないことが重要です。タグは経路を選ぶ仕組みであり、コードを信頼済みに変える仕組みではありません。

bitbucket-pipelines.ymlでは、テスト、アーカイブ、本番署名へ異なるタグを付けます。タグの記述方法はRunnerのYAML経路設定に従い、次の異常系を確認します。

• 存在しないタグを指定した場合、ジョブが誤ったノードへ移動しないこと
• 対象ノードが稼働中でも、許可されていないプールへ迂回しないこと
• ノードが混雑した場合、待機状態を監視できること
• テスト用タグを本番署名ノードへ変更した場合に、レビューで検出できること

条件分岐で本番投入先を決める

• 外部コードを実行するなら、Workspace Runnerではなく、権限を絞った専用ノードへ戻します。
• 複数リポジトリが同じノードを使うなら、署名情報と成果物の保存領域を共有しない設計を選びます。
• 本番署名を行うなら、専用Runner、専用Keychain、承認済みタグをすべて用意できた場合だけ進めます。
• タグの誤指定を監査できないなら、Repository Runnerへ戻して対象範囲を狭めます。
• 混雑時の待機と失敗を把握できないなら、ノード追加より先にキュー監視を整備します。

Apple SiliconのMacを用意するだけでは、iOS CI/CDの再現性は確保できません。macOS、Xcode、SDK、依存ツール、実行ユーザー、証明書ストアを基準化し、変更履歴を残します。Xcodeのコマンドラインツールについては、Appleの公式リファレンスを参照してください。

同じコミットを清掃前後で繰り返し実行し、依存関係の解決、キャッシュ利用、生成されたアーカイブ、署名結果を比較します。完全一致を期待する対象と、ビルド日時など差が出る対象を先に定義すると、原因調査が速くなります。

Linux用Pipelineの設定をそのままmacOSへ移すのは危険です。利用できるRunner機能、キャッシュの扱い、Xcode固有の署名処理を別々に確認し、未対応の処理は手動承認や専用ステップへ分離します。

Runner登録用の認証情報、ソースコードへのアクセス情報、Appleの署名材料、配布権限は別管理にします。Bitbucketの変数とシークレットは、公式の変数・シークレット管理に沿って、リポジトリ、ワークスペース、デプロイ環境の単位を確認してください。

証明書と秘密鍵は、ログへ出力しないことだけでは足りません。インポート、利用、削除、ローテーション、異常時の失効までを手順化します。Appleのコード署名証明書に関する技術ノートと署名済みコード作成の公式説明を、実際の運用手順と照合してください。

検証では、テスト用タグのジョブから本番Keychainを読めないこと、別リポジトリのキャッシュやアーカイブを取得できないことを確認します。秘密情報が一度でもログや成果物に出た場合は、清掃して終わりにせず、直ちに失効と再発行を行います。

経験則：署名材料を「共有Macに置いて、タグで使い分ける」構成は、タグ設定の変更が権限昇格につながります。保管場所、実行ノード、承認経路を分けてください。

自托管Runnerの復旧は、プロセスが再起動したかではなく、意図しないタスクを受けずに安全な状態へ戻れるかで判定します。Runnerの管理状態とジョブログを確認し、復旧後に正しいタグ経路だけで再び受け付けることを確認します。

最低限、次の順で検証します。

1. Runnerプロセスを終了し、再接続後の状態を記録します。
2. Macを再起動し、ログイン操作なしで必要なサービスが起動するか確認します。
3. 通信を一時的に遮断し、実行中ジョブと待機中ジョブの扱いを確認します。
4. Pipelineを取消し、プロセス、Keychain、作業領域が残らないか調べます。
5. 復旧後に、テスト用ジョブだけを投入し、署名ジョブが自動実行されないことを確認します。

Runnerの同時実行数と待機中ステップの確認方法は、公式の同時実行・キュー説明に合わせます。復旧時間や処理性能は一般論で決めず、導入するMacと当日のRunnerバージョンで実測してください。

必要なノード数は、開発者数やApple Siliconの製品名から直接算出できません。実際のジョブ時間、同時に発生するアーカイブ、ピーク時の待機、再実行、障害時に残す余力を測定します。

まず代表的なテスト、依存関係の解決、アーカイブ、署名、配布準備を分けます。次にピーク時間帯のキュー長と、1ノードが安全に処理できるジョブ数を記録します。署名ノードは、負荷を増やすためだけにテストジョブと共有しないでください。

受け入れ判定表

導入方式の比較

固定のMacを社内に置く方式は、物理管理、故障交換、OS更新、電源と通信、余剰容量の確保を自社で負担します。クラウド上の仮想環境へ寄せる方式は、macOS固有の署名や実機条件、接続経路、利用可能な機能を個別に確認しなければなりません。

一方、CALMVPSのMacレンタルを試験ノードや追加ビルド容量として使う場合は、日本語の申込み案内で提供条件を確認し、まず非本番Pipelineで受け入れ証拠を集めてください。料金と契約期間を比較するときは、料金ページだけでなく、署名情報の管理、監視、復旧時の担当範囲もTCOへ含めます。

社内購入のMacは、長期にわたり同じ構成を占有し、物理インターフェースや社内ネットワークへの接続が必要な場合に適しています。ただし、初期購入、保守、交換部品、設置場所、余剰時間帯の遊休が発生します。短期の増員やリリース集中に対しては、固定資産を増やすより、隔離済みのMac容量を期間限定で追加する方が判断しやすい場合があります。

まずは隔離されたMacノードで非本番Pipelineを1本動かしてください。共有環境の境界、署名情報の消去、再起動後の再接続、キュー負荷の証拠が揃わない限り、本番リリースを移してはいけません。すべて監査可能になった段階で、プロジェクト単位の固定ノード追加か、CALMVPSによるリモートMac容量の追加を比較するのが安全です。