Connect a Mac

Install the {{product}} agent on a Mac you own, so native-format jobs with runs-on macos run on it.

Last updated 18 November 2026View as Markdown

The Deutsche Cloud agent takes whole runs of native-format workflows whose jobs ask for macos: Xcode builds, iOS and macOS tests, signing and uploads. It asks for work over outbound HTTPS; no inbound port is opened. Steps run natively on the Mac, so the Mac needs the tools your builds use.

Prerequisites

  • A Mac with Apple silicon and macOS 13 or newer.
  • Node 20 or newer, installed with Homebrew or on PATH (brew install node). The installer does not install Homebrew or Node.
  • Xcode, its command line tools and anything else your builds use, installed for every user.
  • Outbound HTTPS from the Mac to the console, your organization's Git host and object storage.
  • ci:ManageRunners on all of CI (rn:ews::<organization id>:ci:*), and in the console ci:DescribeRunners to open Runners (without it the page shows an access-denied notice).
  • For a Mac that will hold signing certificates or store credentials, a runner group that takes protected branches only (see Create a runner group).

Step 1: Issue a registration token

  1. Open Runners under CI, then choose Add runner.
  2. For Runner group, choose the group.
  3. Choose Issue token.
  4. Copy the command under Or, for Deutsche Cloud's own workflow format on a Mac: the Deutsche Cloud agent. It is shown once.

The token expires after 15 minutes and registers one machine.

Step 2: Install the agent

In Terminal on the Mac, run the command:

curl -fsSL https://console-host/ci/api/agent/install.sh | sudo bash -s -- --token token

Add --name build-mac-1 to name the runner (by default, the Mac's computer name) and --labels xcode-16 for labels beyond macos,arm64.

Result

The Mac appears under Runners with the status Idle. On a wide screen the Machine column shows its system, architecture and cores, and "Jobs directly on the machine · 1 run at a time". Send a job to it with runs-on: macos:

name: ios
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: macos
    steps:
      - run: xcodebuild -scheme App -destination 'generic/platform=iOS Simulator' build

How such a job runs:

  • Each step runs from a login shell, as root, in a fresh clone of the repository at the run's commit; the workspace is deleted when the job ends.
  • The step's environment is built afresh: PATH, HOME, the job's env:, its secrets and the run's variables. The agent's own credential never reaches it.
  • image: on a macos job is refused when the file is parsed, and a build-image or push-image step fails: there is no container engine on the Mac. Put Linux work in a workflow file of its own.
  • The Mac takes one run at a time, and runs the jobs of that run that may run together at the same time.
  • cache and artifact steps work as on a platform machine; the Mac uploads and downloads with a link valid for one object and holds no storage credentials.
  • Cancel run reaches the Mac within about ten seconds and stops the running step.

Repository code runs on the Mac with your tools and files around it. Only connect a Mac to a group whose repositories you would run on it anyway.

Operate the agent

The installer leaves the agent's credential in /usr/local/ews-runner/runner.env (readable by root only), the agent in /usr/local/ews-runner/agent.cjs (downloaded again at every start, so it follows the platform without updates), and a launch daemon /Library/LaunchDaemons/app.deutschecloud.ews-runner.plist that starts it at boot and again when it exits. Its output is in /usr/local/ews-runner/logs/; failed reports and claims are in runner.err.log.

tail -f /usr/local/ews-runner/logs/runner.err.log
sudo launchctl kickstart -k system/app.deutschecloud.ews-runner   # restart it now
curl -fsSL https://console-host/ci/api/agent/install.sh | sudo bash -s -- --uninstall

Uninstalling leaves the runner listed: disable it as well (see Move or disable a runner).

Did this page help you?