feat(ci): introduce merge queue

[elezar]

🏗️ build-from-issue-agent

Summary

Add merge-queue support for the required OpenShell CI gates. The existing copy-pr-bot PR mirror flow remains intact, and merge-group runs publish the same stable OpenShell / ... status contexts for the queued integration SHA.

Related Issue

Closes#1946

Changes

• .github/workflows/branch-checks.yml: add merge_group as a required branch-check trigger.
• .github/workflows/branch-e2e.yml: add merge_group and make push, manual, and queue E2E selection explicit.
• .github/workflows/helm-lint.yml: add merge_group validation for queued integration commits.
• .github/workflows/required-ci-gates.yml: publish required CI statuses for merge-group SHAs without requiring a pull-request/<N> mirror branch.
• .github/actions/pr-gate/action.yml: document that non-push events include merge_group.
• CI.md and architecture/build.md: document the maintainer merge-queue workflow and required contexts.

Deviations from Plan

None — implemented as planned. The branch was rebased after #2022 merged so local validation includes that main Rust test fix.

Testing

• YAML parse for touched workflow/action files
• mise run markdown:lint
• git diff --check origin/main...HEAD
• mise run pre-commit passes locally (attempted after rebasing on fix(server): update driver spec test argument #2022; Rust check/lint, Python, Helm, Markdown, license, docs, and packaging checks passed, but test:rust still fails on this machine because xcrun --show-sdk-path cannot find the macOS SDK and the CLI integration test temporary fake-forward-process cannot link -lSystem)

Tests added:

• Unit: N/A — workflow YAML and docs only.
• Integration: N/A — no application integration paths changed.
• E2E: N/A — no e2e/ files changed.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)

Documentation updated:

• CI.md: merge queue behavior, required contexts, maintainer workflow, and workflow file roles.
• architecture/build.md: CI architecture now includes merge-group validation.

[pimlock]

As I was looking into this, one thing that I realized that is likely contributing to this issue is the fact that our branch checks run on the code as-is on the branch, whereas the default for pull_request triggered workflows is to test against refs/pull/<ID>/merge, which is the result after merging the PR to the current main.

With the copy-pr-bot and push trigger, checks run exactly on the branch's code, which is likely out of date.

[elezar]

As I was looking into this, one thing that I realized that is likely contributing to this issue is the fact that our branch checks run on the code as-is on the branch, whereas the default for pull_request triggered workflows is to test against refs/pull/<ID>/merge, which is the result after merging the PR to the current main.

With the copy-pr-bot and push trigger, checks run exactly on the branch's code, which is likely out of date.

This is interesting. I was not aware of this. Maybe we could reach out to the copy-pr-bot team to better align the behaviour.

One thing to note however, is that even if we were to run against the "merge" result on the PR (which we could do on public infrastructure for steps that don't need repo write access already), this is not updated as main is updated which means that we would still see the same failure mode w.r.t post-merge issues in Rust linting.

[matthewgrossman]

lgtm!