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

# Running checks on a GitHub-hosted runner

> Run your checks on every pull request on GitHub's own macOS runner, with simulators, a CI token and no Mac of yours.

Your pull requests are tested on `macos-15`, the arm64 macOS runner GitHub hosts. You run no Mac, and the runner needs nothing installed beforehand. [CI](https://docs.mobster.dev/ci.md) has the parts every host shares: the comment, the report and the flags.

## Set it up

From your project's folder:

```sh theme={"theme":"css-variables"}
mobster ci init --hosted
```

It writes `.github/workflows/mobster.yml` and prints what's left: make a CI token (below), add it as `MOBSTER_CI_TOKEN` and, for checks with steps, `ANTHROPIC_API_KEY` as repository secrets, commit the file and open a pull request. `--force` replaces an existing file, and `--print` shows the workflow without writing it.

## The workflow

```yaml .github/workflows/mobster.yml theme={"theme":"css-variables"}
name: mobster
on: pull_request
permissions:
  contents: read
  pull-requests: write   # the one comment Mobster keeps up to date
concurrency:
  group: mobster-${{ github.event.pull_request.number }}
  cancel-in-progress: true
env:
  MOBSTER: /Applications/Mobster.app/Contents/MacOS/mobster-agent
jobs:
  checks:
    runs-on: macos-15
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0   # the diff needs the base branch
      - name: Install Mobster
        id: mobster
        run: |
          brew install --cask radishsoftware/tap/mobster-app
          echo "version=$(brew list --cask --versions mobster-app | awk '{print $2}')" >> "$GITHUB_OUTPUT"
          echo "xcode=$(xcodebuild -version | head -1 | tr -d ' ')" >> "$GITHUB_OUTPUT"
      - name: Cache WebDriverAgent
        uses: actions/cache@v4
        with:
          path: ~/Library/Application Support/app.mobster.desktop/wda
          key: mobster-wda-${{ runner.arch }}-${{ steps.mobster.outputs.xcode }}-${{ steps.mobster.outputs.version }}
          restore-keys: |
            mobster-wda-${{ runner.arch }}-${{ steps.mobster.outputs.xcode }}-
      - name: Prepare a simulator
        run: |
          "$MOBSTER" sim doctor --fix
      - name: Test what this PR changed
        run: |
          "$MOBSTER" ci run
        env:
          MOBSTER_CI_TOKEN: ${{ secrets.MOBSTER_CI_TOKEN }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}   # only checks with steps use it
      - name: Upload the report
        id: upload
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: mobster-report
          path: .mobster/ci/
          retention-days: 14
          if-no-files-found: ignore
      - name: Comment on the PR
        if: always()
        run: |
          "$MOBSTER" ci comment
        env:
          GITHUB_TOKEN: ${{ github.token }}
          MOBSTER_ARTIFACT_URL: ${{ steps.upload.outputs.artifact-url }}
```

The cache holds the WebDriverAgent build, the slow part of a first job. Its key names the Xcode and Mobster versions, so a new Xcode or a new Mobster builds it once and every job after restores it. The simulator runtimes come with the runner's Xcode.

## Sign in with a CI token

The job signs in with a CI token, not with Mobster for Mac. It is part of your plan, adds no seat and counts no runs. It licenses simulator checks only (`mobster ci run` and `mobster test`), it ends after 90 days unless you choose up to 365, and it never licenses an iPhone. Make one with `mobster account ci-token create NAME` or in the console under Settings › CI tokens, and revoke it from either. Store it as `MOBSTER_CI_TOKEN`, as a secret of the service. `mobster ci doctor` in the job checks that it is live and says what to fix if it isn't.

## What this runner doesn't do

A hosted Mac has no iPhone, so the checks run on simulators. To test on a phone, use [a Mac of yours](https://docs.mobster.dev/ci/mac-runner.md).

A pull request from a fork gets no repository secrets, so the token is empty there: the job says Mobster couldn't run, and your token never reaches the fork's code.


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