Updating Runners

Runners keep themselves current in two ways:

• Automatic updates — an idle runner notices when Copia advertises a newer version, then downloads, verifies, installs, and restarts onto it with no operator action. This is on by default.

• Manual updates — the Runners page in Copia generates a copy-paste script that updates a specific runner in place. Use this when automatic updates are disabled, when a runner is on a build that can't self-update, or when you'd rather update on your own schedule.

Automatic updates

When Copia advertises a newer runner release, each eligible runner downloads and installs it on its next idle check and restarts onto the new binary. Discovery and installation are fully automatic.

When automatic updates run

A runner auto-updates only when all of the following are true. Otherwise it stays on its current version until you update it manually.

• Auto-update is enabled in config (update.enabled, the default).

• The runner was not registered with --disable-auto-update.

• It is a long-lived runner — not started with --once and not an ephemeral runner.

Restart behavior

How the runner restarts depends on how it was started:

• Foreground / daemon — the runner drains any running job, then re-launches itself onto the new binary.

• Windows service — a detached helper stops and restarts the service through the Service Control Manager, which relaunches it as the freshly installed binary. See Runner as a Windows Service.

Configuration

Auto-update is tuned in the runner's config.yaml:

update:
  # Turn background auto-update on or off. On by default.
  enabled: true
  # How often, while idle, to check for a newer version.
  check_interval: 1h
  # Allow moving to a different (older) version than the one running.
  # Default false: only strictly newer versions are installed.
  allow_downgrade: false

To disable auto-update for a runner at registration time instead, pass --disable-auto-update to act_runner register. This is persisted in the runner's .runner file and takes precedence regardless of config.

Manual updates

From the Runners page in Copia, any runner running an older version than the latest release shows an update available banner. Click Generate Update Script to produce a script tailored to that runner's operating system and architecture. (If Copia can't determine the runner's platform, select the OS and architecture in the dialog first.) A runner already on the latest version shows no banner.

Run the generated script from the directory where the runner was installed. The script:

1

Download

Downloads the correct release archive for the runner's platform.

2

Verify

Verifies its SHA-256 checksum and extracts the new binary — all before touching the installed runner, so a bad download aborts while the current runner is still running.

3

Stop

Stops the running runner and waits for it to exit.

4

Replace and restart

Replaces the old binary and restarts the runner.

On Windows the script auto-detects whether the runner is installed as a Windows service. If it is, the script stops the service through the Service Control Manager (which drains in-flight jobs), overwrites the exact executable the service points to, and restarts it via SCM. Otherwise it uses the standard foreground flow.