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

  1. Open CI → Runners and choose Add runner. You need ci:ManageRunners.

  2. 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.

  3. Copy the install command. It carries a registration token that is valid for 15 minutes, works once, and is shown once.

  4. On the Mac, in Terminal:

    curl -fsSL https://console.<your platform domain>/ci/api/agent/install.sh | sudo bash -s -- --token TOKEN

    Add --name build-mac-1 to choose its name (the default is the Mac's own) and --labels xcode-16 for labels beyond macos,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 build needs, 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 release

The 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: 7

The 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/runners

Each 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 -- --uninstall

Then 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-*, linux or windows-*, or no runner at all;
  • a job that asks only for self-hosted or arm64, 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-on that 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-image and push-image on a macos job.
  • 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:
Did this page help you?