Skip to main content

This version of GitHub Enterprise was discontinued on 2023-01-18. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

Removing self-hosted runners

You can permanently remove a self-hosted runner from a repository, an organization, or an enterprise.

Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.

Removing a runner from a repository

Note: This procedure permanently removes the self-hosted runner. If you only want to temporarily stop a runner from being assigned jobs, you can either shut down the machine or stop the run application. The runner will remain assigned in an "Offline" state, and won't execute any jobs until you restart the runner using the run application.

A self-hosted runner is automatically removed from GitHub Enterprise Server if it has not connected to GitHub Actions for more than 30 days.

To remove a self-hosted runner from a user repository you must be the repository owner. For an organization repository, you must be an organization owner or have admin access to the repository. We recommend that you also have access to the self-hosted runner machine. For information about how to remove a self-hosted runner with the REST API, see "Self-hosted runners."

Alternatively, if you don't have access to the repository, organization, or enterprise on GitHub Enterprise Server to remove a runner, but you would like to re-use the runner machine, then you can delete the .runner file inside the self-hosted runner application directory. This allows the runner to be registered without having to re-download the self-hosted runner application.

  1. On your GitHub Enterprise Server instance, navigate to the main page of the repository.

  2. Under your repository name, click Settings. Repository settings button

  3. In the left sidebar, click Actions.

  4. In the left sidebar, under "Actions", click Runners.

  5. Under "Runners", locate the runner in the list. If your runner is in a group, click to expand the list.

  6. Click next to the runner you want to remove, then click Remove.

    Removing a self-hosted runner setting

  7. You will see instructions for removing the self-hosted runner. Complete either of the following steps to remove the runner, depending on whether it is still accessible:

    • If you have access to the runner machine: Follow the on-screen instructions for your machine's operating system to run the removal command. The instructions include the required URL and an automatically-generated, time-limited token.

      The removal command does the following tasks:

      • Removes the runner from GitHub Enterprise Server.
      • Removes any self-hosted runner application configuration files on the machine.
      • Removes any services configured if not running in interactive mode.
    • If you don't have access to the machine: Click Yes, force remove this runner to force GitHub Enterprise Server to remove the runner.

Removing a runner from an organization

Note: This procedure permanently removes the self-hosted runner. If you only want to temporarily stop a runner from being assigned jobs, you can either shut down the machine or stop the run application. The runner will remain assigned in an "Offline" state, and won't execute any jobs until you restart the runner using the run application.

A self-hosted runner is automatically removed from GitHub Enterprise Server if it has not connected to GitHub Actions for more than 30 days.

To remove a self-hosted runner from an organization, you must be an organization owner. We recommend that you also have access to the self-hosted runner machine. For information about how to remove a self-hosted runner with the REST API, see "Self-hosted runners."

Alternatively, if you don't have access to the repository, organization, or enterprise on GitHub Enterprise Server to remove a runner, but you would like to re-use the runner machine, then you can delete the .runner file inside the self-hosted runner application directory. This allows the runner to be registered without having to re-download the self-hosted runner application.

  1. On your GitHub Enterprise Server instance, navigate to the main page of the organization.

  2. Under your organization name, click Settings.

    Organization settings button

  3. In the left sidebar, click Actions.

  4. In the left sidebar, under "Actions", click Runners.

  5. Under "Runners", locate the runner in the list. If your runner is in a group, click to expand the list.

  6. Click next to the runner you want to remove, then click Remove.

    Removing a self-hosted runner setting

  7. You will see instructions for removing the self-hosted runner. Complete either of the following steps to remove the runner, depending on whether it is still accessible:

    • If you have access to the runner machine: Follow the on-screen instructions for your machine's operating system to run the removal command. The instructions include the required URL and an automatically-generated, time-limited token.

      The removal command does the following tasks:

      • Removes the runner from GitHub Enterprise Server.
      • Removes any self-hosted runner application configuration files on the machine.
      • Removes any services configured if not running in interactive mode.
    • If you don't have access to the machine: Click Yes, force remove this runner to force GitHub Enterprise Server to remove the runner.

Removing a runner from an enterprise

Note: This procedure permanently removes the self-hosted runner. If you only want to temporarily stop a runner from being assigned jobs, you can either shut down the machine or stop the run application. The runner will remain assigned in an "Offline" state, and won't execute any jobs until you restart the runner using the run application.

A self-hosted runner is automatically removed from GitHub Enterprise Server if it has not connected to GitHub Actions for more than 30 days.

To remove a self-hosted runner from an enterprise, you must be an enterprise owner. We recommend that you also have access to the self-hosted runner machine. For information about how to remove a self-hosted runner with the REST API, see the enterprise endpoints in the GitHub Actions REST API.

Alternatively, if you don't have access to the repository, organization, or enterprise on GitHub Enterprise Server to remove a runner, but you would like to re-use the runner machine, then you can delete the .runner file inside the self-hosted runner application directory. This allows the runner to be registered without having to re-download the self-hosted runner application.

  1. In the top-right corner of GitHub Enterprise Server, click your profile photo, then click Enterprise settings. "Enterprise settings" in drop-down menu for profile photo on GitHub Enterprise Server

  2. In the enterprise sidebar, click Policies. Policies tab in the enterprise account sidebar

  3. Under " Policies", click Actions.

  4. Click the Runners tab.

  5. Under "Runners", locate the runner in the list. If your runner is in a group, click to expand the list.

  6. Click next to the runner you want to remove, then click Remove.

    Removing a self-hosted runner setting

  7. You will see instructions for removing the self-hosted runner. Complete either of the following steps to remove the runner, depending on whether it is still accessible:

    • If you have access to the runner machine: Follow the on-screen instructions for your machine's operating system to run the removal command. The instructions include the required URL and an automatically-generated, time-limited token.

      The removal command does the following tasks:

      • Removes the runner from GitHub Enterprise Server.
      • Removes any self-hosted runner application configuration files on the machine.
      • Removes any services configured if not running in interactive mode.
    • If you don't have access to the machine: Click Yes, force remove this runner to force GitHub Enterprise Server to remove the runner.