GitHub has updated its Actions API to provide immediate feedback on programmatically triggered workflows. Developers using the workflow dispatch API endpoint can now receive metadata linking their request to the specific workflow run it initiated, a change designed to simplify automation and tracking within CI/CD pipelines.
Previously, triggering a workflow via the GitHub Actions workflow dispatch API endpoint resulted in a `204 No Content` status code, confirming the request was received but providing no further details. According to a recent announcement, developers can now include a new optional boolean parameter, `return_run_details`, in their API call. When this parameter is set to `true`, the API returns a `200 OK` response containing the workflow ID, the run’s API URL, and its web URL.
This functionality is also integrated into the GitHub CLI, starting with version v2.87.0. When a user triggers a workflow with the `gh workflow run` command, the CLI will now automatically return the URL for the created run and the corresponding `gh run view` command to monitor it.
The primary benefit of this update is the elimination of cumbersome tracking methods. Before this change, developers had to build custom solutions, often involving extensive polling of the API, to find the specific workflow run that corresponded to their dispatch request. This process was inefficient and could add significant complexity to automation scripts. With the new parameter, developers receive a direct and immediate link between their API call and the resulting action.
GitHub stated the update was implemented so developers can easily identify which workflow runs originated from their API calls.
The goal is to remove the need for developers to build their own tracking mechanisms, streamlining the process of integrating GitHub Actions into larger, automated systems. The newest version of the GitHub CLI will default to having this feature enabled to simplify the user experience.
The announcement does not specify if including the `return_run_details` parameter will have any impact on API rate limits or the performance of the endpoint, especially for organizations that trigger a high volume of workflows.
The new API parameter is currently available for use. Developers can begin updating their scripts and applications to take advantage of the new response data. As the GitHub CLI (v2.87.0 and newer) now defaults to returning these details, users of the command-line tool will see this new behavior automatically after updating.
Developers using GitHub Actions should consider the following steps:
- Update the GitHub CLI to version 2.87.0 or a more recent version to access the new default behavior.
- Review existing automation scripts that use the workflow dispatch API to determine if they can be simplified by replacing polling logic with the new `return_run_details` parameter.
Follow us on Bluesky , LinkedIn , and X to Get Instant Updates
