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. 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
4. If applicable, you can delete the old token using the identifier ID

   • Run 

     circleci runner token delete "<token identifier>"

      

     Example:

     circleci runner token delete "350a1717-5c96-4964-9cf4-228a3298d0d1"

      

5. Update your circleci-runner-config.yaml.yamlwith the 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/circleci-runner/circleci-runner-config.yaml
   • macOS: $HOME/Library/Preferences/com.circleci.runner/config.yaml
   • Windows: C:\Program Files\CircleCI\runner-agent-config.yaml
      
6. Restart the Runner Service 

Linux:

sudo systemctl start circleci-runner

macOS:

launchctl bootstrap gui/$(id -u) $HOME/Library/LaunchAgents/com.circleci.runner.plist

launchctl enable gui/$(id -u)/com.circleci.runner

launchctl kickstart -k gui/$(id -u)/com.circleci.runner

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