# 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: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](create-a-runner-group.md)).

## Step 1: Issue a registration token

**Console**
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.

**CLI**
```sh
dcloud ci runners create-registration-token --group-id group-id
```

Use the `installCommand` of the answer.

**API**
```http
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:

```sh
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`:

```yaml
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`.

```sh
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](move-or-disable-a-runner.md)).

## Related

- [Runners and runner groups](runners-and-groups.md)
- [Troubleshooting](troubleshooting.md)
- `ci.runners.create-registration-token`
