CI/CD
vmpal run runs a CI job in a fresh clone of a VM, then deletes the clone. Each job gets a clean machine, like a fresh CI runner, but on your Mac and with your own setup. You prepare the VM once, with the tools your builds need. It works with GitHub Actions, GitLab CI, or any CI runner on your Mac.
Ask your AI agent
Your coding agent can set this up for you. VMPal gives it this walk-through as vmpal help ci. Connect it to VMPal, then ask it, for example:
- "Set up a GitHub Actions job that runs my tests in a fresh clone of my Ubuntu VM."
- "Prepare a Windows VM for CI with Visual Studio Build Tools."
- "Add a GitLab CI job that builds this app in my CI VM and keeps the build as an artifact."
The rest of this page is how it works, for when you want to know.
Prepare a VM once
The golden VM is the VM every job starts from, like a base image. Install what your builds need in it, once:
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 systemslists what you can install, such asdownload:windowsanddownload:macOS.- A new VM shares your Downloads folder. macOS may ask once to let VMPal use it. Answer that before you leave the Mac to run jobs.
Keep the golden VM shut down, because run needs it that way. Shut it down with vmpal stop or the VM's Shut Down. Closing its window isn't enough. That saves the VM instead.
To change it later, start it, make your changes, and shut it down again.
The same screen in every job
A VM's display follows its window, at the size and scale of the screen the window opens on. So UI tests and screenshots can differ from one job to the next. Give the golden VM a fixed display, and every clone gets the same one:
vmpal set "CI Ubuntu" --display 1440x900@2x
That's 1440 × 900 points at 2x, so 2880 × 1800 pixels. The display keeps that size on any screen, and with no window at all. The window shows it scaled to fit. Use @1x for a display without Retina scaling. In a Windows VM, 1x and 2x are 100% and 200% scaling. --display window follows the window again.
Run a job
vmpal run "CI Ubuntu" --isolated --copy-in .:src --copy-out src/out:./out -- /bin/sh -lc 'cd src && make test'
This copies the current folder, such as your checkout, into src in the VM. It runs make test there, then copies src/out back to ./out on your Mac. Here's what run does, in order:
- It clones the VM. Cloning is instant, because the clone shares the VM's disk until it writes.
- It starts the clone and waits until the clone can run commands.
- It copies in what you gave with
--copy-in. - It runs your command and shows its output as it comes.
- It copies out what you gave with
--copy-out, even when the command failed. - It turns the clone off and deletes it for good.
It prints the clone's name and ID on standard error.
The exit code decides pass or fail, as in any CI step. run exits with your command's exit code, so the job passes or fails with your command. Two codes are run's own:
| Exit code | Means |
|---|---|
124 |
The command ran past --timeout (2 hours by default) |
125 |
run itself couldn't do its part. For example, the clone didn't become ready within 10 minutes |
--isolated keeps your Mac out of the clone. The clone gets nothing of your Mac's but the copies. It has no shared folders, forwarded ports, clipboard, drag and drop, speakers or microphone, and it uses the shared network only. Without --isolated, the clone keeps what the golden VM shares, such as your Downloads folder. Every job could then read and change that folder. Or stop sharing it in the golden VM, once, with vmpal set "CI Ubuntu" --unshare Downloads.
| Option | What it does |
|---|---|
--copy-in <Mac path>:<VM path> |
Copies that into the clone before the command, the way cp does. Repeatable |
--copy-out <VM path>:<Mac path> |
Copies that out after the command, even when it failed. Repeatable |
--cwd, --admin, --timeout |
Work as they do for exec. VM paths are relative to the user's home. With --admin, the copies are made as administrator too |
--env NAME=value |
Sets an environment variable for the command. --env NAME passes this Mac's value of NAME, so a secret stays off the command line |
--cpus <n>, --memory <GB> |
Set the clone's CPUs and memory |
--name <name> |
Names the clone. The default is <VM> run <8 hex digits> |
--isolated |
Gives the clone nothing of your Mac's but the copies |
--in-background |
Starts the clone without its window |
--no-sign-in |
Doesn't sign in at the clone's sign-in screen |
--keep |
Keeps the clone, so you can look into it. Delete it later with vmpal delete |
Cancelling
When a job is cancelled, CI sends a SIGINT or SIGTERM. run then stops your command and deletes the clone. A second signal makes run exit at once. It then prints the clone's name and the command that deletes it.
If a clone was left behind, vmpal list shows it. Delete it with vmpal delete <VM> --force --permanently.
Step by step
run runs one command. To run several commands in one clone, do its steps yourself. The clone isn't isolated, so this works like run without --isolated.
The trap line deletes the clone however the step ends. That covers a pass, a failure, a cancel, and a stop by the shell's -e. GitHub's shell runs with -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
Install a self-hosted runner on the Mac. A job then looks like this:
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
execmakesvmpalthe step's own process. When the job is cancelled, the signal then reachesvmpal, and it deletes the clone.if: always()uploadsouteven when the tests fail.
GitLab CI
Install GitLab Runner on the Mac, with the shell executor. A job then looks like this:
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 keeps out even when the tests fail.
Good to know
-
The runner. Install it on the Mac as the logged-in user's LaunchAgent. GitHub's and GitLab's runners install that way. Keep the Mac from sleeping.
vmpalopens VMPal in the background. Jobs run at the same time, each in its own clone, as far as memory and CPUs allow. -
Windows starts at its sign-in screen.
runsigns in with the password VMPal keeps for the VM. Without a kept password, it waits for someone to sign in, and gives up after 10 minutes.- If that password stops working, update it in the golden VM, because clones copy it from there. Use the golden VM's Settings › General › Account › Update Password…, or
vmpal set "CI Windows" --account-password-file <file>. Give-as the file to read the password from standard input. - Commands need
cmd.exeorpowershell.exe. They run with standard rights unless you give--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 - If that password stops working, update it in the golden VM, because clones copy it from there. Use the golden VM's Settings › General › Account › Update Password…, or
-
macOS allows at most two macOS VMs at a time on a Mac. That count includes the ones you run yourself and those in other apps. So run at most two macOS jobs at once. A third job fails right away.
--adminneeds approval in the golden VM first, andvmpal help execsays how.
vmpal help ci has more.