Your Mac isn't your CI runner

A macOS terminal obviously isn't a Linux CI runner. But even a Linux VM on your Mac can drift from what CI runs without you changing anything. "It works locally" and "it works in CI" only mean the same thing if the local environment matches CI's, not just the same distribution family.

A current example: the ubuntu-latest trap

This is happening now: GitHub Actions' ubuntu-latest label is moving from Ubuntu 24.04 to Ubuntu 26.04, rolling out gradually between October 19 and November 19, 2026. A workflow on ubuntu-latest will start running on a different OS version during that window, with different preinstalled tools and some packages removed: exactly the kind of change that breaks a pipeline with no code change on your side. Pinning an explicit version (ubuntu-24.04 rather than ubuntu-latest) avoids the surprise, but only if you know which version you're on and test against it.

Matching a workspace to your runner

Velo Workspaces has official cloud images for both Ubuntu 26.04 LTS and 24.04 LTS. Pick the one your workflow file pins, not the newest, and it's ready about a minute after download. A disposable workspace on the same version is the closest local stand-in for that runner you can get on a Mac, and it costs nothing to throw away and make again.

One difference to keep in mind: on an Apple silicon Mac the workspace is arm64, while GitHub's standard Ubuntu runners are x64 (arm64 runners, such as ubuntu-24.04-arm, exist too). For most scripts that doesn't matter. For anything that downloads architecture-specific binaries, it does, and ARM64 vs. x86-64 on Apple Silicon covers what to watch for.

The loop

Create a disposable workspace on your pinned runner version, run the same install and test steps your CI job runs, and iterate against real failures locally instead of push, wait, read logs. Throw the workspace away once the fix is confirmed. It's much faster than the CI loop for catching environment problems like a missing system package or a tool version mismatch before they cost you a pipeline run.

What this doesn't replace

This reproduces the OS and tools, not the whole CI system. Secrets, CI-only environment variables, matrix builds across versions and whatever your pipeline does around the job aren't part of it. It answers "does this run on the OS my pipeline uses?" cheaply and early; it doesn't replace running the pipeline before you merge.

Related reading: the disposable VM workflow for QA and DevOps, Ubuntu on Apple Silicon, and which distro fits which job. Or download Velo Workspaces and try it yourself.