Skip to content

docs(lavaflow): explain pull request recovery - #239

Open
swkeever wants to merge 8 commits into
mainfrom
skeever/lavaflow-pr-recovery
Open

swkeever wants to merge 8 commits into
mainfrom
skeever/lavaflow-pr-recovery

Conversation

@swkeever

@swkeever swkeever commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Document LavaFlow's one-time retry for a required Actions timeout, reviewed repairs for failures and conflicts on the same PR, and a bounded retry after a verified merge-group check failure.

This documents Kong/volcano-hosting#3532. Publish after the behavior reaches production.

Locally verified with pnpm lint, pnpm lint:docs content/platform/guides, and pnpm build.

@swkeever swkeever changed the title docs(lavaflow): explain merge queue recovery docs(lavaflow): explain CI and merge queue recovery Nov 19, 2026
@swkeever
swkeever marked this pull request as ready for review November 19, 2026 14:05
Copilot AI balanced review requested due to automatic review settings November 19, 2026 14:05

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review: no P0-P2 findings

Reviewed 9e7e9af. Run log

This docs-only change to content/platform/guides/lavaflow.md documents four new LavaFlow behaviors under autonomy: merge: one CI restart after GitHub Actions reports timed_out, up to two reviewed repairs on the same pull request, branch updates when the base requires up-to-date branches, and one requeue after a merge-group check failure. It also rewrites three reason rows and step 3 of the ruleset guide. The newest commit (9e7e9af) lists the CI output LavaFlow reads to write a repair. Overall risk is low. The main open question is release timing: the description says to publish only after the behavior reaches production, and merging to main publishes.

⚪ P3

  • content/platform/guides/lavaflow.md:1289 Recovery paragraphs don't name the reason a run ends with, and cite Slack without support (also reported as: Identify the merge outcome when a repair cannot continue)
  • content/platform/guides/lavaflow.md:1291 "Earlier revision attempts count against the same budget" doesn't say what counts toward the two repairs (also reported as: Define which revisions consume the two-repair budget)
  • content/platform/guides/lavaflow.md:1283 New model inputs (CI job logs, check output, status feedback) aren't covered by the page's data and redaction statements
  • content/platform/guides/lavaflow.md:1286 Repair paragraph doesn't say repair commits pass the same holds and Check before CI starts

Not checked: The AI review read the diff, the code, and the PR's text; it ran no tests or builds and read nothing outside this repository.

  • Whether Kong/volcano-hosting#3532, and whatever ships PR repairs and branch updates, has reached production.
  • Whether the product matches the documented limits: one CI restart, checks_failed after a second timeout, two repairs (and what counts toward them), and one requeue.
  • Which merge.status and reason a run shows during and after a repair or requeue, and whether Slack surfaces that blocker at all.
  • Whether CI job logs, check output and commit-status feedback get the same secret redaction as runtime logs before the models read them.
  • Whether repair and branch-update commits go through the same holds and the Check before CI starts as the first CI start.

Human review: needed

  • Are the CI restart, PR repair, branch-update and requeue behaviors in lavaflow.md live in production? The description says to publish only then, and merging to main publishes.

The AI review found no P0-P2 problems at 9e7e9af, so the code needs no second review for bugs. Decide the points above: approve to accept them, or request changes.

Any collaborator with write access other than the author can approve.

Comment thread content/platform/guides/lavaflow.md Outdated
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: "Waits for any required approvals" conflicts with the guide's approval holds

The new sentence says LavaFlow waits for GitHub's checks "and any required approvals" on the restarted commit. Elsewhere the same page says a repository that requires an approving review holds the fix with repository_requires_approval (line 1125). It also says "An approving review on GitHub doesn't release a hold" (line 1207). Under autonomy: merge, a fix that needs approvals is therefore held and never gets a CI restart. A reader may think approving the new commit will let LavaFlow merge it. Either drop "and any required approvals", or say exactly which approval LavaFlow waits for, if the product really does wait for one.

