Repository navigation
Description
Follow-up to #199, which was closed when merge queue support shipped in #292. @llucax reported in #199 (comment) that the DCO check still does not appear for merge groups, so the merge queue stalls and eventually ejects the PR.
Opening this as its own issue so the discussion isn't buried on a closed one.
Report
Repro: frequenz-floss/frequenz-client-common-python#259 (Remove dummy DCO check for the merge queue — the repo had been satisfying the required DCO check in the merge queue with a placeholder GitHub Actions job, and removing it exposed the problem).
Timeline from the PR timeline API:
| Time (UTC) | Event |
|---|---|
| 2026-07-23T07:40:12Z | auto_merge_enabled |
| 2026-07-23T08:33:16Z | added_to_merge_queue |
| 2026-07-23T09:36:38Z | removed_from_merge_queue by github-merge-queue[bot] |
That is roughly an hour sitting in the queue with DCO reported as Expected — Waiting for status to be reported, then ejection.
What has been ruled out
- The code was deployed.
f9dc6849(the Feat: Add Merge Group support #292 merge) reached the Production environment at2026-07-22T13:06:49Z, about 19 hours before the PR was queued. - The event is subscribed.
GET /apps/dcoreportsmerge_queue_entryinevents, with the app record last updated2026-07-22T14:15:18Z— also before the attempt. No missing permission. GitHub's OpenAPI description formerge_group(bothchecks_requestedanddestroyed) declares no required permission; it is simply app-only. So this is not a repeat of theissues: readgating problem from@dcoapp recheckdoesn't work. DCO is still stuck #289.
This was wrong — see the correction below. Themerge_groupevent does require the Merge queues repository permission at read level, which the app does not currently hold. The OpenAPI document does not encode webhook permission gating; only the prose documentation does. This is the root cause.- Webhook library supports the event. The deployed lockfile resolves
@octokit/webhooks@14.2.0, which handlesmerge_group. - The app is healthy for that installation. The same PR's head commit has
DCO | completed | successfrom thedcoapp, so pull request events are being delivered and processed normally.
The merge group ref and its check runs are long gone, so the failure cannot be reconstructed from the public API.
Hypotheses
Resolved: the root cause is hypothesis 4, added below. The hypotheses that follow are retained for the record.
- The delivery failed at the app. Any exception inside
check()currently results in nothing being reported rather than a failing check — this is the same silent-failure class documented in DCO step stuck even though the review comment with a recheck request exists #302. If the merge-group code path throws (or the function cold-starts past its time limit), the merge queue sees silence and stalls exactly as observed. The fix in progress for DCO step stuck even though the review comment with a recheck request exists #302 adds a safety net that would make this self-diagnosing. - The required check is pinned to a different integration. Required status checks can be bound to a specific app. If the ruleset still pins
DCOto GitHub Actions (from the placeholder-job era), a check run published by thedcoapp would not satisfy it. This would explain why the PR-level check passes while the merge group never clears. - A silent early return in the handler.
merge_group.checks_requestedreturns without reporting anything if thehead_refregex does not match, or ifpulls.getreturns 404/403. In a merge queue, returning silently is indistinguishable from being down: the queue waits, then ejects. These paths arguably should publish a check run explaining themselves rather than staying quiet.
Next steps
- Inspect the app's Recent Deliveries for
merge_grouparound2026-07-23T08:33Zto establish whether a delivery occurred and what status it returned. - Confirm with the reporter whether the required
DCOcheck in their ruleset is pinned to a specific app. - Get a fresh reproduction now that more of the picture is understood.
- Regardless of root cause, reconsider the silent
returnpaths in themerge_grouphandler (hypothesis 3) — stalling a merge queue for an hour is a poor failure mode.
Root cause (resolved)
- The app lacks the
merge_queuespermission. GitHub gates delivery ofmerge_groupon the Merge queues repository permission (read is sufficient), independently of whether the event is subscribed. The subscription was enabled and appears inGET /apps/dco, but no events were ever delivered. Identified by @bramwelt in Merge queue DCO check not reported for merge groups #303 (comment).
Fix requires both adding merge_queues: read to app.yml (for new installations) and adding the permission to the live app registration (which triggers per-installation admin approval).
Activity
bramwelt commentedon Jul 27, 2026
@tykeal The app now requires write permission to merge queues - but I don't see any requests to update the app permissions. Apologies if I didn't call out clearly that an update to the app permissions is necessary after my change was merged.
Current permissions as seen from Application config:

New permissions needed as seen from Application config:

tykeal commentedon Jul 28, 2026
@bramwelt thank you — this is the root cause, and the correction is on me rather than you.
To confirm the level: read is sufficient, not write. GitHub's webhook documentation for
merge_groupstates:The app only ever reports on a merge group — it creates a check run (
checks: write) and reads the pull request (pull_requests: read). It never manipulates the queue itself, which is what write-level access would grant. Somerge_queues: readis the correct ask, and it keeps the added scope as small as possible.Correcting my earlier analysis
I listed "no missing permission" as ruled out in the issue description above. That was wrong, and I've struck it through. I checked GitHub's OpenAPI description, found no permission recorded against the
merge-group-checks-requestedwebhook, and concluded it was ungated. The OpenAPI document simply does not encode webhook permission gating — only the prose documentation does. I should have checked both before asserting it.Confirming the current state:
No
merge_queuesentry.Why this fits every observation
GET /apps/dcodoes reportmerge_queue_entryunderevents. Delivery, however, is gated on the permission, not on the subscription — so the subscription looked correct while no events were ever sent.merge_groupentries. If the handler were erroring, they would have appeared there. They were never delivered at all.For the record on the forensics: the app is currently handling roughly 2.8 million deliveries per day, and the delivery log only pages back about three days, so the original 2026-07-23 window is unrecoverable. That is why this was hard to pin down from the outside — thank you for spotting it from the configuration side.
Next steps
merge_queues: readtoapp.ymlso new installations get it automatically. Note thatapp.ymlonly seeds new installations, so this alone changes nothing for anyone already installed.merge_groupdeliveries should begin and the existing handler from Feat: Add Merge Group support #292 should work unmodified.Still worth fixing regardless
There is a separate PR in progress that makes the
merge_grouphandler publish a diagnostic failing check instead of returning silently when it cannot set up (unrecognisedhead_ref, PR lookup failure). That does not address this permission gap, but it converts a class of failure that currently manifests as an hour-long merge-queue stall followed by ejection into an immediate, legible error. Related: #302 (an unguarded API error leaving a required check unreported) and #305 (the check-run "Re-run" button has never worked).@llucax — this is the answer to your question. Nothing is needed on your side; the fix is on the app registration, and you will see an approval request from your organisation administrator once the permission is added.
Fix: Declare merge queues permission in app.yml
tykeal commentedon Jul 28, 2026
Root cause resolved at the app registration
The live
dcoapp registration has been updated and now reports:Three things changed:
merge_groupon this permission, so without it the event was never sent regardless of the subscription. Thanks to @bramwelt for identifying this.merge_queue_entry, which is not a documented webhook event and which the app has no handler for. The handler has always been registered formerge_group.checks_requested. The Merge group checkbox is not even visible in the App settings UI until the Merge queues permission is granted, which is why this went unnoticed.merge_queue_entrysubscription, since nothing consumes it.app.ymlalready listedmerge_groupcorrectly, so the manifest was never wrong — only the live registration was. #306 has now addedmerge_queues: readto the manifest so that new installations are seeded correctly, and correcteddocs/administration.md, which had previously mis-stated both the UI label and the gating permission for this event.Important for existing installations
Adding a permission requires each installation's admin to approve it. Until an admin approves, that installation continues to receive no
merge_groupdeliveries and merge-queue DCO checks stay broken there. Rollout is therefore gradual and proceeds at the pace admins accept the request, not at the pace of deployment. Organisation owners should have received a notification.Still open
Keeping this issue open until we have observed a real
merge_groupdelivery producing a DCO check run in production. The merge-queue handling added in #292 has never executed in production, so it is untested in the field rather than known-good.A related hardening change is in flight: merge group setup failures currently return silently, which would leave a merge-queue check unreported in exactly the way #302 described. That is addressed by a commit in the upcoming #302 series PR.
Fix: Report a check when merge group setup fails
tykeal commentedon Jul 29, 2026
Code side is now merged and deployed
#309 merged and deployed to production as
e695526a(2026-07-29 09:48 UTC). It includes a commit that makes merge group setup failures publish a diagnostic check run instead of returning silently. Previously, if the merge group head could not be resolved, the app returned without reporting anything, which would leave a merge-queue check unreported in exactly the way #302 described.Current status
Everything we control is now in place:
merge_queues: readmerge_group(and unsubscribed frommerge_queue_entry)app.ymldeclaresmerge_queues: readso new installations are seeded correctly (Fix: Declare merge queues permission in app.yml #306)merge_groupdelivery observed producing a DCO check run in productionWhy this stays open
The merge-queue handling added in #292 has still never executed in production. Until the permission was granted, GitHub was not delivering the event at all, so that code path has never run against a real payload. It is untested in the field rather than known-good, and closing this before observing it work would be closing on inference rather than evidence.
Also note that existing installations must have an administrator approve the added permission before they receive
merge_groupdeliveries. Until an organisation approves it, merge-queue DCO checks remain broken for that organisation regardless of what is deployed. Rollout therefore proceeds at the pace administrators accept the request.If you are running merge queues with this app and can confirm behaviour after approving the permission update, please comment — real-world confirmation is what this issue is waiting on.
tykeal commentedon Jul 29, 2026
Confirmed working in production
We now have end-to-end evidence that merge group DCO checks are being delivered and reported.
Webhook delivery
Resulting check run on the merge group head
That is the first time the merge queue handling added in #292 has executed against a real payload. Both the permission gate and the event subscription are now confirmed correct, and the handler produces a real check run on a real merge group head.
Closing this as resolved.
One loose end, tracked separately
The check run reports
started_at/completed_atof16:40:56Z/16:40:57Z, while thedestroyeddelivery arrived at17:40:23Zand the repository's other check runs on the same head SHA started at17:40:59Z. The near-exact one hour offset, at almost identical minute and second, is unexplained. It is either a genuine gap between the merge group being formed and being torn down, or a timestamp skew in what the app reports.This does not affect correctness of the DCO result, so it is not a reason to hold this issue open. Anyone who sees merge group check timestamps that look an hour out, please open a separate issue with the details.
For other installations
Existing installations still need an administrator to approve the added Merge queues permission before they receive
merge_groupdeliveries. If merge queue checks are still not appearing for you, check the pending permission request first.llucax commentedon Aug 11, 2026
I confirm it works for me now, thanks a lot! 🙏