test(e2e): hermetic end-to-end coverage of a real git merge (#546)

## Summary
### Why?

The existing E2E suite runs Runway on the noop merger, so a request
reaching `landed` proves the pipeline's choreography and nothing at all
about git. Every risky part of merging for real — the `git` binary in
the image, checkout provisioning, the apply and push, head-branch
updates — had no automated coverage through the stack.

None of that needs a provider. The merger speaks `git://` against any
remote, so pointing it at a bare repository on a shared volume exercises
the whole merge path with no credential, no network, and no account
anywhere — which is what lets these assertions gate a pull request.

### What?

A second suite lands `git://` changes and asserts against the repository
itself rather than against request status: which commits reached the
target, in what order, and in how many ref updates. A three-change stack
must arrive in exactly **one** ref update, counted from the target's
reflog — the property that distinguishes a submit queue from merging
changes one at a time, and one that is hard to check against a live
provider.

It also pins two behaviors worth not regressing: a conflicting change
leaves the target untouched, and re-submitting a change after it has
landed is rejected as stale (landing moved its head branch, so the URI
no longer describes where that branch points).

`testutil.NewComposeStack` gained `WithOverlay`, so the suite states
only what differs from the base stack — Runway's merge target — instead
of copying the whole service definition. A copy is the thing that rots:
services added to the base file never reach the duplicate, and nothing
fails until the variant runs.

The suite drives the bare repository with the same pinned git the merger
uses, rather than the host's, since these assertions depend on
repository mechanics and an ambient git brings ambient configuration
with it.

## Test Plan
✅ `make e2e-git-test` — the new suite.

✅ `make e2e-test` — both suites; the existing one is unchanged and still
passes.

Also fixes `make help`, whose target regex excluded digits, so neither
`e2e-test` nor `e2e-git-test` was ever listed.

## Issues

Author: behinddwalls

Makefile

@@ -134,6 +134,11 @@ clean-proto: ## Clean generated proto files
 deps: tidy-go ## Download and tidy Go dependencies
 	@echo "Dependencies installed!"
 
+e2e-git-test: ## Run the hermetic git E2E (real merger against a bare repo; no credentials)
+	@echo "Running hermetic git end-to-end tests..."
+	@$(BAZEL) test //test/e2e/submitqueue:go_default_test --test_output=errors \\
+		--test_filter='TestGitMergeE2E'
+
 e2e-test: ## Run end-to-end tests (hermetic; Bazel builds all inputs; runs in parallel)
 	@echo "Running end-to-end tests (parallel)..."
 	@$(BAZEL) test //test/e2e/... --test_output=errors
@@ -396,20 +401,16 @@ query-deps:
 query-targets:
 	@$(BAZEL) query //...
 
-# Run gateway client (connects to any running gateway service)
-run-client-submitqueue-gateway:
+run-client-submitqueue-gateway: ## Run the gateway client against a running gateway (SERVER_ADDR, MESSAGE)
 	@$(BAZEL) run //service/submitqueue/gateway/client:gateway -- -addr $(or $(SERVER_ADDR),localhost:8081) -message "$(or $(MESSAGE),ping)"
 
-# Run orchestrator client (connects to any running orchestrator service)
-run-client-submitqueue-orchestrator:
+run-client-submitqueue-orchestrator: ## Run the orchestrator client against a running orchestrator (SERVER_ADDR, MESSAGE)
 	@$(BAZEL) run //service/submitqueue/orchestrator/client:orchestrator -- -addr $(or $(SERVER_ADDR),localhost:8082) -message "$(or $(MESSAGE),ping)"
 
-# Run stovepipe client (connects to any running stovepipe service)
-run-client-stovepipe:
+run-client-stovepipe: ## Run the Stovepipe client against a running Stovepipe (SERVER_ADDR, MESSAGE)
 	@$(BAZEL) run //service/stovepipe/client:stovepipe -- -addr $(or $(SERVER_ADDR),localhost:8083) -message "$(or $(MESSAGE),ping)"
 
-# Run runway client (connects to any running runway service)
-run-client-runway:
+run-client-runway: ## Run the Runway client against a running Runway (SERVER_ADDR, MESSAGE)
 	@$(BAZEL) run //service/runway/client:runway -- -addr $(or $(SERVER_ADDR),localhost:8086) -message "$(or $(MESSAGE),ping)"
 
 run-queue-admin: ## Run queue-admin CLI (use ARGS to pass arguments, e.g. make run-queue-admin ARGS="list-topics")
@@ -436,4 +437,4 @@ tidy-go: ## Run go mod tidy
 help: ## Show this help message
 	@echo "Available targets:"
 	@echo ""
-	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-30s\033[0m %s\n", $$1, $$2}'
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-30s\033[0m %s\n", $$1, $$2}'

service/submitqueue/BUILD.bazel

@@ -1,4 +1,7 @@
 exports_files(
-    ["docker-compose.yml"],
+    [
+        "docker-compose.git.yml",
+        "docker-compose.yml",
+    ],
     visibility = ["//visibility:public"],
 )

service/submitqueue/demo/provider/local/BUILD.bazel

@@ -0,0 +1,14 @@
+"""Demo provider configuration for a plain git remote (no provider).
+
+Consumed by the hermetic git E2E, which bind-mounts this directory into the
+orchestrator and runway containers.
+"""
+
+filegroup(
+    name = "config",
+    srcs = [
+        "merge.yaml",
+        "profiles.yaml",
+    ],
+    visibility = ["//test:__subpackages__"],
+)

service/submitqueue/demo/provider/local/merge.yaml

@@ -0,0 +1,32 @@
+# Merge targets for the "local" example: a plain git remote with no provider.
+#
+# This is what the hermetic git E2E (`make e2e-git-test`) runs against — a bare
+# repository on a shared volume, addressed by path. It exercises the whole merge
+# machinery (real fetch, cherry-pick, push, head-branch update) with no
+# credential, no network, and no provider account, which is what lets it gate PRs
+# in CI.
+#
+# It doubles as the worked example of a non-GitHub target: nothing below names a
+# provider, because the merger does not have one. See ../README.md.
+
+defaults:
+  # Any queue without an entry below does not merge for real.
+  merger: {type: noop}
+
+queues:
+  - name: e2e-git-queue
+    merger:
+      type: git
+      # A local path needs no credential, so no tokenEnv is named.
+      remoteUrl: file:///srv/git/sandbox.git
+      remote: origin
+      target: main
+      # Provisioned at startup: cloned, remote configured, target checked out.
+      checkoutPath: /var/runway/checkouts/sandbox
+      defaultStrategy: REBASE
+      checkStaleness: true
+      # Rewriting strategies leave the change's original head unreachable from
+      # the target, so its branch is moved to the commit it landed as. On a
+      # provider this is what makes the change show as merged; here it is simply
+      # observable as the branch having moved.
+      updateHeadBranch: true

service/submitqueue/demo/provider/local/profiles.yaml

@@ -0,0 +1,20 @@
+# Extension profiles for the "local" example: a plain git remote with no provider.
+#
+# There is no provider to ask about a change, and no CI to run, so both edge
+# integrations stay fake. What this example exercises is the merge itself — see
+# merge.yaml.
+
+defaults:
+  # A local git remote has no API to fetch change metadata from; the fake
+  # echoes back each URI it is given.
+  changeProvider: {type: fake}
+  # Every build succeeds immediately, so a land completes in seconds.
+  buildRunner: {type: fake}
+  # Serialize conservatively unless a queue says otherwise.
+  analyzer: {type: all}
+
+queues:
+  - name: e2e-git-queue
+    # Maximum parallelism: batches never conflict, so the test controls
+    # ordering through what it lands rather than through the analyzer.
+    analyzer: {type: none}

service/submitqueue/docker-compose.git.yml

@@ -0,0 +1,45 @@
+# Compose overlay: point Runway at a real git merge target.
+#
+# Layered over docker-compose.yml, which it does not modify:
+#
+#   docker compose -f docker-compose.yml -f docker-compose.git.yml up
+#
+# Used by the hermetic git E2E (`make e2e-git-test`), which merges it through
+# testutil.WithOverlay. Everything else about the stack — the services, their
+# databases, the consumer gate — comes from the base file, so a service added
+# there reaches this variant too.
+#
+# The merge target is a bare repository on a shared volume, addressed by path.
+# That exercises the whole merge path (git in the image, checkout provisioning,
+# real cherry-pick and push, head-branch updates) with no credential, no
+# network, and no account anywhere — which is what lets it gate a pull request.
+#
+# Required in the environment, all owned by the test:
+#   SQ_PROVIDER_CONFIG_DIR   profiles.yaml / merge.yaml selecting each queue's
+#                            extensions (service/submitqueue/demo/provider/local)
+#   SQ_GIT_SANDBOX_DIR       the bare repository the merger fetches and pushes
+#   SQ_RUNWAY_CHECKOUT_DIR   storage for the working trees the merger owns
+
+services:
+  orchestrator-service:
+    environment:
+      # Which change provider, build runner, and conflict analyzer each queue
+      # resolves to. Everything at the edges stays fake here; only the merge is
+      # real.
+      - PROFILES_CONFIG_PATH=/etc/submitqueue/profiles.yaml
+    volumes:
+      - ${SQ_PROVIDER_CONFIG_DIR}:/etc/submitqueue:ro
+
+  runway-service:
+    environment:
+      # Per-queue merge targets. Without this Runway falls back to the noop
+      # merger and nothing would actually be pushed.
+      - MERGE_CONFIG_PATH=/etc/submitqueue/merge.yaml
+    volumes:
+      - ${SQ_PROVIDER_CONFIG_DIR}:/etc/submitqueue:ro
+      - ${SQ_GIT_SANDBOX_DIR}:/srv/git
+      # A checkout is state, not image content, so it is mounted rather than
+      # baked in — and mounting it is also what makes the path writable by a
+      # service running as a non-root user, which the E2E does so its bind
+      # mounts stay readable from the host.
+      - ${SQ_RUNWAY_CHECKOUT_DIR}:/var/runway/checkouts

service/submitqueue/gateway/server/queues.yaml

@@ -11,3 +11,6 @@ queues:
   # exercise the conflict-analysis error path. See newQueueRegistry in the
   # orchestrator example server.
   - name: e2e-conflict-error-queue
+  # Used by the hermetic git E2E, where Runway is wired to a real git merger
+  # against a bare repository. See service/submitqueue/example/provider/local.
+  - name: e2e-git-queue

test/e2e/submitqueue/BUILD.bazel

@@ -3,18 +3,31 @@ load("@rules_go//go:def.bzl", "go_test")
 go_test(
     name = "go_default_test",
     srcs = [
+        "git_suite_test.go",
         "harness_test.go",
         "suite_test.go",
     ],
     data = [
         "//platform/extension/counter/mysql/schema",
         "//platform/extension/messagequeue/mysql/schema",
         "//service/runway/server:docker_test_context",
+        "//service/submitqueue:docker-compose.git.yml",
         "//service/submitqueue:docker-compose.yml",
+        "//service/submitqueue/demo/provider/local:config",
         "//service/submitqueue/gateway/server:docker_test_context",
         "//service/submitqueue/orchestrator/server:docker_test_context",
         "//submitqueue/extension/storage/mysql/schema",
+        "@git",
+        "@git//:git_receive_pack",
+        "@git//:git_upload_archive",
+        "@git//:git_upload_pack",
+        "@git//:templates",
     ],
+    # The git suite drives the bare repository with the same pinned git the
+    # merger uses, rather than whatever the host has installed.
+    env = {
+        "SUBMITQUEUE_TEST_GIT": "$(location @git//:git)",
+    },
     tags = [
         "e2e",
         "integration",