Found by claude-opus-5-5

Comment thread content/platform/guides/lavaflow.md Outdated
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: "Times out" is ambiguous next to checks_timed_out, and the result of a second timeout isn't stated

The reason table just above defines checks_timed_out as checks that didn't all finish within 24 hours. The new paragraph says LavaFlow restarts CI when a required GitHub Actions check "times out". A reader can't tell whether this means a check GitHub concludes as timed_out or LavaFlow's 24-hour limit. They also can't tell whether a fix stopped with checks_timed_out was already retried. The paragraph also doesn't say which reason a fix gets if the restarted CI times out again. Name the GitHub conclusion, or tie the sentence to the matching table row, and state the reason the fix gets after the one retry.

Found by claude-opus-5-5

Comment thread content/platform/guides/lavaflow.md Outdated
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: "Merge mode" and "the watch" are used nowhere else in the guide

The rest of the page calls this setting autonomy: merge (for example lines 944, 1035 and 2330), not "Merge mode". "The watch" is not defined anywhere. "A manual removal ends the watch" also doesn't give the outcome a reader would match on: the merge stops with reason removed_from_queue. The same goes for a merge group that fails again after the one requeue. Use autonomy: merge, and say that both cases stop the merge with removed_from_queue. This ties the paragraph to the rewritten table row. spec/writing.md asks for wire values quoted exactly as the API spells them.

Found by claude-opus-5-5

Comment thread content/platform/guides/lavaflow.md Outdated
| `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 |
| `branch_behind` | The base branch changed and the pull request still needs an update before it can merge |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: branch_behind row lost its cause and fix, and the ruleset step still says LavaFlow doesn't update fix branches

The old row named the cause: the base branch requires pull requests to be up to date and has no merge queue. It also said what to do: LavaFlow doesn't update fix branches, so update the branch first. The new row only says the base changed and the pull request needs an update. A reader who hits branch_behind no longer learns that their Require branches to be up to date setting causes it, or who has to update the branch. Step 3 of Require a status check before LavaFlow merges (lines 993-996) still says "LavaFlow doesn't update fix branches, so it stops a fix whose base branch requires that, with branch_behind". Meanwhile, the new repair paragraph says LavaFlow revises the pull request "against the current base" when there's a conflict. If LavaFlow still never updates a branch that is behind, put the cause and the "update the branch yourself" step back in the row. If repairs now update it, change step 3 to match.

Found by claude-opus-5-5

Comment thread content/platform/guides/lavaflow.md Outdated
`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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Repair paragraph doesn't say which fixes LavaFlow may push repairs to

The CI-restart paragraph opens with autonomy: merge, but the repair paragraph doesn't say which fixes it covers. Other parts of the page say LavaFlow never pushes to a fix you merge after its one CI start (line 910). They also say it never pushes to a held fix (line 1075) or a stopped one (line 1243). Two readers can't tell whether LavaFlow will push model-written repairs to their pull request after its CI fails: someone using open_pr, or someone with a held fix whose CI LavaFlow started once. Say the scope, for example "With autonomy: merge, while LavaFlow waits to merge a fix, …".

Found by claude-opus-5-5

Comment thread content/platform/guides/lavaflow.md Outdated
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Repair paragraph doesn't give the outcome when repairs run out or stop

"Keeps the last reviewed proposal if it cannot complete the repair" doesn't say what the reader sees. The page never defines a "proposal" in this sense. The paragraph also doesn't say which reason the merge gets after the second repair fails. It could be checks_failed for a CI failure or not_mergeable for a conflict. The events that stop the work don't match the codes the tables use. A push by someone else holds the fix with person_commits. A retarget, draft or closure stops it with handed_off, and the table says "drafted" where this paragraph says "redraft". Name the resulting reason or hold code for each case, the same way the timeout paragraph names checks_failed.

