跳到正文

文档 命令行 命令行

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 会依次执行以下步骤:

  1. 克隆虚拟机。克隆是即时完成的,因为在写入之前,克隆与原虚拟机共享磁盘。
  2. 启动克隆,并等待它可以运行命令。
  3. 拷贝进你用 --copy-in 指定的内容。
  4. 运行你的命令,并实时显示输出。
  5. 拷贝出你用 --copy-out 指定的内容,即使命令失败也会拷贝。
  6. 关闭克隆,并将其永久删除。

它会在标准错误输出中打印克隆的名称和 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 中有更多内容。