Tart MacOS Virtualization for GitHub Actions

This guide will help you set up ephemeral workers to run GitHub Actions in a way that's easy to upgrade in the future. The idea is to create and maintain a base image that the workers run, and when it's time to update, you simply upgrade the image and you're good to go.

Overview

We'll use virtualization software called Tart that allows for performant virtualization on macOS. The workflow is:

1. Clone a base image (or create your own)
2. Customize the image for your needs
3. Set up a controller and worker system for GitHub Actions

NOTE: Apple limits you to TWO VMs PER MAC COMPUTER. Yes, this limitation applies even on powerful machines like an M3-Ultra Mac Studio. You can run multiple computers to work around this.

The architecture looks like this:

• Controller – divides up the work
• Worker – runs the VMs
• VM – a COPY of your base image that is discarded after use

To make this less painful, when you create the VM, you'll pass in a startup script that registers the action-worker with GitHub.

We'll use two main tools:

• Tart – handles the VM functionality
• Orchard – manages the orchestration

1. Set Up the Base Image on the Host

1.1 Install Required Software

brew install cirruslabs/cli/tart
brew install cirruslabs/cli/orchard

1.2 Create and Configure Your Base Image

# Download an image
tart clone ghcr.io/cirruslabs/macos-sequoia-base:latest github-runner-base
# Change the settings for the CPU/RAM
tart set --memory 12288 --cpu 4 --disk-size 128 github-runner-base
# Run the image
tart run github-runner-base --net-bridged=en0

1.3 Connect to the Base Image

# In another terminal, SSH in
# Password is admin
ssh admin@`tart ip github-runner-base --resolver=arp`

NOTE: You'll want to SSH in even though the VM opens interactively. SSH will let you copy/paste more easily.

2. Configure the Guest Base Image

All of the following steps are performed inside the base image you just SSH'd into.

2.0 Fix the Disk Resizing

This step ensures the disk is properly resized, as automatic resizing often fails:

diskutil list
sudo diskutil repairDisk disk0
sudo diskutil apfs resizeContainer disk0s2 0
sudo diskutil repairDisk disk0

2.1 Install Required Tools

# Install xcodes 
brew install xcodes
brew install aria2
# Install git-crypt
brew install git-crypt

2.2 Install Specific Xcode Versions

# Install Xcode
xcodes install 16
xcodes install 16.2
sudo xcode-select -s /Applications/Xcode-16.2.0.app/Contents/Developer
# Verify the installation
xcode-select -p
xcodebuild -version

2.3 Update Ruby

brew upgrade ruby-build
brew upgrade rbenv
rbenv versions
rbenv install 3.4.2
rbenv global 3.4.2

2.4 Install Required Gems

gem install bundler
gem install fastlane

NOTE: You'll notice that actions-runner contains the GitHub Actions components.

3. Set Up Orchard

3.1 Generate and Configure Admin Token

echo $(openssl rand -hex 32)

Use the generated value to set the ORCHARD_BOOTSTRAP_ADMIN_TOKEN. Add this to your .zprofile:

export ORCHARD_BOOTSTRAP_ADMIN_TOKEN="_____"

You can test Orchard before configuring the launch daemon by running orchard controller run as long as the environment variable is set.

Next, create the context for your workers:

# Don't forget to run either:
# source ~/.zshrc
# source ~/.zprofile

orchard context create --name production \
  --service-account-name bootstrap-admin \
  --service-account-token $ORCHARD_BOOTSTRAP_ADMIN_TOKEN \
  --no-pki https://127.0.0.1:6120

Confirm it worked:

orchard context list

3.2 Configure Orchard as a Daemon

Create a launch daemon file at /Library/LaunchDaemons/org.cirruslabs.orchard.controller.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>org.cirruslabs.orchard.controller</string>
    <key>UserName</key>
    <string>USER_NAME_TO_RUN_AS</string>
    <key>Program</key>
    <string>/opt/homebrew/bin/orchard</string>
    <key>ProgramArguments</key>
    <array>
      <string>/opt/homebrew/bin/orchard</string>
      <string>controller</string>
      <string>run</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
      <key>PATH</key>
      <string>/bin:/usr/bin:/usr/local/bin:/opt/homebrew/bin</string>
      <key>ORCHARD_BOOTSTRAP_ADMIN_TOKEN</key>
      <string>ORCHARD_BOOTSTRAP_ADMIN_TOKEN_YOU_MADE_RECENTLY</string>
    </dict>
    <key>WorkingDirectory</key>
    <string>/var/empty</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/opt/homebrew/log/orchard-controller-launchd.log</string>
    <key>StandardErrorPath</key>
    <string>/opt/homebrew/log/orchard-controller-launchd.log</string>
  </dict>
</plist>

NOTE: Make sure to set:

• The user this will run as (and create that user if needed)
• The proper path to orchard
• The ORCHARD_BOOTSTRAP_ADMIN_TOKEN
• The logging path