Found by claude-opus-5-5

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Step 3 promises branch updates, but the repair paragraph never lists a branch that is only behind as a trigger

Step 3 now says that when Require branches to be up to date before merging is on, LavaFlow "can update its own fix branch, review the updated patch, and run the checks again". The branch_behind row agrees: LavaFlow "could not complete an update". But the only paragraph that describes LavaFlow pushing to an open fix (lines 1280-1289) lists just two triggers: a GitHub Actions failure, or a conflict with the target branch. A branch that is behind but has no conflict matches neither. It also doesn't say whether such an update counts toward the "up to two repairs". A reader whose main moves often can't tell how many times LavaFlow will update the branch before it stops with branch_behind. Add "the base branch requires it to be up to date and it is behind" to the repair triggers, and say whether it counts toward the two-attempt limit.

Found by claude-opus-5-5

`checks_timed_out` applies when the checks have not all finished within 24
hours.

LavaFlow can revise an open pull request it manages under `autonomy: merge`

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: The opt-in text for autonomy: merge doesn't mention that LavaFlow now pushes repairs to its open fixes

Owners decide whether to turn on merge from Merge fixes and Turn merging on. Lines 957-962 list what turning it on allows: running CI with your pull request workflows' secrets, and force-updating the fix's branch while it holds only LavaFlow's commits. The new paragraph adds model-written replacement patches, pushed to an open pull request after CI fails or the base conflicts. Each one runs CI again. It also adds branch updates when the base requires up-to-date branches. None of this appears near the opt-in, so an owner reading only that section underestimates what merge does. Add a sentence to lines 957-962 that links to the repair paragraph. Also say whether a repair goes through the same holds (human_review_paths, sensitive_path) and the Check before CI starts as the first CI start.

Found by claude-opus-5-5

Comment thread content/platform/guides/lavaflow.md Outdated
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Repair stop events aren't tied to the codes the tables use, and "proposal" is undefined

Failed review and failed checks now name review_unresolved and checks_failed. The final sentence still only says that a push by someone else, a retarget, a redraft or a closure "stops automatic work". The rest of the page reports these as specific codes: another contributor's push holds the fix with person_commits, and the handed_off row covers drafted, closed or moved pull requests (it says "drafted", not "redraft"). "The last published proposal" also uses a term the page never defines; "the pull request's last reviewed commit" says the same thing in the page's own words. spec/writing.md asks for wire values quoted exactly, so name the resulting code for each event.

Found by claude-opus-5-5

@swkeever swkeever changed the title docs(lavaflow): explain CI and merge queue recovery docs(lavaflow): explain pull request recovery Nov 19, 2026
Comment thread content/platform/guides/lavaflow.md Outdated
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Repair paragraph no longer names the reason a run gets when a repair can't continue, and cites Slack

At the previous head, this paragraph named the codes a stopped repair reports (review_unresolved, checks_failed). The new text only says the pull request stays open and that "the dashboard and Slack still show what blocks the published fix: failing checks, a conflict, or an outdated base." An API or MCP reader matching on merge.status/reason can't tell what to expect: probably checks_failed, not_mergeable or branch_behind, and maybe review_unresolved when a repair fails LavaFlow's review. The guides also never say that Slack shows merge state. lavaflow-slack.md says a run started from Slack only opens a pull request, even where the project lets LavaFlow merge, so Slack-started fixes never reach this flow. Name the resulting reason for each blocker, as the timeout paragraph does with checks_failed. Then either link to where Slack reports a fix's blocker or drop "and Slack".

Found by claude-opus-5-5

Comment thread content/platform/guides/lavaflow.md Outdated
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: "Earlier revision attempts count against the same budget" doesn't say what counts toward the two repairs

