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

name: Tests against staging

on:
  pull_request:
    branches: [main]

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

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

      - name: Run tests
        run: |
          curl -X POST https://api.mobileboost.io/tests/execute \
            -H "Content-Type: application/json" \
            -d '{
              "organisationId": "'"${{ secrets.MOBILEBOOST_ORG_ID }}"'",
              "tags": ["critical"],
              "tunnelName": "'"$MOBILEBOOST_TUNNEL_NAME"'"
            }'

The action handles three things that are easy to get wrong by hand:

It picks a unique tunnel name per job, derived from the run ID, the attempt number, and the runner. Two jobs never collide.
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. Defaults to the latest release

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, a container in the cluster that already hosts staging, or an existing build server.

[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

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mobileboost-tunnel
spec:
  replicas: 1
  selector:
    matchLabels: {app: mobileboost-tunnel}
  template:
    metadata:
      labels: {app: mobileboost-tunnel}
    spec:
      containers:
        - name: tunnel
          image: mobileboost/local-tunnel:latest
          args:
            - --tunnel-name=acme-shared
            - --only-hosts=*.acme.internal,10.0.0.0/8
            - --links=8
          env:
            - name: MOBILEBOOST_API_KEY
              valueFrom:
                secretKeyRef: {name: mobileboost, key: api-key}

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 valid but lacks the `tunnel:connect` scope	No, ask an administrator
`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

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

​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

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