macOS runners
Connect your own Mac and run macOS and iOS builds on it, free of runner minutes.
What it is
A macOS runner is a Mac you own that runs your runs-on: macos jobs: Xcode builds, iOS and macOS tests, signing and uploads. You install the runner software on the Mac and register it with your organization; from then on it asks Deutsche Cloud for work over outbound HTTPS, runs the jobs, and sends logs, step results, artifacts and caches back, so a run on your Mac reads in the console exactly like a run on a platform machine. The machine is yours, so its minutes cost nothing.
Concepts
| Term | Meaning |
|---|---|
| Runner | A registered machine. It has a name, labels, a runner group and a credential that only it holds. Listed under CI → Runners. |
| Label | A word a runner carries, such as macos or arm64. A job's runs-on must be among a runner's labels for that runner to take the run. |
| Runner software | The program on the Mac that registers, reports in, takes runs and executes them. It needs no inbound port: nothing connects to the Mac. |
| Claim | A runner taking one queued run, whole, all its jobs included. Exactly one runner gets a run. |
| Isolation | Where a job's steps run. On the machine: in a fresh workspace directory, with your toolchain and files around it. Fresh VM per job: in a disposable macOS virtual machine destroyed afterwards. |
| Capacity | Runs a runner executes at once. Always one: a run on a Mac waits for the run before it to finish. |
| Presence | What the runner is doing now: Idle, Busy (running a run), Offline (no heartbeat for 5 minutes) or Disabled (its credential was revoked). |
How to
Prepare the Mac
- macOS 13 or newer on Apple silicon.
- Node 20 or newer on
PATH(brew install node). The installer does not install Homebrew or Node. - Xcode, command line tools and anything else your builds use, installed the way you would for a person building on that Mac.
- Outbound HTTPS to the console address, to your organization's Git host and to object storage. No inbound port, no VPN.
Connect a Mac
Open CI → Runners and choose Add runner. You need
ci:ManageRunners.Choose a runner group. For a Mac that will hold signing certificates or App Store credentials, choose a group with protected branches only, so a pushed branch cannot run code on it.
Copy the install command. It carries a registration token that is valid for 15 minutes, works once, and is shown once.
On the Mac, in Terminal:
curl -fsSL https://console.<your platform domain>/ci/api/agent/install.sh | sudo bash -s -- --token TOKENAdd
--name build-mac-1to choose its name (the default is the Mac's own) and--labels xcode-16for labels beyondmacos,arm64.
The Mac appears under CI → Runners within a few seconds, as Idle, with its macOS version, architecture and cores.
Send a job to it
name: ios
on:
push:
branches: [main]
jobs:
build:
runs-on: macos
steps:
- run: xcodebuild -scheme App -destination 'generic/platform=iOS Simulator' build
- run: xcodebuild test -scheme App -destination 'platform=iOS Simulator,name=iPhone 16'Every step of a macos job runs from a login shell in a fresh clone of the repository at the run's commit, so PATH is what Terminal gives you. image: is refused on a macos job: there is no container engine on the Mac. Put Linux jobs in a separate workflow file (see Limits).
Build a matrix
jobs:
build:
runs-on: macos
timeout: 1800
strategy:
fail-fast: false
max-parallel: 1
matrix:
config: [debug, release]
swift: ['5.10', '6.0']
exclude: [{ config: debug, swift: '5.10' }]
steps:
- run: swift build -c ${{ matrix.config }}
ship:
needs: [build]
runs-on: macos
steps:
- run: echo "every leg of build succeeded"Each combination is a job of its own on the run page, named build (release, 6.0). ${{ matrix.NAME }} reads the leg's value anywhere a value may hold an expression, and a key the matrix does not have is refused when the file is pushed. needs: [build] waits for every leg. With fail-fast (the default) the first failed leg cancels the legs that have not started; max-parallel caps how many run at once. A Mac runs one job at a time, so the legs of a run go one after another there.
timeout: on a job (seconds) stops the step running when it is spent; the job reads Timed out and its remaining steps Cancelled.
Run a GitHub Actions workflow on the Mac
A .github/workflows file with runs-on: macos-latest (or macos-15, macos-26, macos-15-xlarge, [self-hosted, macOS]) runs on your Mac, matrix included, unchanged from GitHub:
jobs:
build:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [macos-latest, macos-15]
config: [debug, release]
steps:
- uses: actions/checkout@v4
- uses: actions/cache@v4
with: { path: .build, key: 'spm-${{ hashFiles(''Package.swift'') }}' }
- run: swift build -c ${{ matrix.config }}
- uses: actions/upload-artifact@v4
with: { name: 'build-${{ matrix.os }}-${{ matrix.config }}', path: .build }This needs a Mac whose runner software runs each job in a fresh VM (the runner list shows Each job in a fresh VM (…)): GitHub's own runner is started inside the job's VM for that one job, so actions such as actions/checkout, actions/cache, actions/upload-artifact and setup-* run as on GitHub. Every macos-* label goes to your Macs: which macOS and Xcode a job gets is decided by the VM image, not the version in the label.
- Linux and macOS jobs in one run. A matrix like
os: [ubuntu-latest, macos-latest], or a Linux lint job that a macOS buildneeds, runs as one run when your organization has a runner pool that carries the Linux labels (dcloud ci runner-pools create --name linux --labels ubuntu-latest --labels ubuntu-24.04). The Linux jobs then run on the pool's machines and the macOS jobs on your Macs;needs, job outputs and statuses pass between them as between any two jobs. Without such a pool, the run's Linux jobs run on Deutsche Cloud's one machine per run, and its macOS jobs show macOS jobs can't share a run with jobs on Deutsche Cloud's one-machine-per-run Linux hosts… with these two ways out. services:,container:and Docker actions are refused on a macOS job with the reason, as on GitHub, where macOS runners have no Docker either.- The runner the install command sets up runs jobs on the machine and does not take GitHub-syntax jobs.
Use a secret
List it on the job, exactly as for a platform machine:
jobs:
release:
runs-on: macos
secrets: [MATCH_PASSWORD, APP_STORE_CONNECT_KEY]
steps:
- run: bundle exec fastlane releaseThe Mac receives each value for this run only and never writes it to the log: the value, each line of a multi-line value, its base64 and URL-encoded forms are replaced with *** before a line leaves the Mac, also when the value is split across two writes or printed to stderr. A step that transforms the value (reverses it, prints every second character) prints the result in clear.
Keep build output and caches
cache and artifact steps work on a Mac as on a platform machine:
- cache:
key: spm-${{ hash('Package.resolved') }}
restoreKeys: [spm-]
paths: [.build]
- run: swift build -c release
- artifact:
name: app
paths: [.build/release/App]
retentionDays: 7The Mac uploads to and downloads from object storage directly, with a link valid for that one object; it never holds storage credentials.
Watch, cancel and re-run
Runs, steps, durations and logs per step appear under Git → Repositories → the repository → CI while the run executes. Cancel reaches the Mac within about 10 seconds: the running step is killed, the remaining steps and jobs read Cancelled, and the Mac is free for the next run. A failed step does not stop the job's if: always() and if: failure() steps.
See what a runner is doing
CI → Runners shows each runner's presence, its machine (macOS 27.2 · arm64 · 10 cores), its isolation and capacity (Each job in a fresh VM (xcode-27-2-tools) · 1 run at a time, on wide screens), and the run it is executing or executed last, linked to that run. The list refreshes every 15 seconds.
GET /ci/api/runnersEach runner carries presence, capacity, vmImage (null when jobs run on the machine), currentRun and lastRun (id, repoId, number, workflowName, status, claimedAt, finishedAt).
Remove a Mac
On the Mac:
curl -fsSL https://console.<your platform domain>/ci/api/agent/install.sh | sudo bash -s -- --uninstallThen Disable runner in CI → Runners, which revokes its credential. The row stays, so past runs still name the machine that ran them.
Reference
What the installer leaves on the Mac
| Path | What it is |
|---|---|
/usr/local/ews-runner/runner.env |
the runner credential, mode 600, root-only |
/usr/local/ews-runner/agent.cjs |
the runner program, downloaded again from the console at each start |
/usr/local/ews-runner/work/<run id>/<job> |
one workspace per job, deleted when the job ends |
/usr/local/ews-runner/logs/runner.log |
claims, run outcomes, and why a heartbeat failed |
/Library/LaunchDaemons/app.deutschecloud.ews-runner.plist |
starts the runner at boot and again whenever it exits |
The runner reports in every 30 seconds, asks for work every 5 seconds (every 15 after three empty answers), and asks whether its run was cancelled every 10 seconds while it executes.
Isolation
| Runner shows | Where steps run | Between two jobs |
|---|---|---|
Jobs directly on the machine |
on the Mac, as root, in a fresh workspace directory | the workspace is deleted; anything else stays |
Each job in a fresh VM (image) |
in a macOS VM cloned from the named image | the VM is destroyed |
The runner the install command sets up runs jobs on the machine. A step's environment is built from nothing but PATH, HOME, the job's env:, its secrets and the EWS_* run variables, so the runner credential never reaches a build; repository code still runs with your toolchain and your files. Only register a Mac that runs on-the-machine jobs in a group whose repositories you would run on it anyway.
Which jobs reach a Mac
A Mac runs macOS jobs only. A job reaches a Mac runner when it asks for macOS explicitly: runs-on: macos in your own format, runs-on: macos-* or [self-hosted, macOS, …] in a GitHub workflow, or a label only your Macs carry (such as a Mac's own name). Never:
- a job that names
ubuntu-*,linuxorwindows-*, or no runner at all; - a job that asks only for
self-hostedorarm64, even when your Linux runners are busy; - a job of a repository the Mac's runner group does not allow, also when it names the Mac.
Registration enforces the same: a machine that reports macOS cannot register a Linux or Windows label, and a Linux machine no macOS label (the request is refused with the label it named).
Waiting for a Mac
A run with a macos job stays Queued until a runner takes it. The run page and the run lists say why:
| Message | Meaning |
|---|---|
… none is online — no runner with that label is registered. Add one … |
no runner carries the label |
… none is online — build-mac-1 is offline. Start the runner on it. |
the runners with the label have not been heard from for 5 min |
… build-mac-1 is busy with another run; this one starts when one is free. |
every matching runner is executing a run |
Each message with "none is online" names the time the run fails. A run nobody takes within 20 minutes fails with no online runner with label macos. A run waiting behind a busy runner waits up to 2 hours.
Measured on a Mac mini M4 with a runner that boots a fresh VM per job: 6 to 8 seconds from queued to claimed, 13 seconds to a booted VM, 31 to 36 seconds from queued to the first step.
Limits
| Limit | Value |
|---|---|
| Runs at once per runner | 1; the jobs of a run execute one after another on a VM runner |
| Run duration | 2 hours, from queued to finished |
| Unclaimed run | fails after 20 minutes with no online runner |
| Registration token | 15 minutes, one machine |
| Labels per runner | 20, each up to 50 characters |
| A runner that goes quiet | its run fails 5 minutes after its last heartbeat, saying which runner stopped reporting |
| Matrix legs per job | 256 |
| Mixed Linux and macOS | GitHub workflows: one run with a runner pool for the Linux labels; our format: split into two files. A Mac never runs a Linux job either way |
Pricing
Runs on your own runners are free. Their minutes are recorded, so Usage and the cost explorer show them, as Self-hosted runner minutes at €0.00 a minute: every started minute from claim to finish, one line per run. Job minutes on platform machines are priced separately, on Pricing. Logs, artifacts and caches a Mac uploads are stored data like any other run's.
What is not supported
- A matrix built from an expression in your own format (only fixed lists), and in a GitHub workflow a
runs-onthat comes from a matrix computed at run time (fromJSON(needs.x.outputs.m)): such a job is planned for Linux. - GitHub-syntax jobs on a Mac that runs jobs directly on the machine.
- macOS and Deutsche Cloud-hosted Linux jobs in one GitHub-syntax run.
image:,build-imageandpush-imageon amacosjob.- Two runs at once on one runner.
- Intel Macs and macOS older than 13 with the runner the install command sets up.
- Splitting one run between a platform machine and a Mac.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
the run waits with none is online |
the Mac is asleep, off, or the runner stopped | wake the Mac and set it never to sleep; sudo launchctl kickstart -k system/app.deutschecloud.ews-runner |
the run waits with busy with another run |
the Mac is executing an earlier run | wait, cancel the earlier run, or register a second Mac |
no online runner with label macos |
no runner took the run within 20 minutes | bring a runner online, then Re-run |
a run with a linux and a macos job never starts |
no single runner carries both labels | put the macOS jobs in their own workflow file |
Step kind "build-image" needs a container engine |
an image step in a macos job |
move it to a linux job in another workflow |
| the runner shows Offline although the Mac is on | the runner cannot reach the console | read /usr/local/ews-runner/logs/runner.log on the Mac |
| a build cannot find a tool that works in Terminal | the tool is installed for another user than root | install it system-wide, or set PATH in the job's env: |