Upgrading the CircleCI runner on server

Runner for server compatibility

Refer to the server compatibility chart to find the runner version you need for your installation.

Upgrading runner on server

Unlike CircleCI cloud, server does not automatically update the circleci-launch-agent, and requires manual intervention. The following sections detail how to upgrade runners in your server installation across all environments.

Upgrading runner in a containerized environment

This section details how to upgrade runner in containerized environments: Kubernetes and Docker.

Upgrading runner for Kubernetes

Upgrading runner for Docker

  1. Stop any currently running runner containers:

    docker stop <container-name>
  2. Remove the runner containers:

    docker stop <container-name>; docker rm <container-name>;
  3. Start a new runner Docker container:

    CIRCLECI_RESOURCE_CLASS=<resource-class> CIRCLECI_API_TOKEN=<runner-token> agent_version=<agent_version_for_server> docker run --env agent_version --env CIRCLECI_API_TOKEN --env CIRCLECI_RESOURCE_CLASS --name <container-name> <image-id-from-previous-step>
    When starting the docker container on server, the agent_version environment variable will need to be passed in using the --env flag.

Upgrading runner in a non-containerized environment

The process for manually updating the circleci-launch-agent binary can be broken down into three steps for non containerized environments. These steps are expanded upon in the sections below.

  1. Replace existing circleci-launch-agent binary with the new version.

  2. Stop currently running circleci-launch-agent processes.

  3. Start the new version of the circleci-launch-agent binary.

1. Replace the circleci-launch-agent-binary with the new version

Following the same process as in the Download the launch agent binary instructions, update the agent_version environment variable to the correct version from the Runner for server compatibility chart.

export agent_version="<launch-agent-version>"

Then, following the platform specific installation instructions replace the old binary with the newly updated version that was just downloaded.

2. Stop the currently running launch agent

The currently running circleci-launch-agent process will need to be halted before starting the newly updated binary. Platform-specific instructions for this are given below.

Stopping the launch agent on Linux

Run the following commands:

sudo systemctl stop circleci.service
sudo systemctl disable circleci.service
Stopping the launch agent on Mac

Run the following commands:

sudo launchctl unload '/Library/LaunchDaemons/com.circleci.runner.plist'
Stopping the launch agent on Windows

Run the following command:

Stop-ScheduledTask -TaskName "CircleCI Launch Agent"

3. Start the new runner launch agent

Platform-specific instructions are given below.

Starting on Linux

Run the following commands:

sudo systemctl reload circleci.service
sudo systemctl enable circleci.service
sudo systemctl start circleci.service
Starting on Mac

Run the following command:

sudo launchctl load '/Library/LaunchDaemons/com.circleci.runner.plist'
Starting on Windows

Run the following commands:

Start-ScheduledTask -TaskName "CircleCI Launch Agent"


Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.