チーム向けビルド導入ガイド

ランナー導入はこのガイドで

Apple Silicon M4搭載のMac miniを1台まるごとチーム専用で利用できます。インスタンスと接続情報を確認し、ランナーを登録してからXcodeツールチェーンを固定しましょう。問題のある工程だけを切り分けられるので、パイプライン全体をやり直す必要はありません。

ビルドノードを契約 既存インスタンスを確認

既存の注文はコンソールで状態を確認してください。登録トークン、SSHパスワード、署名情報を公開ログに記載しないでください。

注文から接続まで

4つのポイントでノードを確認

支払い確認後、接続情報を取得して確認するまでの目安は約4分です。所要時間は手順の参考値であり、決済ゲートウェイの確認、ネットワークの再試行、依存関係のインストール、ランナー登録にかかる時間は含みません。実際の進行状況はコンソールの表示をご確認ください。

  1. 確認済みの注文を確認

    目安 30秒

    コンソールで注文の支払いが完了していることを確認し、機種、期間、ノードが購入内容と一致しているか確認します。Merge M4 Sは16GB RAM / 256GB SSD、Merge M4 Lは24GB RAM / 512GB SSDです。どちらもApple Silicon M4を搭載しています。

    ここで止まったら：まず請求の状態を確認してください。画面がまだ更新されていないからといって、支払いを繰り返さないでください。注文番号を控え、このページの請求セクションで支払い記録を確認します。

  2. 物理ノードの割り当てを確認

    目安 2分

    注文に紐づくインスタンスの詳細を開き、システムからインスタンスの状態と接続情報が返されるまで待ちます。各マシンは1人のお客様専用で、仮想マシンではありません。同じチーム内のジョブは、設定したランナーで管理します。

    ここで止まったら：インスタンスID、注文番号、現在の状態を控え、コンソールからサポートチケットを送信してください。「請求の支払い完了」と「インスタンスの認証情報が生成済み」は別の状態です。

  3. 接続情報を確認

    目安 1分

    インスタンス詳細からSSHのアドレス、ポート、ユーザー名、VNC接続情報を確認します。各項目に表示された値をそのまま使い、既定のポートを推測したり、以前のインスタンスのアドレスやパスワードを使い回したりしないでください。

    ここで止まったら：現在ログイン中のアカウントが対象の注文を所有していることを確認し、正しいインスタンスを開いているか確認してください。サポートチケットにはインスタンスIDと不足している項目名のみ記載し、パスワード全体は送らないでください。

  4. リモート接続をテスト

    目安 30秒

    SSHはコマンドラインでのビルド、ランナーの登録、ファイル同期に使います。VNCはXcodeのGUI、シミュレーター、対話型の設定に使います。macOSのGUIとコマンドラインの両方を利用でき、組み合わせて作業できます。

    ssh -p "$SSH_PORT" "$SSH_USER@$SSH_HOST"
uname -m
sw_vers

    初回接続時はホストフィンガープリントを確認します。接続できたら、アーキテクチャの出力が arm64であることを確認します。タイムアウトする場合はアドレス、ポート、ローカルネットワークを確認してください。認証に失敗する場合はユーザー名と認証情報を確認します。フィンガープリントの異常を回避するために、ホスト認証を無効にしないでください。

    VNCクライアントには、インスタンス詳細に記載されたVNC用の項目を使ってください。SSHのポートをそのまま使うことはできません。接続できても画面表示が遅い場合は、まず解像度を下げてください。自動ビルドは引き続きSSHで実行できます。

インスタンスと認証情報を確認 リモート接続ガイドを読む

既存のチームCIを利用

ジョブをこのM4に割り当てる

まずCIプラットフォームのランナーまたはエージェント追加画面から、インストーラーと登録コマンドを取得し、ノード上で実行します。以下では登録の要点のみ説明します。トークン、組織のURL、作業ディレクトリはプラットフォームで生成されるため、例の変数をそのまま使わないでください。インストール後は、署名情報を含まないテストジョブを実行します。

