Start Building for Free

Migrate from launch agent to machine runner 3.0 on Linux

1 month ago1 min read
Server v4.4+
On This Page

This page describes how to migrate an existing launch agent installation to machine runner 3.0. Machine runner 3.0 includes improved network resiliency, and a simpler installation management strategy, utilizing operating system packages.

Migrating from launch agent to machine runner 3.0 is a straightforward process. The prerequisites remain the same. First, uninstall and remove launch agent, then, install the machine runner 3.0 agent. The configuration file is 1:1 compatible between the agents so no modifications are needed during the migration

1. Uninstall launch agent

The first step is to uninstall launch agent. The exact process depends on the platform, as described in the following sections.

  1. If the agent has been installed as a systemd service, run the following commands to stop and uninstall the service unit, and delete the service file (the new agent will install a new service unit):

    sudo systemctl stop circleci.service
    sudo systemctl disable circleci.service
    sudo rm /usr/lib/systemd/system/circleci.service
  2. The launch agent binary can now be removed from the machine. The default install location is /opt/circleci/circleci-launch-agent, but this may differ on your machine if the agent was installed somewhere else. The entire /opt/circleci subdirectory can be removed at this point.

  3. Finally, move the agent configuration file. The default location for this is /etc/opt/circleci/launch-agent-config.yaml. Move the file to /etc/circleci-runner/circleci-runner-config.yaml using the following command:

    mv /etc/opt/circleci/launch-agent-config.yaml /etc/circleci-runner/circleci-runner-config.yaml

    Alternatively, you can let the machine agent install process create a config file template and copy the existing config into the newly created file.

RHEL/Rocky Linux

In addition to the steps listed above, the SELinux policy should be uninstalled using the following command:

sudo semodule -r circleci_launch_agent

2. Install the machine agent

  1. Follow the instructions provided in Install machine runner 3.0 on Linux to install machine runner 3.0 using the provided packages.

  2. The packages create template configuration files at /etc/circleci-runner/circleci-runner-config.yaml. This configuration is 1:1 compatible with the launch agent configuration, apart from the auto-update feature. Since auto-update has been removed from the new agent, you should use the appropriate package management update tools to get new versions of the package when they are released. When using the apt package to update the agent package, you will need to clear the configuration file modified prompt. This can be avoided using the --force-confold flag or by removing the modified configuration file before upgrading.

    Once the configuration file has been populated, the following command will restart the agent so it can begin claiming:

    sudo systemctl enable circleci-runner
    sudo systemctl start circleci-runner

Suggest an edit to this page

Make a contribution
Learn how to contribute