> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobster.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# mobster ci

> Run your checks on every pull request, on a hosted runner or a Mac of yours.

Run your app's checks on every pull request or merge request, on a hosted macOS runner (simulators, signed in with a CI token) or a Mac of yours (its simulators and the iPhones plugged into it), in GitHub Actions, GitLab CI, Xcode Cloud, Codemagic, Bitrise or CircleCI. One comment on the PR keeps the verdict, the repro steps, frames, GIFs and videos.

## Usage

```text theme={"theme":"css-variables"}
mobster ci <command>
```

```text theme={"theme":"css-variables"}
examples:
  mobster ci init
  mobster ci doctor
  mobster ci run --device "Test iPhone"
  mobster ci comment --dry-run
```

## Commands

| Command | What it does |
| - | - |
| [`mobster ci init`](#mobster-ci-init) | write the CI workflow for this repository (GitHub Actions, GitLab CI or a hosted Mac) |
| [`mobster ci doctor`](#mobster-ci-doctor) | check that this Mac is ready to be a CI runner |
| [`mobster ci run`](#mobster-ci-run) | test the PR or MR this job builds; the report goes to .mobster/ci |
| [`mobster ci comment`](#mobster-ci-comment) | keep one comment on the PR or MR with the verdict and repro steps |

## `mobster ci init`

Write the workflow that runs `mobster ci run` on every pull request or merge request: on a Mac of yours as a self-hosted runner, or with `--hosted` on a GitHub-hosted macOS runner. `--host` xcode-cloud, codemagic, bitrise or circleci writes that service's file, which runs on its hosted Macs.

### Options

| Name | Default | Description |
| - | - | - |
| `--host {github,gitlab,xcode-cloud,codemagic,bitrise,circleci}` | from the origin remote | where the repository lives, or the CI service to write for |
| `--hosted` | off | run on a GitHub-hosted macOS runner and sign in with a CI token, with no Mac of yours (no iPhone either) |
| `--device NAME` | none | also test on this iPhone, plugged into the runner; repeatable (the runner must list each in MOBSTER\_RUNNER\_DEVICES) |
| `--testflight BUNDLE` | none | with `--device`: your app's TestFlight build on the phone; repeatable |
| `--force` | off | replace the workflow file if it exists |
| `--print` | off | print the workflow instead of writing it |

## `mobster ci doctor`

Check this Mac as a CI runner: Xcode, a simulator runtime, Mobster for Mac and its plan, system sleep, automatic login, the runner service, free disk and the phones the runner allows. Reads only.

### Options

| Name | Default | Description |
| - | - | - |
| `--json` | off | print the rows as JSON |
| `--hosted` | off | check for a hosted runner: skip the rows about keeping a Mac running and check the CI token (automatic inside a hosted job) |

## `mobster ci run`

Run `mobster test pr` for the pull request or merge request this CI job builds, with a screen recording of each simulator run. The suite's report, JUnit file, frames, GIFs and videos go to .mobster/ci for the job's artifacts. Works the same in a terminal.

### Arguments and options

| Name | Default | Description |
| - | - | - |
| `[TEST_FLAG ...]` | none | more `mobster test pr` flags, after a --: mobster ci run -- `--retries` 2 |
| `--base REF` | the job's target branch, else origin/main | the branch the PR merges into |
| `--sim TYPE[@RUNTIME]` | each check's own | a simulator device type to run on; repeatable |
| `--device NAME` | none | an iPhone plugged into this Mac; repeatable. In a CI job the runner must list each in MOBSTER\_RUNNER\_DEVICES, or nothing runs |
| `--testflight BUNDLE` | none | with `--device`: your app's TestFlight build on the phone; repeatable |
| `--no-video` | off | don't record the simulator's screen |

```text theme={"theme":"css-variables"}
exit codes: 0 passed, 1 failed, 2 needs review, 3 couldn't run

examples:
  mobster ci run
  mobster ci run --device "Test iPhone"
  mobster ci run --device "Test iPhone" --device "Lab iPhone" -- --spread
  mobster ci run -- --retries 2 --parallel 2
```

## `mobster ci comment`

Post the verdict in .mobster/ci as one comment on the pull request (GITHUB\_TOKEN) or merge request (MOBSTER\_GITLAB\_TOKEN), updated in place on every push: each failure's repro steps, frame, GIF, video and the command that runs it again. Never fails the job.

### Options

| Name | Default | Description |
| - | - | - |
| `--artifact-url URL` | `$MOBSTER_ARTIFACT_URL`, else the job's page | the uploaded report's link |
| `--dry-run` | off | print the comment and post nothing |
| `--frames {auto,on,off}` | auto | store the frames of up to 3 results that didn't pass in your repository, so the GitHub comment shows them: auto for private repositories and simulator frames, on for public repositories and iPhone frames too, off for none |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.