API: Add endpoint to reset runner registration token

Add a REST API endpoint to allow the automatic reset of the runner
registration token for the GitLab instance, a group, or a project.

Changelog: added
Issue: https://gitlab.com/gitlab-org/gitlab/-/issues/30942

doc/api/runners.md

@@ -675,3 +675,42 @@ Response:
 |-----------|---------------------------------|
 | 200       | Credentials are valid           |
 | 403       | Credentials are invalid         |
+
+## Reset instance's runner registration token
+
+Resets the runner registration token for the GitLab instance.
+
+```plaintext
+POST /runners/reset_registration_token
+```
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
+     "https://gitlab.example.com/api/v4/runners/reset_registration_token"
+```
+
+## Reset project's runner registration token
+
+Resets the runner registration token for a project.
+
+```plaintext
+POST /projects/:id/runners/reset_registration_token
+```
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
+     "https://gitlab.example.com/api/v4/projects/9/runners/reset_registration_token"
+```
+
+## Reset group's runner registration token
+
+Resets the runner registration token for a group.
+
+```plaintext
+POST /groups/:id/runners/reset_registration_token
+```
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
+     "https://gitlab.example.com/api/v4/groups/9/runners/reset_registration_token"
+```

lib/api/ci/runners.rb

@@ -222,6 +222,56 @@ module API
         end
       end
 
+      resource :runners do
+        before { authenticate_non_get! }
+
+        desc 'Resets runner registration token' do
+          success Entities::Ci::ResetRegistrationTokenResult
+        end
+        post 'reset_registration_token' do
+          authorize! :update_runners_registration_token
+
+          ApplicationSetting.current.reset_runners_registration_token!
+          present ApplicationSetting.current_without_cache.runners_registration_token, with: Entities::Ci::ResetRegistrationTokenResult
+        end
+      end
+
+      params do
+        requires :id, type: String, desc: 'The ID of a project'
+      end
+      resource :projects, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
+        before { authenticate_non_get! }
+
+        desc 'Resets runner registration token' do
+          success Entities::Ci::ResetRegistrationTokenResult
+        end
+        post ':id/runners/reset_registration_token' do
+          project = find_project! user_project.id
+          authorize! :update_runners_registration_token, project
+
+          project.reset_runners_token!
+          present project.runners_token, with: Entities::Ci::ResetRegistrationTokenResult
+        end
+      end
+
+      params do
+        requires :id, type: String, desc: 'The ID of a group'
+      end
+      resource :groups, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
+        before { authenticate_non_get! }
+
+        desc 'Resets runner registration token' do
+          success Entities::Ci::ResetRegistrationTokenResult
+        end
+        post ':id/runners/reset_registration_token' do
+          group = find_group! user_group.id
+          authorize! :update_runners_registration_token, group
+
+          group.reset_runners_token!
+          present group.runners_token, with: Entities::Ci::ResetRegistrationTokenResult
+        end
+      end
+
       helpers do
         def filter_runners(runners, scope, allowed_scopes: ::Ci::Runner::AVAILABLE_SCOPES)
           return runners unless scope.present?

lib/api/entities/ci/reset_registration_token_result.rb

+# frozen_string_literal: true
+
+module API
+  module Entities
+    module Ci
+      class ResetRegistrationTokenResult < Grape::Entity
+        expose(:token) {|object| object}
+      end
+    end
+  end
+end

spec/requests/api/ci/runners_reset_registration_token_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe API::Ci::Runners do
+  subject { post api("#{prefix}/runners/reset_registration_token", user) }
+
+  shared_examples 'bad request' do |result|
+    it 'returns 400 error' do
+      expect { subject }.not_to change { get_token }
+
+      expect(response).to have_gitlab_http_status(:bad_request)
+      expect(json_response).to eq(result)
+    end
+  end
+
+  shared_examples 'unauthenticated' do
+    it 'returns 401 error' do
+      expect { subject }.not_to change { get_token }
+
+      expect(response).to have_gitlab_http_status(:unauthorized)
+    end
+  end
+
+  shared_examples 'unauthorized' do
+    it 'returns 403 error' do
+      expect { subject }.not_to change { get_token }
+
+      expect(response).to have_gitlab_http_status(:forbidden)
+    end
+  end
+
+  shared_examples 'not found' do |scope|
+    it 'returns 404 error' do
+      expect { subject }.not_to change { get_token }
+
+      expect(response).to have_gitlab_http_status(:not_found)
+      expect(json_response).to eq({ 'message' => "404 #{scope.capitalize} Not Found" })
+    end
+  end
+
+  shared_context 'when unauthorized' do |scope|
+    context 'when unauthorized' do
+      let_it_be(:user) { create(:user) }
+
+      context "when not a #{scope} member" do
+        it_behaves_like 'not found', scope
+      end
+
+      context "with a non-admin #{scope} member" do
+        before do
+          target.add_developer(user)
+        end
+
+        it_behaves_like 'unauthorized'
+      end
+    end
+  end
+
+  shared_context 'when authorized' do |scope|
+    it 'resets runner registration token' do
+      expect { subject }.to change { get_token }
+
+      expect(response).to have_gitlab_http_status(:success)
+      expect(json_response).to eq({ 'token' => get_token })
+    end
+
+    if scope != 'instance'
+      context 'when malformed id is provided' do
+        let(:prefix) { "/#{scope.pluralize}/some%20string" }
+
+        it_behaves_like 'not found', scope
+      end
+    end
+  end
+
+  describe '/api/v4/runners/reset_registration_token' do
+    describe 'POST /api/v4/runners/reset_registration_token' do
+      before do
+        ApplicationSetting.create_from_defaults
+        stub_env('IN_MEMORY_APPLICATION_SETTINGS', 'false')
+      end
+
+      let(:prefix) { '' }
+
+      context 'when unauthenticated' do
+        let(:user) { nil }
+
+        it_behaves_like 'unauthenticated'
+      end
+
+      context 'when unauthorized' do
+        let(:user) { create(:user) }
+
+        context "with a non-admin instance member" do
+          it_behaves_like 'unauthorized'
+        end
+      end
+
+      include_context 'when authorized', 'instance' do
+        let_it_be(:user) { create(:user, :admin) }
+
+        def get_token
+          ApplicationSetting.current_without_cache.runners_registration_token
+        end
+      end
+    end
+  end
+
+  describe '/api/v4/groups/:id/runners/reset_registration_token' do
+    describe 'POST /api/v4/groups/:id/runners/reset_registration_token' do
+      let_it_be(:group) { create_default(:group, :private) }
+
+      let(:prefix) { "/groups/#{group.id}" }
+
+      include_context 'when unauthorized', 'group' do
+        let(:target) { group }
+      end
+
+      include_context 'when authorized', 'group' do
+        let_it_be(:user) { create_default(:group_member, :maintainer, user: create(:user), group: group ).user }
+
+        def get_token
+          group.reload.runners_token
+        end
+      end
+    end
+  end
+
+  describe '/api/v4/projects/:id/runners/reset_registration_token' do
+    describe 'POST /api/v4/projects/:id/runners/reset_registration_token' do
+      let_it_be(:project) { create_default(:project) }
+
+      let(:prefix) { "/projects/#{project.id}" }
+
+      include_context 'when unauthorized', 'project' do
+        let(:target) { project }
+      end
+
+      include_context 'when authorized', 'project' do
+        let_it_be(:user) { project.owner }
+
+        def get_token
+          project.reload.runners_token
+        end
+      end
+    end
+  end
+end