GitHub Actions

リポジトリまたは組織の設定でself-hosted runnerを追加し、macOSとARM64のパッケージを選択します。展開後、runnerディレクトリでプラットフォームが提示する設定コマンドを実行し、プロセスを起動します。

./config.sh \
  --url "$RUNNER_URL" \
  --token "$RUNNER_TOKEN" \
  --labels macos-m4
./run.sh

ワークフローで runs-on: [self-hosted, macOS, ARM64, macos-m4]を指定し、ラベルが登録結果と一致することを確認します。ラベルはジョブの振り分けに使われるもので、マシン上でジョブが自動的に分離されるわけではありません。

確認ポイント：プラットフォーム上でオンラインと表示され、テストジョブの uname -m の出力が arm64であることを確認します。常時稼働させる場合は、インストーラーに付属するサービスの説明に従って設定し、同じビルドユーザーで実行してください。

推奨ラベル：macos-m4

GitLab Runner

プロジェクトまたはグループでランナーを作成し、現在のバージョンで使う認証トークンを取得します。ARM64版をインストールして登録し、shell executorを選択します。ジョブはそのビルドユーザーのmacOS環境で実行されます。

gitlab-runner register
gitlab-runner verify
gitlab-runner run

プラットフォームでランナーに macos-m4 ラベルを設定し、ジョブの tags にも同じ値を指定します。対話形式で登録する際は、プラットフォームが提示するURLとトークンを入力してください。トークンをリポジトリに保存しないでください。

確認ポイント：ランナーが正しいプロジェクトに紐づき、ジョブが実行状態に進むことを確認します。待機が続く場合は、ラベル、保護ブランチの設定、ランナーのプロジェクト権限を確認してから、マシンの負荷を確認してください。

実行方式：shell

Jenkinsエージェント

専用ノードを作成し、リモート作業ディレクトリと macos-m4 ラベルを設定します。コントローラーの指示に従って互換性のあるJavaをインストールし、コントローラーから提供されたエージェントファイルをダウンロードして、生成された起動パラメーターを使います。

java -jar agent.jar \
  -url "$JENKINS_URL" \
  -secret "$AGENT_SECRET" \
  -name "$AGENT_NAME" \
  -webSocket \
  -workDir "$AGENT_WORKDIR"

パイプラインで agent { label 'macos-m4' }を指定します。作業ディレクトリにはビルドユーザーの書き込み権限が必要です。Javaのバージョンはコントローラーの要件に合わせてください。ローカルターミナルでJavaが起動できるかどうかだけで判断しないでください。

確認ポイント：コントローラー上でノードがオンラインと表示され、ワークスペースが想定したディレクトリにあることを確認します。まずexecutorを1つにして基準を取り、メモリ、ディスク、テスト負荷に応じて並列数を検討してください。

まず単一ジョブで確認

マシン全体を専有できるため、他のお客様とのCPU競合はありません。ただし、チーム内のジョブ待ち行列は別途管理が必要です。同じランナーで複数のジョブを同時に実行する場合は、並列数、ワークスペース、署名情報の分離をチームで設定してください。

再現可能な環境を固定

ローカルとCIで同じXcodeを使う

「ターミナルではビルドできるのに、ランナーでは失敗する」場合、ツールチェーンのパスや実行ユーザーの違いが原因であることがよくあります。まず現在のバージョンを記録し、ツールチェーンを選択してから必要なシミュレーターランタイムを追加してください。最初からXcodeを再インストールする必要はありません。

切り替える前にバージョンを記録

複数のXcodeは、それぞれ別のアプリケーションパスに配置できます。以下のコマンドでシステム情報、現在の開発ディレクトリ、ビルドツールのバージョンを記録し、プロジェクトの要件と照合してください。

