Introduction

There are times when a Self-Hosted runner resource class token needs to be rotated either for best security practices or if it has been unintentionally exposed in plain text when working with a CircleCI Support engineer on a support request.

Prerequisites

• An existing running installation of a Self-Hosted Runner Resource Class on either a Linux, macOS, or Windows environment
• A current installation of the CircleCI CLI on your machine

Instructions

1. Navigate to your terminal, and confirm that the CircleCI CLI is installed by running circleci version
2. Get a list of tokens for your resource class
   • Run circleci runner token list <resource-class name>
      
     Example:

     $ circleci runner token list runner-rc/support-demo
     +--------------------------------------+----------+----------------------+
     |                ID                    | NICKNAME |       CREATED AT     |
     +--------------------------------------+----------+----------------------+
     | 350a1717-5c96-4964-9cf4-228a3298d0d1 |          | 2022-05-09T16:20:45Z |
     +--------------------------------------+----------+----------------------+

3. Delete Token using the identifier ID
   • Run circleci runner token delete "<token identifier>"
     
     Example:
     circleci runner token delete "350a1717-5c96-4964-9cf4-228a3298d0d1"
     
     
4. Create a new token 
   • circleci runner token create <resource-class-name> "<nickname>"

     Example:
     circleci runner token create runner-rc/support-demo "NEW"
     
     
   • This will return an auth_token value that will be used in the next step
     
     
5. Update launch-agent-config.yamlwith new token by updating the `auth_token` field with the new value from the response in Step 4 above and save this file.
   
   Please note: The default location of this file will depend on the OS that this runner is hosted on.
   • Linux: /etc/opt/circleci/launch-agent-config.yaml
   • macOS: /Library/Preferences/com.circleci.runner/launch-agent-config.yaml
   • Windows: C:\Program Files\CircleCI\launch-agent-config.yaml
     
     
6. Restart the Runner Service 

Linux:
sudo systemctl start circleci.service

macOS:

sudo launchctl unload '/Library/LaunchDaemons/com.circleci.runner.plist'

sudo launchctl load '/Library/LaunchDaemons/com.circleci.runner.plist

Windows:
Uninstalling CircleCI self-hosted runners will prepare the system for installation again.

1. Download the Uninstall-CircleCIRunner.ps1script from GitHub to an easily accessible location.

2. Open PowerShell as an administrator and navigate to the directory where you placed the script file.

3. Run the following in your PowerShell:

   ./Uninstall-CircleCIRunner.ps1

Additional Resources:

• Best Practices of API Token Rotation
• Enable SSH on a Machine Runner
• How to delete a Self-Hosted Runner Resource Class