From d8eb9349ee79059046064f7b29a0873ec43a3248 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 08:54:30 -0500 Subject: [PATCH 1/8] docs(lavaflow): explain merge queue recovery --- content/platform/guides/lavaflow.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index 933c43a7..75502e44 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -1253,7 +1253,7 @@ review the change, then merge or close the pull request yourself. | `blocked_by_rules` | A rule of the repository that LavaFlow can't satisfy blocks the merge | | `not_mergeable` | GitHub can't merge the pull request, for example because it conflicts with its base branch. Resolve the conflict first | | `branch_behind` | The base branch requires pull requests to be up to date with it and has no merge queue. LavaFlow doesn't update fix branches, so update the branch first | -| `removed_from_queue` | The fix isn't in the merge queue, and LavaFlow can't tell why: its checks may have failed there, or someone removed it | +| `removed_from_queue` | The fix left the merge queue. Check the pull request timeline for the reason | | `reads_failed` | LavaFlow failed to read the pull request for about an hour while the fix may have been in the merge queue, so it took the fix out of the queue, or failed to read the project's settings or repository for about a day while merging was paused. When it couldn't reach the pull request to take it out, its comment says the fix may still merge from the queue. For a fix you merge, which LavaFlow never queues, only the latter applies, with its CI start paused | | `unreadable` | The pull request has more checks, reviews, labels or commits than LavaFlow reads, so it can't judge the fix | | `permission_missing` | The Volcano GitHub App, or the owner's GitHub account, lacks a permission the merge needs. Grant the App's requested permissions; the owner must be able to push | @@ -1270,6 +1270,11 @@ review the change, then merge or close the pull request yourself. New reasons may appear. +If GitHub removes a LavaFlow pull request from the merge queue because the +merge group's checks failed, LavaFlow can queue the same pull request again +once. Its current head must still pass CI and satisfy the repository's merge +rules. A manual removal ends the watch. + While merging is paused, a waiting merge gets `reason` `paused`. LavaFlow takes a queued fix out of the merge queue, so it shows `waiting_for_checks`, and queues it again when merging resumes. A fix that merged into a project that From 97ca70cd695c73d9fb50c6ba814377d0da30e7d2 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 08:59:37 -0500 Subject: [PATCH 2/8] docs(lavaflow): explain CI retry --- content/platform/guides/lavaflow.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index 75502e44..1acad5a1 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -1270,6 +1270,11 @@ review the change, then merge or close the pull request yourself. New reasons may appear. +In Merge mode, LavaFlow can restart CI once on the same pull request when a +required GitHub Actions check times out and the other checks are settled. The +new commit keeps the same changes. LavaFlow waits for GitHub's checks and any +required approvals on that commit. + If GitHub removes a LavaFlow pull request from the merge queue because the merge group's checks failed, LavaFlow can queue the same pull request again once. Its current head must still pass CI and satisfy the repository's merge From 3984e29771636caf4aa9bc98cb6257d9d1668eb5 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 09:09:15 -0500 Subject: [PATCH 3/8] docs(lavaflow): clarify retry outcomes --- content/platform/guides/lavaflow.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index 1acad5a1..819b69b2 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -1270,15 +1270,18 @@ review the change, then merge or close the pull request yourself. New reasons may appear. -In Merge mode, LavaFlow can restart CI once on the same pull request when a -required GitHub Actions check times out and the other checks are settled. The -new commit keeps the same changes. LavaFlow waits for GitHub's checks and any -required approvals on that commit. - -If GitHub removes a LavaFlow pull request from the merge queue because the -merge group's checks failed, LavaFlow can queue the same pull request again -once. Its current head must still pass CI and satisfy the repository's merge -rules. A manual removal ends the watch. +With `autonomy: merge`, LavaFlow can restart CI once on the same pull request +when GitHub Actions reports `timed_out` for a required check and the other +checks have finished. The new commit keeps the same changes. LavaFlow +evaluates the new checks and the repository's merge requirements again. If +the required check times out again, the reason is `checks_failed`. +`checks_timed_out` applies when the checks have not all finished within 24 +hours. + +If GitHub removes the pull request from the merge queue because the checks +on the combined changes failed, LavaFlow can queue the same pull request +again once. Its current head must still pass CI and satisfy the repository's +merge rules. A manual removal stops automatic merging. While merging is paused, a waiting merge gets `reason` `paused`. LavaFlow takes a queued fix out of the merge queue, so it shows `waiting_for_checks`, and From 4686a70aa44ab103a1b67abd95bac9ba50994606 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 09:39:57 -0500 Subject: [PATCH 4/8] docs(lavaflow): explain reviewed PR repairs --- content/platform/guides/lavaflow.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index 819b69b2..90f0579a 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -1248,11 +1248,11 @@ review the change, then merge or close the pull request yourself. | `handed_off` | Someone drafted or closed the pull request, or moved it to another branch, so LavaFlow stopped. Nothing to do | | `review_unresolved` | LavaFlow's review didn't pass the fix; the run's [`review`](#why-a-review-stopped) says why. Finish the fix yourself, or close the pull request | | `settings_changed` | The project's settings no longer let LavaFlow merge, or start the CI of a fix you merge: LavaFlow was turned off, `autonomy` is no longer `merge` (no longer `open_pr` or `merge` for a fix you merge), the owner's plan no longer includes LavaFlow, or the project is being deleted. Turning merging back on doesn't resume this fix | -| `checks_failed` | A check on the fix failed. Its details are on the pull request | +| `checks_failed` | A check on the fix failed. Its results and any revised commits appear on the pull request | | `checks_timed_out` | The checks didn't all finish within 24 hours. A required check pinned to a GitHub App counts only as that App's check run | | `blocked_by_rules` | A rule of the repository that LavaFlow can't satisfy blocks the merge | | `not_mergeable` | GitHub can't merge the pull request, for example because it conflicts with its base branch. Resolve the conflict first | -| `branch_behind` | The base branch requires pull requests to be up to date with it and has no merge queue. LavaFlow doesn't update fix branches, so update the branch first | +| `branch_behind` | The base branch changed and the pull request still needs an update before it can merge | | `removed_from_queue` | The fix left the merge queue. Check the pull request timeline for the reason | | `reads_failed` | LavaFlow failed to read the pull request for about an hour while the fix may have been in the merge queue, so it took the fix out of the queue, or failed to read the project's settings or repository for about a day while merging was paused. When it couldn't reach the pull request to take it out, its comment says the fix may still merge from the queue. For a fix you merge, which LavaFlow never queues, only the latter applies, with its CI start paused | | `unreadable` | The pull request has more checks, reviews, labels or commits than LavaFlow reads, so it can't judge the fix | @@ -1278,6 +1278,15 @@ the required check times out again, the reason is `checks_failed`. `checks_timed_out` applies when the checks have not all finished within 24 hours. +When GitHub Actions reports a failure on the current commit, or GitHub +reports a conflict with the target branch, LavaFlow can revise the same pull +request. It reviews the complete change against the current base, keeps the +last reviewed proposal if it cannot complete the repair, and allows up to +two repair attempts. After a reviewed repair, LavaFlow runs CI on the new +commit and continues to merge when the repository's requirements are met. +A push by another contributor, a retarget, a redraft, or a closure stops +automatic work on that pull request. + If GitHub removes the pull request from the merge queue because the checks on the combined changes failed, LavaFlow can queue the same pull request again once. Its current head must still pass CI and satisfy the repository's From 75738a69cbd9c635e3a4ffff7d1428986c5dbff4 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 09:43:35 -0500 Subject: [PATCH 5/8] docs(lavaflow): clarify repair eligibility and outcomes --- content/platform/guides/lavaflow.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index 90f0579a..ad553c3f 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -990,10 +990,9 @@ branch ruleset: 2. Name it, set **Enforcement status** to **Active**, and under **Target branches** add your production branch, such as `main`. 3. Turn on **Require status checks to pass**, choose **Add checks**, and add - the name your pull request workflow's job reports, such as `test`. Leave - **Require branches to be up to date before merging** off: LavaFlow doesn't - update fix branches, so it stops a fix whose base branch requires that, with - `branch_behind`. + the name your pull request workflow's job reports, such as `test`. If you + enable **Require branches to be up to date before merging**, LavaFlow can + update its own fix branch, review the updated patch, and run the checks again. 4. Leave the Volcano GitHub App off the ruleset's bypass list. LavaFlow holds every fix on a base branch whose rules it can bypass, with `rules_bypass`. 5. Choose **Create**. @@ -1252,7 +1251,7 @@ review the change, then merge or close the pull request yourself. | `checks_timed_out` | The checks didn't all finish within 24 hours. A required check pinned to a GitHub App counts only as that App's check run | | `blocked_by_rules` | A rule of the repository that LavaFlow can't satisfy blocks the merge | | `not_mergeable` | GitHub can't merge the pull request, for example because it conflicts with its base branch. Resolve the conflict first | -| `branch_behind` | The base branch changed and the pull request still needs an update before it can merge | +| `branch_behind` | The base branch moved and LavaFlow could not complete an update. Update the branch and run the checks again before merging | | `removed_from_queue` | The fix left the merge queue. Check the pull request timeline for the reason | | `reads_failed` | LavaFlow failed to read the pull request for about an hour while the fix may have been in the merge queue, so it took the fix out of the queue, or failed to read the project's settings or repository for about a day while merging was paused. When it couldn't reach the pull request to take it out, its comment says the fix may still merge from the queue. For a fix you merge, which LavaFlow never queues, only the latter applies, with its CI start paused | | `unreadable` | The pull request has more checks, reviews, labels or commits than LavaFlow reads, so it can't judge the fix | @@ -1278,12 +1277,14 @@ the required check times out again, the reason is `checks_failed`. `checks_timed_out` applies when the checks have not all finished within 24 hours. -When GitHub Actions reports a failure on the current commit, or GitHub -reports a conflict with the target branch, LavaFlow can revise the same pull -request. It reviews the complete change against the current base, keeps the -last reviewed proposal if it cannot complete the repair, and allows up to -two repair attempts. After a reviewed repair, LavaFlow runs CI on the new -commit and continues to merge when the repository's requirements are met. +LavaFlow can revise an open pull request it manages under `autonomy: merge` +when GitHub Actions reports a failure on its current commit, or GitHub +reports a conflict with the target branch. LavaFlow reviews the whole +replacement against the current base and can attempt up to two repairs on +the same pull request. It runs CI on each reviewed repair and continues to +merge when the repository's requirements are met. A patch that fails review +leaves the last published proposal open with `review_unresolved`. If the +last repair's checks fail, the pull request stays open with `checks_failed`. A push by another contributor, a retarget, a redraft, or a closure stops automatic work on that pull request. From b137d1c41108f95ba6f06c8cc00e2f7ff60e6bbf Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 09:47:37 -0500 Subject: [PATCH 6/8] docs(lavaflow): describe branch updates in merge mode --- content/platform/guides/lavaflow.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index ad553c3f..d744ba15 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -942,8 +942,8 @@ does. ## Merge fixes With `autonomy: merge`, LavaFlow merges a fix's pull request once its -reviewers pass it, its required checks pass, and nothing holds it. It merges -only into a base branch that requires at least one status check: on any other, +reviewers pass it, its required checks pass, and nothing holds it. LavaFlow +can push reviewed repairs to the fix branch it manages. It merges only into a base branch that requires at least one status check: on any other, it holds every fix with `no_required_checks`. See [Require a status check before LavaFlow merges](#require-a-status-check-before-lavaflow-merges). With @@ -1278,15 +1278,17 @@ the required check times out again, the reason is `checks_failed`. hours. LavaFlow can revise an open pull request it manages under `autonomy: merge` -when GitHub Actions reports a failure on its current commit, or GitHub -reports a conflict with the target branch. LavaFlow reviews the whole +when GitHub Actions reports a failure on its current commit, GitHub reports +a conflict, or the target branch moves and the pull request needs an update. +LavaFlow reviews the whole replacement against the current base and can attempt up to two repairs on the same pull request. It runs CI on each reviewed repair and continues to merge when the repository's requirements are met. A patch that fails review -leaves the last published proposal open with `review_unresolved`. If the -last repair's checks fail, the pull request stays open with `checks_failed`. -A push by another contributor, a retarget, a redraft, or a closure stops -automatic work on that pull request. +leaves the last published version of the fix open with `review_unresolved`. +If the last repair's checks fail, the pull request stays open with +`checks_failed`. A push by another contributor holds the fix for +`person_commits`. Retargeting, redrafting, or closing the pull request +stops LavaFlow with `handed_off`. If GitHub removes the pull request from the merge queue because the checks on the combined changes failed, LavaFlow can queue the same pull request From 4d42979cab681268bbabf72be5c134708fe4d29f Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 10:45:57 -0500 Subject: [PATCH 7/8] docs(lavaflow): explain the remaining repair blocker --- content/platform/guides/lavaflow.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index d744ba15..2e90e327 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -1283,10 +1283,11 @@ a conflict, or the target branch moves and the pull request needs an update. LavaFlow reviews the whole replacement against the current base and can attempt up to two repairs on the same pull request. It runs CI on each reviewed repair and continues to -merge when the repository's requirements are met. A patch that fails review -leaves the last published version of the fix open with `review_unresolved`. -If the last repair's checks fail, the pull request stays open with -`checks_failed`. A push by another contributor holds the fix for +merge when the repository's requirements are met. If a repair cannot +continue, the pull request stays open and the dashboard and Slack still +show what blocks the published fix: failing checks, a conflict, or an +outdated base. Earlier revision attempts count against the same budget. +A push by another contributor holds the fix for `person_commits`. Retargeting, redrafting, or closing the pull request stops LavaFlow with `handed_off`. From 9e7e9af208703af0a06601eec2cc36eba2a101a2 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 16:55:43 -0500 Subject: [PATCH 8/8] docs(lavaflow): explain published CI feedback --- content/platform/guides/lavaflow.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index 2e90e327..d05f9df7 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -1278,15 +1278,17 @@ the required check times out again, the reason is `checks_failed`. hours. LavaFlow can revise an open pull request it manages under `autonomy: merge` -when GitHub Actions reports a failure on its current commit, GitHub reports -a conflict, or the target branch moves and the pull request needs an update. -LavaFlow reviews the whole -replacement against the current base and can attempt up to two repairs on -the same pull request. It runs CI on each reviewed repair and continues to -merge when the repository's requirements are met. If a repair cannot -continue, the pull request stays open and the dashboard and Slack still -show what blocks the published fix: failing checks, a conflict, or an -outdated base. Earlier revision attempts count against the same budget. +when CI reports a failure on its current commit, GitHub reports a conflict, +or its target branch moves and the pull request needs an update. It can use +GitHub Actions job logs, required GitHub App check output and annotations, +and feedback published with required commit statuses. + +LavaFlow reviews the whole replacement against the current base and can +attempt up to two repairs on the same pull request. It runs CI on each +reviewed repair and continues to merge when the repository's requirements +are met. If a repair cannot continue, the pull request stays open. The +dashboard and Slack show the failing checks, conflict, or outdated base. +Earlier revision attempts count against the same budget. A push by another contributor holds the fix for `person_commits`. Retargeting, redrafting, or closing the pull request stops LavaFlow with `handed_off`.