Prevent admin token resets on Dedicated hosted runners

Problem

On GitLab Dedicated, GitLab creates and operates hosted runners for each tenant and keeps their authentication tokens. Today an instance admin can reset a hosted runner's token through the API.

Resetting a hosted runner's authentication token through the API should not be possible for anyone, so the runner's identity stays under GitLab's control.

With Trust only hosted registrations for Dedicated G... (!263883 - merged) (merged 2026-10-22), which trusts these runners, this is the last prerequisite for restricted models in GitLab-hosted flows on Dedicated.

Change

  • New ability reset_runner_authentication_token. In CE it is granted wherever update_runner is, so nothing changes by default.
  • The EE policy prevents it, for every user, on runners GitLab operates for a Dedicated tenant: instance runners with a hosted registration (Ci::HostedRunner; only GitLab's provisioning creates one).
  • Ci::Runners::ResetAuthenticationTokenService now checks the new ability. Both admin paths go through it: POST /runners/:id/reset_authentication_token and token revocation through POST /admin/token/revoke.
  • On a hosted runner, the refusal says why: "GitLab manages the authentication token of this hosted runner. To rotate it, contact GitLab Support." The runners API returns it with a 403. The token revocation API returns it with a 400, its status for every service error.
  • The Dedicated hosted runners docs get a section on how to rotate a hosted runner token.
  • Unchanged:
    • updating and deleting hosted runners, which are documented customer settings;
    • the runner rotating its own token (POST /runners/reset_authentication_token with the runner's token, source: :runner_api), which does not go through the ability;
    • every runner without a hosted registration, which covers everything off Dedicated.

"Hosted runner" here means a runner with a hosted registration. It is not Ci::Runner#dedicated_gitlab_hosted?, which also matches admin-bot runners without one; those stay resettable.

Uses the same hosted-runner signal as the merged Trust only hosted registrations for Dedicated G... (!263883 - merged): the hosted registration (Switch to using hosted_runners table to disting... (#533869)).

Impact

Today With this MR
Dedicated, hosted runner, any user resets token through the API allowed for admins, new token returned 403 with the message above (400 from POST /admin/token/revoke), token unchanged
Dedicated, hosted runner, admin edits tags/timeout or deletes allowed allowed
Dedicated, hosted runner, runner rotates its own token allowed allowed
Dedicated, runner without a hosted registration allowed allowed
GitLab.com, self-managed allowed allowed

What customers do instead

  • Normal use: nothing. GitLab manages these tokens.
  • Suspected exposure: pause the runner in the Admin area. It stops picking up new jobs. Then contact GitLab Support to rotate the token.
  • The 403 message and the new docs section say the same.
  • A reset by the customer also disconnected the runner GitLab operates, so it needed GitLab anyway.
  • Trade-off: an exposed token stays valid until Support rotates it. A paused runner picks up no jobs meanwhile.

Backward compatibility

  • The new ability mirrors update_runner in CE, so existing roles keep the same reset rights.
  • Open questions for the Dedicated team:
    • Possible consumer: Dedicated tooling that resets hosted-runner tokens through the API with a human admin's credentials.
    • Not known yet; we're confirming with the Dedicated team. Such resets would now be refused.
    • If it does, reset through provisioning. Don't add a per-user exemption: that would reopen the lock.
    • Do all live hosted runners have a hosted registration? Runners without one are not locked.
  • Creating hosted runners through provisioning is unaffected. On a hosted runner, the reset service refuses every user, including the Admin Bot. The runner can still rotate its own token.

Tests

  • Policy specs:
    • CE: the new ability follows update_runner.
    • EE, on Dedicated: no one can reset a hosted runner's token, admin bot included; read, update and delete stay allowed. An admin can still reset an admin-bot-created instance runner without a hosted registration, and a customer-registered runner.
    • EE: a runner with a hosted registration stays locked when gitlab_dedicated_instance is false. This example fails if the lock is gated on Gitlab::Dedicated.feature_available?(:hosted_runners).
  • REST spec: on Dedicated, hosted runner reset → 403 with the message, token unchanged; update and delete still allowed; reset allowed for runners without a hosted registration; off Dedicated, a runner with a hosted registration is still refused.
  • Service spec: an admin and the admin bot are refused on a hosted runner, with the message; runner_api succeeds; an admin can reset a runner without a hosted registration.
  • /admin/token/revoke: refused on a hosted runner; allowed on a runner without a hosted registration and on a customer-registered runner.
  • 376 examples, 0 failures across these 7 spec files (2026-11-01, 689ab88db44b merged with master 34ef0d2e2808):
    • ee/spec/lib/authn/tokens/runner_authentication_token_spec.rb
    • ee/spec/policies/ee/ci/runner_policy_spec.rb
    • ee/spec/requests/api/ci/runners_spec.rb
    • ee/spec/services/ee/ci/runners/reset_authentication_token_service_spec.rb
    • spec/policies/ci/runner_policy_spec.rb
    • spec/lib/authn/tokens/runner_authentication_token_spec.rb
    • spec/services/ci/runners/reset_authentication_token_service_spec.rb
  • The last two CE files are regression runs. This MR doesn't change them.
  • CE spec/requests/api/ci/runners_spec.rb (unchanged API file): 475 examples, 0 failures.
  • gettext:updated_check and gettext:lint pass. rake gitlab:permissions:validate passes (at ed49247f7dbb; no permission files changed since).
  • Later commits: docs wording, rubocop line wraps, two more message assertions (off-Dedicated refusal and token revocation), and a merge of master 34ef0d2e2808 (the same master as above). CI covers them.
  • Run in a GDK sandbox on 2026-11-01 at 689ab88db44b merged with master 34ef0d2e2808, which includes Trust only hosted registrations for Dedicated G... (!263883 - merged).

How to set up and validate

  1. Simulate a Dedicated instance: set gitlab_dedicated_instance to true in application settings.
  2. In a Rails console, create a hosted runner the way provisioning does: Ci::Runners::CreateRunnerService.new(user: Users::Internal.admin_bot, params: { runner_type: 'instance_type', hosted_runner: true }).execute.
  3. As an admin, POST /api/v4/runners/:id/reset_authentication_token → 403 with the message above, token unchanged.
  4. Register an instance runner through the UI or POST /api/v4/user/runners and reset its token → 201, new token.

End-to-end check (GDK sandbox simulating Dedicated, 2026-11-01, 689ab88db44b, same merge):

  • Admin reset of a hosted runner (created by the admin bot, with a hosted registration) → 403 with the message, token unchanged.
  • Admin reset of an instance runner without a hosted registration → 201, new token.
  • A runner rotating its own token → 201, and the new token verifies.
  • Admin pause and unpause of the hosted runner → 200.

Not in this MR

  • One shared Ci::Runner method for this check and the runner validator's hosted-runner check: https://gitlab.com/gitlab-org/gitlab/-/work_items/635228+ (confidential).

  • The REST route keeps permissions: :update_runner for granular tokens, because the new ability isn't in an assignable permission group. The new ability is checked in the reset service, which the endpoint calls.

Context

Part of https://gitlab.com/gitlab-org/gitlab/-/work_items/633832+.

Edited by Meir Benayoun

Merge request reports

Loading
Loading