Add API to "Play" a scheduled pipeline immediately

This brings parity to the API, as currently this can only be done via
the UI.

changelogs/unreleased/rs-scheduled-pipeline-play-api.yml

+---
+title: Add API to "Play" a scheduled pipeline immediately
+merge_request: 23718
+author:
+type: added

doc/api/pipeline_schedules.md

@@ -279,6 +279,36 @@ curl --request DELETE --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" "https://gi
 }
 ```
 
+## Run a scheduled pipeline immediately
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/201786) in GitLab 12.8.
+
+Trigger a new scheduled pipeline, which runs immediately. The next scheduled run
+of this pipeline is not affected.
+
+```text
+POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/play
+```
+
+| Attribute              | Type           | required   | Description                                                                                                     |
+| ----------------       | ---------      | ---------- | --------------------------                                                                                      |
+| `id`                   | integer/string | yes        | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `pipeline_schedule_id` | integer        | yes        | The pipeline schedule id                                                                                        |
+
+Example request:
+
+```sh
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/42/pipeline_schedules/1/play
+```
+
+Example response:
+
+```json
+{
+  "message": "201 Created"
+}
+```
+
 ## Pipeline schedule variables
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/34518) in GitLab 10.0.

lib/api/pipeline_schedules.rb

@@ -111,6 +111,25 @@ module API
         destroy_conditionally!(pipeline_schedule)
       end
 
+      desc 'Play a scheduled pipeline immediately' do
+        detail 'This feature was added in GitLab 12.8'
+      end
+      params do
+        requires :pipeline_schedule_id, type: Integer, desc: 'The pipeline schedule id'
+      end
+      post ':id/pipeline_schedules/:pipeline_schedule_id/play' do
+        authorize! :play_pipeline_schedule, pipeline_schedule
+
+        job_id = RunPipelineScheduleWorker
+          .perform_async(pipeline_schedule.id, current_user.id)
+
+        if job_id
+          created!
+        else
+          render_api_error!('Unable to schedule pipeline run immediately', 500)
+        end
+      end
+
       desc 'Create a new pipeline schedule variable' do
         success Entities::Variable
       end

spec/requests/api/pipeline_schedules_spec.rb

@@ -322,6 +322,56 @@ describe API::PipelineSchedules do
     end
   end
 
+  describe 'POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/play' do
+    let_it_be(:pipeline_schedule) { create(:ci_pipeline_schedule, project: project) }
+
+    let(:route) { ->(id) { "/projects/#{project.id}/pipeline_schedules/#{id}/play" } }
+
+    context 'authenticated user with `:play_pipeline_schedule` permission' do
+      it 'schedules a pipeline worker' do
+        project.add_developer(developer)
+
+        expect(RunPipelineScheduleWorker)
+          .to receive(:perform_async)
+          .with(pipeline_schedule.id, developer.id)
+          .and_call_original
+        post api(route[pipeline_schedule.id], developer)
+
+        expect(response).to have_gitlab_http_status(:created)
+      end
+
+      it 'renders an error if scheduling failed' do
+        project.add_developer(developer)
+
+        expect(RunPipelineScheduleWorker)
+          .to receive(:perform_async)
+          .with(pipeline_schedule.id, developer.id)
+          .and_return(nil)
+        post api(route[pipeline_schedule.id], developer)
+
+        expect(response).to have_gitlab_http_status(:internal_server_error)
+      end
+    end
+
+    context 'authenticated user with insufficient access' do
+      it 'responds with not found' do
+        project.add_guest(user)
+
+        post api(route[pipeline_schedule.id], user)
+
+        expect(response).to have_gitlab_http_status(:not_found)
+      end
+    end
+
+    context 'unauthenticated user' do
+      it 'responds with unauthorized' do
+        post api(route[pipeline_schedule.id])
+
+        expect(response).to have_gitlab_http_status(:unauthorized)
+      end
+    end
+  end
+
   describe 'POST /projects/:id/pipeline_schedules/:pipeline_schedule_id/variables' do
     let(:params) { attributes_for(:ci_pipeline_schedule_variable) }