本文へスキップ

ドキュメント コマンドライン コマンドライン

CI/CD

vmpal runは、VMの新しいクローンでCIジョブを実行し、終わったらクローンを削除します。どのジョブも、まっさらなCIランナーと同じようにクリーンなマシンで実行されますが、動くのは自分のMac上で、環境も自分で用意したものです。ビルドに必要なツールを入れたVMを一度用意するだけで済みます。GitHub Actions、GitLab CI、そのほかMac上で動くどのCIランナーでも使えます。

AIエージェントに頼む

この設定はコーディングエージェントに任せられます。VMPalは、このページと同じ手順をvmpal help ciとしてエージェントに渡します。エージェントをVMPalに接続してから、たとえば次のように頼みます。

  • 「UbuntuのVMの新しいクローンでテストを実行するGitHub Actionsのジョブを設定して。」
  • 「Visual Studio Build Toolsを入れて、CI用のWindows VMを準備して。」
  • 「CI用のVMでこのアプリをビルドして、ビルドをアーティファクトとして残すGitLab CIのジョブを追加して。」

このページの残りでは、しくみを知りたい方のために動作を説明します。

VMを一度準備する

ゴールデンVMは、すべてのジョブの出発点になるVMで、ベースイメージのようなものです。ビルドに必要なものを、一度だけインストールしておきます。

vmpal create download:ubuntu --name "CI Ubuntu" --cpus 4 --memory 8 --wait
vmpal exec "CI Ubuntu" --admin -- apt-get update
vmpal exec "CI Ubuntu" --admin -- apt-get install -y build-essential git
vmpal stop "CI Ubuntu"
  • インストールできるものはvmpal systemsで一覧表示できます。download:windowsやdownload:macOSなどがあります。
  • 新しいVMはダウンロードフォルダを共有します。macOSが、VMPalにダウンロードフォルダの使用を許可するかどうかを一度だけ尋ねることがあります。ジョブを実行させたままMacから離れる前に、これに答えておきましょう。

runを使うには、ゴールデンVMをシャットダウンしておく必要があります。vmpal stopか、VMの「シャットダウン」でシャットダウンしてください。ウインドウを閉じるだけでは不十分です。ウインドウを閉じると、VMはシャットダウンされずに保存されます。

あとで変更するには、VMを起動して変更を加え、再びシャットダウンします。

どのジョブでも同じ画面に

VMのディスプレイはウインドウに追従し、ウインドウを開いた画面のサイズとスケールに合わせて変わります。そのため、UIテストやスクリーンショットの結果がジョブごとに異なることがあります。ゴールデンVMのディスプレイを固定しておけば、すべてのクローンが同じディスプレイになります。

vmpal set "CI Ubuntu" --display 1440x900@2x

これは2xの1440 × 900ポイント、つまり2880 × 1800ピクセルです。ディスプレイは、どの画面でも、ウインドウがまったくなくても、このサイズのままです。ウインドウには収まるように拡大・縮小して表示されます。Retinaのスケーリングを使わないディスプレイには@1xを使います。WindowsのVMでは、1xと2xはそれぞれ100%と200%のスケーリングになります。--display windowを指定すると、再びウインドウに追従します。

ジョブを実行する

vmpal run "CI Ubuntu" --isolated --copy-in .:src --copy-out src/out:./out -- /bin/sh -lc 'cd src && make test'

このコマンドは、チェックアウトしたリポジトリなどの現在のフォルダを、VM内のsrcにコピーします。そこでmake testを実行し、src/outをMacの./outにコピーして戻します。runは次の順に処理を行います。

  1. VMをクローンします。クローンは書き込みが発生するまでVMのディスクを共有するため、一瞬で作成されます。
  2. クローンを起動し、コマンドを実行できるようになるまで待ちます。
  3. --copy-inで指定したものをコピーします。
  4. コマンドを実行し、出力を逐次表示します。
  5. --copy-outで指定したものを、コマンドが失敗した場合でもコピーして取り出します。
  6. クローンの電源をオフにし、完全に削除します。

クローンの名前とIDは標準エラー出力に表示されます。

一般的なCIのステップと同じく、成功か失敗かは終了コードで決まります。runはコマンドの終了コードで終了するため、ジョブの成否はコマンドの成否と一致します。次の2つのコードはrun独自のものです。

終了コード 意味
124 コマンドが--timeout(デフォルトは2時間)を超えて実行された
125 run自体が処理を完了できなかった。たとえば、クローンが10分以内に準備できなかった

--isolated:クローンをMacから切り離します。クローンが受け取るのは、コピーしたものだけです。共有フォルダ、転送ポート、クリップボード、ドラッグ&ドロップ、スピーカー、マイクは使えず、ネットワークは共有ネットワークだけを使います。--isolatedを付けない場合、クローンはダウンロードフォルダなど、ゴールデンVMが共有しているものをそのまま引き継ぎます。その場合、どのジョブもそのフォルダを読み書きできてしまいます。あるいは、vmpal set "CI Ubuntu" --unshare DownloadsでゴールデンVMの共有を一度解除しておく方法もあります。

