Skip to content

ci: add self-hosted macOS HVF runtime job#91

Open
Max042004 wants to merge 1 commit into
sysprog21:mainfrom
Max042004:ci/macos-hvf
Open

ci: add self-hosted macOS HVF runtime job#91
Max042004 wants to merge 1 commit into
sysprog21:mainfrom
Max042004:ci/macos-hvf

Conversation

@Max042004

@Max042004 Max042004 commented Jun 9, 2026

Copy link
Copy Markdown
Collaborator

GitHub-hosted macOS runners do not expose Apple's Hypervisor.framework (HVF):
the hosted runner OS itself runs inside a virtualization layer that withholds
HVF, so hv_vm_create() returns HV_UNSUPPORTED. Because of this, the existing
build-macos job can only compile elfuse and verify the HVF entitlement — it
can never actually boot a guest.

This PR adds a runtime-macos job that runs on a self-hosted Apple Silicon
runner
(an M4 machine) where HVF is available, so the real runtime path —
booting a Linux guest under HVF + Rosetta — is exercised in CI for the first
time. The hosted build-macos job is unchanged and keeps gating builds as
before; this job runs after it (needs: build-macos).

Closes #51.

What the runtime-macos job does

  • runs-on: [self-hosted, macOS, arm64], needs: build-macos, 60-minute
    timeout.
  • Per-ref concurrency: cancels in-progress runs for the same PR, but lets
    main runs finish.

Where it runs (trigger gating)

The job is fenced by:

if: >
  github.repository == 'sysprog21/elfuse' &&
  (github.event_name == 'push' || github.event_name == 'pull_request')

github.repository is the repository the workflow actually runs in, so this
single check expresses exactly when the physical runner should be used:

  • PR targeting main — runs. A pull_request from any fork is evaluated
    in the upstream (sysprog21/elfuse) Actions context, so a collaborator who
    pushes a branch to their own fork and opens a PR against upstream gets the
    full runtime suite. This is the normal contributor flow and must work.
  • Push to main — runs. Post-merge validation on the mainline.
  • Activity in a fork's own context — skipped. Pushing a branch to a fork
    without opening an upstream PR (or a fork's own workflow_dispatch) runs in
    the fork's context, where github.repository is the fork, so the job is
    skipped and never queues against a runner the fork doesn't have.

Note this intentionally does not use a head.repo == base.repo guard
(which would reject every collaborator PR, since those come from forks) and does
not require a ci-hvf label. The trust boundary for untrusted outside
fork PRs is the repository setting Settings → Actions → General → "Require
approval for all outside collaborators"
(or stricter): such PRs cannot start
any workflow run until a maintainer approves them. A maintainer reviewing the
diff before approving — and never approving fork PRs that touch
.github/workflows/ — remains the real gate, exactly as
pull_request_target / workflow_run are avoided here.

Steps, in order

  1. Host infosw_vers, uname -a, sysctl kern.hv_support, assert the
    host is arm64.
  2. Cache + install Homebrew packages (binutils, qemu) — only installs
    what is missing.
  3. Tool versions — make / objcopy / qemu-aarch64 / python3.
  4. Check Rosetta for Linux — verifies
    /Library/Apple/usr/libexec/oah/RosettaLinux/rosetta exists; if not, it
    emits a ::error:: with the exact install command and dumps the oah
    directory to aid debugging.
  5. Build elfuse (make elfuse).
  6. Verify the HVF entitlement is embedded in the binary via codesign.
  7. Run the runtime tests: make test-hello, make test-multi-vcpu,
    make check, then the full bash tests/test-matrix.sh all matrix.

cubic-dev-ai[bot]

This comment was marked as resolved.

@Max042004 Max042004 changed the title ci: test macOS HVF runtime on fork ci: test macOS HVF runtime Jun 9, 2026
@jserv jserv self-assigned this Jun 9, 2026
@Max042004 Max042004 force-pushed the ci/macos-hvf branch 2 times, most recently from b18134f to 5186357 Compare June 16, 2026 04:45

@jserv jserv left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Improve Git commit messages to properly describe changes related to the self-hosted macOS runner.

@jserv

jserv commented Jun 17, 2026

Copy link
Copy Markdown
Contributor

Refine the descriptions of both pull request body and commit message to address the close of #51 .

@Max042004 Max042004 force-pushed the ci/macos-hvf branch 2 times, most recently from 2e06673 to a30de42 Compare June 23, 2026 11:39
@Max042004 Max042004 changed the title ci: test macOS HVF runtime ci: add self-hosted macOS HVF runtime job Jun 23, 2026
@Max042004 Max042004 force-pushed the ci/macos-hvf branch 2 times, most recently from a46bdff to 8502cb8 Compare June 23, 2026 11:44
Hypervisor.framework needs real Apple Silicon hardware, so the hosted
build-macos job can only compile elfuse and check the entitlement, never
boot a guest. Add a runtime-macos job on a self-hosted Apple Silicon
runner ([self-hosted, macOS, arm64]) that actually exercises the VM
under HVF.

The job is scoped to the upstream repository with
github.repository == 'sysprog21/elfuse', so it runs for pushes to main
and for pull_requests targeting main -- including PRs opened from a
collaborator's fork -- but never inside a fork's own Actions context, so
a branch pushed to a fork without an upstream PR triggers nothing.
Untrusted outside fork PRs are held by the repository's "require
approval for outside collaborators" setting, so a maintainer still gates
every outside run without needing a head-ref guard or a label. The job
runs after build-macos, serializes per ref through a concurrency group,
and cancels in-progress runs only for pull requests.

It asserts the host is arm64, reports kern.hv_support, caches and
installs just the missing Homebrew packages (binutils, qemu), and fails
early with install guidance when Rosetta for Linux is absent. After make
elfuse it confirms the com.apple.security.hypervisor entitlement is
codesigned into build/elfuse, then runs test-hello, test-multi-vcpu,
make check, and tests/test-matrix.sh all.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Provision self-hosted Apple Silicon runner to exercise HVF runtime tests

2 participants