ドキュメント

ランナーの登録は10分で終わります

MacRunのマシンは、標準的なGitHub Actionsのセルフホストランナーです。パイプラインはそのままで、YAMLを2行変えるだけです。

マシンに接続する

マシンは公開インターネットではなく、Tailscaleのプライベートネットワーク上にあります。そのため、狙われるSSHポートもなく、守りを固める作業も不要です。接続に必要なのは、最初の一度だけの2つの作業です。

tailscale.com/download からTailscaleをインストールし、サインインします。個人利用は無料です。ここで多くのチームが必要とするアカウント規模でも無料です。macOS、Linux、Windowsで動きます。マシンの準備ができたら共有の招待をお送りするので、承認してください。アクセスできるのはそのマシン1台だけで、私たちのネットワーク上のほかのものには一切アクセスできません。

ポータルには、マシンのアドレスが入った正確なコマンドが表示されます。

ssh runner@100.x.x.x

管理すべきパスワードや鍵はありません。認証はTailscaleが行います。Tailscaleアカウントのメールアドレスが請求先と違う場合は、ポータルからそのアドレス向けの共有をリクエストしてください。

CIのジョブにTailscaleは不要です。GitHub Actionsは、GitHub自身の外向き接続でランナーに届きます。Tailscaleは、マシンのシェルを使いたいときのためだけのものです。

必要なときは画面を開く

CIにはSSHで十分です。ログだけでは足りないときは、同じプライベートネットワーク経由の画面共有で同じマシンにつながります。Instruments、シミュレーター、XcodeのUIが、手元のMacと同じように動きます。ポータルには、アドレス、ユーザー名 runner、契約ごとに固有のパスワードが表示されます。

Macの場合、Finderを開き、「移動」 → 「サーバへ接続」（⌘K）を選びます。

vnc://100.x.x.x

Windowsの場合、 RealVNC Viewer かTightVNCをインストールし、 100.x.x.x:5900 に接続します。 Linuxの場合、RemminaとTigerVNCのどちらも使えます。アドレスは同じです。クライアントがパスワードだけを求める場合は、ユーザー名を空欄のままにしてください。

これは、ほとんどのCIサービスにはできないことです。ホステッドランナーで得られるのはログだけです。Instrumentsでしか再現しないクラッシュは、調べようがありません。

GitHubから登録トークンを取得する

リポジトリ（またはOrganization）で Settings → Actions → Runners → New runner を開きます。GitHubが1回限りのトークンを表示します。これを下のコマンドに貼り付けます。Organizationレベルのランナーは、そのOrganizationのすべてのリポジトリで共有されます。

マシンにランナーを登録する

上と同じ方法でSSHで入り、ポータルにある設定コマンドを実行します（マシンのラベルは入力済みです）。

cd ~/actions-runner
./config.sh --url https://github.com/YOUR-ORG/YOUR-REPO \
  --token <RUNNER_TOKEN> \
  --labels self-hosted,macOS,macrun-unit-01 \
  --unattended

# start it as a service (survives reboots)
./svc.sh install && ./svc.sh start

runner-agentデーモンが、このサービスを自動で動かし続けます。クラッシュしても、30秒以内に再起動します。

YAMLを2行変える

ワークフローからランナーを指定します。変更点はこれだけです。

 jobs:
   build:
-    runs-on: macos-latest
+    runs-on: [self-hosted, macOS, macrun-unit-01]

パイプラインのそれ以外の部分は、まったく変わりません。

Xcodeのバージョン

最近のXcodeはプリインストール済みで、 xcodes でバージョンが固定されています。ジョブの中で選ぶか、ポータルから新しいバージョンをリクエストしてください（たいてい当日中に対応します）。

- run: sudo xcodes select 26.6
- run: xcodebuild -version

キャッシュは最初から温まっています

マシンはあなた専用なので、キャッシュは実行の間もローカルディスクに残ります。毎回ダウンロードし直す無駄はありません。よく使うパスは次のとおりです。

~/Library/Developer/Xcode/DerivedData   # build cache
~/Library/Caches/CocoaPods              # pods
~/.gradle  ~/.npm  ~/.gem               # toolchain caches
~/Library/Caches/org.swift.swiftpm      # SwiftPM

復元キーを確定的にしたい場合は、今までどおり actions/cache も使えます。ただ、ほとんどのiOSビルドでは、温まったローカルディスクのほうが効果的です。

マシンを管理する

再起動、Xcodeのバージョンのリクエスト、請求の管理はポータルから行えます。ほかに必要なことがあれば、MacRunからのどのメールに返信してもかまいません。人間が返信します。