Skip to main content

Removing self-hosted runners

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

Removing a runner from a repository

Notes:

  • 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 Cloud if it has not connected to GitHub Actions for more than 14 days. An ephemeral self-hosted runner is automatically removed from GitHub Enterprise Cloud if it has not connected to GitHub Actions for more than 1 day.
  • Just-in-time (JIT) runners can only run a single job. If JIT runners never run a job, they will automatically be removed. To remove a JIT runner before automatic removal, you must remove the JIT runner on GitHub.com.

To remove a self-hosted runner from a user repository you must be the repository owner. Organization owners and users with the "Manage organization runners and runner groups" permission can remove a runner from a repository in the organization. For more information about custom organization roles, see "About custom organization roles."

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 "REST API endpoints for self-hosted runners."

Alternatively, if you don't have access to the repository, organization, or enterprise on GitHub Enterprise Cloud 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 (that is, the directory into which you downloaded and unpacked the runner software). This allows the runner to be registered without having to re-download the self-hosted runner application.

  1. On GitHub.com, navigate to the main page of the repository.

  2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.

  3. In the left sidebar, click Actions, then click Runners.

  4. In the list of runners, click on the name of the runner you'd like to configure.

  5. Click Remove.

  6. 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 Cloud.
      • 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 Force remove this runner to force GitHub Enterprise Cloud to remove the runner.

Removing a runner from an organization

Notes:

  • 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 Cloud if it has not connected to GitHub Actions for more than 14 days. An ephemeral self-hosted runner is automatically removed from GitHub Enterprise Cloud if it has not connected to GitHub Actions for more than 1 day.
  • Just-in-time (JIT) runners can only run a single job. If JIT runners never run a job, they will automatically be removed. To remove a JIT runner before automatic removal, you must remove the JIT runner on GitHub.com.

To remove a self-hosted runner from an organization, you must be an organization owner or have the "Manage organization runners and runner groups" permission. 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 "REST API endpoints for self-hosted runners."

For more information about custom organization roles, see "About custom organization roles."

Alternatively, if you don't have access to the repository, organization, or enterprise on GitHub Enterprise Cloud 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 (that is, the directory into which you downloaded and unpacked the runner software). This allows the runner to be registered without having to re-download the self-hosted runner application.

  1. On GitHub.com, navigate to the main page of the organization.

  2. Under your organization name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of the tabs in an organization's profile. The "Settings" tab is outlined in dark orange.

  3. In the left sidebar, click Actions, then click Runners.

  4. In the list of runners, click on the name of the runner you'd like to configure.

  5. Click Remove.

  6. 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 Cloud.
      • 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 Force remove this runner to force GitHub Enterprise Cloud to remove the runner.

Removing a runner from an enterprise

Notes:

  • 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 Cloud if it has not connected to GitHub Actions for more than 14 days. An ephemeral self-hosted runner is automatically removed from GitHub Enterprise Cloud if it has not connected to GitHub Actions for more than 1 day.
  • Just-in-time (JIT) runners can only run a single job. If JIT runners never run a job, they will automatically be removed. To remove a JIT runner before automatic removal, you must remove the JIT runner on GitHub.com.

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 Cloud 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 (that is, the directory into which you downloaded and unpacked the runner software). 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.com, click your profile photo, then click Your enterprises.

  2. In the list of enterprises, click the enterprise you want to view.

  3. In the enterprise account sidebar, click Policies.

  4. Under " Policies", click Actions.

  5. Click the Runners tab.

  6. In the list of runners, click on the name of the runner you'd like to configure.

  7. Click Remove.

  8. 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 Cloud.
      • 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 Force remove this runner to force GitHub Enterprise Cloud to remove the runner.