Machine runner installation on Linux

Server v4.0 - v4.6

Prerequisites

To install machine runners and run jobs, you will need to have root access, and have the following utilities and tools installed on your system:

Coreutils
curl
sha256sum (if not pre-installed):
- sudo apt install coreutils for Ubuntu/Debain
- sudo yum install coreutils for Red Hat
tar
Gzip
sepolicy ( RHEL 8 only)
rpmbuild ( RHEL 8 only)
The CircleCI CLI if you wish to install runners from the command line

Self-hosted runner terms agreement

1. Create namespace and resource class

2. Download launch-agent script and install binary

Save the download-launch-agent script in the root of your project. When run (see the next step) the script will download the launch-agent binary, verify the checksum, and set the launch agent version.

Self-hosted runners on cloud auto-update to the latest supported versions. For server, specific self-hosted runner versions are validated for interoperability, and self-hosted runners do not auto-update.
Set your target platform and run the download-launch-agent.sh script to download, verify, and install the binary.
- If you are using cloud, use the table below to find your platform variable:
  Installation Target Variable
  Linux x86_64
  platform=linux/amd64
  Linux ARM64
  platform=linux/arm64
  Linux s390x
  platform=linux/s390x
  Linux ppc64le
  platform=linux/ppc64le
  
  For example, on cloud, to set your platform for Linux x86_64 and run the download-launch-agent.sh script, run the following:
  
  export platform=linux/amd64 && sh ./download-launch-agent.sh
- For server v4.x and up, use the table below to find the compatible machine runner launch-agent version for the version of server you are running:
  Server version Launch agent version
  4.0
  1.1.73695-40bf772
  4.1
  1.1.73695-40bf772
  4.2
  1.1.73695-40bf772
  4.3
  1.1.73189-8792751
  
  Substitute <launch-agent-version> with your launch-agent version for server and run the following:
  
  export agent_version="<launch-agent-version>" && sh ./download-launch-agent.sh
  
  Once your runner is successfully set up, you can delete the download-launch-agent.sh file.

Installation Target	Variable
Linux x86_64	`platform=linux/amd64`
Linux ARM64	`platform=linux/arm64`
Linux s390x	`platform=linux/s390x`
Linux ppc64le	`platform=linux/ppc64le`

Server version	Launch agent version
4.0	1.1.73695-40bf772
4.1	1.1.73695-40bf772
4.2	1.1.73695-40bf772
4.3	1.1.73189-8792751

3. Create `circleci` user and working directory

These will be used when executing the task-agent. These commands must be run as a user with permissions to create other users (for example, root). For information about GECOS, see the wiki page.

Ubuntu/Debian

id -u circleci &>/dev/null || sudo adduser --disabled-password --gecos GECOS circleci

CentOS/RHEL

id -u circleci &>/dev/null || sudo adduser -c GECOS circleci

Create the working directory and set permissions

sudo mkdir -p /var/opt/circleci

sudo chmod 0750 /var/opt/circleci

sudo chown -R circleci /var/opt/circleci /opt/circleci

Consider running the following additional command if you would like to use certified orbs, without errors, that work on Cloud on your self-hosted runner. Note that this enables code to execute root commands on your machine, and changes to the system may persist after the job is run.

echo "circleci ALL=(ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers

4. Create self-hosted runner configuration

Create a launch-agent-config.yaml file with a path of /etc/opt/circleci/launch-agent-config.yaml, owned by circleci, with permissions 600. Use the following commands:

sudo mkdir -p /etc/opt/circleci && sudo touch /etc/opt/circleci/launch-agent-config.yaml

sudo chown -R circleci: /etc/opt/circleci

sudo chmod 600 /etc/opt/circleci/launch-agent-config.yaml

Copy the following to the new /etc/opt/circleci/launch-agent-config.yaml file:

api:
  auth_token: AUTH_TOKEN
  # On server, set url to the hostname of your server installation. For example,
  # url: https://circleci.example.com

runner:
  name: RUNNER_NAME
  working_directory: /var/opt/circleci/workdir
  cleanup_working_directory: true

Replace AUTH_TOKEN with the resource class token created in the set up process.
Replace RUNNER_NAME with the name you would like for your self-hosted runner. RUNNER_NAME is unique to the machine that is installing the runner. RUNNER_NAME can be any value you would like, and it does not need to include any part of your namespace or resource class name. However, it is recommended to use the hostname of the machine so that it can be used to identify the agent when viewing statuses and job results in the CircleCI web app. The only special characters accepted in RUNNER_NAME are . () - _.

