Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 37 additions & 9 deletions content/platform/guides/lavaflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

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

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**.
Expand Down Expand Up @@ -1248,12 +1247,12 @@ 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 |
| `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 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 |
| `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 |
Expand All @@ -1270,6 +1269,35 @@ review the change, then merge or close the pull request yourself.

New reasons may appear.

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.

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

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

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

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

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

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

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

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
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
queues it again when merging resumes. A fix that merged into a project that
Expand Down