CircleCI Self-hosted Runner Installation on Linux

1 week ago • 4 min read

Cloud Server v3.x

Create the CircleCI self-hosted runner configuration
Install the CircleCI self-hosted runner configuration
Create the USERNAME user and working directory
- Ubuntu/Debian
- CentOS/RHEL
Configure SELinux policy (RHEL 8)
Referencing your self-hosted runner on a job
- Verify the service is running
Enable the systemd unit
Start the service

This page describes how to install CircleCI self-hosted runner on Linux.

This page is a continuation of installing self-hosted runners. You will need to have an existing namespace and resource class to continue below. You can do this on the CircleCI web app by navigating to Self-Hosted Runners (see the documentation for the Web App Installation). You can also use the CLI.

Create the CircleCI self-hosted runner configuration

Create a launch-agent-config.yaml file.

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

Copy and paste into the newly created file the recommended CircleCI self-hosted runner configuration for Linux:

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
  command_prefix: ["sudo", "-niHu", "USERNAME", "--"]
  working_directory: /var/opt/circleci/workdir
  cleanup_working_directory: true

Replace AUTH_TOKEN with the resource class token created in the Authentication step
Replace RUNNER_NAME with the name you would like for your self-hosted runner
RUNNER_NAME is unique to the 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
USERNAME is the user on your machine that you want to run the runner launch agent
This is not your CircleCI account username, but the user on the machine that the agent will be installed on

Install the CircleCI self-hosted runner configuration

Once created, save the configuration file to /opt/circleci/launch-agent-config.yaml owned by root with permissions 600:

sudo chown root: /opt/circleci/launch-agent-config.yaml

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

Create the USERNAME 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 (e.g. root). For information about GECOS, see the wiki page.

Ubuntu/Debian

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

sudo mkdir -p /var/opt/circleci/workdir
sudo chown -R USERNAME /var/opt/circleci/workdir
sudo chmod 0750 /var/opt/circleci/workdir

Consider running the following additional command if you would like to use certified orbs that work on Cloud on your self-hosted runner, without errors. 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 "USERNAME ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

CentOS/RHEL

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

sudo mkdir -p /var/opt/circleci/workdir
sudo chown -R USERNAME /var/opt/circleci/workdir
sudo chmod 0750 /var/opt/circleci/workdir

echo "circleci ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

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 /opt/circleci/policy and generate the initial policy module:

sudo mkdir -p /opt/circleci/policy

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

sudo sepolicy generate --path /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 /opt/circleci/policy/circleci_launch_agent.te

sudo /opt/circleci/policy/circleci_launch_agent.sh

Referencing your self-hosted runner on a job

After setting up your self-hosted runner, you will need to reference it on a job by setting some fields in your .circleci/config.yml file. The fields you must set for a specific job to run using your self-hosted runners are:

machine: true
resource_class: your-namespace/your-resource

Here is a simple example of how you could set up a job:

version: 2.1
workflows:
  testing:
    jobs:
      - runner
jobs:
  runner:
    machine: true
    resource_class: your-namespace/your-resource
    steps:
      - run: echo "Hi I'm on Runners!"

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

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 (/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 /opt/circleci/launch-agent-config.yaml

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

journalctl -u circleci

Enable the `systemd` unit

This step is optional.

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

Create /opt/circleci/circleci.service owned by root with permissions 755.

sudo chown root: /opt/circleci/circleci.service

sudo chmod 755 /opt/circleci/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 self-hosted runner installation to start on boot, it is important to note that the launch agent will attempt to consume and start jobs as soon as it starts, so it should be configured appropriately before starting. The launch agent 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 /opt/circleci/launch-agent-config.yaml
Restart=always
User=root
NotifyAccess=exec
TimeoutStopSec=18300
[Install]
WantedBy = multi-user.target

Unlike the task agent, which uses the environment of the circleci user, the launch agent will need to have any required environment variables (e.g., proxy settings) explicitly defined in the unit configuration file. These can be set by Environment= or EnvironmentFile=. Please visit the systemd documentation for more information.

You can now enable the service:

systemctl enable /opt/circleci/circleci.service

Start the service

When the CircleCI 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.

systemctl start circleci.service

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.