Runner setup
This section describes the best practices how to configure and run the runner from the system that doesn't have the runner installed. It is worth re-iterating that the runner is only available for Linux.
Setup example
This setup assumes that you have a Linux machine, and you have terminal access to it. It can be your local machine, or it can be a VPS.
Step 1: Downloading assets
To install the runner, we need to download the binary. The instructions how to download the runner are available in the New runner page.
You can see the dropdown containing runner versions. Please always pick the latest version. The platform is heavily under development, and the new features will be available on the newest runner only.
If you are running on the VPS, you have the example bash script to download the runner assets using wget command, and to unzip it.
If you want to run the runner on your local machine where you have GUI, you can click the download button instead.
Once your runner assets are downloaded and extracted, you can proceed to the next step.
Step 2: Configuring the runner
Copy the command from the UI. The token provided by the page is a single-use token valid for 15 minutes. That means that you cannot re-use the same token to configure your runners multiple times.
Once the command is executed, the runner will prompt you for the name. Please assign the unique name to the runner.
If you don't want to have a prompt, you can provide the name using the --name flag.
If configuration is successful, you can see that in your current working directory, there is a new file named .runner. Please do not share this file with anyone. The file contains configuration information for the runner to use when restarted. If you remove this file, the runner will not be able to connect to the bountyhub back-end, and you will have to re-configure it.
Step 3: Run the runner
In order to start the runner, you can run it as a service (in the background), or you can run it as long as your terminal session is open (foreground). Regardless of the method, you may want to step back at this moment and set up your machine.
For this particular example, I installed required tools that I use in my workflows on the server. I also install the bh CLI, which I use to fetch results of my previous scans.
Now that all the tools exist on PATH, I open the settings page and create a new PAT. The token has job_results:read permission. Please copy that token and open/create the new .env file in the directory where the runner is. You can run the following command as an example:
echo "BOUNTYHUB_TOKEN=[YOUR_TOKEN]" > .env
Before finally running the runner, double check that you have bh installed and present on path by running which bh.
If everything is ready, then you can either:
- Simply run in the foreground by running
./runner run. - Install the runner as a service and start it:
sudo ./runner service install && sudo ./runner service start.