Runner Fleet Operations

Runners execute tests on behalf of the admin node: API and load tests, browser
tests, mobile tests, security scans. This guide covers a runner’s life from the
operator’s side — connecting a new one, keeping its token valid, taking it out
of service, and upgrading the fleet without losing work.

For the runner settings themselves (pull mode, labels, one-task CI runners), see
Ephemeral Runners and
Runner Labels and Targeting.

Connect a new runner

1. Open Admin Panel > Integrations and click Add Integration.

2. Choose the type (for example Test Runner), a name and the namespaces the
   runner may serve.

3. Copy the token. It is shown once, together with ready-made start commands
   for the platform you pick.

4. Start the runner with the admin URL and the token:

   docker run --rm \
     -e MOCKARTY_ADMIN_URL=https://mockarty.example.com \
     -e MOCKARTY_RUNNER_TOKEN=mki_your_integration_token \
     "$MOCKARTY_RUNNER_IMAGE"
   

The runner connects out to the admin node; nothing needs to reach the runner.
It appears in the Runner fleet view on the same page within seconds, with its
status, capacity, labels and release version.

Several runners can share one token — each process registers separately. Use
one connection per group of runners you want to manage together (for example
per team or per region): its token is what you rotate and revoke.

Keep the token valid

A runner token is valid for 90 days from when it was issued or last rotated.
Mockarty warns the administrators 14, 7 and 1 day before a token expires and
again when it has expired, in the notification bell and in the admin node’s log.
The warning names the connection.

To replace a token without interrupting any runner, create a second connection
with the same settings, move the runners to its token one by one, then delete
the old connection. Rotate Token on the connection is faster, but the old
token stops working at once. Both ways are described in
Rotating Keys, Tokens and Certificates.

Take a runner out of service

In the Runner fleet view, click Drain on the runner and give a reason.
The fleet stops giving it new work; what it is running finishes. The decision
stays in place across restarts until you click Return to rotation, so a
runner you took out for maintenance does not rejoin by itself.

Stopping a runner process gracefully (SIGTERM, docker stop, a Kubernetes pod
deletion) also finishes the current task before the process exits; the fleet
then shows the runner as offline (a one-task CI runner disappears from it).

Upgrade the fleet

Upgrade the admin nodes first, then the runners. A runner one release behind
the admin keeps working; the fleet view marks it upgrade soon. A runner two
or more releases behind is marked upgrade the runner, and one newer than the
admin upgrade the admin first — both are outside the range the admin keeps
compatible.

To upgrade runners without losing work:

1. Drain the runner.
2. When it shows no active tasks, stop it.
3. Start the new version with the same token and settings.
4. Click Return to rotation.

On Kubernetes, a rolling update of the runner deployment does steps 2 and 3 for
you: each old pod finishes its task before it exits.

To stop unsupported runners from taking work at all, set on the admin node:

MOCKARTY_RUNNER_VERSION_POLICY=enforce

A runner outside the supported range is then refused when it connects, and its
log names both versions and what to upgrade. The default (warn) lets it
connect and only marks it.