Merge branch 'aw-rest-api-manual-job-variables' into 'master'

Add job_variables_attributes to play build API

See merge request gitlab-org/gitlab!81317

doc/api/jobs.md

@@ -822,16 +822,38 @@ Triggers a manual action to start a job.
 POST /projects/:id/jobs/:job_id/play
 ```
 
-| Attribute | Type           | Required               | Description |
-|-----------|----------------|------------------------|-------------|
-| `id`      | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
-| `job_id`  | integer        | **{check-circle}** Yes | ID of a job. |
+| Attribute                  | Type            | Required               | Description |
+|----------------------------|-----------------|------------------------|-------------|
+| `id`                       | integer/string  | **{check-circle}** Yes | ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `job_id`                   | integer         | **{check-circle}** Yes | ID of a job. |
+| `job_variables_attributes` | array of hashes | **{dotted-circle}** No | An array containing the custom variables available to the job. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/37267) GitLab 14.9. |
+
+Example request:
 
 ```shell
-curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/1/play"
+curl --request POST "https://gitlab.example.com/api/v4/projects/1/jobs/1/play
+     --header "PRIVATE-TOKEN: <your_access_token>"
+     --data @variables.json
 ```
 
-Example of response
+`@variables.json` is structured like:
+
+```json
+{
+  "job_variables_attributes": [
+    {
+      "key": "TEST_VAR_1",
+      "value": "test1"
+    },
+    {
+      "key": "TEST_VAR_2",
+      "value": "test2"
+    }
+  ]
+}
+```
+
+Example response:
 
 ```json
 {

lib/api/ci/jobs.rb

@@ -144,6 +144,11 @@ module API
         end
         params do
           requires :job_id, type: Integer, desc: 'The ID of a Job'
+          optional :job_variables_attributes, type: Array,
+            desc: 'User defined variables that will be included when running the job' do
+            requires :key, type: String, desc: 'The name of the variable'
+            requires :value, type: String, desc: 'The value of the variable'
+          end
         end
 
         post ':id/jobs/:job_id/play', urgency: :low, feature_category: :continuous_integration do
@@ -155,7 +160,7 @@ module API
 
           bad_request!("Unplayable Job") unless job.playable?
 
-          job.play(current_user)
+          job.play(current_user, params[:job_variables_attributes])
 
           status 200
 

spec/requests/api/ci/jobs_spec.rb

@@ -707,12 +707,14 @@ RSpec.describe API::Ci::Jobs do
   end
 
   describe 'POST /projects/:id/jobs/:job_id/play' do
+    let(:params) { {} }
+
     before do
-      post api("/projects/#{project.id}/jobs/#{job.id}/play", api_user)
+      post api("/projects/#{project.id}/jobs/#{job.id}/play", api_user), params: params
     end
 
     context 'on a playable job' do
-      let_it_be(:job) { create(:ci_bridge, :playable, pipeline: pipeline, downstream: project) }
+      let_it_be(:job) { create(:ci_build, :manual, project: project, pipeline: pipeline) }
 
       before do
         project.add_developer(user)
@@ -720,6 +722,8 @@ RSpec.describe API::Ci::Jobs do
 
       context 'when user is authorized to trigger a manual action' do
         context 'that is a bridge' do
+          let_it_be(:job) { create(:ci_bridge, :playable, pipeline: pipeline, downstream: project) }
+
           it 'plays the job' do
             expect(response).to have_gitlab_http_status(:ok)
             expect(json_response['user']['id']).to eq(user.id)
@@ -729,8 +733,6 @@ RSpec.describe API::Ci::Jobs do
         end
 
         context 'that is a build' do
-          let_it_be(:job) { create(:ci_build, :manual, project: project, pipeline: pipeline) }
-
           it 'plays the job' do
             expect(response).to have_gitlab_http_status(:ok)
             expect(json_response['user']['id']).to eq(user.id)
@@ -738,6 +740,47 @@ RSpec.describe API::Ci::Jobs do
             expect(job.reload).to be_pending
           end
         end
+
+        context 'when the user provides valid custom variables' do
+          let(:params) { { job_variables_attributes: [{ key: 'TEST_VAR', value: 'test' }] } }
+
+          it 'applies the variables to the job' do
+            expect(response).to have_gitlab_http_status(:ok)
+            expect(job.reload).to be_pending
+            expect(job.job_variables.map(&:key)).to contain_exactly('TEST_VAR')
+            expect(job.job_variables.map(&:value)).to contain_exactly('test')
+          end
+        end
+
+        context 'when the user provides a variable without a key' do
+          let(:params) { { job_variables_attributes: [{ value: 'test' }] } }
+
+          it 'reports that the key is missing' do
+            expect(response).to have_gitlab_http_status(:bad_request)
+            expect(json_response['error']).to eq('job_variables_attributes[0][key] is missing')
+            expect(job.reload).to be_manual
+          end
+        end
+
+        context 'when the user provides a variable without a value' do
+          let(:params) { { job_variables_attributes: [{ key: 'TEST_VAR' }] } }
+
+          it 'reports that the value is missing' do
+            expect(response).to have_gitlab_http_status(:bad_request)
+            expect(json_response['error']).to eq('job_variables_attributes[0][value] is missing')
+            expect(job.reload).to be_manual
+          end
+        end
+
+        context 'when the user provides both valid and invalid variables' do
+          let(:params) { { job_variables_attributes: [{ key: 'TEST_VAR', value: 'test' }, { value: 'test2' }] } }
+
+          it 'reports the invalid variables and does not run the job' do
+            expect(response).to have_gitlab_http_status(:bad_request)
+            expect(json_response['error']).to eq('job_variables_attributes[1][key] is missing')
+            expect(job.reload).to be_manual
+          end
+        end
       end
 
       context 'when user is not authorized to trigger a manual action' do