dragonflybsd-vm

Running DragonFly BSD in GitHub Actions

GitHub Actions runners only offer Ubuntu, Windows, and macOS. The vmactions/dragonflybsd-vm action fills the gap for projects that need to test on DragonFly BSD. It boots a DragonFly BSD virtual machine on an ubuntu-latest runner using QEMU and then runs the user's commands inside that guest. The README states the latest major version is v1 and the latest full version is v1.3.3. People moving from the older v0 release are told to set runs-on to ubuntu-latest, since the action itself always launches the VM from a Linux host. This lets a team keep one CI definition while still exercising BSD specific behavior that Linux runners would never catch.

The README shows a minimal test.yml to demonstrate the flow. The workflow listens on push, checks out the code with actions/checkout, and then calls vmactions/dragonflybsd-vm@v1. The with block passes an envs list of variable names to forward, a prepare script that installs packages such as socat with pkg, and a run script that prints the working directory, lists files, reports the user and environment, runs uname, and echoes OK. The envs field names the secrets and variables copied into the VM. The run block is the actual command executed in the guest. All of the host source tree is synchronized into the VM, the working directory matches the host, and the GITHUB plus CI variables arrive inside the guest. The prepare and run scripts always execute with sh no matter what the default login shell of the BSD image is.

Choosing sync method, release, and architecture

The action copies code between host and guest through a selectable sync method. The default is rsync, and the README also documents sshfs, nfs, scp, 9p, and tar as options. With a live mount such as nfs or sshfs the workspace is shared immediately on both sides. With a copy method such as rsync or scp the wrapper syncs the tree into the VM before each custom shell step and copies changes back afterwards. The README warns that sshfs on DragonFly BSD is effectively read only, so only rsync, scp, and nfs are listed for that platform. A copyback flag set to false stops files from returning to the host, which only matters for the copy based methods.

Release selection defaults to DragonFly BSD 6.4.2. The release field accepts a full version like 6.4.0 or a leading prefix like 6, in which case the newest matching release is used so the workflow does not need editing for every point release. Each part given must match in full, so a nonexistent release fails the job rather than falling back silently. Architecture defaults to x86_64 but can be set to aarch64, and the host runner should stay ubuntu-latest even then. A custom shell wrapper lets later steps run directly inside the VM, and sync-time can align the guest clock with NTP.

Port forwarding, memory, caching, and debugging

Several options tune the virtual machine beyond the basic run. The nat field maps host ports to guest ports, so a service listening on 80 inside the VM can be reached on 8080 from the runner. Memory defaults to 6144 megabytes and is changed with the mem field, while cpu sets how many cores the guest sees, defaulting to all host cores. Caching is on by default and stores apt packages plus VM images, but disable-cache turns it off.

The cache-after-prepare option shortens repeated builds. After the prepare step finishes installing packages, the action shuts the VM down cleanly, caches the prepared image, and reboots it before run. Later runs with the same prepare script restore that image and skip prepare entirely. The cache key includes a hash of the prepare script and the sync method, so editing either rebuilds the image from the base. The action reports a cache-after-prepare-hit output of true when it restored a prepared image. The option does nothing when disable-cache is set or prepare is empty.

For failures, debug-on-error opens a remote VNC session and pauses so the user can inspect the guest. A vnc-password parameter protects that link, and the session continues once the user touches a continue file inside the VM. The README notes an AI ready skill can generate these workflows automatically.

Image build pipeline and supported targets

The DragonFly BSD images are not hand built. The README points to the anyvm-org/dragonflybsd-builder repository, where GitHub Actions download the official DragonFly BSD installer ISO, boot it in QEMU, perform an unattended installation, enable ssh, pre install the packages named in the configuration, and finally export the installed disk as a compressed qcow2 image. The upstream install media comes from the official DragonFly BSD mirror, with the download page listed in the README. This automated pipeline keeps each released image consistent and reproducible.

The action is part of a larger VMActions family that offers similar VMs for other operating systems, linked from vmactions.org and powered by anyvm.org. The README mentions an AI ready mode: a companion skill understands the full VMActions interface and can write the GitHub Actions file from a plain language request such as run my tests on DragonFly BSD. The skill picks the right action, release, and architecture, installs the toolchain in prepare, forwards secrets, syncs code, and avoids common mistakes like forgetting the per OS default shell. Under the hood, the action relies on QEMU to run the guest. The README lists macOS and Windows runner support as an upcoming feature, so today the host must be Linux.

Editorial conclusion

The action is published at github.com/vmactions/dragonflybsd-vm and the latest tagged release is v1.3.3.