Support GitHub merge queues when RTD PR builds are required to merge

[gipert]

Details

I tried to enable GitHub's merge queue on a project that enables reporting PR builds on GitHub and sets it as a required status check before merging.

Expected Result

The PR is automatically merged after all checks have passed.

Actual Result

GitHub waits for ReadTheDocs to report the PR status check, which is never reported. The PR stays in the queue and is never merged.

Related?

I had to add on: merge_group: [ref] to my GHA workflow file to fix a similar problem with the other required status checks run with GitHub Actions.

Front conversations

[webknjaz]

@humitos I was just about to file a similar report. This is a blocker for projects wanting to use RTD with Merge Queues enabled.

I want to add that GitHub issues a push event in addition to merge_group, but RTD doesn't seem to react to it either.

This is what a deadlock this causes looks like:

[jeff-m-sullivan]

Having the same issue. pre-commit.ci is the only other third part CI service I'm currently using, and it worked without any configuration changes.

[humitos]

@stsewd have you used merge queues? I'm not sure how it works internally, maybe we need to listen to a different event to re-run the build?

I want to add that GitHub issues a push event in addition to merge_group

@webknjaz do you a link to the docs where this is explained?

[jeff-m-sullivan]

@humitos I think this is the relevant documentation: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue#how-merge-queues-work

[stsewd]

@stsewd have you used merge queues? I'm not sure how it works internally, maybe we need to listen to a different event to re-run the build?

Haven't used them. But I think the problem is that we report the commit status only on open PRs. Merge queues create a separate branch, but it doesn't create a PR. Should be fixed once we implement #11739.

[webknjaz]

@humitos I think the note in this section https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue#triggering-merge-group-checks-with-github-actions is a more accurate reference. It's kinda obvious that since it makes temporary branches, that action by itself triggers a push event just like any other branch creations. It's important to understand that those are ephemeral and are deleted quite soon, once the related PRs are kicked from the queue for various reasons (could be a failure of a check required in branch protection or success of all required checks meaning that the target branch could be fast-forwarded to that commit; could also be a user triggered termination).

@stsewd aren't there also statuses for branches? FWIW, the problem to solve here is the slug to be used in deployment URLs for such ephemeral builds. They won't follow the PR schema because they may correspond to multiple PRs merged-in at the same time, with the target branch not yet fast-forwarded to that state.

[webknjaz]

Note that the “two events” thing can cause double builds if you don't deduplicate them. Here's what I tend to do in GHA to run on merge_queue, but not push: https://github.com/ansible/awx-plugins/blob/0d569b5/.github/workflows/ci-cd.yml#L10.

[webknjaz]

Should be fixed once we implement #11739.

Yes, it sounds like this would fix the problem.

[stsewd]

@stsewd aren't there also statuses for branches?

No, we just report statuses for commits from open PRs.

FWIW, the problem to solve here is the slug to be used in deployment URLs for such ephemeral builds.

Haven't looked, but if they are normal branches, RTD should just create a new build (users may need to create a rule to activate and build those branches automatically on RTD).

[webknjaz]

Haven't looked, but if they are normal branches, RTD should just create a new build

Yes, they are regular Git branches having more than one slash in their names.

[rashidnhm]

Hello, wondering if there is any updates on this, or if there is a way to help with the development of this feature. We wanted to use merge queues but require RTD builds on PRs.

One solution was to ensure the build on RTD passes before adding a PR to the queue. However, this isn't ideal as it's not clear if a previous merge to main branch could have cause RTD build failures.

[stsewd]

Hi @rashidnhm, no updates so far. We may work on this once we have migrated our GH OAuth app to a GitHub App (#11942).