Load the daemon:

sudo launchctl load -w /Library/LaunchDaemons/org.cirruslabs.orchard.controller.plist

3.3 Set Up the Worker

Since the worker communicates with the controller, create an account and generate a token for it:

orchard create service-account worker --roles "compute:read" --roles "compute:write"

Create a bootstrap token:

orchard get bootstrap-token worker

NOTE: The token should look like a public key and start with orchard-bootstrap-token-v0.

Create a launch daemon file for the worker at /Library/LaunchDaemons/org.cirruslabs.orchard.worker.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key>
    <string>org.cirruslabs.orchard.worker</string>
    <key>UserName</key>
    <string>USER_NAME_TO_RUN_AS</string>
    <key>Program</key>
    <string>/opt/homebrew/bin/orchard</string>
    <key>ProgramArguments</key>
    <array>
      <string>/opt/homebrew/bin/orchard</string>
      <string>worker</string>
      <string>run</string>
      <string>--bootstrap-token</string>
      <string>orchard-bootstrap-token-v0...........</string>
      <string>localhost</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
      <key>PATH</key>
      <string>/bin:/usr/bin:/usr/local/bin:/opt/homebrew/bin</string>
    </dict>
    <key>WorkingDirectory</key>
    <string>/var/empty</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/opt/homebrew/log/orchard-launchd.log</string>
    <key>StandardErrorPath</key>
    <string>/opt/homebrew/log/orchard-launchd.log</string>
  </dict>
</plist>

3.4 Create a Startup Script for GitHub Actions

Create a startup script that will configure and start the GitHub Actions runner:

runner-01.sh:

#!/bin/bash

echo "export GITHUB_TOKEN=YOUR_TOKEN_GOES_HERE" >> ~/.zshrc
echo "export GITHUB_URL=https://github.com/your-org-goes-here" >> ~/.zshrc
echo "export RUNNER_NAME=tart-01" >> ~/.zshrc
echo "export RUNNER_PATH=/Users/admin/actions-runner" >> ~/.zshrc

export GITHUB_TOKEN=YOUR_TOKEN_GOES_HERE
export GITHUB_URL=https://github.com/your-org-goes-here
export RUNNER_NAME=tart-01
export RUNNER_PATH=/Users/admin/actions-runner

sleep 7

cd ${RUNNER_PATH}
rm -rf .runner .credentials
# Configure runner
./config.sh --unattended \
            --url "${GITHUB_URL}" \
            --token "${GITHUB_TOKEN}" \
            --replace \
            --name "${RUNNER_NAME}"

# Install as a service (uses launchd on macOS)
./svc.sh install
./svc.sh start

Now, create a VM using your base image and the startup script:

orchard create vm --image github-runner-base runner-01 --net-bridged=en0 --startup-script=@runner-01.sh --restart-policy=OnFailure --cpu 8 --memory 16384

TIP: For debugging, you can set --headless=false to see the VM's display, and you can omit the startup script if needed.

NOTE: You'll create and delete these images frequently. This is the normal workflow for upgrades.

4. Upgrading Xcode

When you need to upgrade Xcode or other components, follow these steps:

4.1 Download a New Base Image

# Download an image
tart clone ghcr.io/cirruslabs/macos-sequoia-base:latest new-github-runner-base
# Change the settings for the CPU/RAM
tart set --memory 12288 --cpu 4 --disk-size 128 new-github-runner-base
# Run the image
tart run new-github-runner-base --net-bridged=en0

4.2 Configure the New Image

Follow the same steps from section 2 to set up the new image:

4.2.0 Connect to the New Image

# SSH in with password admin
ssh admin@`tart ip new-github-runner-base --resolver=arp`

4.2.1 Fix the Disk Resizing

diskutil list
sudo diskutil repairDisk disk0
sudo diskutil apfs resizeContainer disk0s2 0
sudo diskutil repairDisk disk0

4.2.2 Install Required Tools

# Install xcodes and other tools
brew install xcodes
brew install aria2
brew install git-crypt

4.2.3 Install Xcode

# Install Xcode versions
xcodes install 16
xcodes install 16.2
sudo xcode-select -s /Applications/Xcode-16.2.0.app/Contents/Developer
# Verify the installation
xcode-select -p
xcodebuild -version

4.2.4 Update Ruby

brew upgrade ruby-build
brew upgrade rbenv
rbenv versions
rbenv install 3.4.2
rbenv global 3.4.2

4.2.5 Install Required Gems

gem install bundler
gem install fastlane

4.3 Replace the Old VM with the New One

orchard delete vm runner-01
orchard create vm --image new-github-runner-base runner-01 --net-bridged=en0 --startup-script=@runner-01.sh --restart-policy=OnFailure --cpu 8 --memory 16384

You're all set! Your GitHub Actions runners are now running on the updated image.