VM Actions

Inputs

参数

Every with: input the VM actions accept. They are the same across all of them -- swapping freebsd-vm for netbsd-vm changes the guest, not the interface.

这些 action 接受的全部 with: 参数。所有 action 的参数完全一致 —— 把 freebsd-vm 换成 netbsd-vm，换的是客户机，不是接口。

prepare

optionalno default

Commands run inside the VM before run, for installing tools and dependencies. Each system has its own package manager; the cards on the front page show the one each action's own example uses.

在 run 之前于虚拟机内执行的命令，用来装工具和依赖。 每个系统的包管理器不同，首页的系统卡片上标着各 action 自带示例用的那个。

prepare: |
  pkg install -y gmake

run

optionalno default

The CI script, executed inside the VM. The working directory matches the host, so relative paths behave the same as in a normal step.

在虚拟机内执行的 CI 脚本。工作目录和宿主机一致，相对路径的行为 和普通 step 一样。

run: |
  ./configure
  gmake
  gmake check

release

optionaldefaults to the action's own default release默认为该 action 自己的默认版本

Which release to boot. Giving only the leading, .-separated part is enough: release: "13" runs the newest 13.x that action ships, so the workflow does not need editing for every point release. Each part must match in full -- a release that does not exist fails the job rather than quietly falling back to another one.

启动哪个版本。只写前面用 . 分隔的部分就够了： release: "13" 会用该 action 提供的最新 13.x， 这样每出一个小版本不用改 workflow。每一段都必须完整匹配 —— 写一个不存在的版本会让任务失败，而不是悄悄退回到别的版本。

release: "13"

arch

optionalx86_64

The guest CPU architecture. Which values an action accepts depends on the system and the release -- see the coverage matrix. The runner stays ubuntu-latest whatever you pick; using an arm runner instead is much slower.

客户机的 CPU 架构。每个 action 支持哪些取值取决于系统和版本，见覆盖矩阵。 无论选哪个，runner 都保持 ubuntu-latest；换成 arm runner 反而慢得多。

arch: aarch64

envs

optionalno default

Names of the environment variables to carry into the VM, space separated. Every GITHUB_* variable and CI=true go in regardless; this input is how your own values and secrets follow.

要带进虚拟机的环境变量名，空格分隔。所有 GITHUB_* 变量和 CI=true 无条件带入；你自己的值和 secret 要靠这个参数指定。

env:
  MYTOKEN: ${{ secrets.MYTOKEN }}
  MYTOKEN2: "value2"
# ...
with:
  envs: 'MYTOKEN MYTOKEN2'

usesh

optionalfalse

Run the run script with sh instead of the guest's default shell. Several systems default to something other than a POSIX shell -- FreeBSD and MidnightBSD to tcsh, OpenBSD to ksh, BlissOS to Android's mksh -- so a script written for sh needs this.

用 sh 而不是客户机默认 shell 来跑 run 脚本。有几个系统的默认 shell 不是 POSIX shell —— FreeBSD 和 MidnightBSD 是 tcsh，OpenBSD 是 ksh，BlissOS 是 Android 的 mksh —— 按 sh 写的脚本需要打开它。

usesh: true

sync

optionalrsync

How the source tree is shared with the VM: rsync, sshfs, nfs, scp, or no to share nothing. Not every method works on every system and architecture; the coverage matrix lists what each combination supports, and the first one listed is that combination's default.

源码树用哪种方式共享给虚拟机：rsync、 sshfs、nfs、scp，或者 no 表示不共享。不是每种方式在每个系统和架构上都能用；覆盖矩阵 列出了每个组合支持哪些，其中列在最前面的就是该组合的默认值。

sync: nfs

copyback

optionaltrue

Whether build results are copied out of the VM back to the host when the step finishes. Applies to rsync and scp; sshfs and nfs are live mounts, so both sides already see the same files.

step 结束时是否把构建产物从虚拟机拷回宿主机。对 rsync 和 scp 有效；sshfs 和 nfs 是实时挂载，两边本来就是同一份文件。

sync: rsync
copyback: false

nat

optionalno default

Ports to forward from the runner into the VM. Prefix a mapping with udp: for UDP.

从 runner 转发进虚拟机的端口。UDP 端口在映射前加 udp: 前缀。

nat: |
  "8080": "80"
  "8443": "443"
  udp:"8081": "80"

mem

optional6144

Memory for the VM, in MB.

虚拟机内存，单位 MB。

mem: 4096

cpu

optionalevery core of the host宿主机的全部核心

Number of CPU cores given to the VM.

分配给虚拟机的 CPU 核心数。

cpu: 3

sync-time

optionalfalse

Synchronize the guest clock with NTP at boot. Worth setting if something inside the VM is sensitive to the wall clock.

启动时用 NTP 校准客户机时钟。虚拟机里有对系统时间敏感的东西时值得打开。

sync-time: true

disable-cache

optionalfalse

Turn off caching of apt packages on the host and of VM images and artifacts.

关闭宿主机上 apt 包以及虚拟机镜像和产物的缓存。

disable-cache: true

