Inconsistent reporting of "pull_requests" in /repos/X/Y/actions/runs #22501
Description
[maintainer edit]
Content plan here
Code of Conduct
- I have read and agree to the GitHub Docs project's Code of Conduct
What article on docs.github.com is affected?
https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run
What part(s) of the article would you like to see updated?
At present, "pull_requests" is reported for workflow runs associated with same-repository pull requests, but is not reported for workflow runs associated with forked-repository pull requests. This appears to be a bug in the site.
This should be fixed and the precise semantics of "pull_requests" should be documented.
Approved docs updates
- Combine the notes in the "pull_request" section of "Events that trigger workflows, and add the following note as a third bullet point:
The
pull_requestwebhook event payload is empty for merged pull requests and pull requests that come from forked repositories.
Additional information
Scenario:
Suppose that Alice has a public repository and defines a workflow that is triggered by the pull_request event. (As documented at https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request , this means that the workflow operates on the "PR merge branch" - i.e., the result of merging the pull-request branch with the base branch - not the pull-request branch itself.)
Bob creates a fork of Alice's repository, makes changes, and creates a pull request asking Alice to merge his branch into hers.
Problem:
In the JSON document returned by https://api.github.com/repos/alice/myproject/actions/runs, each run has a key "pull_requests".
For runs that are attached to pull requests that Alice creates against her own repository, "pull_requests" contains information about the pull request.
For runs that are attached to pull requests that Bob creates against Alice's repository, "pull_requests" is empty.
Why this matters:
This matters because "pull_requests" includes the state of the base branch at the time the workflow was invoked. Indirectly, therefore, it tells us how to reconstruct the "PR merge branch" that was supplied as input to the workflow.
If Alice or Bob wants to reproduce the run for debugging, they need to know what tree was supplied to the workflow. If Alice wants to ensure tests will pass after merging Bob's branch, she needs to be able to tell whether or not the workflow run is "up-to-date".
As far as I can tell, "pull_requests" is the only place this informatiom is visible, unless by downloading the logs of every run and trying to parse that information out of them.
If there is any way to obtain this information other than by using "pull_requests", that would be helpful to know.
Example:
A workflow run generated from a same-repository pull request (pull 1698):
https://api.github.com/repos/MIT-LCP/physionet-build/actions/runs?branch=lm/dua
{
"total_count": 24,
"workflow_runs": [
{
"id": 3605481679,
...
"event": "pull_request",
...
"pull_requests": [
{
"url": "https://api.github.com/repos/MIT-LCP/physionet-build/pulls/1698",
"id": 1115448553,
"number": 1698,
"head": {
"ref": "lm/dua",
"sha": "9fdda058e73a1363f13c897271af8e3110637cd9",
"repo": {
"id": 82719282,
"url": "https://api.github.com/repos/MIT-LCP/physionet-build",
"name": "physionet-build"
}
},
"base": {
"ref": "dev",
"sha": "6be772842bc86810db961ed23e1d975803836da5",
"repo": {
"id": 82719282,
"url": "https://api.github.com/repos/MIT-LCP/physionet-build",
"name": "physionet-build"
}
}
}
],
...
},
...
]
}
A workflow run generated from a forked-repository pull request (pull 1697):
https://api.github.com/repos/MIT-LCP/physionet-build/actions/runs?branch=feature/user-api
{
"total_count": 27,
"workflow_runs": [
{
"id": 3452619163,
...
"event": "pull_request",
...
"pull_requests": [
],
...
},
...
]
}