Occasional pkgs/by-name checkout failure

[infinisil]

I'm getting the following error from CI on a new PR I opened, from the check-by-name.yml workflow:

  Error: fatal: couldn't find remote ref refs/pull/255902/merge
  The process '/usr/bin/git' failed with exit code 128

Originally posted by @doronbehar in #237439 (comment)

[infinisil]

Here is the failed workflow run.

It looks the same as actions/checkout#36, but there the problem seems to have been that the PR was merged before the workflow was able to run.

This doesn't appear to be the case here though, because the workflow failed at exactly 2023-09-18 14:12:57 but the PR was only merged days later. However, the PR was opened at
exactly 2023-09-18 14:12:45, just 12 seconds before the workflow failed.

I think the problem can occur when the PR has a merge conflict, or GitHub hasn't computed the merge commit yet, so the ref isn't valid yet.

Relevant GitHub docs are here:

The value of the mergeable attribute can be true, false, or null. If the value is null, then GitHub has started a background job to compute the mergeability. After giving the job time to complete, resubmit the request. When the job finishes, you will see a non-null value for the mergeable attribute in the response. If mergeable is true, then merge_commit_sha will be the SHA of the test merge commit.

Kind of makes sense, can't get a merge ref before that.

I think the best way around this would be to fetch both the latest base branch commit and the PR's head commit, then do an explicit git merge (and skip the worflow if there's a conflict).

[infinisil]

Another case here: https://github.com/NixOS/nixpkgs/actions/runs/6321982259/job/17166813954, and indeed it's due to a merge conflict, the PR (#257561) even got the merge conflict label assigned.

Turns out the manual merging idea is pretty tricky, because to merge two commits, git needs a common ancestor, but Git doesn't have that without fetching the Git history, and GitHub doesn't have an API endpoint for getting that either.

Maybe the best approach here is to have a step before the checkout which just resolves the merge ref using

$ git ls-remote https://github.com/nixos/nixpkgs refs/pull/257709/merge
953fe4fffc716776fa6f163a929e689b8462f110	refs/pull/257709/merge

And fails with a better error if it can't be resolved.

(If it can be resolved, that resolved SHA should get used in following steps to avoid a potential race condition).

[infinisil]

I just created #259074 which improves the error message in case of conflicts. I'll consider this fixed after that.

[infinisil]

Looks like it's not just merge conflicts that can cause this: https://github.com/NixOS/nixpkgs/actions/runs/6548548919/job/17783482639?pr=261650

The corresponding PR definitely doesn't have a merge conflict: #261650

@Artturin opened #261693 to hopefully see what's going on in the future. I'll open this issue again for now

[infinisil]

I think this is the solution: https://docs.github.com/en/rest/guides/using-the-rest-api-to-interact-with-your-git-database?apiVersion=2022-11-28#checking-mergeability-of-pull-requests

See also https://docs.github.com/en/rest/pulls/pulls?apiVersion=2022-11-28#get-a-pull-request

[infinisil]

This should be fixed by #261741