オプション 動作
--copy-in <Mac path>:<VM path> コマンドの前に、cpと同じ方法でクローンにコピーします。複数回指定できます
--copy-out <VM path>:<Mac path> コマンドのあとに、コマンドが失敗した場合でもコピーして取り出します。複数回指定できます
--cwd、--admin、--timeout execと同じように動作します。VMのパスはユーザのホームからの相対パスです。--adminを付けると、コピーも管理者として行います
--env NAME=value コマンドの環境変数を設定します。--env NAMEはこのMacのNAMEの値を渡すので、シークレットをコマンドラインに書かずに済みます
--cpus <n>、--memory <GB> クローンのCPU数とメモリを設定します
--name <name> クローンに名前を付けます。デフォルトは<VM> run <8 hex digits>です
--isolated コピー以外は、Macのものを何もクローンに渡しません
--in-background ウインドウを開かずにクローンを起動します
--no-sign-in クローンのサインイン画面でサインインしません
--keep 中を調べられるように、クローンを残します。あとでvmpal deleteで削除してください

キャンセル

ジョブがキャンセルされると、CIはSIGINTまたはSIGTERMを送ります。するとrunはコマンドを停止し、クローンを削除します。2回目のシグナルを受け取ると、runはすぐに終了します。このとき、クローンの名前と、クローンを削除するためのコマンドを表示します。

クローンが残ってしまった場合は、vmpal listに表示されます。vmpal delete <VM> --force --permanentlyで削除してください。

手順を分けて実行する

runが実行するコマンドは1つです。1つのクローンで複数のコマンドを実行するには、その手順を自分で行います。このクローンは切り離されていないため、--isolatedなしのrunと同じように動作します。

trapの行は、ステップがどのように終わってもクローンを削除します。成功、失敗、キャンセル、シェルの-eによる停止のどの場合もです。GitHubのシェルは-e付きで実行されます。

vm=$(vmpal clone "CI Ubuntu" --name "ci-$GITHUB_RUN_ID" --start --wait -q)
trap 'vmpal delete "$vm" --force --permanently' EXIT; trap 'exit 130' INT; trap 'exit 143' TERM
vmpal cp . "$vm:src"
vmpal exec "$vm" --cwd src -- make test || status=$?
vmpal cp "$vm:src/out" ./out
exit "${status:-0}"

GitHub Actions

Macにセルフホストランナーをインストールします。ジョブは次のようになります。

jobs:
  test:
    runs-on: [self-hosted, macOS, ARM64]
    steps:
      - uses: actions/checkout@v7
      - run: exec vmpal run "CI Ubuntu" --isolated --copy-in .:src --copy-out src/out:./out -- /bin/sh -lc 'cd src && make test'
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: out
          path: out
  • execにより、vmpalがステップのプロセスそのものになります。そのため、ジョブがキャンセルされるとシグナルがvmpalに届き、クローンが削除されます。
  • if: always()により、テストが失敗した場合でもoutをアップロードします。

GitLab CI

MacにGitLab Runnerをインストールし、shell executorを使います。ジョブは次のようになります。

test:
  script:
    - vmpal run "CI Ubuntu" --isolated --copy-in .:src --copy-out src/out:./out -- /bin/sh -lc 'cd src && make test'
  artifacts:
    when: always
    paths: [out/]

when: alwaysにより、テストが失敗した場合でもoutを残します。

知っておきたいこと

  • ランナー:ログインしているユーザのLaunchAgentとしてMacにインストールします。GitHubとGitLabのランナーは、この方法でインストールされます。Macはスリープしないようにしておきます。vmpalはVMPalをバックグラウンドで起動します。ジョブは、メモリとCPUが許す限り、それぞれ専用のクローンで同時に実行されます。

  • Windowsはサインイン画面で起動します。runは、VMPalがそのVM用に保存しているパスワードでサインインします。保存されたパスワードがない場合は、誰かがサインインするのを待ち、10分で打ち切ります。

    • そのパスワードが使えなくなった場合は、ゴールデンVMでパスワードを更新してください。クローンはゴールデンVMからパスワードをコピーするためです。ゴールデンVMの設定 › 一般 › アカウント › パスワードを更新…、またはvmpal set "CI Windows" --account-password-file <file>を使います。ファイルに-を指定すると、標準入力からパスワードを読み込みます。
    • コマンドにはcmd.exeまたはpowershell.exeが必要です。--adminを付けない限り、標準の権限で実行されます。
    vmpal create download:windows --name "CI Windows" --wait
    vmpal stop "CI Windows"
    vmpal run "CI Windows" --isolated --copy-in .:src --cwd src -- powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File build.ps1
    
  • macOSでは、1台のMacで同時に実行できるmacOSのVMは最大2台です。この数には、自分で実行しているVMや、ほかのアプリのVMも含まれます。そのため、同時に実行するmacOSのジョブは2つまでにしてください。3つ目のジョブはすぐに失敗します。--adminを使うには、まずゴールデンVMで承認が必要です。手順はvmpal help execで確認できます。

詳しくはvmpal help ciをご覧ください。