Upgrade the platform
Server and runner ship together in a platform release. Upgrade them to the same target version. The operator CLI and Action tooling belong to a separate tooling release; consult the supported combination and release notes rather than assuming their numeric versions must match.
Use the version selector to review the target release's installation/configuration instructions. Test representative workflows in an isolated installation before changing a shared service.
Prepare a maintenance window
- Stop new operational submissions through your team's maintenance process; there is no installation-wide maintenance-mode command.
- Inspect Runs, settle active work, and reconcile any uncertain execution with its owning runner.
- Stop the runners, then stop the server. Retain runner work volumes and identities.
- Take a consistent backup of the complete server data directory, including its encryption key, logs, database, and NATS state. Preserve runner state separately. Follow backup and recovery guidance.
- Retain the previous artifact versions and record the new platform/tooling pair.
An idle, approved, non-ephemeral runner can be stopped normally and restarted with the same identity. If you explicitly used pyplines runner drain, that identity remains administratively draining: the current server does not implement resume. Follow runner replacement guidance, enrolling a new identity with a separate work volume after the old one has settled. Do not erase old state to force replacement.
Upgrade container deployments
On the server host, update PLATFORM_VERSION in its .env to the selected plain version. With services already stopped and the backup complete:
docker compose pull server
docker compose up -d server
docker compose logs --tail 100 server
The new server opens the existing data volume and applies database migrations. Check HTTPS health and administrator login before starting runners.
On each runner host, set its .env to the same platform version:
docker compose pull runner
docker compose up -d runner
docker compose logs --tail 100 runner
Retain the original state volume and server URL for a normally stopped runner. It reuses its saved identity without a new enrollment token. Do not run mixed server/runner versions as an assumed rolling-upgrade strategy; such compatibility is not promised by these guides.
Upgrade Linux services
Download and verify both target binaries using the procedure in server installation and runner installation. Stop services and back up their data before replacing binaries in /usr/local/bin.
Opening the server applies migrations automatically. To run them explicitly while the server is stopped:
sudo -u pyplines-server /usr/local/bin/pyplines-server migrate --data /var/lib/pyplines
sudo systemctl start pyplines-server
sudo journalctl -u pyplines-server -n 100 --no-pager
Once the server is healthy, start the runner on each host:
sudo systemctl start pyplines-runner
sudo journalctl -u pyplines-runner -n 100 --no-pager
Verify before resuming operations
Check reported component versions, runner admission and heartbeats, retained historical Runs, and the verification workflow. Upgrade workstation tooling separately when the selected supported combination requires it:
python -m pip install --upgrade "pyplines-cli==$TOOLING_VERSION"
pyplines version
Existing Action images carry their SDK/runtime; a CLI upgrade does not rebuild them. Update Action dependencies and republish only when required by that Action's maintenance or compatibility requirements.
Recovery after an unsuccessful upgrade
Stop accepting work and preserve the failed installation's state for investigation. An older server binary is not guaranteed to understand a migrated database; changing the image tag back is not a complete rollback procedure.
Restore only a compatible, complete backup in a controlled recovery process. Server state may lag effects already performed in external systems. Reconcile those effects and the owning runners before enabling new work. See backups and execution recovery.