Is it possible to reconfigure a self-hosted runner?

[Rod-at-DOH]

🏷️ Discussion Type

Question

💬 Feature/Topic Area

Actions Runner

Discussion Details

About 3 years ago I configured a GitHub Self-Hosted Runner to run on one of our Windows Servers. It has worked fine and since then its use has increased to several hundreds of GitHub runs per month.

However, when I configured that self-hosted runner, I did so only for 1 GitHub organization. At the time, that was fine, as we only had 2 organizations, and even removed one of them. However, this year we've added 2 more GitHub organizations. I foresee the possibility of adding even more GitHub organizations. The 2 new organizations we've added will only have scripting code, such as SAS, R, Python, and SQL. None of them, I believe, will require a GitHub Action for deployments. But I am not so sure about the other organizations we may need to add. Now I'm wondering if I can take the self-hosted runner, which is only configured to be used by the one organization we had 3 years ago, to our GitHub Enterprise level. (I think it is possible to have a self-hosted runner on a Windows Server, configured for a GitHub Enterprise.) If that is possible, then how do we go about reconfiguring our self-hosted runner?

[ChHussain]

Yes,you can use a self-hosted runner at the enterprise level in GitHub, but you won’t be able to directly convert your existing organization-level runner. Instead, you’ll need to remove and re-register it under the enterprise scope.

At a high level, self-hosted runners in GitHub can be configured at three levels: repository, organization, and enterprise. Enterprise-level runners are designed for exactly your use case — sharing runners across multiple organizations.

To move your existing runner:

1. Go to your enterprise account settings → Actions → Runners, and create a new self-hosted runner there. This will generate a registration token.

2. On your Windows server where the runner is currently installed, remove the existing configuration:

   .\config.cmd remove
   

3. Reconfigure the runner using the enterprise registration details:

   .\config.cmd
   

   When prompted, use the enterprise URL and the new token.

Once registered at the enterprise level, you can use runner groups to control which organizations (or repositories) have access to it. This is especially helpful if you want to separate workloads (e.g., heavy CI vs. lightweight scripting jobs).

One thing to keep in mind: plan the change during a quiet period, since removing the runner will interrupt any jobs currently in progress.

Overall, moving to an enterprise-level runner is a good approach if you expect to support multiple organizations now or in the future.