Configure SELinux policy (RHEL 8)

An SELinux policy is required for self-hosted runner to accept and launch jobs on RHEL 8 systems (earlier versions of RHEL are unsupported). Note that this policy does not add any permissions to the ones that may be required by individual jobs on this self-hosted runner install.

Create directory /etc/opt/circleci/policy and generate the initial policy module:

sudo mkdir -p /etc/opt/circleci/policy

# Install sepolicy and rpmbuild if you haven't already
sudo yum install -y policycoreutils-devel rpm-build

sudo sepolicy generate --path /etc/opt/circleci/policy --init /opt/circleci/circleci-launch-agent

Download the following type enforcing file circleci_launch_agent.te and install the policy:

sudo curl https://raw.githubusercontent.com/CircleCI-Public/runner-installation-files/main/rhel8-install/circleci_launch_agent.te --output /etc/opt/circleci/policy/circleci_launch_agent.te

sudo /etc/opt/circleci/policy/circleci_launch_agent.sh

5. Start machine runner

You can now start machine runner as follows:

sudo /opt/circleci/circleci-launch-agent --config /etc/opt/circleci/launch-agent-config.yaml

You can also optionally run machine runner as a systemd service.

Machine runner configuration example

Once you have installed configuration runner, select Continue in the CircleCI web app and you will be presented with an example configuration snippet showing a job configured to use your new self-hosted runner resource class.

The fields you must set for a specific job to run using your machine runners are:

machine: true
resource_class: <namespace>/<resource-class>

Simple example of how you could set up a job:

version: 2.1

workflows:
  build-workflow:
    jobs:
      - runner
jobs:
  runner:
    machine: true
    resource_class: <namespace>/<resource-class>
    steps:
      - run: echo "Hi I'm on Runners!"

The job will then execute using your self-hosted runner when you push the .circleci/config.yml to your VCS provider.

The job will then execute using your self-hosted runner when you push the config to your VCS provider.

Enable the `systemd` unit

This step is optional.

You will need to have systemd version 235+ installed for this optional step.

Create /usr/lib/systemd/system/circleci.service owned by root with permissions 755.

sudo touch /usr/lib/systemd/system/circleci.service

sudo chown root: /usr/lib/systemd/system/circleci.service

sudo chmod 755 /usr/lib/systemd/system/circleci.service

You must ensure that TimeoutStopSec is greater than the total amount of time a task will run for, which defaults to 5 hours.

If you want to configure the CircleCI’s self-hosted runner installation to start on boot, it is important to note that machine runner will attempt to consume and start jobs as soon as it starts, so it should be configured appropriately before starting. Machine runner may be configured as a service and be managed by systemd with the following scripts:

[Unit]
Description=CircleCI Runner
After=network.target
[Service]
ExecStart=/opt/circleci/circleci-launch-agent --config /etc/opt/circleci/launch-agent-config.yaml
Restart=always
User=circleci
NotifyAccess=exec
TimeoutStopSec=18300
[Install]
WantedBy = multi-user.target

Unlike task-agents, which use the environment of the circleci user, launch-agents will need to have any required environment variables (for example, proxy settings) explicitly defined in the unit configuration file. These can be set by Environment= or EnvironmentFile=. Visit the systemd documentation for more information.

You can now enable the service:

sudo systemctl enable circleci.service

Start the service

When the CircleCI’s self-hosted runner service starts, it will immediately attempt to start running jobs, so it should be fully configured before the first start of the service.

sudo systemctl start circleci.service

Verify the service is running

The system reports a very basic health status through the status field in systemctl. This will report Healthy or Unhealthy based on connectivity to the CircleCI APIs.

You can see the status of the agent by running:

systemctl status circleci.service --no-pager

Which should produce output similar to:

circleci.service - CircleCI Runner
   Loaded: loaded (/var/opt/circleci/circleci.service; enabled; vendor preset: enabled)
   Active: active (running) since Fri 2020-05-29 14:33:31 UTC; 18min ago
 Main PID: 5592 (circleci-launch)
   Status: "Healthy"
    Tasks: 8 (limit: 2287)
   CGroup: /system.slice/circleci.service
           └─5592 /opt/circleci/circleci-launch-agent --config /etc/opt/circleci/launch-agent-config.yaml

You can also see the logs for the system by running:

journalctl -u circleci

Troubleshooting

Refer to the Troubleshoot Machine Runner section of the Troubleshoot Self-hosted Runner guide if you encounter issues installing or running machine runner on Linux.