Local testing in CI

A CI job can open a tunnel, run tests against it, and close it again. The one thing to get right first is where the tunnel runs.

Pick the right runner

The tunnel has to run somewhere that can already reach your internal services.

Your setup	What to do
Self-hosted runners inside your network	Run `mb-local` in the job. This is the common case, and the snippets below cover it
Cloud-hosted runners (GitHub-hosted, GitLab SaaS)	These sit outside your network and cannot reach your staging environment, so a tunnel started there has nothing to offer. Use a shared tunnel instead
A mix of both	Use a shared tunnel. Jobs reference it by name wherever they run

Starting mb-local on a cloud-hosted runner does not fail loudly. The tunnel connects, and then every request through it fails because the runner cannot reach your services either. If your runners are not inside your network, use a shared tunnel.

GitHub Actions

Tunnels are available on the AI SDET path, which runs generated test code on MobileBoost devices. Set mode: ai-sdet on the run-tests action, as below. See Which runs can use a tunnel.

Upload the build, open a tunnel, then run the tests against both:

name: Tests against staging

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: [self-hosted, internal-network]
    steps:
      - uses: actions/checkout@v4

      - name: Build the app
        run: ./gradlew assembleRelease

      - name: Upload the build
        id: upload
        uses: MobileBoostHQ/actions/upload-build@v1
        with:
          api-key: ${{ secrets.MOBILEBOOST_API_KEY }}
          organisation-id: ${{ vars.MOBILEBOOST_ORG_ID }}
          build-path: app/build/outputs/apk/release/*.apk

      - name: Start MobileBoost tunnel
        id: tunnel
        uses: MobileBoostHQ/actions/setup-local-tunnel@v1
        with:
          api-key: ${{ secrets.MOBILEBOOST_API_KEY }}
          only-hosts: "*.acme.internal,10.0.0.0/8"

      - name: Run tests against the build, through the tunnel
        uses: MobileBoostHQ/actions/run-tests@v1
        with:
          api-key: ${{ secrets.MOBILEBOOST_API_KEY }}
          organisation-id: ${{ vars.MOBILEBOOST_ORG_ID }}
          build-id: ${{ steps.upload.outputs.build-id }}
          mode: ai-sdet
          tags: critical
          tunnel-name: ${{ steps.tunnel.outputs.tunnel-name }}
          async: false

The tunnel closes itself when the job ends, including when it fails or is cancelled, so there is no cleanup step to remember.

Which runs can use a tunnel

Tunnels work on the AI SDET path: mode: ai-sdet, where MobileBoost runs generated test code on its own devices. A tunnel terminates on the device host, so the run has to be on a MobileBoost device for one to exist. The default mode: gpt-driver runs on a third-party device cloud, which MobileBoost does not operate and a tunnel cannot reach. Passing tunnel-name there is an error rather than a silent no-op, so a run never quietly goes ahead on the public internet while your workflow says otherwise.

What setup-local-tunnel handles for you

It picks a unique tunnel name per job, derived from the run ID, the attempt number, and the job. Parallel and matrix jobs never collide, and a re-run never collides with the attempt it is replacing.
It waits until the tunnel is usable before the step finishes, so your tests never start against a tunnel that is not up yet.
It stops the tunnel in a post step, which runs even when the job fails or is cancelled.

It exports the name it chose as MOBILEBOOST_TUNNEL_NAME for later steps.

Inputs

Input	Required	Description
`api-key`	Yes	Your MobileBoost API key. Store it as a repository secret
`only-hosts`	No	Hosts this tunnel may reach. Strongly recommended
`exclude-hosts`	No	Hosts it may never reach. Wins over `only-hosts`
`tunnel-name`	No	Override the generated name. Only useful with a shared tunnel
`version`	No	Pin a binary version, e.g. `v0.3.2`. Defaults to the latest release
`wait-for-ready`	No	How long to wait for the tunnel to become usable. Defaults to `60s`

Other CI providers

Without a ready-made action, do the same three things by hand: unique name, wait for ready, and stop it in a step that always runs.

GitLab CI
Bitrise
Jenkins
CircleCI

test:
  stage: test
  tags: [internal-network]
  before_script:
    - curl -fsSL https://get.mobileboost.io/mb-local/latest/linux-amd64 -o mb-local
    - chmod +x mb-local
    - ./mb-local --daemon start
        --tunnel-name "gl-$CI_JOB_ID"
        --only-hosts "*.acme.internal"
        --wait-for-ready 60s
  script:
    - ./run-mobileboost-tests.sh "gl-$CI_JOB_ID"
  after_script:
    - ./mb-local --daemon stop --tunnel-name "gl-$CI_JOB_ID"

Add MOBILEBOOST_API_KEY as a masked project variable under Settings > CI/CD > Variables. It is then already in the environment, so nothing needs to pass it explicitly.after_script runs even when script fails, which is what makes the cleanup reliable. $CI_JOB_ID is unique per job, so parallel jobs never collide.

Store your key as a Bitrise Secret named MOBILEBOOST_API_KEY, then add a Script step before your test step:

curl -fsSL https://get.mobileboost.io/mb-local/latest/darwin-arm64 -o mb-local
chmod +x mb-local

./mb-local --daemon start \
           --tunnel-name "bitrise-$BITRISE_BUILD_NUMBER" \
           --only-hosts "*.acme.internal" \
           --wait-for-ready 60s

envman add --key MOBILEBOOST_TUNNEL_NAME --value "bitrise-$BITRISE_BUILD_NUMBER"

Then stop it in a step with Run if previous Step failed enabled, so it also runs on failure:

./mb-local --daemon stop --tunnel-name "$MOBILEBOOST_TUNNEL_NAME"

pipeline {
    agent { label 'internal-network' }

    environment {
        MOBILEBOOST_API_KEY = credentials('mobileboost-api-key')
        TUNNEL_NAME   = "jenkins-${env.BUILD_TAG}"
    }

    stages {
        stage('Start tunnel') {
            steps {
                sh '''
                    curl -fsSL https://get.mobileboost.io/mb-local/latest/linux-amd64 -o mb-local
                    chmod +x mb-local
                    ./mb-local --daemon start \
                               --tunnel-name "$TUNNEL_NAME" \
                               --only-hosts "*.acme.internal" \
                               --wait-for-ready 60s
                '''
            }
        }
        stage('Run tests') {
            steps {
                sh './run-mobileboost-tests.sh "$TUNNEL_NAME"'
            }
        }
    }

    post {
        always {
            sh './mb-local --daemon stop --tunnel-name "$TUNNEL_NAME" || true'
        }
    }
}

The post { always { ... } } block is what guarantees cleanup on failure and on abort.

version: 2.1

jobs:
  test:
    machine: true
    steps:
      - checkout
      - run:
          name: Start MobileBoost tunnel
          command: |
            curl -fsSL https://get.mobileboost.io/mb-local/latest/linux-amd64 -o mb-local
            chmod +x mb-local
            ./mb-local --daemon start \
                       --tunnel-name "circle-$CIRCLE_WORKFLOW_JOB_ID" \
                       --only-hosts "*.acme.internal" \
                       --wait-for-ready 60s
      - run:
          name: Run tests
          command: ./run-mobileboost-tests.sh "circle-$CIRCLE_WORKFLOW_JOB_ID"
      - run:
          name: Stop MobileBoost tunnel
          when: always
          command: ./mb-local --daemon stop --tunnel-name "circle-$CIRCLE_WORKFLOW_JOB_ID"

when: always makes the cleanup step run even after a failure.

Give every job a unique tunnel name

A tunnel name identifies one connection. If two jobs use the same name at the same time, the second one is refused rather than silently taking over the first. Build the name from something your CI guarantees is unique:

CI	Use
GitHub Actions	`${{ github.run_id }}-${{ github.run_attempt }}-${{ strategy.job-index }}`
GitLab CI	`$CI_JOB_ID`
Bitrise	`$BITRISE_BUILD_NUMBER`
Jenkins	`$BUILD_TAG`
CircleCI	`$CIRCLE_WORKFLOW_JOB_ID`

If you omit --tunnel-name, mb-local derives one from these variables itself.

A matrix build needs the matrix index too. The run ID alone is shared by every job in the matrix, so five parallel jobs would fight over one name and four of them would be refused.

Wait for the tunnel, do not sleep

--wait-for-ready blocks until the tunnel can actually carry traffic, then keeps running. Use it instead of sleep:

./mb-local --daemon start --tunnel-name "$NAME" --wait-for-ready 60s

If the tunnel is not usable within the timeout, the command exits non-zero and your job fails with a clear reason. That is much better than a run where every test times out.

Run a shared tunnel

For teams running many jobs, one long-lived tunnel beats one tunnel per job. It removes tunnel setup from every pipeline, works for cloud-hosted runners, and removes name collisions entirely. Run it on any host inside your network: a small VM, an existing build server, or the box that already hosts staging. It needs no inbound access, so a machine with nothing else exposed is a good home for it.

[Unit]
Description=MobileBoost Local tunnel
After=network-online.target

[Service]
Environment=MOBILEBOOST_API_KEY=your-api-key
ExecStart=/usr/local/bin/mb-local \
  --tunnel-name acme-shared \
  --only-hosts '*.acme.internal,10.0.0.0/8' \
  --links 8
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Jobs then reference it by name and start nothing themselves:

{
  "organisationId": "org123",
  "tags": ["critical"],
  "tunnelName": "acme-shared"
}

Raise --links on a shared tunnel. It sets how many parallel connections carry traffic, so a large test run does not queue behind itself. Eight is a good starting point for a tunnel serving a whole team.

Keep exactly one process per shared tunnel name. Two replicas would both claim the name, and the second is refused.

Keep the access key out of your logs

The access key is a credential. Store it in your CI secret store and pass it through the environment rather than --key, so it never appears in a command line that gets logged.

export MOBILEBOOST_API_KEY="$MOBILEBOOST_API_KEY"
./mb-local --tunnel-name "$NAME"

mb-local never writes the key to its own logs at any verbosity.

Check the exit code

CI should tell a wrong key apart from a network blip. mb-local uses distinct exit codes so you can:

Code	Meaning	Retry?
`0`	Clean exit	-
`10`	API key rejected	No
`11`	Cannot reach MobileBoost	Maybe, check egress first
`12`	Tunnel could not be established	Maybe
`13`	A tunnel with this name is already connected	No, fix the name
`15`	The key is real but not permitted to open tunnels, such as a read-only key	No, use a normal API key
`20`	Tunnel limit for your organisation reached	No
`22`	Binary too old	No, upgrade

Full list in the CLI reference.

Getting started

Test definitions

Test execution

Test reports

Pick the right runner

GitHub Actions

Which runs can use a tunnel

What setup-local-tunnel handles for you

Inputs

Other CI providers

Give every job a unique tunnel name

Wait for the tunnel, do not sleep

Run a shared tunnel

Keep the access key out of your logs

Check the exit code

​Pick the right runner

​GitHub Actions

​Which runs can use a tunnel

​What setup-local-tunnel handles for you

​Inputs

​Other CI providers

​Give every job a unique tunnel name

​Wait for the tunnel, do not sleep

​Run a shared tunnel

​Keep the access key out of your logs

​Check the exit code

Pick the right runner

GitHub Actions

Which runs can use a tunnel

What setup-local-tunnel handles for you

Inputs

Other CI providers

Give every job a unique tunnel name

Wait for the tunnel, do not sleep

Run a shared tunnel

Keep the access key out of your logs

Check the exit code