Skip to content

fix(lavaflow): explain required approval waits - #497

Merged
swkeever merged 1 commit into
mainfrom
skeever/lavaflow-required-approval-wait
Nov 17, 2026
Merged

swkeever merged 1 commit into
mainfrom
skeever/lavaflow-required-approval-wait

Conversation

@swkeever

Copy link
Copy Markdown
Collaborator

When GitHub requires a human review, LavaFlow Merge mode now keeps an active approval wait instead of handing off permanently. Show that state as “waiting for required approval” and explain automatic continuation after approval and CI pass; paused waits still show as paused.

Vendors only the three changed canonical LavaFlow schema components and regenerates the API client. Existing unknown-status fallback remains compatible with older servers.

Validation: complete LavaFlow command and output package tests; changed-package golangci-lint (0 issues); OpenAPI generation check. Public documentation is coordinated in volcano-docs. Production deployment remains on hold until Sean releases it tomorrow.

@swkeever
swkeever marked this pull request as ready for review November 17, 2026 02:08
@swkeever
swkeever requested a review from a team as a code owner November 17, 2026 02:08
@swkeever
swkeever requested review from shawnwu-kong and a balanced review from Copilot November 17, 2026 02:08
@swkeever
swkeever enabled auto-merge November 17, 2026 02:08

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

Copy link
Copy Markdown

AI review: no P0-P2 findings

Reviewed 3862b30. Run log

Adds the waiting_for_approval LavaFlow merge status to the vendored OpenAPI spec and generated client. lavaflow show now prints it as "waiting for required approval (merges automatically after approval and CI)", and a paused wait still prints as paused. The change only adds an enum value and its display text, and it comes with tests, so the risk is low. Unknown statuses already print as given, so older and newer servers both still work.

⚪ P3

  • openapi/openapi.yaml:31096 Vendored hold-reason description refers to a run choices field this spec doesn't define
  • internal/output/lavaflow.go:643 Companion volcano-docs PR isn't linked as AGENTS.md requires

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 the deployed LavaFlow API actually sends merge.status: waiting_for_approval, and with which reason values; the PR says production deployment is on hold.
  • Whether internal/apiclient/client.gen.go matches a fresh generator run on the updated spec; the PR says this check passed.
  • Whether the companion content/cli PR in Kong/volcano-docs exists and describes the new status.
  • Confirm the server’s approval-wait and automatic-continuation behavior matches the updated schema descriptions.
  • Verify the companion Kong/volcano-docs PR updates content/cli and that both PRs link to each other, as AGENTS.md requires.

Human review: not needed

