Describe the feature or problem you’d like to solve

Due to the limits around workflow dispatch API, currently the workflow run command does not return the created workflow run ID. It's been a long-time feature request from the community (See #4001) but we couldn't resolve it due to the platform limits.

Now, the underlying REST API endpoint is going to be updated so that it can optionally return some information about the created workflow run.

Proposed solution

Users have already adopted unusual workarounds/hacks to overcome the situation. A native support via workflow run will remove the need for additional dependencies or unreliable ways of getting the same information. See #4001 for more context.

So, we need to prepare the workflow run command to support this new feature in advance of public GA.

Additional context

1. API changes and backward/forward compatibility concerns

The API endpoint we use to create a dispatch event is (docs):

POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches

Currently the endpoint accepts ref and workflow inputs (body) and responds with 204 No Content on success. With the upcoming changes, there'll be a new optional boolean field in the request body, named return_run_details, that enabling it will change the response status code to 200 OK with a body like this:

{
  "workflow_run_id": 999,
  "run_url": "http://api.github.com/repos/monalisa/foo/actions/runs/999",
  "html_url": "http://github.com/monalisa/foo/actions/runs/999"
}

However, there are a few points that we need to be careful about when implementing this:

1. Backward compatibility; feature detection: We cannot simply provide return_run_details: true as the option is not unavailable/undefined on older GHES versions (i.e. v3.20 or earlier) and providing unknown fields in the request will result in 400 Bad Request. Therefore, gh needs to perform a light feature detection to figure out the availability of the feature. By "light" I mean we only need to confirm the API host is either github.com or it's newer than GHES v3.20.

2. Forward compatibility; expect both 200 and 204: Even on github.com or newer GHES instances, gh should still expect both 200 or 204 responses.

3. Forward compatibility; older gh versions (already done): In the future, the API endpoint may change its behaviour and always respond with 200 OK plus run details. We have confirmed that older gh versions are immune to this kind of behaviour, since the underlying HTTP client wrapper gracefully handles 200s with no provided response struct.

2. Interactive vs non-interactive output

Currently, workflow run output is as below, and this behaviour should be kept when the API server does not support the return_run_details field.

• Interactive: success message, hint at run list command, exit code zero.
• Non-interactive: only exit code zero.

However, when the API server support the run details feature, the output should be like this:

• Interactive: success message, created workflow run URL (i.e. html_url), hint at run list, hint at run view <ID>, exit code zero.
• Non-interactive: exit code zero, html_url of the created run. This is to make the output consistent with pr create and issue create commands.

3. JSON output support

For now we don't want to add JSON output support, because:

• Unlike pr create or issue create command (who also do not have the JSON output option), the returned workflow run information are not that much. It's just a URL/number.
• The --json option is already taken (to provide workflow run inputs as a JSON file), so we'll have to introduce a different option name, which is a new thing and needs internal discussion.