CircleCI Runner Overview
CircleCI runner enables you to use your own infrastructure for running jobs. This means you will be able to build and test on a wider variety of architectures, as well as have additional control over the environment. The diagram below illustrates how CircleCI runner extends our existing systems.
CircleCI runner use cases
There are two key use cases CircleCI aims to meet with the runner:
Privileged access & controls - CircleCI understands that some customers require running jobs on on-premises or limited-access infrastructure due to stricter isolation requirements. Some things that the runner enables are:
IP restrictions - Runners can have static IP addresses that you can control
Identity Access Management (IAM) permissions - If you set up runners in AWS, they can be assigned IAM permissions
Monitor the operating system
Connect to private networks
Unique compute requirements - Customers who need to run jobs on an environment or architecture that CircleCI does not offer as a resource class can use the runner to fill that need.
Available CircleCI runner platforms
CircleCI runner is available on multiple platforms. Support levels fall into two categories:
Supported Level platforms ensure that CircleCI runners are both built and tested on their respective systems.
With a Supported platform, users receive the following:
Documentation and best practices
Support: CircleCI Customer Engineers will assist customers to resolve issues within their usual Gold Service Level Agreements (SLAs)
Supported CircleCI runners are available on the following platforms:
Ubuntu 18.04 or later (x86_64 or ARM64)
RHEL8 (x86_64 or ARM64)
Mac OS X 10.15+ (Intel)
macOS 11.2+ (Apple M1)
Docker (x86_64 or ARM64)
Windows Server 2019, 2016 (x86_64)
On Preview Level platforms, CircleCI runners are currently in development, thus testing is not complete.
With a Preview platform, users receive the following:
A full integration that is a work-in-progress — thus, some manual configuration may be required to install, configure, and deploy
Work-in-progress documentation and best practices
Support: CircleCI Customer Engineers will provide assistance and guidance on best practices for installing, configuring, and operating CircleCI runners
Users are encouraged to provide feedback in order to rapidly improve the CircleCI runner user experience and meet its necessary criteria as a Supported platform
Preview CircleCI runners are available on the following platforms:
Additional Linux distributions - RHEL, SUSE, Debian, etc. (x86_64 or ARM64)
CircleCI runner operation
Once CircleCI runner is installed, the runner polls
circleci.com for work, runs jobs, and returns status, logs, and artifacts to CircleCI. When the runner is not running a job, it will auto-update itself when a new version is released.
The runner consists of two components: the launch agent and the task agent.
launch agent (launch-agent) - manages gathering the information required to run a task (defined as a parallel run of a job) while also downloading and launching a task agent process
task agent (task-agent) - handles running a task retrieved and configured by the launch agent
The system has been designed to allow administrators to configure the task-agent to run with a lower level of privileges than the launch-agent. Any user who is able to execute a job will be able to gain the same privileges as task-agent. The instructions below are the recommended deployment which follows this approach (launch agent will run as root, but task agent will run as circleci).
To achieve better throughput, you can break your single build process into different steps and run them concurrently (at the same time). CircleCI offers the flexibility of deploying work to runners across all your resource classes.
Rather than limit the total number of registered runners, CircleCI runners are limited by the total number of runner jobs (tasks) across your resource classes.
Debugging with SSH
CircleCI runner is not recommended for use with public projects that have the "Build forked pull requests" setting enabled. In this case, a malicious actor may alter your machine or execute code on it by forking your repository, committing code, and opening a pull request. Untrusted jobs running on your CircleCI runner pose significant security risks for your machine and network environment, especially if your machine persists its environment between jobs. Some of the risks include:
Malicious programs running on the machine
Escaping the machine’s runner sandbox
Exposing access to the machine’s network environment
Persisting unwanted or dangerous data on the machine
Referencing your runner on a job
After setting up the 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 runner are:
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 runner when you push the config to your VCS provider.
|A namespace is a unique identifier claimed by a user or organization. Each user or organization can claim one unique and immutable namespace. Organizations are, by default, limited to claiming only one namespace. This policy is designed to limit name-squatting and namespace noise. If you need to change your namespace, please contact support.|
Take the runner course with CircleCI Academy to learn more about running jobs on your infrastructure.
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.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.