Comment thread openapi/openapi.yaml
code:
type: string
description: 'Why the fix is held. `client_reported_commit`: the fix is built on a commit Volcano can''t tie to a push. `path`: it changes a path in `human_review_paths`, or deploy or infrastructure configuration Volcano always holds, such as `volcano-config.yaml`, Terraform files, a YAML or JSON file that declares a resource, a YAML template that mentions `apiVersion` or `kind`, a file in a Helm chart or Kustomize directory, or, in a repository too large to read in full, any file no other path reason holds. `sensitive_path`: it changes another path Volcano always holds: authentication or authorization code, Next.js middleware included; secret, key, certificate or cryptography files; a coding agent''s instructions or settings, or Git hook configuration; CI configuration; a dependency manifest or lockfile, or a `package.json` change to what installs or its install scripts; or runtime, container or other configuration files. `label`: the pull request has the `needs-human-review` label. `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. `changes_requested`: a reviewer requested changes. `repository_requires_approval`: the repository requires an approving review. `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. `commit_convention`: no title can meet the repository''s commit convention. `ungated_workflows`: the fix opened past workflows that can run it with the repository''s secrets before a person approves it, as the project''s owner allowed, or LavaFlow couldn''t check its workflows, so LavaFlow never starts its CI or merges it. `lineage_undoes_parent`: the fix follows up an earlier LavaFlow fix and deletes or changes lines that fix added, which could undo it. `lineage_cap`: the fix''s lineage opened as many pull requests as it may. `lineage_held`: an earlier pull request in the fix''s lineage was held, stopped or closed. `recent_regressions`: fixes LavaFlow merged in the project recently caused new errors. Other codes name a concern LavaFlow''s reviewers raised. New codes may appear.'
description: 'Why the fix is held. `client_reported_commit`: the fix is built on a commit Volcano can''t tie to a push. `path`: it changes a path in `human_review_paths`, or deploy or infrastructure configuration Volcano always holds, such as `volcano-config.yaml`, Terraform files, a YAML or JSON file that declares a resource, a YAML template that mentions `apiVersion` or `kind`, a file in a Helm chart or Kustomize directory, or, in a repository too large to read in full, any file no other path reason holds. `sensitive_path`: it changes another path Volcano always holds: authentication or authorization code, Next.js middleware included; secret, key, certificate or cryptography files; a coding agent''s instructions or settings, or Git hook configuration; CI configuration; a dependency manifest or lockfile, or a `package.json` change to what installs or its install scripts; or runtime, container or other configuration files. `label`: the pull request has the `needs-human-review` label. `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. `changes_requested`: a reviewer requested changes. `repository_requires_approval`: a legacy run was handed off because the repository required an approving review. That final hold stays final; new merge watches use `waiting_for_approval` instead. `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 a person merges it names only rules that kept LavaFlow from starting the fix''s CI, such as `code_scanning` or `workflows`, or that LavaFlow couldn''t read them. `commit_convention`: no title can meet the repository''s commit convention. `ungated_workflows`: the fix opened past workflows that can run it with the repository''s secrets before a person approves it, as the project''s owner allowed, or LavaFlow couldn''t check its workflows, or, when LavaFlow was about to start its CI or add it to a merge queue, a workflow could run it with those secrets before a person approves it or couldn''t be read, so LavaFlow takes it no further and never merges it. A fix held for another reason before its CI starts lists it too when that check, run without starting CI, finds such a workflow or can''t finish. `ci_outside_actions`: when LavaFlow was about to start the fix''s CI, the repository could run CI, a build or a preview outside GitHub Actions: the root of the fix''s tree or its base branch''s holds another service''s configuration, such as `.travis.yml`, `.circleci/` or `netlify.toml`, which `paths` names, another app reported checks or statuses on the base branch, or LavaFlow couldn''t read them in full. LavaFlow starts CI only when it finds no sign of CI outside GitHub Actions, so it never starts this fix''s CI or merges it. `lineage_undoes_parent`: the fix follows up an earlier LavaFlow fix and deletes or changes lines that fix added, which could undo it. `lineage_cap`: the fix''s lineage opened as many pull requests as it may. `lineage_held`: an earlier pull request in the fix''s lineage was held, stopped or closed; one a person merges holds it only when closed. `recent_regressions`: fixes LavaFlow merged in the project recently caused new errors. `no_test`: the fix changes code the repository tests and adds no test, because testing it needs test infrastructure the repository doesn''t have or the change has no effect a test can observe. `choices_to_confirm`: the fix states behavior it decides beyond stopping the error, listed in the run''s `choices` and, on a private repository, under Choices to confirm in the pull request''s description, for a person to confirm, and LavaFlow''s reviewers didn''t all mark each choice as needing no person. It never applies alongside `person_merges`: the person confirms the choices while reviewing the fix. `risky_change`: the fix adds or removes a line that converts a value, such as with `float()` or `parseInt()`, in a file that names a rate limit or quota, authentication or authorization, or money, so values such as NaN, Infinity or a negative number could get past a check there; `paths` names the files. `review_notes`: LavaFlow''s reviewers passed the fix, but its review''s last round left notes, findings below `major` that a later round no longer sends back for revision, such as a decision the fix makes without stating it. `person_merges`: a person reviews and merges the fix, because the project''s autonomy is `open_pr`, merging was unavailable when it opened, or its run may only open a pull request; LavaFlow ran the fix''s CI once first unless another reason, or the CI start''s own checks, stopped it. Other codes name a concern LavaFlow''s reviewers raised. New codes may appear.'

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚪ P3: Vendored hold-reason description refers to a run choices field this spec doesn't define

Only three schema components were copied from the server spec. The new LavaflowHoldReason.code description now says choices_to_confirm lists behavior "in the run's choices", but choices appears nowhere else in openapi/openapi.yaml or in client.gen.go. Anyone reading the generated Go docs or the vendored spec is pointed to a field the CLI's client doesn't have. Nothing breaks at runtime because the CLI never reads it. Either vendor the choices property with it, or accept the gap until the next full spec sync.

Found by claude-opus-5-5

case apiclient.LavaflowMergeStatusWaitingForChecks:
return "waiting for CI"
case apiclient.LavaflowMergeStatusWaitingForApproval:
return "waiting for required approval (merges automatically after approval and CI)"

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚪ P3: Companion volcano-docs PR isn't linked as AGENTS.md requires

This adds user-facing output in lavaflow show, a new merge status line. AGENTS.md asks for a companion PR in Kong/volcano-docs updating content/cli, with the two PRs linked. The description only says docs are "coordinated in volcano-docs" and gives no link, so this review can't confirm the docs change exists. Link the companion PR.

Found by claude-opus-5-5

@swkeever
swkeever added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit 7b601bd Nov 17, 2026
26 of 27 checks passed
@swkeever
swkeever deleted the skeever/lavaflow-required-approval-wait branch November 17, 2026 02:23
@kong-volcano-app kong-volcano-app Bot mentioned this pull request Nov 17, 2026
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