Merge branch 'pedropombeiro/347211/graphql-deprecate-active-mutation-field' into 'master'

GraphQL: Deprecate active field in RunnerUpdateInput

See merge request gitlab-org/gitlab!79131

app/graphql/mutations/ci/runner/update.rb

@@ -28,7 +28,12 @@ module Mutations
 
         argument :active, GraphQL::Types::Boolean,
                  required: false,
-                 description: 'Indicates the runner is allowed to receive jobs.'
+                 description: 'Indicates the runner is allowed to receive jobs.',
+                 deprecated: { reason: :renamed, replacement: 'paused', milestone: '14.8' }
+
+        argument :paused, GraphQL::Types::Boolean,
+                 required: false,
+                 description: 'Indicates the runner is not allowed to receive jobs.'
 
         argument :locked, GraphQL::Types::Boolean, required: false,
                  description: 'Indicates the runner is locked.'

app/services/ci/update_runner_service.rb

@@ -9,6 +9,8 @@ module Ci
     end
 
     def update(params)
+      params[:active] = !params.delete(:paused) if params.include?(:paused)
+
       runner.update(params).tap do |updated|
         runner.tick_runner_queue if updated
       end

data/deprecations/14-5-runner-api-status-does-contain-paused.yml

-- name: "REST API Runner will not contain `paused`"
+- name: "REST and GraphQL API Runner status will not return `paused`"
   announcement_milestone: "14.5" # The milestone when this feature was first announced as deprecated.
   announcement_date: "2021-11-22"
   removal_milestone: "15.0" # the milestone when this feature is planned to be removed

data/deprecations/14-8-runner-api-active-field-replaced-with-paused-breaking-change.yml

+- name: "REST and GraphQL API Runner usage of `active` replaced by `paused`"
+  announcement_milestone: "14.8"
+  announcement_date: "2022-02-22"
+  removal_milestone: "15.0"
+  removal_date: "2022-05-22"
+  breaking_change: true
+  reporter: pedropombeiro
+  body: |
+    Occurrences of the `active` identifier in the GitLab Runner REST and GraphQL API endpoints will be
+    renamed to `paused` in GitLab 15.0, namely:
+
+    - GraphQL API:
+      - the `CiRunner` property;
+      - the `RunnerUpdateInput` input type for the `runnerUpdate` mutation;
+      - the `runners` and `Group.runners` queries.
+    - REST API:
+      - endpoints taking or returning `active` properties, such as:
+        - `GET /runners`
+        - `GET /runners/all`
+        - `GET /runners/:id` / `PUT /runners/:id`
+        - `PUT --form "active=false" /runners/:runner_id`
+        - `GET /projects/:id/runners` / `POST /projects/:id/runners`
+        - `GET /groups/:id/runners`
+
+    The 15.0 release of the GitLab Runner will start using the `paused` property when registering runners, and therefore
+    will only be compatible with GitLab 15.0 and later. Until 15.0, GitLab will accept the deprecated `active` flag from
+    existing runners.
+  stage: Verify
+  tiers: [Core, Premium, Ultimate]
+  issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/347211
+  documentation_url: https://docs.gitlab.com/ee/api/runners.html
+  image_url: # (optional) This is a link to a thumbnail image depicting the feature
+  video_url: # (optional) Use the youtube thumbnail URL with the structure of https://img.youtube.com/vi/UNIQUEID/hqdefault.jpg

doc/api/graphql/reference/index.md

