Filter deployments using the environment & status

This adds support to DeploymentsFinder and the deployments API for
filtering deployments using an environment name and/or deployment
status. This for example allows one to get all successful deployments
for the "production" environment, without having to filter out
deployments manually.

app/finders/deployments_finder.rb

@@ -17,6 +17,8 @@ class DeploymentsFinder
   def execute
     items = init_collection
     items = by_updated_at(items)
+    items = by_environment(items)
+    items = by_status(items)
     sort(items)
   end
 
@@ -58,6 +60,24 @@ class DeploymentsFinder
     items
   end
 
+  def by_environment(items)
+    if params[:environment].present?
+      items.for_environment_name(params[:environment])
+    else
+      items
+    end
+  end
+
+  def by_status(items)
+    return items unless params[:status].present?
+
+    unless Deployment.statuses.key?(params[:status])
+      raise ArgumentError, "The deployment status #{params[:status]} is invalid"
+    end
+
+    items.for_status(params[:status])
+  end
+
   def sort_params
     order_by = ALLOWED_SORT_VALUES.include?(params[:order_by]) ? params[:order_by] : DEFAULT_SORT_VALUE
     order_direction = ALLOWED_SORT_DIRECTIONS.include?(params[:sort]) ? params[:sort] : DEFAULT_SORT_DIRECTION

app/models/deployment.rb

@@ -30,6 +30,11 @@ class Deployment < ApplicationRecord
   delegate :name, to: :environment, prefix: true
 
   scope :for_environment, -> (environment) { where(environment_id: environment) }
+  scope :for_environment_name, -> (name) do
+    joins(:environment).where(environments: { name: name })
+  end
+
+  scope :for_status, -> (status) { where(status: status) }
 
   scope :visible, -> { where(status: %i[running success failed canceled]) }
 

changelogs/unreleased/deployments-api-filters.yml

+---
+title: Filter deployments using the environment & status
+merge_request: 22996
+author:
+type: added

doc/api/deployments.md

@@ -15,6 +15,16 @@ GET /projects/:id/deployments
 | `sort`    | string  | no       | Return deployments sorted in `asc` or `desc` order. Default is `asc` |
 | `updated_after` | datetime | no | Return deployments updated after the specified date |
 | `updated_before` | datetime | no | Return deployments updated before the specified date |
+| `environment` | string | no | The name of the environment to filter deployments by |
+| `status` | string | no | The status to filter deployments by |
+
+The status attribute can be one of the following values:
+
+- created
+- running
+- success
+- failed
+- canceled
 
 ```bash
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments"

lib/api/deployments.rb

@@ -21,6 +21,14 @@ module API
         optional :sort, type: String, values: DeploymentsFinder::ALLOWED_SORT_DIRECTIONS, default: DeploymentsFinder::DEFAULT_SORT_DIRECTION, desc: 'Sort by asc (ascending) or desc (descending)'
         optional :updated_after, type: DateTime, desc: 'Return deployments updated after the specified date'
         optional :updated_before, type: DateTime, desc: 'Return deployments updated before the specified date'
+        optional :environment,
+          type: String,
+          desc: 'The name of the environment to filter deployments by'
+
+        optional :status,
+          type: String,
+          values: Deployment.statuses.keys,
+          desc: 'The status to filter deployments by'
       end
 
       get ':id/deployments' do

spec/finders/deployments_finder_spec.rb

@@ -25,6 +25,42 @@ describe DeploymentsFinder do
           is_expected.to match_array([deployment_1])
         end
       end
+
+      context 'when the environment name is specified' do
+        let!(:environment1) { create(:environment, project: project) }
+        let!(:environment2) { create(:environment, project: project) }
+        let!(:deployment1) do
+          create(:deployment, project: project, environment: environment1)
+        end
+
+        let!(:deployment2) do
+          create(:deployment, project: project, environment: environment2)
+        end
+
+        let(:params) { { environment: environment1.name } }
+
+        it 'returns deployments for the given environment' do
+          is_expected.to match_array([deployment1])
+        end
+      end
+
+      context 'when the deployment status is specified' do
+        let!(:deployment1) { create(:deployment, :success, project: project) }
+        let!(:deployment2) { create(:deployment, :failed, project: project) }
+        let(:params) { { status: 'success' } }
+
+        it 'returns deployments for the given environment' do
+          is_expected.to match_array([deployment1])
+        end
+      end
+
+      context 'when using an invalid deployment status' do
+        let(:params) { { status: 'kittens' } }
+
+        it 'raises ArgumentError' do
+          expect { subject }.to raise_error(ArgumentError)
+        end
+      end
     end
 
     describe 'ordering' do

spec/requests/api/deployments_spec.rb

@@ -40,6 +40,18 @@ describe API::Deployments do
         end
       end
 
+      context 'with the environment filter specifed' do
+        it 'returns deployments for the environment' do
+          get(
+            api("/projects/#{project.id}/deployments", user),
+            params: { environment: deployment_1.environment.name }
+          )
+
+          expect(json_response.size).to eq(1)
+          expect(json_response.first['iid']).to eq(deployment_1.iid)
+        end
+      end
+
       describe 'ordering' do
         let(:order_by) { 'iid' }
         let(:sort) { 'desc' }