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/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
Comments
Article is closed for comments.