Upgrading the CircleCI self-hosted runner on server
Server v3.x This page describes how to update the CircleCI self-hosted runner on CircleCI server installations.
Self-hosted runner for server compatibility
Refer to the server compatibility chart to find the runner version you need for your installation.
Upgrading self-hosted 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 self-hosted runners in your server installation across all environments.
Upgrading self-hosted runner in a containerized environment
This section details how to upgrade self-hosted runner in containerized environments: Kubernetes and Docker.
Upgrading self-hosted runner for Kubernetes
Refer to the Kubernetes Installation Instructions.
Upgrading self-hosted runner for Docker
-
Stop any currently running self-hosted runner containers:
docker stop <container-name> -
Remove the self-hosted runner containers:
docker stop <container-name>; docker rm <container-name>; -
Start a new self-hosted 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_versionenvironment variable will need to be passed in using the--envflag.
Upgrading self-hosted 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.
-
Replace existing
circleci-launch-agentbinary with the new version. -
Stop currently running
circleci-launch-agentprocesses. -
Start the new version of the
circleci-launch-agentbinary.
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 Self-hosted runners 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.serviceStopping 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 self-hosted 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.serviceStarting 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"Additional resources
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.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
