Skip to main content
In this guide, you’ll learn how to remove a GitHub Actions self-hosted runner at the repository, organization, or enterprise level. You can either delete it via the GitHub UI or clean up directly on the runner host using the configuration script.

​
Removing a Runner via the GitHub UI

  1. Navigate to your repository’s Settings > Actions > Runners.
  2. Click the runner you want to remove.
The image shows a GitHub repository settings page, specifically the "Runners" section under "Actions," displaying a self-hosted runner named "prod-ubuntu-runner" with an idle status.
  1. On the runner details page, click Remove.
The image shows a GitHub Actions settings page for a self-hosted runner named "prod-ubuntu-runner" with no active jobs running. There is a "Remove" button highlighted in red.
If you have MFA enabled, GitHub will prompt you for your authentication code. Once verified, the runner is permanently removed from the repository.

​
Cleaning Up the Runner Host

After deleting the runner in the UI, you may want to wipe its local installation, especially if you plan to repurpose the machine.

​
Using the Configuration Script

Run the config.sh remove command on the host. Replace <TOKEN> with the token shown in your runner settings. 
./config.sh remove --token BDEP64UGVZVU2AQTIMJUN3FG7ZKU --unattended
This command will:
  • Uninstall the runner application
  • Remove configuration files
  • Unregister the runner from GitHub
Ensure you copy the exact token from your repository’s runner settings. An invalid token will prevent the runner from unregistering.

​
Stopping the Runner Process Manually

If you skip the config script, simply terminate the running service or process (e.g., run.sh). The runner will appear as offline in GitHub and will not accept new jobs. According to the GitHub documentation, any self-hosted runner offline for over 14 days is automatically removed.
The image shows a GitHub documentation page about removing self-hosted runners, with instructions and notes on the process.

​
Removing a Runner at Organization or Enterprise Level

The steps are identical for organization or enterprise runners:
  1. Go to Organization Settings or Enterprise Settings > Actions > Runners.
  2. Select the runner and click Remove.
  3. On the runner host, run the same config.sh remove command or stop the service.
The image shows a GitHub Docs page about removing a runner from an organization, with instructions and notes on the process. The sidebar lists various GitHub Actions topics.

​
Comparison of Removal Methods

MethodScopeEffectCommand
GitHub UIRepo, Org, EnterpriseImmediate UI removalN/A
config.sh removeRunner hostUninstalls & unregisters runner./config.sh remove --token <TOKEN>
Manual process terminationRunner hostMarks runner offline, auto-prune after 14 dayskill <PID> or stop service

​
References

Watch Video

Practice Lab