Support return_run_details parameter in workflow_dispatch

[Copilot]

Implementation Plan for workflow_dispatch return_run_details Support

• Understand the existing codebase structure
• Modify workflow_dispatch method in lib/octokit/client/actions_workflows.rb
  • Add conditional logic to check for return_run_details option
  • Use post when return_run_details is true, boolean_from_response otherwise
  • Update documentation/comments
• Add test cases in spec/octokit/client/actions_workflows_spec.rb
  • Add test for return_run_details: true scenario
  • Keep existing test for default boolean behavior
  • Updated test to use actual GitHub API response format (workflow_run_id, run_url, html_url)
  • Updated to use workflow run ID without underscores (22103568458) to match API format
• Run tests to validate changes
  • All 8 tests pass
• Verify no unintended side effects
  • Confirmed boolean_from_response was not modified
  • Verified backward compatibility with existing behavior
  • Fixed linting issues
• Request code review
  • Reviewed and confirmed implementation is correct
  • CodeQL security scan: 0 alerts
• Address feedback
  • Updated test response to match actual GitHub API format
  • Removed underscores from workflow run ID to exactly match API response

Original prompt

Problem

The GitHub API endpoint POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches now accepts a new parameter return_run_details. When return_run_details: true is passed (with API version 2022-11-28), the API returns 200 with a JSON body containing workflow run details, instead of the usual 204 No Content.

The current workflow_dispatch method in lib/octokit/client/actions_workflows.rb (line 41-43) uses boolean_from_response, which:

1. Only considers [201, 202, 204] as success (see lib/octokit/connection.rb line 168-173). A 200 response is treated as failure, so the method incorrectly returns false even though the dispatch succeeded.
2. Completely discards the response body, so even if we added 200 to the success list, the user would never receive the run details JSON.

This is a breaking behavior change — users who pass return_run_details: true will get false back instead of the run details.

Current Code

lib/octokit/client/actions_workflows.rb (lines 41-43):

def workflow_dispatch(repo, id, ref, options = {})
  boolean_from_response :post, "#{Repository.path repo}/actions/workflows/#{id}/dispatches", options.merge({ ref: ref })
end

lib/octokit/connection.rb (lines 168-173):

def boolean_from_response(method, path, options = {})
  request(method, path, options)
  [201, 202, 204].include? @last_response.status
rescue Octokit::NotFound
  false
end

spec/octokit/client/actions_workflows_spec.rb (lines 49-57):

describe '.workflow_dispatch', :vcr do
  it 'creates a workflow dispatch event' do
    workflow_file_name = 'simple_workflow.yml'
    request = stub_post("/repos/#{@test_repo}/actions/workflows/#{workflow_file_name}/dispatches")

    @client.workflow_dispatch(@test_repo, workflow_file_name, 'main')
    assert_requested request
  end
end

Required Changes

1. Modify workflow_dispatch in lib/octokit/client/actions_workflows.rb

Change the method so that:

• When return_run_details: true is in the options, it uses post (which returns the parsed response body) instead of boolean_from_response. The return_run_details key should be included in the request body sent to the API (not stripped out).
• When return_run_details is not provided or is falsy, it preserves the existing behavior using boolean_from_response for backward compatibility.

The updated method should look approximately like:

# Create a workflow dispatch event
#
# @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 When true, the response will include
#   workflow run details instead of returning a simple boolean. Requires API version 2022-11-28.
#
# @return [Boolean | Sawyer::Resource] True if event was dispatched (default), or a
#   Sawyer::Resource with run details if return_run_details is true
# @see https://docs.github.com/en/rest/reference/actions#create-a-workflow-dispatch-event
def workflow_dispatch(repo, id, ref, options = {})
  options = options.merge({ ref: ref })
  if options[:return_run_details]
    post "#{Repository.path repo}/actions/workflows/#{id}/dispatches", options
  else
    boolean_from_response :post, "#{Repository.path repo}/actions/workflows/#{id}/dispatches", options
  end
end

2. Add tests in spec/octokit/client/actions_workflows_spec.rb

Add a new test case within the .workflow_dispatch describe block for the return_run_details: true scenario. The test should:

• Stub a POST request that returns 200 with a JSON body containing run details (e.g., { id: 123, status: "queued" })
• Verify the method returns the parsed response body (Sawyer::Resource) instead of a boolean
• Keep the existing test for the default boolean behavior

3. Do NOT modify boolean_from_response in lib/octokit/connection.rb

The boolean_from_response method is used by many other endpoints across the library. Do not add 200 to its success status list, as that could have unintended side effects on other API methods. The fix should be scoped to the workflow_dispatch method only.

This pull request was created from Copilot chat.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[sneha-krip]

Here's an example request that shows what the response body looks like

curl -L -X POST -H "Accept: application/vnd.github+json" -H "Authorization: Bearer $PAT" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/repos/github/sneha-krip-demo/actions/workflows/177005888/dispatches -d '{"ref":"main"}'
{
  "workflow_run_id": 22103568458,
  "run_url": "https://api.github.com/repos/github/sneha-krip-demo/actions/runs/22103568458",
  "html_url": "https://github.com/github/sneha-krip-demo/actions/runs/22103568458"
}

[sneha-krip]

@copilot Can we update to more closely resemble what the response body would actually be

[Copilot]

Updated the test to use the actual GitHub API response format with workflow_run_id, run_url, and html_url fields as shown in your example. (commit 1607fe2)

[sneha-krip]

@copilot Workflow run ID should look like 22103568458, not 22_103_568_458

[Copilot]

Updated to use 22103568458 without underscores in the test to match the actual API response format. Added rubocop disable comments to preserve this formatting. (commit 6bada3c)