Move or disable a runner

Put a self-hosted runner into another runner group, or stop trusting it by revoking its credential.

Last updated 18 November 2026View as Markdown

Replace runner-id with the runner's id and group-id with the group's id.

Prerequisites

  • ci:ManageRunners on all of CI (rn:ews::<organization id>:ci:*). Runners belong to the organization, not to a repository, so the action is checked on the whole service. Without it the console's row menu says "Needs ci:ManageRunners".
  • In the console, also ci:DescribeRunners on all of CI to open Runners; without it the page shows an access-denied notice.

Move a runner to another group

  1. Open Runners under CI.
  2. In the runner's row menu, choose Move to group.
  3. Choose the group, or Default.
  4. Choose Move.

The runner takes only the runs its new group allows, from its next claim on. 404 answers a runner or a group that is not in your organization; "Runner group not found" names the group.

Disable a runner

Disabling revokes the runner's credential: the machine stops taking work and cannot reconnect. The runner stays listed, so past runs still name the machine that ran them. It cannot be enabled again; register the machine anew with a new token instead (see Register a runner).

  1. Open Runners under CI.
  2. In the runner's row menu, choose Disable runner.
  3. Choose Disable.

The runner's status turns Disabled, and its row has no menu from then on.

The answer is 200 with the runner, status disabled; disabling it again answers 200 too. Jobs that need its labels wait for another runner, and fail after 20 minutes if no runner with those labels is online.

Uninstalling the runner software from the machine does not remove it from the list: disable it here as well.

Did this page help you?