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.

[elezar]

Question: Why not just default to the values for workflow_dispatch (which is what this code was doing beforehand).

[elezar]

I think we should rather not run e2e tests in the merge queue -- or use the same logic as we do for PRs?

[TaylorMutch]

Is it just because of waiting for e2e tests can take a while or might flake for infra reasons?

[pimlock]

+1 to not running all E2E. We could get started with that and potentially have a smaller set of E2E that runs on merge queue if needed?

For PRs that need e2e (i.e. have the label) we could have them to be up to date with main. Github has that as a setting, but it's global, so it wouldn't be enforced though.

[drew]

if we don't run e2e on merge queues then we lose coverage, right? e2e tests are optional on branch checks.

[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.