The paragraph lists three triggers: an Actions failure, a conflict, and a target branch that moves so the pull request needs an update. It caps repairs at two. The closing sentence, "Earlier revision attempts count against the same budget", doesn't say what an "earlier revision attempt" is or whether a plain branch update counts as one of the two. Step 3 of the ruleset guide now invites owners to turn on Require branches to be up to date before merging. An owner whose main moves often can't tell how many base moves LavaFlow absorbs before it stops with branch_behind. State plainly whether a branch update uses up one of the two repairs.

Found by claude-opus-5-5

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Recovery paragraphs don't name the reason a run ends with, and cite Slack without support

"If a repair cannot continue, the pull request stays open. The dashboard and Slack show the failing checks, conflict, or outdated base" doesn't give the merge.status/reason an API, CLI or MCP reader would match on. That is probably checks_failed, not_mergeable or branch_behind, or review_unresolved when a repair fails LavaFlow's review. The requeue paragraph has the same gap. "A manual removal stops automatic merging" doesn't say the run gets removed_from_queue, and nothing says what happens when the one requeue fails again. The guides also never say Slack shows merge state: lavaflow-slack.md (line 112) says a Slack-started run only opens a pull request. Name the resulting reason for each case, as the timeout paragraph does with checks_failed. Then either link to where Slack reports a fix's blocker, or drop "and Slack".

Found by claude-opus-5-5

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: "Earlier revision attempts count against the same budget" doesn't say what counts toward the two repairs

The paragraph lists three triggers: a CI failure, a conflict, and a target branch that moves. It caps repairs at two. The closing sentence doesn't say what an "earlier revision attempt" is. The page already uses "revision" for review-round revisions (line 1983) and the pre-open checks revision (line 450). It also doesn't say whether a plain branch update uses up one of the two repairs. Step 3 of the ruleset guide invites owners to turn on Require branches to be up to date before merging. An owner whose main moves often can't tell how many base moves LavaFlow absorbs before it stops with branch_behind. State which events use up the budget.

Found by claude-opus-5-5

LavaFlow can revise an open pull request it manages under `autonomy: merge`
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,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: New model inputs (CI job logs, check output, status feedback) aren't covered by the page's data and redaction statements

The latest commit says repairs use GitHub Actions job logs, required GitHub App check output and annotations, and feedback published with required commit statuses. The page's data statements predate this. Line 19 says LavaFlow sends "this project's logs and source code" to an AI service. Lines 829-832 say LavaFlow redacts secrets before the models read "your logs, issue, report and a written issue's description". Neither says whether CI output and third-party check text are sent and redacted the same way. An owner deciding on autonomy: merge needs that, because CI logs can carry values GitHub doesn't mask. Say whether these sources get the same redaction, and mention them where the page says what LavaFlow sends.

Found by claude-opus-5-5

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Repair paragraph doesn't say repair commits pass the same holds and Check before CI starts

"It runs CI on each reviewed repair" means model-written replacement code runs your CI with your pull request workflows' secrets. Check before CI starts describes only the first CI start, and the path holds (path, sensitive_path, risky_change) are described for the fix as opened. Only line 2485 hints that the workflow check covers revisions. A reader can't tell whether a repair that touches CI configuration or a human_review_paths glob is held, or whether the workflow and CI-outside-Actions checks run again before each repaired commit lands. Add one sentence saying so, with a link to that section.

Found by claude-opus-5-5

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Identify the merge outcome when a repair cannot continue

The paragraph says the pull request stays open, but does not map failed or exhausted repairs to merge.status and reason. The adjacent table distinguishes review_unresolved, checks_failed, not_mergeable, and branch_behind. State which outcomes apply so API and MCP readers can interpret a stopped repair.

Found by gpt-6.1-sol

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ P3: Define which revisions consume the two-repair budget

“Earlier revision attempts” is undefined. The guide also describes revisions during initial review, and this paragraph includes branch updates among repair triggers. Clarify whether those initial revisions and branch-only updates consume the same two attempts, so readers can understand how much recovery remains.

Found by gpt-6.1-sol

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants