Add sha filter to list pipelines

To find the pipeline for a specific sha requires scanning the list of
all pipelines for a ref that contains the sha. This makes it hard to
find the pipeline id needed to access a trace for a specific job run
in the pipeline using the API.

app/finders/pipelines_finder.rb

@@ -14,6 +14,7 @@ class PipelinesFinder
     items = by_scope(items)
     items = by_status(items)
     items = by_ref(items)
+    items = by_sha(items)
     items = by_name(items)
     items = by_username(items)
     items = by_yaml_errors(items)
@@ -69,6 +70,14 @@ class PipelinesFinder
     end
   end
 
+  def by_sha(items)
+    if params[:sha].present?
+      items.where(sha: params[:sha])
+    else
+      items
+    end
+  end
+
   def by_name(items)
     if params[:name].present?
       items.joins(:user).where(users: { name: params[:name] })

changelogs/unreleased/jramsay-44880-filter-pipelines-by-sha.yml

+---
+title: Add sha filter to pipelines list API
+merge_request: 18125
+author:
+type: changed

doc/api/pipelines.md

@@ -14,6 +14,7 @@ GET /projects/:id/pipelines
 | `scope`   | string  | no       | The scope of pipelines, one of: `running`, `pending`, `finished`, `branches`, `tags` |
 | `status`  | string  | no       | The status of pipelines, one of: `running`, `pending`, `success`, `failed`, `canceled`, `skipped` |
 | `ref`     | string  | no       | The ref of pipelines |
+| `sha`     | string  | no       | The sha or pipelines |
 | `yaml_errors`| boolean  | no       | Returns pipelines with invalid configurations |
 | `name`| string  | no       | The name of the user who triggered pipelines |
 | `username`| string  | no       | The username of the user who triggered pipelines |

lib/api/pipelines.rb

@@ -19,6 +19,7 @@ module API
         optional :status,   type: String, values: HasStatus::AVAILABLE_STATUSES,
                             desc: 'The status of pipelines'
         optional :ref,      type: String, desc: 'The ref of pipelines'
+        optional :sha,      type: String, desc: 'The sha of pipelines'
         optional :yaml_errors, type: Boolean, desc: 'Returns pipelines with invalid configurations'
         optional :name,     type: String, desc: 'The name of the user who triggered pipelines'
         optional :username, type: String, desc: 'The username of the user who triggered pipelines'

spec/finders/pipelines_finder_spec.rb

@@ -203,5 +203,25 @@ describe PipelinesFinder do
         end
       end
     end
+
+    context 'when sha is specified' do
+      let!(:pipeline) { create(:ci_pipeline, project: project, sha: '97de212e80737a608d939f648d959671fb0a0142') }
+
+      context 'when sha exists' do
+        let(:params) { { sha: '97de212e80737a608d939f648d959671fb0a0142' } }
+
+        it 'returns matched pipelines' do
+          is_expected.to eq([pipeline])
+        end
+      end
+
+      context 'when sha does not exist' do
+        let(:params) { { sha: 'invalid-sha' } }
+
+        it 'returns empty' do
+          is_expected.to be_empty
+        end
+      end
+    end
   end
 end