Using Runner command prefixes in Machine Runner

Overview

The runner.command_prefix setting in CircleCI Machine Runner allows you to define a prefix that wraps and runs the task-agent. This can be useful for executing commands with elevated permissions or setting up custom environments before running tasks. The prefix is specified as a YAML list of arguments or a custom script that ensures the correct execution of the task-agent.

Prerequisites

  • A working CircleCI Machine Runner setup
  • Basic understanding of YAML configuration in CircleCI
  • Basic understanding of bash scripting
  • Sufficient permissions to modify runner configurations

Method

Using sudo to Elevate Permissions

If you need to run the task-agent with elevated permissions, you can use sudo as part of runner.command_prefix:

runner:
command_prefix: ["sudo", "-niHu", "USERNAME", "--"]

This configuration will ensure that the task-agent runs with the specified user's permissions.

Using a Custom Wrapper Script

You can also specify a custom script to handle additional setup or logging before launching the task-agent. The script must:

  1. Ensure the task-agent runs properly
  2. Forward the exit code from the task-agent

Example Custom Wrapper Script

Save the following script as /var/opt/circleci/wrapper.sh and make it executable:

#!/bin/bash

task_agent_cmd=${@:1}
echo "About to run CircleCI task agent: ${task_agent_cmd}"
$task_agent_cmd
exit=$?
echo "CircleCI task agent finished."
exit $exit

Then, configure the runner to use this script:

runner:
command_prefix: ["/var/opt/circleci/wrapper.sh"]

Example: Setting Up an NVM Environment

If you need to initialize a Node Version Manager (NVM) environment before executing the task-agent, you can use the following script:

#!/bin/bash
set -a echo "NVM env setup" export NVM_DIR="/home/circleci/.nvm" source "$NVM_DIR/nvm.sh" export PATH="$NVM_DIR:$PATH" task_agent_cmd=${@:1} echo "About to run CircleCI task agent: ${task_agent_cmd}" $task_agent_cmd exit=$? echo "CircleCI task agent finished."
exit $exit

Configure the runner to use the script:

runner:
  command_prefix: ["/path/to/nvm-wrapper.sh"]

Summary

The runner.command_prefix setting provides flexibility in executing commands within CircleCI Machine Runner. It can be used to elevate permissions, wrap task execution in a script, or configure environments before running tasks. Properly implementing a custom script ensures seamless execution and correct exit code propagation.

Additional Resources

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.