Repository navigation
feat(ci): introduce merge queue for main #1946
Description
Problem Statement
main can break when a pull request passes CI on a stale branch head, then GitHub creates a final merge commit against a newer main that was never tested by the PR checks.
We saw this with PR #1870 and PR #1577. PR #1870 passed Branch Checks on stale head 29d57cc, whose merge-base did not include #1577. The final merge commit ff028ce0 combined #1870 TLS reload shutdown handling with #1577 compute watcher shutdown handling, introduced a duplicate shutdown_tx binding, and caused main Rust lint to fail in https://github.com/NVIDIA/OpenShell/actions/runs/27656754843/job/81792472668.
PR #1945 fixes that immediate break, but the integration gap remains.
Proposed Design
Enable GitHub merge queue for the protected main branch and require queued merge groups to pass the same gates required for normal PRs.
Implementation outline:
- Enable
Require merge queuefor themainbranch protection/ruleset. - Add the
merge_grouptrigger to workflows that publish required PR gate inputs, especially:.github/workflows/branch-checks.yml.github/workflows/branch-e2e.yml.github/workflows/helm-lint.yml
- Confirm
.github/workflows/required-ci-gates.ymlcan evaluate and publish required gate statuses for merge-group runs, or update it so the required contexts are reported for merge queue validation. - Keep the required contexts aligned with the existing PR gate contexts:
OpenShell / Branch ChecksOpenShell / E2EOpenShell / GPU E2EOpenShell / Helm Lint
- Document the expected maintainer workflow for adding a PR to the merge queue instead of merging directly.
GitHub documentation notes that merge queues validate PR changes applied to the latest target branch and any earlier queued changes, and that GitHub Actions workflows used as required checks must include the merge_group event: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue
Alternatives Considered
Require PR branches to be up to date before merging.
That would likely have caught the #1870/#1577 interaction too, because #1870 would have had to rerun checks after updating to include #1577. However, it pushes more manual branch-update work onto contributors and maintainers. Merge queue is a better fit for a busy main branch because it validates the final integration state without forcing every PR author to repeatedly rebase or merge main by hand.
Rely only on push CI after merge.
This detects breakage after main is already broken, which is what happened here.
Agent Investigation
- Loaded
watch-github-actionsto inspect failing run27656754843/ job81792472668. - Failure was
cargo clippy --workspace --all-targets -- -D warningsrejecting unused variableshutdown_txincrates/openshell-server/src/lib.rs. git blameand history showed the production duplicate channel came from the interaction of:- feat(gateway): add reconciler lease for HA multi-replica deployments #1577 /
e73745f1adding compute watcher shutdown handling. - feat(server): support TLS certificate hot-reload #1870 /
ff028ce0adding TLS reload shutdown handling.
- feat(gateway): add reconciler lease for HA multi-replica deployments #1577 /
- PR feat(server): support TLS certificate hot-reload #1870 checks passed on head
29d57cc, which did not include feat(gateway): add reconciler lease for HA multi-replica deployments #1577. The broken code only existed in the final merge commit onto newermain. - Opened PR fix(server): share gateway shutdown channel #1945 to fix the immediate CI failure by sharing the existing gateway shutdown channel.
Activity
elezar commentedon Jun 17, 2026
Additional example: #1872 is another case this issue should cover.
#1872 fixed the server build after #1566 introduced gRPC rate limiting code that used the private
tonic::body::BoxBodyalias. The PR checks for #1566 passed before the final integrated state onmainexposed the tonic 0.14 incompatibility. A merge queue, or a strict up-to-date-branch requirement, would have forced the final branch-plus-current-mainstate through the required Rust checks before merge instead of relying on push CI aftermainwas already broken.This reinforces that the work is not only a repository setting change. The required CI workflows need to support merge queue validation explicitly. In the current workflow set,
.github/workflows/branch-checks.yml,.github/workflows/branch-e2e.yml, and.github/workflows/helm-lint.ymltrigger onpushtopull-request/[0-9]+plusworkflow_dispatch, but notmerge_group..github/workflows/required-ci-gates.ymlalso keys its aggregation aroundpull_request_targetand completed workflow runs from those branch workflows. The implementation should update these workflows so the required contexts are reported for merge-group SHAs.elezar commentedon Jun 26, 2026
Implementation Plan
Issue type:
featComplexity: Medium
Confidence: Medium — the repository workflow changes are clear, but the final merge-queue ruleset setting is outside the repo and must be enabled by a maintainer.
Summary
Add merge-queue support to the existing required CI gate model without replacing the current copy-pr-bot mirror flow for PRs. The implementation should trigger the required workflows on
merge_group, publish the existingOpenShell / ...status contexts for merge-group SHAs, and document how maintainers enqueue PRs instead of merging directly.Scope
.github/workflows/branch-checks.yml: add amerge_grouptrigger so normal branch checks run against GitHub's queued integration commit..github/workflows/branch-e2e.yml: add amerge_grouptrigger and make the E2E selection explicit per event type; preserve label-gated behavior for mirrored PR pushes, preserve full-suite behavior for manual dispatch, and run the required merge-queue suites for queued integration commits..github/workflows/helm-lint.yml: add amerge_grouptrigger and keep non-push behavior as an unconditional Helm validation path..github/workflows/required-ci-gates.yml: teach the status publisher to handle merge-group runs in addition to PR mirror runs. It should post the same required contexts to the merge-group SHA, skip mirror validation for merge groups, query workflow runs withevent=merge_group, and preserve the existing PR-head status behavior unchanged..github/actions/pr-gate/action.yml: update comments/metadata if needed so non-push behavior explicitly coversworkflow_dispatchandmerge_group.CI.md: document the maintainer merge-queue workflow, required ruleset configuration, and how merge-group checks relate to the existing PR mirror checks.architecture/build.md: update the CI overview to include merge queue validation of the final integration state.Implementation Steps
merge_grouptriggers to the branch check, branch E2E, and Helm lint workflows.push,workflow_dispatch, andmerge_groupeach have deliberate suite-selection behavior.required-ci-gates.ymlto resolve merge-group context, post statuses to the merge-group SHA, and evaluate merge-group workflow runs without requiring apull-request/<N>mirror branch.OpenShell / Branch Checks,OpenShell / E2E,OpenShell / GPU E2E, andOpenShell / Helm Lintexactly as before.CI.mdandarchitecture/build.mdwith the merge queue operating model and the maintainer-side GitHub ruleset step: enableRequire merge queueformainand require the sameOpenShell / ...contexts for queued merges.Test Plan
mise run pre-commitand focused review of the shell paths inrequired-ci-gates.yml. If a workflow syntax checker is available in the repo/toolchain, run it as part of pre-commit or a targeted workflow lint command.e2e/files are expected to change. The functional validation is the PR's GitHub Actions run, followed by a maintainer enabling merge queue and enqueueing a PR to verifymerge_groupstatus publication.Risks & Open Questions
Documentation Impact
CI.mdfor contributor and maintainer workflow details.architecture/build.mdfor the canonical CI architecture overview.LSM Compatibility
/procaccess, binary execution behavior, or sandbox runtime policy.Revision 1 — initial plan
feat(ci): introduce merge queue
elezar commentedon Jun 26, 2026
Implementation Complete
PR: #2024
What was built
Added merge-queue support to the required CI gate workflows while preserving the existing copy-pr-bot PR mirror path. Merge-group runs now trigger the relevant workflows and publish the stable
OpenShell / ...required contexts for queued integration SHAs.Tests
mise run markdown:lint: passedgit diff --check origin/main...HEAD: passedmise run pre-commit: attempted; all non-Rust-test checks plus Rust check/lint completed, but localtest:rustfails because this machine cannot resolve the macOS SDK (xcrun --show-sdk-pathfails) and the CLI integration test temporaryfake-forward-processcannot link-lSystem.Docs updated
CI.mdarchitecture/build.mdThe issue will auto-close when the PR is merged.
feat(ci): introduce merge queue
github-actions commentedon Jul 11, 2026
This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.
feat(ci): introduce merge queue
feat(ci): introduce merge queue (#2024)
Chore/resync 20260820 (#4)