Xcodeジョブは通るのに、実行先のMacや署名環境が毎回変わって本番投入できない。

最短の解決策は、固定Xcode・内製依存・署名情報が必要なジョブだけを、独立アカウントのリモートMacへCircleCI Machine Runner 3 リモートMac デプロイすることです。標準化されたジョブは托管実行環境に残し、Runnerがオンラインになった後も、実ジョブ、再起動復旧、ワークスペース清掃まで確認してから本番へ進めてください。

この記事の対象者

CircleCIでiOSまたはmacOSのパイプラインを管理し、固定したツールチェーンを必要とする開発者向けです。署名情報、プライベートリポジトリ、社内サービスをCIへ接続するDevOps担当者や、リモートMacの権限・更新・障害復旧を管理する人にも適しています。

最終更新：2026年8月29日。CircleCIの公式Runner概要、Machine Runner 3の設定リファレンス、macOSインストールガイド、AppleのXcode関連文書を基に確認しています。インストール方法や対応範囲が変更された場合は、作業前に公式文書を再確認してください。

01

デプロイ前にジョブの移行範囲を決める

Machine Runner 3は、ノードに存在するOS、開発ツール、依存ファイルを直接利用してジョブを実行します。したがって、環境を固定できる反面、Xcodeの更新、キャッシュ、ユーザー権限、証明書の管理責任が自分側に移ります。Runnerの実行モデルを確認したうえで、対象を絞ってください。

判断は次の条件分岐で十分です。

  • 固定したXcodeやmacOS専用ツールが必要なら、リモートMacのMachine Runnerを選びます。
  • 署名証明書やプロビジョニング情報を専用環境に隔離したいなら、一般ビルドとは別のresource classを用意します。
  • 社内API、プライベート依存、限定ネットワークへ接続する必要があるなら、自分で管理するMacノードを候補にします。
  • OS差分や秘密情報が不要な標準ジョブなら、托管実行環境へ戻すほうが運用負担を抑えられます。
  • 長時間稼働、物理デバイス接続、固定された社内経路が必須なら、レンタル前に接続要件と復旧方法を確認します。

CircleCIのRunner概要では、Machine Runnerを含む実行方式と対応環境が整理されています。Apple Silicon Macへの導入可否は、契約時の説明ではなく、公式macOSインストールガイドで作業日に確認してください。

02

第一段階：アカウントとresource classを分離する

最初に、普段の管理者アカウントとは別に、Runner専用のローカル実行アカウントを作成します。ソース、キャッシュ、ログ、署名関連ファイルを同じ権限で扱うと、ビルド失敗時の調査用ログへ秘密情報が混ざる危険があります。

対象 推奨する分離 確認する証拠
実行ユーザー Runner専用の低権限アカウント ジョブ内のユーザー確認
ソース領域 ジョブ用ディレクトリに限定 他プロジェクトを読めないこと
キャッシュ 共有範囲を明示 前回ジョブの生成物が残らないこと
署名情報 リリース用ノードまたは専用resource class 一般ビルドから参照できないこと
ログ 保存先とマスキングを定義 トークンやパスワードが出ないこと

CircleCIでは、namespaceとresource classを組み合わせて、特定のノードへジョブを振り分けます。resource classの公式説明に沿って、以下のような値を自分の環境に置き換えて登録します。

resource_class: <NAMESPACE>/<RESOURCE_CLASS>

namespace、resource class、ホスト名、作業ディレクトリ、認証値はすべてプレースホルダーで管理します。トークンはリポジトリ、設定ファイルの公開領域、ビルドログへ直接書き込まず、保存場所、ローテーション手順、失効手順を先に決めてください。

CircleCI self-hosted runnerでresource classを設定する要点は何ですか。
ジョブ側に指定したresource classと、登録済みノード側の値を完全に一致させることです。似た名前を複数作ると、ジョブが待機したまま原因を追いにくくなります。まず専用の検証用クラスを作り、最小ジョブでルーティングを確認してから本番用へ分けます。

03

第二段階：Machine Runner 3を導入して観測する

インストールは、作業当日に確認したCircleCI公式のmacOS手順をそのまま使います。配布ファイルの取得、macOSの隔離属性や署名・公証に関する確認、設定ファイルの配置、ノード名と作業ディレクトリの指定を、手順ごとに記録してください。自己流のサービス化コマンドへ置き換えると、アップデート時に復旧方法が失われます。

導入直後は、次の順で確認します。

  • 専用アカウントでRunnerプロセスが起動している。
  • 設定ファイルに認証値、ノード名、作業ディレクトリが正しく反映されている。
  • CircleCIのRunner inventoryで対象ノードが想定の状態になっている。
  • ローカルログに認証失敗、接続切断、権限拒否が出ていない。
  • 作業ディレクトリへ、意図したアカウントだけが書き込める。
検証段階 実行する内容 合格条件 停止条件
登録 Runnerを起動してinventoryを確認 対象ノードを識別できる 認証失敗が続く
ルーティング 検証用resource classでジョブ実行 指定Macで開始する ジョブが待機する
Xcode 小さな破棄可能プロジェクトをビルド 終了コードと成果物を取得できる ツールチェーンが見つからない
再起動 計画的にMacを再起動 Runnerと管理経路が戻る 手動ログインが必要
清掃 失敗後に作業領域を確認 秘密情報と生成物が残らない 次のジョブへ汚染する

Runnerのオンライン表示だけでは、デプロイ完了とは判定しません。公式の設定リファレンスと自托管Runnerの排障手順を照合し、管理画面、プロセス、ログの三方向で状態を確認します。

04

第三段階：Xcode CIの最小ジョブを通す

まず署名を必要としない破棄可能なプロジェクトを使います。ジョブの目的は、Xcode CIを完成させることではなく、指定したmacOS構築ノードで環境が再現できることを証明することです。

確認項目は、実行ユーザーのホームディレクトリ、Xcodeの場所、Command Line Toolsの選択、依存パッケージ、ビルド成果物の保存です。AppleのCommand Line Toolsの導入説明とXcodeのコマンドラインツール選択方法を基準にし、GUIログインを前提にしないでください。

実ジョブでは、少なくとも次を保存します。

  • ジョブの終了コード
  • Xcodeとツールチェーン確認の出力
  • テスト結果または成果物
  • 実行ノードを識別できるログ
  • 失敗後に清掃した作業ディレクトリの状態

CircleCI自托管RunnerからXcodeを呼び出す場合、最初に何を確認しますか。
Xcodeのバージョン名だけでなく、Runnerの実行ユーザーが同じ開発者ディレクトリとCommand Line Toolsへアクセスできるかを確認します。対話型ログインで設定した環境変数やキーチェーンを、そのまま非対話ジョブが利用できるとは限りません。

05

第四段階：署名ジョブを別系統にする

通常のコンパイルと署名付き公開を同じresource classへ置くと、証明書や秘密鍵へアクセスできるジョブが増えます。一般ビルド用とリリース用をタスク、アカウント、作業領域のいずれか、できれば複数の境界で分けてください。

署名分離で見るべき点

  • リリース用resource classを一般ビルドから指定できない。
  • 証明書、プロファイル、秘密鍵の保存場所を限定する。
  • ジョブログへ秘密値が出ない。
  • 失敗時に一時ファイルと署名関連の生成物を削除する。
  • 退職、端末交換、トークン漏えい時の失効経路を確認する。
  • 署名方式は、CircleCIと現在のチーム運用が公式に対応する方法だけを採用する。

CircleCIの自托管Runnerに関するセキュリティ情報を読み、実際の実行ユーザーの権限と、macOS側のキーチェーン設定を突き合わせます。実在する証明書名、アカウント名、トークン、キーチェーンパスワードは設定例へ書きません。

06

第五段階：再起動と連続実行で本番可否を決める

計画的な再起動を一度行い、Macの起動後にRunner、ジョブの再取得、Xcode呼び出し、SSHやVNCなどの管理経路が戻るかを確認します。自動ログインや手動起動が必要なら、24時間運用の前提は未成立です。

その後、連続ジョブで次の状態を見ます。

  • 前回の失敗ファイルが次のジョブへ残らない。
  • キャッシュが意図せず別ブランチへ影響しない。
  • 同じresource classにジョブが滞留したとき、待機理由を追跡できる。
  • ログの保存期間と取得権限が決まっている。
  • トークンの更新・失効後に、復旧手順を実行できる。

リモートMacの再起動後にRunnerを自動復旧させるにはどうしますか。
Runnerの起動設定だけでなく、macOSの起動状態、専用ユーザー、ネットワーク到達性、管理用SSHまたはVNCの復旧を一つの手順として確認します。公式の自托管Runner接続トラブルシューティングに照らし、管理画面がオンラインになる前後のログを残してください。

VpsMeshのリモートMacを使う場合も、いきなり署名付き公開へ移行するのではなく、プロジェクト期間に合わせて検証用ノードを確保し、無署名ビルド、再起動、作業領域の清掃を先に実施するのが安全です。必要なMacの調達条件は、日本語のMacレンタル案内や、Mac miniの構成と注文方法で確認できます。

自前のMac miniを常時稼働させる方法は、ハードウェア購入、設置場所、電源、障害交換、固定回線の管理が必要です。一般的なクラウドLinux環境はmacOS専用のXcodeツールチェーンを実行できず、仮想化環境も実機依存の署名やツール互換性で追加検証が発生します。短期の試験導入や開発チーム間の分離が目的なら、VpsMeshでリモートMacをレンタルし、検証済みのMac構築ノードとして使うほうが、購入前に運用上の弱点を洗い出しやすいです。

まずは署名を使わない最小ジョブでresource classとXcodeの経路を確認し、再起動後も同じ状態へ戻れることを証明してください。その証拠が揃ってから、署名情報を扱うリリースジョブを段階的に移すのが、CircleCI Machine Runner 3を本番へ入れる現実的な順序です。