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 whereverupdate_runneris, 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::ResetAuthenticationTokenServicenow checks the new ability. Both admin paths go through it:POST /runners/:id/reset_authentication_tokenand token revocation throughPOST /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_tokenwith 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_runnerin 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_instanceis false. This example fails if the lock is gated onGitlab::Dedicated.feature_available?(:hosted_runners).
- CE: the new ability follows
- 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_apisucceeds; 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,
689ab88db44bmerged with master34ef0d2e2808):ee/spec/lib/authn/tokens/runner_authentication_token_spec.rbee/spec/policies/ee/ci/runner_policy_spec.rbee/spec/requests/api/ci/runners_spec.rbee/spec/services/ee/ci/runners/reset_authentication_token_service_spec.rbspec/policies/ci/runner_policy_spec.rbspec/lib/authn/tokens/runner_authentication_token_spec.rbspec/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_checkandgettext:lintpass.rake gitlab:permissions:validatepasses (ated49247f7dbb; 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
689ab88db44bmerged with master34ef0d2e2808, which includes Trust only hosted registrations for Dedicated G... (!263883 - merged).
How to set up and validate
- Simulate a Dedicated instance: set
gitlab_dedicated_instancetotruein application settings. - 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. - As an admin,
POST /api/v4/runners/:id/reset_authentication_token→ 403 with the message above, token unchanged. - Register an instance runner through the UI or
POST /api/v4/user/runnersand 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::Runnermethod 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_runnerfor 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+.