Connect a Mac
Install the {{product}} agent on a Mac you own, so native-format jobs with runs-on macos run on it.
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:ManageRunnerson all of CI (rn:ews::<organization id>:ci:*), and in the consoleci:DescribeRunnersto 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
- Open Runners under CI, then choose Add runner.
- For Runner group, choose the group.
- Choose Issue token.
- Copy the command under Or, for Deutsche Cloud's own workflow format on a Mac: the Deutsche Cloud agent. It is shown once.
dcloud ci runners create-registration-token --group-id group-idUse the installCommand of the answer.
POST /ci/api/runners/registration-tokens
{ "groupId": "8a3e2c1d-4b5f-4e6a-9c7d-0e1f2a3b4c5d" }Use the installCommand of the answer.
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 tokenAdd --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' buildHow 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'senv:, its secrets and the run's variables. The agent's own credential never reaches it. image:on amacosjob is refused when the file is parsed, and abuild-imageorpush-imagestep 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.
cacheandartifactsteps 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 -- --uninstallUninstalling leaves the runner listed: disable it as well (see Move or disable a runner).