cache-after-prepare

optionalfalse

Shut the VM down cleanly once prepare has finished, cache that prepared image, and boot again before run. Later runs with the same prepare script restore the prepared image and start directly at run.

在 prepare 跑完后干净地关机、缓存这个已准备好的镜像， 然后在 run 之前重新启动。之后使用相同 prepare 脚本的构建会直接恢复该镜像并从 run 开始。

  • The cache key includes a hash of the prepare script and the sync method, so changing either rebuilds the prepared image from the base image.
  • 缓存 key 包含 prepare 脚本和 sync 方式的哈希，改动其中任何一个都会从基础镜像重新构建。
  • The source tree is still synchronized on every run; only prepare is skipped.
  • 源码树每次仍然会同步，跳过的只有 prepare。
  • The first run is slower: the VM is shut down after prepare, the image is cached, and the VM boots again.
  • 第一次会更慢：prepare 之后关机、缓存镜像、再启动一次。
  • Ignored when disable-cache: true is set or prepare is empty.
  • 设置了 disable-cache: true 或者 prepare 为空时，该参数被忽略。
cache-after-prepare: true
prepare: |
  pkg install -y gmake

debug-on-error

optionalfalse

When prepare or run fails, enable a remote VNC link and wait instead of tearing the machine down. Connect, look around, and run touch ~/continue inside the VM to let the action finish.

当 prepare 或 run 失败时，开启一个远程 VNC 链接并等待，而不是直接销毁机器。连进去看现场，然后在虚拟机里执行 touch ~/continue 让 action 继续。

Drive it from a repository variable so it is not left on by accident.

用仓库变量控制它，免得不小心一直开着。

debug-on-error: ${{ vars.DEBUG_ON_ERROR }}

More on debug on error失败调试的详细说明

vnc-password

optionalempty空

Protects the VNC link opened by debug-on-error. The username can be anything; the password is this value.

保护 debug-on-error 打开的 VNC 链接。用户名可以随便填， 密码就是这个值。

debug-on-error: ${{ vars.DEBUG_ON_ERROR }}
vnc-password: ${{ secrets.VNC_PASSWORD }}

custom-shell-name

optionalthe OS name系统名

Names the shell wrapper that lets later workflow steps run inside the VM. See custom shell.

给那个让后续 workflow step 在虚拟机里执行的 shell 包装脚本命名。 见 自定义 shell。

custom-shell-name: vmsh

data-dir

optionalchosen by the action由 action 决定

Where VM data and images are stored. Worth pointing at a larger filesystem when the default one runs out of room.

虚拟机数据和镜像的存放位置。默认位置空间不够时可以指到更大的文件系统。

cache-dir

optionala temporary path临时路径

Overrides where the cache is kept.

覆盖缓存的存放位置。

debug

optionalfalse

Print debug output from the action itself. Unrelated to debug-on-error, which opens a shell into the machine.

打印 action 自身的调试信息。和 debug-on-error 无关 —— 那个是开一个进机器的 会话。

osname

set by the action由 action 自行设置

The guest OS name. Each action supplies its own; there is no reason to set it yourself.

客户机系统名。每个 action 会自己填好，不需要你设置。

Outputs输出

cache-after-prepare-hit

true when a prepared VM image was restored and the prepare step was skipped, false otherwise.

当成功恢复了已准备好的虚拟机镜像、跳过了 prepare 步骤时为 true，否则为 false。

- uses: vmactions/freebsd-vm@v1
  id: vm
  with:
    cache-after-prepare: true
    prepare: |
      pkg install -y gmake
- run: echo "${{ steps.vm.outputs.cache-after-prepare-hit }}"

Custom shell自定义 shell

Start the VM in one step, then run any number of later steps inside it by setting shell:. The wrapper changes into $GITHUB_WORKSPACE first, if it exists.

用一个 step 启动虚拟机，之后任意多个 step 通过设置 shell: 在里面执行。包装脚本会先 cd 进 $GITHUB_WORKSPACE（如果存在）。 

steps:
  - uses: actions/checkout@v7
  - name: Start VM
    id: vm
    uses: vmactions/freebsd-vm@v1
    with:
      sync: nfs
      custom-shell-name: vmsh
  - name: Step one, inside the VM
    shell: vmsh {0}
    run: |
      pwd
      uname -a
  - name: Step two, also inside the VM
    shell: vmsh {0}
    run: |
      gmake check

How file changes propagate between host and guest depends on sync:

文件改动怎么在宿主机和客户机之间传播，取决于 sync：

  • nfs or sshfs: the workspace is a live mount, so changes are visible on both sides immediately.
  • nfs 或 sshfs：工作目录是实时挂载， 改动两边立刻都能看到。
  • rsync or scp: the wrapper syncs the workspace into the VM before each step and back afterwards. rsync transfers incrementally; scp copies the whole workspace every time, which gets slow on a large tree.
  • rsync 或 scp：包装脚本在每个 step 之前把工作目录同步进虚拟机、之后再同步回来。rsync 是增量传输； scp 每次都拷整个工作目录，目录大了会很慢。