Add API to stop stale environments

Changelog: added

app/services/environments/stop_stale_service.rb

@@ -18,7 +18,7 @@ def execute
         )
       end
 
-      ServiceResponse.success(message: 'Successfully scheduled stale environments to stop')
+      ServiceResponse.success(message: 'Successfully requested stop for all stale environments')
     end
   end
 end

doc/api/environments.md

@@ -412,3 +412,28 @@ Example response:
   "updated_at": "2019-05-27T18:55:13.252Z"
 }
 ```
+
+## Stop stale environments
+
+Issue stop request to all environments that were last modified or deployed to before a specified date. Excludes protected environments. Returns `200` if stop request was successful and `400` if the before date is invalid. For details of exactly when the environment is stopped, see [Stop an environment](../ci/environments/index.md#stop-an-environment).
+
+```plaintext
+POST /projects/:id/environments/stop_stale
+```
+
+| Attribute | Type           | Required | Description                                                                                                                                                                                    |
+|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user                                                                                 |
+| `before`  | date           | yes      | Stop environments that have been modified or deployed to before the specified date. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). Valid inputs are between 10 years ago and 1 week ago |
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/stop_stale?before=10%2F10%2F2021"
+```
+
+Example response:
+
+```json
+{
+  "message": "Successfully requested stop for all stale environments"
+}
+```

doc/ci/environments/index.md

@@ -436,6 +436,8 @@ There are multiple ways to clean up [dynamic environments](#create-a-dynamic-env
 - If you do _NOT_ use [merge request pipelines](../pipelines/merge_request_pipelines.md), GitLab stops an environment [when the associated feature branch is deleted](#stop-an-environment-when-a-branch-is-deleted).
 - If you set [an expiry period to an environment](../yaml/index.md#environmentauto_stop_in), GitLab stops an environment [when it's expired](#stop-an-environment-after-a-certain-time-period).
 
+To stop stale environments, you can [use the API](../../api/environments.md#stop-stale-environments).
+
 #### Stop an environment when a branch is deleted
 
 You can configure environments to stop when a branch is deleted.

lib/api/environments.rb

@@ -188,6 +188,35 @@ class Environments < ::API::Base
         present environment, with: Entities::Environment, current_user: current_user
       end
 
+      desc 'Stop stale environments' do
+        detail 'It returns `200` if stale environment check was scheduled successfully'
+        failure [
+          { code: 400, message: 'Bad request' },
+          { code: 401, message: 'Unauthorized' }
+        ]
+        tags %w[environments]
+      end
+      params do
+        requires :before,
+                 type: DateTime,
+                 desc: 'Stop all environments that were last modified or deployed to before this date.'
+      end
+      post ':id/environments/stop_stale' do
+        authorize! :stop_environment, user_project
+
+        bad_request!('Invalid Date') if params[:before] < 10.years.ago || params[:before] > 1.week.ago
+
+        service_response = ::Environments::StopStaleService.new(user_project, current_user, params.slice(:before)).execute
+
+        if service_response.error?
+          status 400
+        else
+          status 200
+        end
+
+        present message: service_response.message
+      end
+
       desc 'Get a specific environment' do
         success Entities::Environment
         failure [

spec/requests/api/environments_spec.rb

@@ -4,12 +4,14 @@
 
 RSpec.describe API::Environments, feature_category: :continuous_delivery do
   let_it_be(:user) { create(:user) }
+  let_it_be(:developer) { create(:user) }
   let_it_be(:non_member) { create(:user) }
   let_it_be(:project) { create(:project, :private, :repository, namespace: user.namespace) }
   let_it_be_with_reload(:environment) { create(:environment, project: project) }
 
   before do
     project.add_maintainer(user)
+    project.add_developer(developer)
   end
 
   describe 'GET /projects/:id/environments', :aggregate_failures do
@@ -182,6 +184,50 @@
     end
   end
 
+  describe 'POST /projects/:id/environments/stop_stale' do
+    context 'as a maintainer' do
+      it 'returns a 200' do
+        post api("/projects/#{project.id}/environments/stop_stale", user), params: { before: 1.week.ago.to_date.to_s }
+
+        expect(response).to have_gitlab_http_status(:ok)
+      end
+
+      it 'returns a 400 for bad input date' do
+        post api("/projects/#{project.id}/environments/stop_stale", user), params: { before: 1.day.ago.to_date.to_s }
+
+        expect(response).to have_gitlab_http_status(:bad_request)
+        expect(json_response['message']).to eq('400 Bad request - Invalid Date')
+      end
+
+      it 'returns a 400 for service error' do
+        expect_next_instance_of(::Environments::StopStaleService) do |service|
+          expect(service).to receive(:execute).and_return(ServiceResponse.error(message: 'Test Error'))
+        end
+
+        post api("/projects/#{project.id}/environments/stop_stale", user), params: { before: 1.week.ago.to_date.to_s }
+
+        expect(response).to have_gitlab_http_status(:bad_request)
+        expect(json_response['message']).to eq('Test Error')
+      end
+    end
+
+    context 'a non member' do
+      it 'rejects the request' do
+        post api("/projects/#{project.id}/environments/stop_stale", non_member), params: { before: 1.week.ago.to_date.to_s }
+
+        expect(response).to have_gitlab_http_status(:not_found)
+      end
+    end
+
+    context 'a developer' do
+      it 'rejects the request' do
+        post api("/projects/#{project.id}/environments/stop_stale", developer), params: { before: 1.week.ago.to_date.to_s }
+
+        expect(response).to have_gitlab_http_status(:forbidden)
+      end
+    end
+  end
+
   describe 'PUT /projects/:id/environments/:environment_id' do
     it 'returns a 200 if name and external_url are changed' do
       url = 'https://mepmep.whatever.ninja'