@@ -4158,12 +4158,13 @@ Input type: `RunnerUpdateInput`
 | Name | Type | Description |
 | ---- | ---- | ----------- |
 | <a id="mutationrunnerupdateaccesslevel"></a>`accessLevel` | [`CiRunnerAccessLevel`](#cirunneraccesslevel) | Access level of the runner. |
-| <a id="mutationrunnerupdateactive"></a>`active` | [`Boolean`](#boolean) | Indicates the runner is allowed to receive jobs. |
+| <a id="mutationrunnerupdateactive"></a>`active` **{warning-solid}** | [`Boolean`](#boolean) | **Deprecated:** This was renamed. Please use `paused`. Deprecated in 14.8. |
 | <a id="mutationrunnerupdateclientmutationid"></a>`clientMutationId` | [`String`](#string) | A unique identifier for the client performing the mutation. |
 | <a id="mutationrunnerupdatedescription"></a>`description` | [`String`](#string) | Description of the runner. |
 | <a id="mutationrunnerupdateid"></a>`id` | [`CiRunnerID!`](#cirunnerid) | ID of the runner to update. |
 | <a id="mutationrunnerupdatelocked"></a>`locked` | [`Boolean`](#boolean) | Indicates the runner is locked. |
 | <a id="mutationrunnerupdatemaximumtimeout"></a>`maximumTimeout` | [`Int`](#int) | Maximum timeout (in seconds) for jobs processed by the runner. |
+| <a id="mutationrunnerupdatepaused"></a>`paused` | [`Boolean`](#boolean) | Indicates the runner is not allowed to receive jobs. |
 | <a id="mutationrunnerupdateprivateprojectsminutescostfactor"></a>`privateProjectsMinutesCostFactor` | [`Float`](#float) | Private projects' "minutes cost factor" associated with the runner (GitLab.com only). |
 | <a id="mutationrunnerupdatepublicprojectsminutescostfactor"></a>`publicProjectsMinutesCostFactor` | [`Float`](#float) | Public projects' "minutes cost factor" associated with the runner (GitLab.com only). |
 | <a id="mutationrunnerupdaterununtagged"></a>`runUntagged` | [`Boolean`](#boolean) | Indicates the runner is able to run untagged jobs. |

doc/update/deprecations.md

@@ -226,7 +226,7 @@ In milestone 15.0, we will remove the `pipelines` attribute from the API respons
 
 **Planned removal milestone: 15.0 (2022-05-22)**
 
-### REST API Runner will not contain `paused`
+### REST and GraphQL API Runner status will not return `paused`
 
 WARNING:
 This feature will be changed or removed in 15.0
@@ -717,6 +717,36 @@ The `merged_by` field in the [merge request API](https://docs.gitlab.com/ee/api/
 
 ## 14.8
 
+### REST and GraphQL API Runner usage of `active` replaced by `paused`
+
+WARNING:
+This feature will be changed or removed in 15.0
+as a [breaking change](https://docs.gitlab.com/ee/development/contributing/#breaking-changes).
+Before updating GitLab, review the details carefully to determine if you need to make any
+changes to your code, settings, or workflow.
+
+Occurrences of the `active` identifier in the GitLab Runner REST and GraphQL API endpoints will be
+renamed to `paused` in GitLab 15.0, namely:
+
+- GraphQL API:
+  - the `CiRunner` property;
+  - the `RunnerUpdateInput` input type for the `runnerUpdate` mutation;
+  - the `runners` and `Group.runners` queries.
+- REST API:
+  - endpoints taking or returning `active` properties, such as:
+    - `GET /runners`
+    - `GET /runners/all`
+    - `GET /runners/:id` / `PUT /runners/:id`
+    - `PUT --form "active=false" /runners/:runner_id`
+    - `GET /projects/:id/runners` / `POST /projects/:id/runners`
+    - `GET /groups/:id/runners`
+
+The 15.0 release of the GitLab Runner will start using the `paused` property when registering runners, and therefore
+will only be compatible with GitLab 15.0 and later. Until 15.0, GitLab will accept the deprecated `active` flag from
+existing runners.
+
+**Planned removal milestone: 15.0 (2022-05-22)**
+
 ### Vulnerability Check
 
 WARNING:

spec/services/ci/update_runner_service_spec.rb

@@ -23,6 +23,20 @@ RSpec.describe Ci::UpdateRunnerService do
       end
     end
 
+    context 'with paused param' do
+      let(:params) { { paused: true } }
+
+      it 'updates the runner and ticking the queue' do
+        expect(runner.active).to be_truthy
+        expect(update).to be_truthy
+
+        runner.reload
+
+        expect(runner).to have_received(:tick_runner_queue)
+        expect(runner.active).to be_falsey
+      end
+    end
+
     context 'with cost factor params' do
       let(:params) { { public_projects_minutes_cost_factor: 1.1, private_projects_minutes_cost_factor: 2.2 }}