CI/CD
vmpal run 在虚拟机的全新克隆中运行一个 CI 作业,然后删除这个克隆。每个作业都能得到一台干净的机器,就像全新的 CI 运行器,只不过它在你的 Mac 上,用的是你自己的环境。虚拟机只需准备一次,装好构建所需的工具即可。它适用于 GitHub Actions、GitLab CI,以及 Mac 上的任何 CI 运行器。
交给 AI 智能体
你的编程智能体可以替你完成这些设置。VMPal 以 vmpal help ci 的形式向它提供本页的操作指南。把它连接到 VMPal,然后向它提出请求,例如:
- “设置一个 GitHub Actions 作业,在我的 Ubuntu 虚拟机的全新克隆中运行测试。”
- “准备一台装有 Visual Studio Build Tools 的 Windows 虚拟机,用于 CI。”
- “添加一个 GitLab CI 作业,在我的 CI 虚拟机中构建这个应用,并把构建结果保存为产物。”
本页其余部分介绍其工作原理,供你想深入了解时参考。
一次性准备虚拟机
母版虚拟机(golden 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。- 新虚拟机会共享你的“下载”文件夹。macOS 可能会询问一次是否允许 VMPal 使用它。请在离开 Mac、让它运行作业之前先回应这个询问。
请让母版虚拟机保持关机状态,因为 run 要求如此。用 vmpal stop 或虚拟机的“关机”来关闭它。只关闭它的窗口是不够的,那样只会保存虚拟机。
以后要修改它,就启动它、做出更改,然后再次关机。
每个作业的屏幕都一样
虚拟机的显示器跟随其窗口,采用窗口所在屏幕的尺寸和缩放比例。因此,UI 测试和截图在不同作业之间可能会有差异。给母版虚拟机设置一个固定的显示器,每个克隆就都会得到相同的显示器:
vmpal set "CI Ubuntu" --display 1440x900@2x
这表示 1440 × 900 点、2 倍缩放,也就是 2880 × 1800 像素。无论在哪个屏幕上,甚至完全没有窗口时,显示器都保持这个尺寸,窗口则按比例缩放显示它。使用 @1x 可得到不带 Retina 缩放的显示器。在 Windows 虚拟机中,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'
这会把当前文件夹(例如你检出的代码)拷贝到虚拟机中的 src,在那里运行 make test,然后把 src/out 拷贝回 Mac 上的 ./out。run 会依次执行以下步骤:
- 克隆虚拟机。克隆是即时完成的,因为在写入之前,克隆与原虚拟机共享磁盘。
- 启动克隆,并等待它可以运行命令。
- 拷贝进你用
--copy-in指定的内容。 - 运行你的命令,并实时显示输出。
- 拷贝出你用
--copy-out指定的内容,即使命令失败也会拷贝。 - 关闭克隆,并将其永久删除。
它会在标准错误输出中打印克隆的名称和 ID。
和任何 CI 步骤一样,由退出码决定成功还是失败。run 以你的命令的退出码退出,因此作业的成败与你的命令一致。有两个代码是 run 自己的:
| 退出码 | 含义 |
|---|---|
124 |
命令运行超过了 --timeout(默认 2 小时) |
125 |
run 自身没能完成它的工作。例如,克隆没有在 10 分钟内准备就绪 |
--isolated 把你的 Mac 隔离在克隆之外。除了拷贝进去的内容,克隆得不到 Mac 上的任何东西:没有共享文件夹、转发端口、剪贴板、拖放、扬声器或麦克风,并且只使用共享网络。不加 --isolated 时,克隆会保留母版虚拟机共享的内容,例如你的“下载”文件夹,每个作业都可能读取和更改这个文件夹。你也可以在母版虚拟机中一次性停止共享它:vmpal set "CI Ubuntu" --unshare Downloads。
| 选项 | 作用 |
|---|---|
--copy-in <Mac path>:<VM path> |
在运行命令之前把指定内容拷贝到克隆中,方式与 cp 相同。可重复使用 |
--copy-out <VM path>:<Mac path> |
在命令运行之后把指定内容拷贝出来,即使命令失败也会拷贝。可重复使用 |
--cwd、--admin、--timeout |
与 exec 中的用法相同。虚拟机路径相对于用户的个人文件夹。使用 --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 随即停止你的命令并删除克隆。如果再收到一个信号,run 会立即退出,并打印克隆的名称和删除它的命令。
如果有克隆残留下来,vmpal list 会显示它。用 vmpal delete <VM> --force --permanently 删除它。
逐步执行
run 只运行一条命令。要在同一个克隆中运行多条命令,请自己完成它的各个步骤。这样的克隆不是隔离的,因此效果与不加 --isolated 的 run 相同。
trap 那一行确保无论步骤如何结束,克隆都会被删除:成功、失败、取消,以及因 shell 的 -e 而中止。GitHub 的 shell 就带有 -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 执行器。作业的写法如下:
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。GitHub 和 GitLab 的运行器就是这样安装的。不要让 Mac 进入睡眠。
vmpal会在后台打开 VMPal。在内存和 CPU 允许的范围内,多个作业可以同时运行,各自使用自己的克隆。 -
Windows 启动后会停在登录界面。
run会用 VMPal 为该虚拟机保存的密码登录。如果没有保存密码,它会等待有人登录,10 分钟后放弃。- 如果这个密码失效了,请在母版虚拟机中更新它,因为克隆会从那里拷贝密码。使用母版虚拟机的 设置 › 通用 › 账户 › 更新密码…,或者
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 在一台 Mac 上最多允许同时运行两台 macOS 虚拟机,包括你自己运行的和其他应用中的虚拟机。因此一次最多运行两个 macOS 作业,第三个作业会立即失败。
--admin需要先在母版虚拟机中获得批准,vmpal help exec介绍了方法。
vmpal help ci 中有更多内容。