Start-GitHubWorkflow is used in automation to trigger GitHub Actions workflows via the workflow dispatch API. A common follow-up task after triggering a workflow is to monitor the resulting run — for example, to wait for it to complete or to link to its logs.
Request
Current experience
Start-GitHubWorkflow triggers a workflow dispatch and discards the response. The caller has no way to know which run was created by their dispatch call. The only workaround is to poll Get-GitHubWorkflowRun immediately after dispatching and guess which run was triggered — a race-prone approach that does not work reliably in concurrent environments.
Desired experience
GitHub shipped a new return_run_details parameter on POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches. When return_run_details: true is included in the request body, the API returns 200 OK with the created workflow run's ID, API URL, and HTML URL instead of the previous 204 No Content.
Start-GitHubWorkflow should always include return_run_details: true and return the run object to the caller, making the behavior consistent with other Start-* and data-returning commands in the module.
Acceptance criteria
Start-GitHubWorkflow always includes return_run_details: true in the request body- The created run object is always written to the pipeline
- The returned object contains at minimum the run ID and the HTML URL for the run
Technical decisions
Always return: Pass return_run_details = $true unconditionally in the $body hashtable. No opt-in parameter is needed — callers can discard output with $null = if they do not need it. This is consistent with the module's general philosophy of returning data rather than silently discarding it.
Response handling: Remove the $null = assignment and instead pipe Invoke-GitHubAPI through Select-Object -ExpandProperty Response to return the object to the caller.
GHES availability: The return_run_details parameter is currently only available on GitHub.com. On older GHES versions the body field will be silently ignored and the API will continue to return 204 No Content, yielding no output. This is acceptable — GHES users will get the improved behavior once their instance is upgraded.
Function type: The function is currently a filter, which conflicts with the coding standard requiring begin, process, and end blocks. This change should not refactor the filter to a function unless it becomes necessary to implement the feature correctly. A separate issue should track that refactoring.
Breaking changes: None. The current function returns nothing. Returning an object is additive and does not break existing callers.
No new class needed: The dispatch response is a flat object with a handful of fields. Return it as-is from the API response rather than introducing a dedicated class.
Implementation plan
Core changes
Documentation
Tests
Start-GitHubWorkflowis used in automation to trigger GitHub Actions workflows via the workflow dispatch API. A common follow-up task after triggering a workflow is to monitor the resulting run — for example, to wait for it to complete or to link to its logs.Request
Current experience
Start-GitHubWorkflowtriggers a workflow dispatch and discards the response. The caller has no way to know which run was created by their dispatch call. The only workaround is to pollGet-GitHubWorkflowRunimmediately after dispatching and guess which run was triggered — a race-prone approach that does not work reliably in concurrent environments.Desired experience
GitHub shipped a new
return_run_detailsparameter onPOST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches. Whenreturn_run_details: trueis included in the request body, the API returns200 OKwith the created workflow run's ID, API URL, and HTML URL instead of the previous204 No Content.Start-GitHubWorkflowshould always includereturn_run_details: trueand return the run object to the caller, making the behavior consistent with otherStart-*and data-returning commands in the module.Acceptance criteria
Start-GitHubWorkflowalways includesreturn_run_details: truein the request bodyTechnical decisions
Always return: Pass
return_run_details = $trueunconditionally in the$bodyhashtable. No opt-in parameter is needed — callers can discard output with$null =if they do not need it. This is consistent with the module's general philosophy of returning data rather than silently discarding it.Response handling: Remove the
$null =assignment and instead pipeInvoke-GitHubAPIthroughSelect-Object -ExpandProperty Responseto return the object to the caller.GHES availability: The
return_run_detailsparameter is currently only available on GitHub.com. On older GHES versions the body field will be silently ignored and the API will continue to return204 No Content, yielding no output. This is acceptable — GHES users will get the improved behavior once their instance is upgraded.Function type: The function is currently a
filter, which conflicts with the coding standard requiringbegin,process, andendblocks. This change should not refactor the filter to a function unless it becomes necessary to implement the feature correctly. A separate issue should track that refactoring.Breaking changes: None. The current function returns nothing. Returning an object is additive and does not break existing callers.
No new class needed: The dispatch response is a flat object with a handful of fields. Return it as-is from the API response rather than introducing a dedicated class.
Implementation plan
Core changes
return_run_details = $trueto$bodyinsrc/functions/public/Workflows/Start-GitHubWorkflow.ps1$null =and return the response object fromInvoke-GitHubAPIDocumentation
.SYNOPSIS/.DESCRIPTIONto reflect that the run object is returned.EXAMPLEshowing how to capture the returned run URLTests
idandhtml_url