Merge queue DCO check not reported for merge groups

[tykeal]

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 at 2026-07-22T13:06:49Z, about 19 hours before the PR was queued.
• The event is subscribed. GET /apps/dco reports merge_queue_entry in events, with the app record last updated 2026-07-22T14:15:18Z — also before the attempt.
• No missing permission. GitHub's OpenAPI description for merge_group (both checks_requested and destroyed) declares no required permission; it is simply app-only. So this is not a repeat of the issues: read gating problem from @dcoapp recheck doesn't work. DCO is still stuck #289.
  This was wrong — see the correction below. The merge_group event 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 handles merge_group.
• The app is healthy for that installation. The same PR's head commit has DCO | completed | success from the dco app, 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.

1. 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.
2. The required check is pinned to a different integration. Required status checks can be bound to a specific app. If the ruleset still pins DCO to GitHub Actions (from the placeholder-job era), a check run published by the dco app would not satisfy it. This would explain why the PR-level check passes while the merge group never clears.
3. A silent early return in the handler. merge_group.checks_requested returns without reporting anything if the head_ref regex does not match, or if pulls.get returns 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_group around 2026-07-23T08:33Z to establish whether a delivery occurred and what status it returned.
• Confirm with the reporter whether the required DCO check 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 return paths in the merge_group handler (hypothesis 3) — stalling a merge queue for an hour is a poor failure mode.

cc @llucax @bramwelt

---

Root cause (resolved)

4. The app lacks the merge_queues permission. GitHub gates delivery of merge_group on the Merge queues repository permission (read is sufficient), independently of whether the event is subscribed. The subscription was enabled and appears in GET /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).

[bramwelt]

@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]

@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_group states:

To subscribe to this event, a GitHub App must have at least read-level access for the "Merge queues" repository permission.

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. So merge_queues: read is 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-requested webhook, 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:

$ gh api /apps/dco --jq '.permissions'
{"checks":"write","contents":"read","members":"read","metadata":"read","pull_requests":"read"}

No merge_queues entry.

Why this fits every observation

• The Merge queue entry checkbox was enableable in the UI and GET /apps/dco does report merge_queue_entry under events. Delivery, however, is gated on the permission, not on the subscription — so the subscription looked correct while no events were ever sent.
• A scan of every failed delivery over a three-day window (23,403 of them) contained zero merge_group entries. If the handler were erroring, they would have appeared there. They were never delivered at all.
• It explains why the check simply never materialised for @llucax rather than appearing and failing.

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

1. Add merge_queues: read to app.yml so new installations get it automatically. Note that app.yml only seeds new installations, so this alone changes nothing for anyone already installed.
2. Add the permission to the live app registration. As you note, adding a permission triggers per-installation approval by each installing admin, so this will roll out gradually as administrators accept it. There is no way to avoid that for a permission addition.
3. Once accepted on a given installation, merge_group deliveries 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_group handler publish a diagnostic failing check instead of returning silently when it cannot set up (unrecognised head_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.

[tykeal]

Root cause resolved at the app registration

The live dco app registration has been updated and now reports:

merge_queues: read
events: [check_run, merge_group, pull_request, pull_request_review,
         pull_request_review_comment, push]

Three things changed:

1. Added the Merge queues (read) permission. GitHub gates delivery of merge_group on this permission, so without it the event was never sent regardless of the subscription. Thanks to @bramwelt for identifying this.
2. Subscribed to the correct event. The app had been subscribed to merge_queue_entry, which is not a documented webhook event and which the app has no handler for. The handler has always been registered for merge_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.
3. Removed the merge_queue_entry subscription, since nothing consumes it.

app.yml already listed merge_group correctly, so the manifest was never wrong — only the live registration was. #306 has now added merge_queues: read to the manifest so that new installations are seeded correctly, and corrected docs/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_group deliveries 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_group delivery 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.

[tykeal]

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:

• Live app holds merge_queues: read
• Live app subscribed to merge_group (and unsubscribed from merge_queue_entry)
• app.yml declares merge_queues: read so new installations are seeded correctly (Fix: Declare merge queues permission in app.yml #306)
• Merge group failures now report a check rather than failing silently (Fix: Report DCO check when compare API fails #309)
• A real merge_group delivery observed producing a DCO check run in production

Why 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_group deliveries. 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]

Confirmed working in production

We now have end-to-end evidence that merge group DCO checks are being delivered and reported.

Webhook delivery

event:      merge_group.destroyed
repository: riscv/riscv-unified-db
response:   200 ("ok"), 2.2s
merge group head: af3d6e22e21c62fdc8d05161e4caf095cd5e12e6
merge group base: 36cfd4908cd0430b80710c9073912bc114da4658

Resulting check run on the merge group head

name:       DCO
app:        dco
status:     completed
conclusion: success
id:         90643824358

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_at of 16:40:56Z / 16:40:57Z, while the destroyed delivery arrived at 17:40:23Z and the repository's other check runs on the same head SHA started at 17: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_group deliveries. If merge queue checks are still not appearing for you, check the pending permission request first.