Add return_run_details parameter support for workflow dispatch

lib/octokit/client/actions_workflows.rb

@@ -35,11 +35,17 @@ def workflow(repo, id, options = {})
       # @param repo [Integer, String, Repository, Hash] A GitHub repository
       # @param id [Integer, String] Id or file name of the workflow
       # @param ref [String] A SHA, branch name, or tag name
+      # @param options [Hash] Optional parameters
+      # @option options [Boolean] :return_run_details Fetch run details
       #
-      # @return [Boolean] True if event was dispatched, false otherwise
+      # @return [Boolean, Sawyer::Resource] Boolean success or run details
       # @see https://docs.github.com/en/rest/reference/actions#create-a-workflow-dispatch-event
       def workflow_dispatch(repo, id, ref, options = {})
-        boolean_from_response :post, "#{Repository.path repo}/actions/workflows/#{id}/dispatches", options.merge({ ref: ref })
+        merged_params = options.merge({ ref: ref })
+        endpoint_path = "#{Repository.path repo}/actions/workflows/#{id}/dispatches"
+
+        wants_details = merged_params[:return_run_details]
+        wants_details ? post(endpoint_path, merged_params) : boolean_from_response(:post, endpoint_path, merged_params)
       end
 
       # Enable a workflow

spec/octokit/client/actions_workflows_spec.rb

@@ -54,6 +54,44 @@
       @client.workflow_dispatch(@test_repo, workflow_file_name, 'main')
       assert_requested request
     end
+
+    context 'with return_run_details option' do
+      it 'returns a boolean when set to false' do
+        wf_file = 'simple_workflow.yml'
+        http_stub = stub_post("/repos/#{@test_repo}/actions/workflows/#{wf_file}/dispatches")
+
+        output = @client.workflow_dispatch(@test_repo, wf_file, 'main', return_run_details: false)
+
+        expect(output).to be(true).or be(false)
+        assert_requested http_stub
+      end
+
+      it 'gets run details from API response' do
+        wf_file = 'simple_workflow.yml'
+        # rubocop:disable Style/NumericLiterals
+        api_response_body = {
+          workflow_run_id: 22103568458,
+          run_url: "https://api.github.com/repos/#{@test_repo}/actions/runs/22103568458",
+          html_url: "https://github.com/#{@test_repo}/actions/runs/22103568458"
+        }.to_json
+        # rubocop:enable Style/NumericLiterals
+
+        http_stub = stub_post("/repos/#{@test_repo}/actions/workflows/#{wf_file}/dispatches")
+                    .to_return(
+                      status: 200,
+                      body: api_response_body,
+                      headers: { 'Content-Type' => 'application/json' }
+                    )
+
+        output = @client.workflow_dispatch(@test_repo, wf_file, 'main', return_run_details: true)
+
+        expect(output.class.name).to eq('Sawyer::Resource')
+        expect(output.workflow_run_id).to be(22103568458) # rubocop:disable Style/NumericLiterals
+        expect(output.run_url).to match('actions/runs/22103568458')
+        expect(output.html_url).to match("github.com/#{@test_repo}/actions/runs/22103568458")
+        assert_requested http_stub
+      end
+    end
   end # .workflow_dispatch
 
   describe '.workflow_enable' do