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:
Ensure the task-agent runs properly
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/bashtask_agent_cmd=${@:1}
echo "About to run CircleCI task agent: ${task_agent_cmd}"
$task_agent_cmd
exit=$?
echo "CircleCI task agent finished."
exit $exitThen, 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 -aecho "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 $exitConfigure 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