Getting Started

Get SAIR running in your CI pipeline in under 15 minutes.

This guide is for running SAIR on your own phones. Using phones other users share, from CI? Skip to step 2: the job starts its own Proxy and needs no phones or DeviceSource. From an agent? See Run tests from an agent; it needs only an API key.

How it works

SAIR has three components: the Orchestrator (hosted by us), the Proxy and DeviceSource (run on your infrastructure). DeviceSource runs on the machine with USB devices; the Proxy can run on the same host or elsewhere on your network. All CI runners share the same Proxy. Your CI pipeline calls sair-acquire to lock a device, runs tests with stock adb, and calls sair-release when done.

1

Set up Proxy and DeviceSource

DeviceSource must run on the machine with USB-connected devices. The Proxy can run on the same host or any reachable machine on your network. DeviceSource discovers devices and pushes them to the Proxy, which coordinates locks with the Orchestrator. All your CI runners share the same Proxy. Devices are private to your account unless you share them into the global fleet from the dashboard; shared devices can be locked by any SAIR user, with the owner's jobs served first.

# Install SAIR tools
curl -fsSL https://raw.githubusercontent.com/compscidr/sair/main/install.sh | bash

# Start a dedicated ADB server on a non-default port
adb kill-server
adb -P 5038 start-server

# Start the Proxy and DeviceSource
export SAIR_API_KEY="your-api-key"
sair-proxy &
sair-device-source
2

Install SAIR tools in CI

The sair-acquire and sair-release tools ship as a GitHub Action, pinned to a SAIR release tag. Bump the tag when you want to upgrade, so a breaking change never lands in your CI unannounced.

- uses: compscidr/sair@v0.1.34

sair-acquire talks to a Proxy. If the runner can't reach one of yours, for instance a hosted runner using phones other users share, have the action start one in the job, at the same release. It needs no phones or DeviceSource: it reaches the phone you lock through the Orchestrator, and reads SAIR_API_KEY from the job's env.

env:
  SAIR_API_KEY: ${{ secrets.SAIR_API_KEY }}
steps:
  - uses: compscidr/sair@v0.1.34
    with:
      proxy: true
3

Update your CI workflow

Add device acquisition around your existing test step. Your connectedCheck command stays exactly the same.

# .github/workflows/test.yml
steps:
  # ... your build steps ...

  - uses: compscidr/sair@v0.1.34

  - name: Acquire device lock
    run: sair-acquire

  - name: Run instrumented tests
    run: ./gradlew connectedCheck

  - name: Release device lock
    if: always() && env.SAIR_LOCK_ID != ''
    run: sair-release --status ${{ job.status }}
Next: CI options →