Summary

Implements support for GitHub's workflow dispatch return_run_details parameter (API version 2026-03-10) that returns immediate workflow run details when triggering a workflow dispatch event.

cf. doc here: https://docs.github.com/en/rest/actions/workflows?apiVersion=2026-03-10&versionId=free-pro-team%40latest&category=actions#create-a-workflow-dispatch-event

Changes

• New Parameter: Added return_run_details boolean parameter to Workflow.create_dispatch() (default: False)
• Return Type: When return_run_details=True, returns a WorkflowRun object instead of a boolean
• Backward Compatible: Existing behavior unchanged when parameter is False (default)
• Test Coverage: Added test case testCreateDispatchWithReturnRunDetails with replay data

Benefits

• Immediate Access: Get workflow run details immediately without polling or searching
• Better UX: Enable immediate access to methods like cancel(), rerun(), get_jobs() on the returned WorkflowRun object
• API Alignment: Matches GitHub's latest Actions API capabilities

Example Usage

# Old behavior (still works)
success = workflow.create_dispatch(ref="main", inputs={})  # Returns bool

# New behavior with run details
run = workflow.create_dispatch(ref="main", inputs={}, return_run_details=True)
print(f"Workflow run ID: {run.id}")
print(f"View at: {run.html_url}")
run.cancel()  # Can immediately interact with the run

Test plan

• Unit tests pass with new test case
• Tested against live GitHub API (EnterpriseDB/poc repository)
• Backward compatibility verified (default behavior unchanged)
• Both throw=True and throw=False code paths tested