Runners are machines that execute pipelines. The application provides cloud-hosted runners, and you can manage your own by using a self-hosted runner.

Runners are machines or containers used to execute pipelines. Refactr provides cloud-hosted runners in several flavors, including containers and virtual machines. We host these runners in our secure cloud environment with the highest degree of isolation.

Runner architecture

Runners communicate with the application by first authenticating and then polling for available runs. This communication happens outbound only, so that when running a self-hosted runner in your own environment, no inbound connections are required. Once a run is available, the runner attempts to acquire the run, and if successful, it will then download the pipeline to execute, along with associated data, such as variables.

Currently, only Linux runners are supported, and CentOS 8 is the recommended operating system.

Adding a new runner

To add a new runner, visit the “Account Settings” page, select “Runners” on the left nav bar, and then click “Add Runner”.

You can choose from several types of runners, both cloud-hosted and self-hosted. Cloud-hosted runners are ready to use immediately, whereas self-hosted runners provide the executable download and authentication details so that you can install a runner on your own infrastructure.

Running pipelines in parallel

Each runner can run a single pipeline at a time. To handle a large number of pipeline runs, you can assign multiple runners to a single project. When a project has multiple runners, runs will be distributed among them in a first-come-first-serve manner.

Customizing a runner

All runners have a startup script option, which allows you to enter an arbitrary shell script that is executed only once when the runner starts up. If you’re using a self-hosted runner, you can configure your own environment as you like.

Note that if you need to install tools or dependencies that will be used by your pipelines, it is highly recommended to install those tools as a part of your pipeline steps, either manually or by using the built-in tool installer step modules. This ensures that your pipeline will always use the same version of the tools.

Starting and stopping runners

Cloud-hosted runners can be started and stopped manually by visiting the runner page in the application. Note that stopping a runner will abruptly fail any runs that were executing on the runner, and these runs may appear as running until the system flushes, which can take a few hours.

Runners are configured with an idle timeout in seconds. When a runner has not run any pipelines for this number of seconds, it will be automatically stopped. Stopping a cloud-hosted runner is equivalent to deleting a virtual machine, so all persistent storage will be deleted. When the runner is started again, it will be a completely new machine.

Additionally, self-hosted runners will automatically transition to “Stopped” status when the agent server has not received communication from the runner in four hours. This prevents the runner from indefinitely blocking the run queue. To bring a self-hosted runner back into “Running” status, simply start the runner again and ensure it connects to the agent server.

Runner autostart

By default, runners are configured to automatically start when runs are queued and there are no idle runners. To enable or disable this functionality, visit the runner page and edit the runner settings.

Viewing the status of a runner

Runners can have the following statuses:

  • Stopped: The runner is not running, and cannot execute pipeline runs. Cloud-hosted runners in this state have no associated cloud runner.
  • Pending: Waiting for a cloud container to become available. Normally runners will have this status for only a few seconds after being started. Self-hosted runners cannot have this status.
  • Running: The runner is running. It may not be able to execute runs yet if it is still starting up, particularly if a long-running startup script is configured in the runner options.

The status of a runner is available on the runner page.

Working with files and paths

The runner uses a directory to store data for pipeline runs called the “workspace” directory, which defaults to /workspace. For each pipeline run, a temporary directory is created within the workspace called the “run” directory. The run directory is deleted immediately after a run finishes, so it is a useful location to store temporary files.

For script step modules, and other modules that run as a subprocess, the process’s working directory will be the same as the run directory. Any file path properties are resolved relative to this directory.

Accessing metadata about a pipeline run

It’s often useful to retrieve information about the pipeline run itself during execution, such as the pipeline ID or name. A set of environment variables are automatically set for all steps that run as a subprocess, including script modules, which can be used to access this information.

Here are the available metadata environment variables:

  • RUN_ID
  • JOB_ID

These values can also be retrieved from any expression directly by using the env.* syntax. For example, to retrieve the agent version in an expression, use env.AGENT_VERSION. For more information, see the expression reference

Self-Hosted Runners

Self-hosted runners enable you to run pipelines on any infrastructure, including inside on-premise environments and behind firewalls. The runner is packaged as an executable which can be run as a service or as a Docker container.

Runner Agent Installation

Retrieve the runner executable from the application by opening a runner from the project or organization pages, and then clicking the “Download Agent” button. Several recent versions of the runner are available. Generally you will want the latest version. Transfer the files to your desired runner machine and install the executable to run as a service, for example by using systemd. The downloaded targz file also includes supporting library files, which must be placed in the same folder as the executable.

A sample Dockerfile is provided here.

Configuration File

The runner agent requires a configuration file to start. By default, it will look for the configuration file in /etc/runner-agent.json. You may also specify the path to the configuration file by setting the CONFIG_PATH environment variable.

Below is an example runner configuration file with all possible fields and their default values. All of these fields are optional except AGENT_ID and AGENT_KEY.

  "AGENT_ID": "<enter your agent id here>",
  "AGENT_KEY": "<enter your agent key here>",
  "LOG_PATH": "/var/log/runner-agent",
  "LOG_FILENAME_PATTERN": "runner-agent-%DATE%.log",
  "LOG_LEVEL": "info",
  "WORKSPACE_PATH": "/opt/runner-agent/workspace"

AGENT_ID: Unique identifier for the runner. This value is retrieved from the application.

AGENT_KEY: Authentication key for the runner. This value is retrieved from the application.

LOG_PATH: Path to the directory where log files will be written.

LOG_FILENAME_PATTERN: If LOG_PATH is provided, specifies the log file naming pattern. Occurences of %DATE% will be replaced with the current date in YYYY-MM-DD format.

LOG_RETENTION: The retention duration for log files. If a number is provided, this is the maximum number of log files. If a string ending in “d” is provided, such as “20d”, this is the number of days before log files are deleted.

LOG_LEVEL: The verbosity of log output. One of “info”, “warning”, “debug”, or “error”.

WORKSPACE_PATH: Path to the root of the runner workspace. Pipeline run directories will be created within this directory.

Runner authentication

Self-hosted runners require a unique identifier (AGENT_ID), as well as an authentication token (AGENT_KEY) to authenticate with the agent server. AGENT_KEY is similar to a password, and should be stored securely. It can also be regenerated from the application, which will immediately invalidate any runner that is currently using the key until its configuration file is updated with the new key. Changing the key requires restarting the runner agent.