ようこそ

CircleCI Runner Overview

The CircleCI runner is currently only available if you are on the Scale Plan. Please reach out to your sales representative for information on how to sign up for the Scale Plan.

Introduction

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 providing you with additional control over the environment. The diagram below illustrates how CircleCI runner extends our existing systems.

CircleCI Runner Architecture
Figure 1. Runner Architecture

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.

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).

CircleCI runner limitations

There are a few limitations you should be aware of when using CircleCI runner:

Currently, the runner officially supports the following platforms:

  • Intel + Ubuntu

  • Arm64 + Ubuntu

  • Intel + macOS

Additional platforms have been tested but are not yet officially supported by the runner. For more information on platforms that have been tested, but are not supported, and platforms that have not been tested, please refer to the Runner Installation page.

The following features are not yet available, but may be in the future:

  • Rerun with SSH

  • Test splitting

  • add_ssh_keys

Public repositories

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.

Prerequisites

In order to use CircleCI runner, you must:

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 a special way in your .circleci/config.yml file. The fields you must set for a specific job to run using your runner 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 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.