From 565df51a5e44911ec5cd63838979b8b1e678d810 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 07:19:32 -0500 Subject: [PATCH 1/6] docs(lavaflow): explain Slack issue-to-merge delivery --- content/platform/guides/lavaflow-slack.md | 30 +++++++++++++---------- content/platform/guides/lavaflow.md | 3 ++- 2 files changed, 19 insertions(+), 14 deletions(-) diff --git a/content/platform/guides/lavaflow-slack.md b/content/platform/guides/lavaflow-slack.md index 95e57e6c..308bb806 100644 --- a/content/platform/guides/lavaflow-slack.md +++ b/content/platform/guides/lavaflow-slack.md @@ -106,14 +106,18 @@ report. A later mention in the thread starts a new report, which reads the thread again: for example, a request for a change after the run's result, or a retry after LavaFlow refused the report at a limit. -LavaFlow then answers in the thread with the project it picked and a link to -its repository, and posts the outcome as a new reply. It never edits an -earlier reply, so the thread keeps each step of the report. A run from Slack goes as far as opening a fix -pull request, even where the project lets LavaFlow merge, and so does a run -someone starts again on the report's issue: merging a fix someone reported in -Slack stays a person's step. The outcome is the pull request's link, or a -fixed reason it opened none, and a link to the run in Volcano. The run link -opens the report's project in the same environment as the Slack app and still +LavaFlow replies with the project it picked and its repository. When the +project uses Merge mode and the owner has allowed repository CI, LavaFlow +can take the owner's requested change from Slack to the connected branch. +It reviews and revises the draft PR, marks it ready once review clears, +and follows the repository's required checks and approvals. If they all pass, +LavaFlow merges the PR. It uses the repository's merge queue when required. +A documentation fix from a problem report can also follow this path when +Volcano verifies that the project deployed the exact base commit. + +LavaFlow links the PR while following it and replies when GitHub records the +merge or LavaFlow needs help. If it opens no PR, the thread gives a reason. +The run link opens the report's project in the same environment as the Slack app and still requires access to that project. It never holds the diagnosis: everyone in the channel reads the answer, including people who can't see the project's runs. Read the diagnosis in Volcano, and follow the run like any @@ -164,11 +168,11 @@ what you're asking for: run and asks you to say what to change in your own message. LavaFlow builds what the request asks for and nothing beyond it, and its -reviewers hold anything else the change adds. The request can't change what -LavaFlow may do: its permissions, the files it may not change, its review, and -when it opens a pull request stay the same, and the run stops at a pull -request for a person to review and merge. The pull request says it proposes a -requested change, not a fix, and the run's `diagnosis.requested` is `true`. +reviewers hold anything else the change adds. Your project settings and +repository rules determine whether LavaFlow can merge. You can ask it to leave the PR as a draft or stop before merge. Asking +it to open a draft PR still lets LavaFlow mark it ready when reviews pass. +The pull request describes the requested change, and the run sets +`diagnosis.requested` to `true`. When the request is unclear, the result already exists, or the change lies outside the repository, LavaFlow opens nothing and says so in the thread. diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index 933c43a7..aa6bd03b 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -1118,6 +1118,7 @@ LavaFlow holds a fix for these reasons: | `sensitive_path` | It changes another path Volcano always holds: authentication code, secret files, agent instructions, CI, dependencies or configuration; see below | | `label` | The pull request has the `needs-human-review` label | | `client_reported_commit` | The fix is built on a commit Volcano can't tie to a push | +| `report_admission_lost` | LavaFlow could no longer verify the Slack report's base or merge authorization. See [Slack reports](lavaflow-slack.md) | | `no_checks` | No CI ran on it | | `required_check_skipped` | A required check was skipped | | `no_required_checks` | The base branch requires no check, so passing checks alone don't vouch for the fix | @@ -1252,7 +1253,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 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 moved after review and LavaFlow needs a current base for this merge. Update the branch and check the changes again | | `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 | | `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 | From 39e2d3d9cc8296c6c8c4a4d58ab39d6d996adf57 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 07:36:34 -0500 Subject: [PATCH 2/6] docs(lavaflow): describe issue-to-merge across sources --- content/platform/guides/lavaflow-aikido.md | 7 +++-- content/platform/guides/lavaflow-slack.md | 32 ++++++++++++-------- content/platform/guides/lavaflow.md | 35 ++++++++++------------ 3 files changed, 39 insertions(+), 35 deletions(-) diff --git a/content/platform/guides/lavaflow-aikido.md b/content/platform/guides/lavaflow-aikido.md index 2c9e2339..1ee2ca85 100644 --- a/content/platform/guides/lavaflow-aikido.md +++ b/content/platform/guides/lavaflow-aikido.md @@ -6,9 +6,10 @@ description: 'Connect an Aikido workspace so LavaFlow opens fix pull requests fo Connect your [Aikido](https://www.aikido.dev) workspace, bind a project, and each new code (SAST) issue Aikido finds on the project's GitHub repository starts a [LavaFlow](lavaflow.md) run. LavaFlow -reads the issue, diagnoses it, and opens a pull request with the fix for you -to review. It never merges an Aikido fix, and it writes nothing back to -Aikido: follow the run in Volcano. +reads the issue, diagnoses it, and opens a pull request when it can fix the +problem. With `autonomy: merge`, LavaFlow follows the PR through review, +required checks, and merge. Follow the run in Volcano. LavaFlow writes +nothing back to Aikido. Aikido reports need the project's `lavaflow.aikido` capability. They are rolling out environment by environment, so check it first. It is available diff --git a/content/platform/guides/lavaflow-slack.md b/content/platform/guides/lavaflow-slack.md index 308bb806..6fece008 100644 --- a/content/platform/guides/lavaflow-slack.md +++ b/content/platform/guides/lavaflow-slack.md @@ -106,17 +106,20 @@ report. A later mention in the thread starts a new report, which reads the thread again: for example, a request for a change after the run's result, or a retry after LavaFlow refused the report at a limit. -LavaFlow replies with the project it picked and its repository. When the -project uses Merge mode and the owner has allowed repository CI, LavaFlow -can take the owner's requested change from Slack to the connected branch. -It reviews and revises the draft PR, marks it ready once review clears, -and follows the repository's required checks and approvals. If they all pass, -LavaFlow merges the PR. It uses the repository's merge queue when required. -A documentation fix from a problem report can also follow this path when -Volcano verifies that the project deployed the exact base commit. - -LavaFlow links the PR while following it and replies when GitHub records the -merge or LavaFlow needs help. If it opens no PR, the thread gives a reason. +LavaFlow replies with the project it picked and its repository. With +[`autonomy: merge`](lavaflow.md#merge-fixes), LavaFlow can take an issue from +Slack to a merge on the project's production branch. It pins the repository +revision, reviews and revises the draft PR, and marks it ready once review +clears. It follows the required checks and approvals and merges the PR when +they pass. It uses the repository's merge queue when required. With +`autonomy: open_pr`, you review and merge the resulting PR. + +LavaFlow links to the PR and the Volcano run. It replies when GitHub records +the merge or LavaFlow needs help. If it opens no PR, the thread gives a reason. +LavaFlow can follow an active report until its 10-day retention window ends. +If the project connection, base, or merge authorization changes, the run +shows `report_admission_lost`. Check the connection and PR before retrying. + The run link opens the report's project in the same environment as the Slack app and still requires access to that project. It never holds the diagnosis: everyone in the channel reads the answer, including people who can't see the @@ -169,8 +172,11 @@ what you're asking for: LavaFlow builds what the request asks for and nothing beyond it, and its reviewers hold anything else the change adds. Your project settings and -repository rules determine whether LavaFlow can merge. You can ask it to leave the PR as a draft or stop before merge. Asking -it to open a draft PR still lets LavaFlow mark it ready when reviews pass. +repository rules determine whether LavaFlow can merge. To stop after opening +the PR, write `@Volcano add hello.md containing "hello world". Open a PR and +leave the merge to me.` LavaFlow keeps the run at `pull_request`. To keep it +as a draft, say "leave the PR as a draft." Asking to open a draft PR still +lets LavaFlow mark it ready when reviews pass. The pull request describes the requested change, and the run sets `diagnosis.requested` to `true`. When the request is unclear, the result already exists, or the change lies diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index aa6bd03b..6a8d3875 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -92,10 +92,8 @@ starts none, and neither does an error issue with `exception: false`. An issue you [write](issues.md#write-an-issue) starts a run as you write it, and only then. The run reads your description as what to change, with no logs, -at the head of the project's production branch, and follows your settings as -any run does, with one exception: under `autonomy: merge`, LavaFlow doesn't -merge its fix. The branch head is no push Volcano saw deploy, so the fix waits -for you to merge it, held under `client_reported_commit`. +at the verified head of the project's production branch. The run follows +your autonomy settings through review, checks, and merge. A [build issue](issues.md#failed-builds) starts a run the first time a deploy fails, since the build fails the same way until the code changes. The run reads @@ -663,10 +661,10 @@ The commit comes from one of these: on the run. A redeploy of the same upload, such as one a variable change starts, carries no commit LavaFlow reads. -For any other deployment, LavaFlow diagnoses from the logs alone. A fix on a -reported commit is held for a person under `client_reported_commit`. A fix on a -`verification: repository` commit opens only while the production branch still -holds that commit. +For any other deployment, LavaFlow diagnoses from the logs alone. A fix on +a `verification: repository` commit opens only while the production branch +still holds that commit. It stays held under `client_reported_commit` until +someone verifies that it fixes the deployed code. ### Deploy code LavaFlow can read @@ -1117,8 +1115,8 @@ LavaFlow holds a fix for these reasons: | `path` | It changes a path in `human_review_paths`, as the settings were when its pull request opened or as they are now, or deploy or infrastructure configuration | | `sensitive_path` | It changes another path Volcano always holds: authentication code, secret files, agent instructions, CI, dependencies or configuration; see below | | `label` | The pull request has the `needs-human-review` label | -| `client_reported_commit` | The fix is built on a commit Volcano can't tie to a push | -| `report_admission_lost` | LavaFlow could no longer verify the Slack report's base or merge authorization. See [Slack reports](lavaflow-slack.md) | +| `client_reported_commit` | Volcano could not verify that the reported commit matches the deployed files | +| `report_admission_lost` | LavaFlow could no longer verify the report's base or merge authorization. Check the source connection and the proposed changes | | `no_checks` | No CI ran on it | | `required_check_skipped` | A required check was skipped | | `no_required_checks` | The base branch requires no check, so passing checks alone don't vouch for the fix | @@ -1253,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 moved after review and LavaFlow needs a current base for this merge. Update the branch and check the changes again | +| `branch_behind` | The repository requires an up-to-date branch, or the base of a verified report moved after review. Update the PR branch and check the changes again | | `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 | | `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 | @@ -1645,9 +1643,9 @@ tell which first included it, and `deployed_at` is the merge time. ### Draft pull requests `draft` says whether the pull request is a draft, as GitHub last reported it to -LavaFlow, and is `null` for one opened before LavaFlow recorded it. A draft -waits for a person to mark it ready; `draft_reason` says why it is one, and is -`null` otherwise. +LavaFlow, and is `null` for one opened before LavaFlow recorded it. An +initial review draft can become ready automatically when reviews pass. After +review finishes, `draft_reason` explains why the PR remains a draft. | `draft_reason` | Why the pull request is a draft | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -2813,11 +2811,10 @@ on, not the code that shipped while it was off. ### How Code Quality fixes open -A Code Quality fix opens as a draft pull request, and LavaFlow never merges -it, even with `autonomy: merge`. It opens only when LavaFlow's review passed -the fix, and not while another project on the same repository has an open -Code Quality pull request for the same finding. The issue keeps its diagnosis -either way. +LavaFlow opens a Code Quality PR once its review passes and the repository +has no open Code Quality PR for the same finding. With `autonomy: merge`, +LavaFlow follows the PR through the same controls as any other fix. With +`autonomy: open_pr`, you merge the PR. The issue keeps its diagnosis either way. On a repository that isn't private, LavaFlow writes no fix for a finding with security impact, since the diff would disclose the problem before it is fixed. From c9417cd522f69fc0b923a1be97fa1c8e617f24b5 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 07:41:15 -0500 Subject: [PATCH 3/6] docs(lavaflow): align review and merge guidance --- content/platform/guides/lavaflow-aikido.md | 5 +++-- content/platform/guides/lavaflow-slack.md | 7 ++++--- content/platform/guides/lavaflow.md | 18 +++++++++--------- 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/content/platform/guides/lavaflow-aikido.md b/content/platform/guides/lavaflow-aikido.md index 1ee2ca85..0016825e 100644 --- a/content/platform/guides/lavaflow-aikido.md +++ b/content/platform/guides/lavaflow-aikido.md @@ -117,8 +117,9 @@ A new issue starts a run when all of these hold: - Its code repository is on GitHub, and is the bound project's repository. LavaFlow reads the issue's title, rule, file and lines, and Aikido's advice -for fixing it, then runs its usual diagnosis, fix and review. The run stops at -a pull request, whatever the project's own autonomy. +for fixing it, then runs its usual diagnosis, fix, and review. The project's +autonomy determines whether LavaFlow follows the fix through merge or leaves +the merge to you. If several bound projects share the repository, the first one bound that LavaFlow can run on gets the issue. diff --git a/content/platform/guides/lavaflow-slack.md b/content/platform/guides/lavaflow-slack.md index 6fece008..236665ac 100644 --- a/content/platform/guides/lavaflow-slack.md +++ b/content/platform/guides/lavaflow-slack.md @@ -114,8 +114,9 @@ clears. It follows the required checks and approvals and merges the PR when they pass. It uses the repository's merge queue when required. With `autonomy: open_pr`, you review and merge the resulting PR. -LavaFlow links to the PR and the Volcano run. It replies when GitHub records -the merge or LavaFlow needs help. If it opens no PR, the thread gives a reason. +The thread receives a link to the run in Volcano and a link to the PR when +one opens. LavaFlow replies when GitHub records the merge or LavaFlow needs +help. If no PR opens, the thread gives a reason. LavaFlow can follow an active report until its 10-day retention window ends. If the project connection, base, or merge authorization changes, the run shows `report_admission_lost`. Check the connection and PR before retrying. @@ -174,7 +175,7 @@ LavaFlow builds what the request asks for and nothing beyond it, and its reviewers hold anything else the change adds. Your project settings and repository rules determine whether LavaFlow can merge. To stop after opening the PR, write `@Volcano add hello.md containing "hello world". Open a PR and -leave the merge to me.` LavaFlow keeps the run at `pull_request`. To keep it +leave the merge to me.` LavaFlow opens the PR and leaves the merge to you. To keep it as a draft, say "leave the PR as a draft." Asking to open a draft PR still lets LavaFlow mark it ready when reviews pass. The pull request describes the requested change, and the run sets diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index 6a8d3875..4f436914 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -663,8 +663,8 @@ The commit comes from one of these: For any other deployment, LavaFlow diagnoses from the logs alone. A fix on a `verification: repository` commit opens only while the production branch -still holds that commit. It stays held under `client_reported_commit` until -someone verifies that it fixes the deployed code. +still holds that commit. The reason `client_reported_commit` asks you to review +the proposal against the deployed code and merge it yourself. ### Deploy code LavaFlow can read @@ -1577,7 +1577,7 @@ While LavaFlow still works on a run, `progress` says how far it has come: | `queued` | Waiting to start | | `diagnosing` | Finding the root cause | | `fixing` | Writing the fix | -| `reviewing` | Reviewing the fix; the pull request opens after it | +| `reviewing` | Reviewing the fix, often on an open draft PR | | `waiting_for_checks` | Waiting for its pull request's checks to pass | | `merge_queued` | Queued to merge | @@ -1649,7 +1649,7 @@ review finishes, `draft_reason` explains why the PR remains a draft. | `draft_reason` | Why the pull request is a draft | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `open_pr` | LavaFlow doesn't merge the fix, because autonomy is `open_pr`, merging was unavailable when it opened, or the run may only open a pull request, and its review didn't pass, LavaFlow's CI start for fixes you merge wasn't available, or your repository may run CI or previews outside GitHub Actions (or LavaFlow couldn't check; see [Review and merge fixes yourself](#review-and-merge-fixes-yourself)); or it was already a draft when the run took it on. Review it and mark it ready | +| `open_pr` | LavaFlow doesn't merge the fix, because autonomy is `open_pr`, merging was unavailable when it opened, or the run may only open a pull request, and its review didn't pass, LavaFlow's CI start for fixes you merge wasn't available, or your repository may run CI or previews outside GitHub Actions (or LavaFlow couldn't check; see [Review and merge fixes yourself](#review-and-merge-fixes-yourself)); or the reporter asked LavaFlow to keep it as a draft. Review it and mark it ready when appropriate | | `review_unresolved` | LavaFlow's review didn't pass the fix, so LavaFlow never merges it. Decide whether to finish it | | `converted_to_draft` | LavaFlow opened it ready for review, and someone made it a draft since | @@ -2910,16 +2910,16 @@ off, and any credential that reads the project's runs reads them. People in your Slack workspace can report a problem by mentioning `@Volcano` in a channel bound to the project, and LavaFlow diagnoses it like an issue. The -person who mentions it can also ask, in their own words, for new content or -functionality, which LavaFlow proposes as a pull request for a person to -review. The thread gets the outcome; the diagnosis stays in Volcano. See +person who mentions it can also use their own words to request a change. +The project's autonomy governs how far LavaFlow follows the PR. The thread +gets the outcome and the diagnosis stays in Volcano. See [Report problems from Slack](lavaflow-slack.md). ## Fix Aikido issues Connect an Aikido workspace and bind the project, and each new code (SAST) -issue Aikido finds on its repository starts a run that stops at a fix pull -request. See +issue Aikido finds on its repository starts a LavaFlow run. Fixes follow +the project's autonomy. See [Fix Aikido issues with LavaFlow](lavaflow-aikido.md). ## Agents From 6b890d248d2df5f714ce1b62527cdc7613a41a89 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 07:47:03 -0500 Subject: [PATCH 4/6] docs(lavaflow): explain required approvals and initial review --- content/platform/guides/lavaflow.md | 33 ++++++++++++++++------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index 4f436914..3b4fdb19 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -663,8 +663,8 @@ The commit comes from one of these: For any other deployment, LavaFlow diagnoses from the logs alone. A fix on a `verification: repository` commit opens only while the production branch -still holds that commit. The reason `client_reported_commit` asks you to review -the proposal against the deployed code and merge it yourself. +still holds that commit. LavaFlow holds the PR with `client_reported_commit`. +Review the proposal against the deployed code, then merge it yourself. ### Deploy code LavaFlow can read @@ -763,7 +763,7 @@ fixes or names that code, are held for you as `breaks_contract`. A listed choice covers only the behavior it describes: a reviewer still asks you about any other change in behavior that nothing justifies. A later round's `minor` problem, such as a decision the revision still doesn't list, doesn't send -the fix back again, so the review can pass and the pull request opens. With +the fix back again. The review can pass and the proposal stays available. With `autonomy: merge`, LavaFlow then holds the fix for you with `review_notes` rather than merging it. @@ -1068,11 +1068,11 @@ doesn't turn merging on again: turn it on again yourself. ### Waiting and held -A fix that only waits, for its checks or a merge queue slot, keeps moving, and -LavaFlow merges it when the wait ends. A held fix is yours for good: LavaFlow -never merges, pushes to, rebases or dequeues it again. The run's -`hold_reasons` say why. Review it and merge it on GitHub if you want it, or -close it. +A fix waiting for required checks, GitHub approval, or the merge queue +stays with LavaFlow. Once the requirements pass, LavaFlow finishes the merge. +A fix in `waiting_for_approval` needs a required approving review on GitHub. +A fix in `held` needs attention for a reason listed in `hold_reasons`. Review +and merge it on GitHub, or close it. A fix that needs a person when its pull request opens shows `waiting_for_checks`, with no `hold_reasons`, until LavaFlow's first read @@ -1121,7 +1121,7 @@ LavaFlow holds a fix for these reasons: | `required_check_skipped` | A required check was skipped | | `no_required_checks` | The base branch requires no check, so passing checks alone don't vouch for the fix | | `changes_requested` | A reviewer requested changes on GitHub | -| `repository_requires_approval` | The repository requires an approving review | +| `repository_requires_approval` | A historical hold for missing approval. Current runs wait in `waiting_for_approval` while GitHub requires approval | | `person_commits` | Someone other than LavaFlow pushed to the fix's branch | | `rules_bypass` | The Volcano GitHub App can bypass a ruleset on the base branch | | `unchecked_rules` | The base branch has a rule LavaFlow doesn't check, such as required signatures. On a fix you merge, it names only rules that kept LavaFlow from starting its CI, such as `code_scanning` or `workflows`, or says LavaFlow couldn't read the rules | @@ -1203,8 +1203,8 @@ repository that isn't private requires opens, and LavaFlow holds it with A required check passes only when it succeeds: `neutral` and `skipped` don't count, a check pinned to an app counts only as that app's check run, and -Volcano's own checks never count. An approving review on GitHub doesn't -release a hold. +Volcano's own checks never count. An approval can resume a PR in +`waiting_for_approval`. A PR in `held` stays with the person reviewing it. A run that may merge carries `merge`: @@ -1644,8 +1644,9 @@ tell which first included it, and `deployed_at` is the merge time. `draft` says whether the pull request is a draft, as GitHub last reported it to LavaFlow, and is `null` for one opened before LavaFlow recorded it. An -initial review draft can become ready automatically when reviews pass. After -review finishes, `draft_reason` explains why the PR remains a draft. +initial review draft can become ready automatically when reviews pass. +`draft_reason` is `null` during initial review. If the PR remains a draft +after review, `draft_reason` explains why. | `draft_reason` | Why the pull request is a draft | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -2594,8 +2595,10 @@ in the first example. ## Read the review on the pull request -LavaFlow's AI reviewers check each fix before its pull request opens. The -run's `review` always has their verdict and +With initial review enabled, LavaFlow opens a draft for a Live fix and posts +review feedback there as it works. Code Quality and runs without initial +review review the patch before opening a PR. The run's `review` contains the +verdict and [the findings](#read-a-reviews-findings), and on a private repository the pull request's description has the review's summary. From 2d3ef4ec2e036840026cc8d849e7bd7ac5470652 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 07:55:18 -0500 Subject: [PATCH 5/6] docs(lavaflow): align API and CLI merge lifecycle guidance --- content/cli/lavaflow.md | 15 +++++++++------ content/platform/guides/lavaflow.md | 9 +++++---- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/content/cli/lavaflow.md b/content/cli/lavaflow.md index af0b9de9..4173c4e5 100644 --- a/content/cli/lavaflow.md +++ b/content/cli/lavaflow.md @@ -185,11 +185,11 @@ that changes a path, use `--human-review-path`; see [Merge fixes](#merge-fixes). ### Merge fixes -At autonomy `merge`, LavaFlow can merge its fix pull requests. A fix built on -a commit the deploy reported, at either -[verification level](deploy.md#verification), is always held for a person. -Only a fix on a commit that a push to the repository deployed is free of that -hold. A fix it holds or stops is yours to review and merge on GitHub. +At autonomy `merge`, LavaFlow can merge fixes built on verified source, +including a frontend upload with [file verification](deploy.md#verification). +For an upload with repository verification only, check the fix against the +deployed code and merge it yourself. LavaFlow gives those fixes the +`client_reported_commit` hold. ```bash volcano cloud lavaflow settings set --autonomy merge @@ -237,7 +237,10 @@ volcano cloud lavaflow settings set --human-review-path 'infra/**' --human-revie ``` `show` prints `Merge:` in its `Fix:` block with where the merge is: -`waiting for CI`, `queued to merge`, `merged`, `held` or `stopped`. A merged +`waiting for CI`, `queued to merge`, `merged`, `held` or `stopped`. When +GitHub still requires an approval, the run's API status is +`merge.status: waiting_for_approval`. LavaFlow continues after approval. +A merged fix says `merged by LavaFlow`, or `merged by someone else` when a person merged it while LavaFlow waited. While merging is paused, a waiting fix says `paused while merging is off` instead. `held` and diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index 3b4fdb19..9f034dec 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -1226,6 +1226,7 @@ A run that may merge carries `merge`: | `status` | Meaning | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `waiting_for_checks` | Waits for the checks on the fix's commit | +| `waiting_for_approval` | Checks passed and GitHub requires an approving review. LavaFlow continues after approval. | | `queued` | In the repository's merge queue | | `merged` | Merged; the run's `pull_request.state` is `merged` | | `held` | Handed to you for good, for `hold_reasons`; each `question` says why LavaFlow holds it and what to check before you merge it | @@ -1578,7 +1579,7 @@ While LavaFlow still works on a run, `progress` says how far it has come: | `diagnosing` | Finding the root cause | | `fixing` | Writing the fix | | `reviewing` | Reviewing the fix, often on an open draft PR | -| `waiting_for_checks` | Waiting for its pull request's checks to pass | +| `waiting_for_checks` | Waiting for required checks or GitHub approval. Read `merge.status` to tell which is pending. | | `merge_queued` | Queued to merge | `step` is the stage's place, from 1, among the run's `steps`: 2 for @@ -2595,9 +2596,9 @@ in the first example. ## Read the review on the pull request -With initial review enabled, LavaFlow opens a draft for a Live fix and posts -review feedback there as it works. Code Quality and runs without initial -review review the patch before opening a PR. The run's `review` contains the +When LavaFlow opens a draft before its review, it posts feedback on that +PR as it works. For Code Quality, LavaFlow reviews the patch before opening +a PR. The run's `review` contains the verdict and [the findings](#read-a-reviews-findings), and on a private repository the pull request's description has the review's summary. From 852fd8061be7d0331607a943d65a1436fff66643 Mon Sep 17 00:00:00 2001 From: Sean Keever <33592180+swkeever@users.noreply.github.com> Date: Thu, 19 Nov 2026 08:00:05 -0500 Subject: [PATCH 6/6] docs(lavaflow): clarify rollout and source verification --- content/cli/deploy.md | 7 +++---- content/platform/guides/lavaflow-slack.md | 12 +++++++----- content/platform/guides/lavaflow.md | 9 +++++---- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/content/cli/deploy.md b/content/cli/deploy.md index 62c07010..4a60d31b 100644 --- a/content/cli/deploy.md +++ b/content/cli/deploy.md @@ -343,10 +343,9 @@ A reported commit Volcano can't confirm is recorded with `verification: none`, and LavaFlow diagnoses that deployment from the logs alone. That includes a frontend upload that doesn't match its commit, and a workflow run for a pull request, which deploys GitHub's merge commit on no branch. At autonomy -`merge`, LavaFlow holds a fix built on a reported commit, at either level, for -a person to merge. A fix built on a commit that a -[push to the repository deployed](#cloud-projects-that-deploy-from-git) has no -such hold. `frontends deploy --from` keeps the commit of the build it +`merge`, fixes on file-verified uploads can merge after the required reviews +and checks. LavaFlow holds a fix with repository-only verification for you to +check against the deployed code and merge. `frontends deploy --from` keeps the commit of the build it publishes. A frontend redeploy reports no commit of its own, and LavaFlow reads it as the commit of the build that made its artifact. diff --git a/content/platform/guides/lavaflow-slack.md b/content/platform/guides/lavaflow-slack.md index 236665ac..a7911dbd 100644 --- a/content/platform/guides/lavaflow-slack.md +++ b/content/platform/guides/lavaflow-slack.md @@ -109,17 +109,19 @@ retry after LavaFlow refused the report at a limit. LavaFlow replies with the project it picked and its repository. With [`autonomy: merge`](lavaflow.md#merge-fixes), LavaFlow can take an issue from Slack to a merge on the project's production branch. It pins the repository -revision, reviews and revises the draft PR, and marks it ready once review -clears. It follows the required checks and approvals and merges the PR when +revision and reviews the fix. Where review on a draft PR is available, it +revises that draft and marks it ready once review clears. It follows the required checks and approvals and merges the PR when they pass. It uses the repository's merge queue when required. With `autonomy: open_pr`, you review and merge the resulting PR. The thread receives a link to the run in Volcano and a link to the PR when one opens. LavaFlow replies when GitHub records the merge or LavaFlow needs help. If no PR opens, the thread gives a reason. -LavaFlow can follow an active report until its 10-day retention window ends. -If the project connection, base, or merge authorization changes, the run -shows `report_admission_lost`. Check the connection and PR before retrying. +LavaFlow follows an active report within its retention window, at most 10 days +from the report. If the report expires before the merge, or LavaFlow loses +access or can no longer verify the base, the run holds the PR with +`report_admission_lost`. Review and merge the open PR on GitHub if it is +still applicable. The run link opens the report's project in the same environment as the Slack app and still requires access to that project. It never holds the diagnosis: diff --git a/content/platform/guides/lavaflow.md b/content/platform/guides/lavaflow.md index 9f034dec..2d17a434 100644 --- a/content/platform/guides/lavaflow.md +++ b/content/platform/guides/lavaflow.md @@ -897,7 +897,7 @@ commit to the branch to run your CI, mark the pull request ready for review, then review and merge it, and [keep the CI skip out of your base branch](#keep-the-ci-skip-out-of-your-base-branch). -**Once it is available,** a fix whose review passed opens ready for review. +**Once it is available,** LavaFlow can make a fix ready after its review passes. Its commit skips CI at first. About a minute later, LavaFlow's first read of the pull request runs your repository's CI on it once, the way it starts CI under `merge` (see [Check before CI starts](#check-before-ci-starts)): where @@ -2596,9 +2596,10 @@ in the first example. ## Read the review on the pull request -When LavaFlow opens a draft before its review, it posts feedback on that -PR as it works. For Code Quality, LavaFlow reviews the patch before opening -a PR. The run's `review` contains the +In environments where review on a draft PR has rolled out, LavaFlow first +opens a draft for Live fixes and posts feedback there as it works. Elsewhere, +it completes its review before opening the PR. Code Quality always reviews +the patch before opening a PR. The run's `review` contains the verdict and [the findings](#read-a-reviews-findings), and on a private repository the pull request's description has the review's summary.