sw_vers
xcode-select -p
xcodebuild -version
xcrun --find swift

マシン全体のデフォルトを変更する場合は、 xcode-selectを使います。切り替える前に、ほかのビルドが実行中でないことを確認し、CIの実行ユーザーでも結果を再確認してください。

sudo xcode-select --switch \
  /Applications/Xcode.app/Contents/Developer
xcodebuild -version

ジョブごとに選択し、プロジェクトごとに追加

チームで複数バージョンのXcodeを使う場合は、各ジョブに DEVELOPER_DIRを設定して、全体設定の切り替えによる影響を抑えます。例のパスは、ノード上に実在するバージョンのディレクトリに置き換えてください。

export DEVELOPER_DIR="/Applications/Xcode.app/Contents/Developer"
xcodebuild -version
xcrun simctl list runtimes
xcrun simctl list devices available
df -h

Xcodeの設定で、プロジェクトの要件に合わせてシミュレーターランタイムをダウンロードします。ランタイム、シミュレーターのデータ、DerivedDataはすべてディスクを使用します。インストール前に空き容量を確認し、チームで実際に使うバージョンだけを残してください。

コマンドが使えるだけでは、プロジェクトの依存関係がすべて揃っているとは限りません。同じユーザーでRuby、CocoaPods、パッケージマネージャー、プロジェクトのロックファイルを確認してください。初回インストール時の確認プロンプトには、まず対話環境で応答します。

最初のビルドを実行する前に、ランナーの実行環境で次の3点を確認
確認項目確認するコマンド・場所合格条件
ツールチェーンのパスxcode-select -p とジョブの環境変数プロジェクトで指定されたXcodeを参照し、バージョンが想定どおりであること
実行ユーザーwhoami、printf '%s\n' "$HOME"ビルドユーザー、ホームディレクトリ、キーチェーンの所有ユーザーが一致すること
ワークスペースとディスクpwd、df -hワークスペースに書き込みでき、依存関係、作業ファイル、アーカイブに十分な空き容量があること

チーム内の用語を統一

8つの用語で押さえる8つの違い

マシン、接続方法、ジョブの振り分けを分けて考えると、問題がどの層で起きているか正確に伝えられます。

物理ノード
macOSとビルドジョブを実行するMac mini本体です。インスタンス詳細の接続情報は、契約中のノードに対応しています。
専用
マシン全体が1人のお客様に割り当てられ、ほかのお客様とCPUを共有しません。チーム内のジョブの並列実行は別途管理が必要です。
仮想マシンではない
共有ホストから切り分けた仮想インスタンスではなく、専用の物理Mac環境を利用できます。
VNC
macOSのGUIをリモートで表示・操作する接続方式です。Xcode、シミュレーター、対話型の設定に適しています。
SSH
暗号化されたコマンドライン接続方式です。ビルドコマンドの実行、プロセス管理、対応ツールによるファイル転送に使えます。
セルフホストランナー
チームが自分たちのノードに登録して管理するCI実行プログラムです。CIプラットフォームからジョブを受け取り、実行します。
Apple Silicon
Macに搭載されているApple製チップのアーキテクチャです。本サービスの2機種はどちらもM4です。依存関係やランナーパッケージがarm64に対応しているか確認してください。
Thunderbolt 5接続
ディレクトリに記載された、台数ごとに料金が発生する接続オプションです。複数台のCPUやメモリが自動的に1台分に統合されるわけではなく、ワークロードの構成は別途必要です。

ログを残してから環境を変更

エラーの発生箇所からビルドを復旧

まず失敗したコマンド、終了コード、最初の有効なエラーを保存し、変更する変数を1つに絞って再実行します。Xcodeの切り替え、キャッシュの削除、ランナーの再登録を同時に行うと、どの変更で解決したのか分からなくなります。

署名エラー：まず実行ユーザーとキーチェーンを確認

まず「コンパイルエラー」と「署名エラー」を切り分けます。アーカイブまたは署名の段階でエラーが出た場合に限り、署名証明書、対応する秘密鍵、プロビジョニングプロファイル、有効期限を確認してください。これらの情報はプロジェクトの要件に合わせてチームで設定します。

whoami
security list-keychains -d user
security find-identity -v -p codesigning

GUIでは署名できるのにCIで失敗する場合は、ランナーが同じユーザーで起動しているか、対象のキーチェーンが検索対象に含まれているか、非対話型プロセスに必要なアクセス権があるかを確認してください。キーチェーンのロック解除が必要な場合は、CIの保護されたシークレットから認証情報を渡してください。パスワードをスクリプト、コマンド履歴、ログに記載しないでください。

証明書のインポート後は、プロビジョニングプロファイルのチーム、アプリ識別子、ビルド設定も確認してください。サポートチケットには、機密情報を除いたエラーのみ添付してください。秘密鍵、証明書のパスワード、署名情報全体はアップロードしないでください。

キャッシュの問題：まず対象プロジェクトだけを整理

同じコミットで再実行し、Xcodeのバージョンを記録します。特定の依存関係だけの解決に失敗する場合は、まずロックファイル、依存関係のバージョン、ダウンロードエラーを確認してください。ネットワークの失敗は、キャッシュを何度もすべて削除しても解決しません。

プロジェクト専用のDerivedDataパスを設定すると、そのプロジェクトの生成物だけを再ビルドできます。以下のコマンドは、すでに分離されたワークスペース向けです。実行前に変数を実際のパスと共有スキームに置き換えてください。

xcodebuild \
  -workspace "$WORKSPACE" \
  -scheme "$SCHEME" \
  -derivedDataPath "$PROJECT_DERIVED_DATA" \
  clean build

clean を実行すると、次回のビルドに時間がかかります。複数のジョブで同じ書き込み可能なキャッシュディレクトリを共有しないでください。削除や移行の前に、そのディレクトリを使用中のジョブを停止してください。

ディスク容量不足：キャッシュ、ランタイム、生成物を切り分ける

まず空き容量を確認し、DerivedData、アーカイブ、シミュレーターのデータが実際にどれだけ容量を使っているか調べます。ユーザーディレクトリ全体を再帰的に削除したり、アーカイブのアップロード中に生成物を削除したりしないでください。

df -h
du -sh "$HOME/Library/Developer/Xcode/DerivedData"
du -sh "$HOME/Library/Developer/Xcode/Archives"
du -sh "$HOME/Library/Developer/CoreSimulator"

関連するジョブを停止してから、使われていないプロジェクトキャッシュを削除し、Xcodeで不要なランタイムを削除します。バックアップ済みの過去のアーカイブは、チームの保管ルールに従って整理してください。プロジェクト、署名情報、リリース成果物は個別にバックアップが必要です。

長期的に容量が必要な場合は、注文時に+1TB SSDまたは+2TB SSDの追加オプションを検討できます。ストレージの増設でメモリが増えるわけではありません。ジョブの並列実行ではなく、ディスクがボトルネックかどうかを先に確認してください。

ランナーがオフライン：接続、プロセス、権限を順に確認

まずSSHでノードに接続できることを確認し、次にランナーのプロセスとログを調べます。ノードに接続できるのにCIプラットフォーム上でオフラインの場合は、プロセスが終了していないか、CIコントローラーにネットワーク接続できるか、トークンやノードの権限が変更されていないかを確認してください。

ランナーをフォアグラウンドで一度起動し、最初に表示された接続エラーを保存します。フォアグラウンドでは動作するのに、ターミナルを終了すると停止する場合は、そのランナーの手順に従って常駐サービスを設定してください。サービスの実行ユーザーは、ツールチェーン、作業ディレクトリ、キーチェーンの設定と一致させます。

再起動する前に、アーカイブやアップロードが実行中でないことを確認してください。処理中の生成物が不完全になるおそれがあります。プラットフォーム上でオンラインなのにジョブがキューに残る場合は、ランナーを何度も削除して登録し直すのではなく、ラベル、ブランチ権限、並列数の制限を確認してください。

複数のインスタンスグループやプールを使う場合は、ノードに識別しやすいラベルを追加します。たとえば macos-m4-build と macos-m4-releaseを設定すれば、リリースジョブを、対応する署名環境を設定したノードだけに振り分けられます。

取引を確認してから再試行

支払い記録を注文と照合

日単位、週単位、月単位、四半期単位で料金が発生し、すべて米ドル（USD）で決済されます。対応する支払い方法はUSDT-TRC20、およびStripe経由のVisa / Mastercard / Amexのみです。利用できる決済ゲートウェイはバックエンドの応答をご確認ください。

USDT-TRC20を送金したのに注文が確認待ち

注文の支払いページに表示されたネットワーク、送金先アドレス、金額をそれぞれ確認してください。送金記録があっても注文が確認済みとは限りません。ブロックチェーン上の取引状態とコンソールの請求状態の両方を確認します。

確認を急ぐために再送金しないでください。また、別の注文の支払い情報を現在の注文に使わないでください。注文番号、トランザクションハッシュ、金額、送金日時を控え、コンソールからサポートチケットを送信してください。ウォレットの秘密鍵やリカバリーフレーズは送らないでください。

支払いページを閉じてしまった場合は、まず同じ注文に戻って現在の状態を確認してから、支払いを続けるか判断してください。同じサービスへの重複支払いを避けられます。

カード決済が完了しない場合は、認証とカード発行会社の結果を確認

カード情報と請求先情報に誤りがないか、利用可能額が足りているか、カード発行会社の認証が完了しているか確認してください。リダイレクト先のページがブロックされた場合は、現在の決済手続きに必要なページを開けるようにしてから、注文の状態を確認します。

決済が拒否された場合は、エラーの概要を保存し、カード発行会社に取引制限を確認してください。短時間に何度も送信しないでください。銀行側で引き落としが記録されているのに注文が未確認の場合は、すぐに再決済せず、まずサポートチケットで確認してください。

サポートチケットには注文番号、発生日時、機密情報を除いたエラーのスクリーンショットを添付してください。カード番号全桁、セキュリティコード、銀行の認証コードを送る必要はありません。

更新前にインスタンス、期間、期限を確認

コンソールから既存インスタンスに対応するサブスクリプションまたは請求を開き、インスタンスID、期限、請求対象の期間を確認してから支払います。新規注文と既存インスタンスの更新は別の手続きです。機種名だけで判断しないでください。

更新が完了したかどうかは、請求とインスタンスの状態で確認してください。自動更新されるとは限りません。期限前にプロジェクト、キャッシュ方針、リリース成果物をバックアップしてください。インスタンス解放後のディスク消去を、復元できるバックアップとして扱わないでください。

ノードは年間365日稼働しています。サービスの稼働状況に関する問題は、インスタンスID、影響を受けた時間帯、接続エラーを添えてお問い合わせください。ユーザーがプロセスを停止した場合と、ノードが利用できない場合を混同しないでください。

再現に必要な情報を添える

状況をサポートに伝える

既存インスタンスの問題は、コンソールからサポートチケットを送信してください。インスタンスID、発生日時とタイムゾーン、失敗した手順、期待した結果、機密情報を除いたログを添付します。複数台の起動やランナープールの計画については、お問い合わせページで要件を整理するか、 support@vpsmerge.comまでメールでご連絡ください。

パスワード、登録トークン、秘密鍵、支払い情報全体は送らないでください。画面いっぱいの重複ログより、最初に発生した有効なエラーを残すほうが原因を特定しやすくなります。

コンソールからサポートチケットを送信 チームからの問い合わせ内容を整理