docs Inconsistent reporting of `"pull_requests"` in `/repos/X/Y/actions/runs`

Inconsistent reporting of `"pull_requests"` in `/repos/X/Y/actions/runs`

Open bemoody opened this issue 1 year ago • 7 comments

Code of Conduct

[X] 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.

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": [

      ],
      ...
    },
    ...
  ]
}

Dec 06 '22 20:12 bemoody

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

Dec 06 '22 20:12 welcome[bot]

@bemoody Thanks so much for opening an issue! We appreciate all the provided information.

I'll triage this for the team to take a look :eyes:

Dec 07 '22 15:12 cmwilson21

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert :eyes: