feat(runway): git-backed merger with REBASE

## Summary

### Why?

Runway's `merger` extension has had exactly one implementation — `noop`, which always succeeds. Nothing actually merges anything. This lands the first real backend: a `Merger` driven by the `git` CLI against a local checkout.

It ships REBASE only. The strategy-specific apply paths are small and independent, but the machinery underneath them — the pinned git runtime, object resolution, the reset/apply/push cycle, contention retry, dry-run discard, conflict classification — is shared and is the bulk of what needs review. Landing it with one strategy keeps that review separable from the per-strategy mechanics that follow in this stack.

### What?

Adds `runway/extension/merger/git`.

**A change is a range of commits, not a commit.** A change URI pins a pull request to a single head SHA, but a pull request is routinely several commits. Applying the head alone applies only that commit's diff against its own parent: it conflicts against context its predecessors would have established, or — when the commits touch different files — succeeds while silently dropping everything before the head. So the unit replayed is the range from the change's merge base with the target up to its head. A change already contained in the target has an empty range and is a no-op, which is what keeps redelivery idempotent.

A range runs through git's sequencer, which changes the control flow versus a single pick: the operation stops on a commit it declines and `--skip` advances to the next rather than ending. Two kinds of commit stop it harmlessly — one already present on the target, and one that was empty to begin with — and both are skipped. Anything else is a real conflict, and the in-progress pick is aborted so the checkout stays usable. The commits an apply produced are read back off the checkout rather than tracked per-invocation, which stays correct when the sequencer drops some.

**Referenced commits are guaranteed present before anything is applied.** The default fetch refspec is `+refs/heads/*`, which does not cover a provider's change refs: a pull request head never also pushed as a branch — the normal case for a fork — is simply absent, and the apply then fails with git's "bad object", indistinguishable from a conflict. Every commit the request names is now fetched and verified up front, for all steps, so an unusable request fails without having mutated the checkout. Commits are requested by SHA (relying on the server serving a want for a reachable-but-unadvertised object, which github.com allows), falling back to the provider's canonical ref, with deployment-supplied refspecs as a last resort. Neither fetch is shallow — the range needs ancestry.

A commit a *reachable* remote cannot supply is terminal; a remote that will not answer stays retryable. The first is a property of the request, the second a property of the moment.

**One seam for change providers.** Every URI is reduced to the only three things the merger needs — the commit to apply, the ref the provider publishes it under, and a label for synthesized messages. `github://` and `git://` are supported; an unrecognized scheme is terminal. Adding a provider is one case in that mapping rather than a change to any apply path.

**Optional staleness check.** Fetching by SHA guarantees the merger applies exactly the commit the URI names, not that it is still the change's head — a force-push leaves the superseded commit fetchable on most hosts. When enabled, each change's canonical ref is read (one ref advertisement, no object transfer) and a mismatch is terminal.

**Atomicity, contention, dry run.** Nothing reaches the remote until the final push. If the push is rejected because the remote tip moved, the whole reset/apply/push cycle retries up to a bounded number of attempts. `CheckMergeability` runs the identical apply path but never pushes, then resets and reports empty outputs, committing intermediate steps locally so a multi-step check sees the same conflict surface a real merge would.

**Runtime hygiene.** Every invocation uses an explicitly pinned git runtime and a scrubbed environment — no system or global config, no interactive prompts. That leaves no ambient identity, so the committer is injected per-invocation.

`isConcreteStrategy` currently admits only REBASE; SQUASH_REBASE, MERGE and PROMOTE are rejected as invalid requests until their apply paths land later in this stack. The merger is not wired into the server yet, so this adds no production behavior.

## Test Plan

✅ `bazel test //runway/...` — 6/6 targets pass, including the new `//runway/extension/merger/git` suite (40s)

The suite drives a real git binary against throwaway repositories. Beyond the single-commit cases (stacked URIs, already-landed changes, multi-step requests, conflicts, checkout recovery, contention retry, give-up after max attempts, DEFAULT resolution, dry runs), it covers what this change is actually about: a multi-commit change expressed as **one** URI for both disjoint and overlapping edits, a partially-landed change, an empty commit inside a range, a conflict inside a range leaving no sequencer state behind, stacked multi-commit changes not duplicating each other's commits, a head reachable only via its pull-request ref, an unavailable commit classified as invalid rather than conflicting, the staleness check on and off, and provider resolution across schemes.

The regression tests were verified to fail against head-only picking: reverting just that line fails 5 of them, and they pass with the range applied.

Author: behinddwalls

runway/extension/merger/git/BUILD.bazel

@@ -0,0 +1,52 @@
+load("@rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "go_default_library",
+    srcs = [
+        "changeref.go",
+        "git_merger.go",
+        "objects.go",
+    ],
+    importpath = "github.com/uber/submitqueue/runway/extension/merger/git",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//api/base/mergestrategy/protopb:go_default_library",
+        "//api/runway/messagequeue:go_default_library",
+        "//api/runway/messagequeue/protopb:go_default_library",
+        "//platform/base/change/git:go_default_library",
+        "//platform/base/change/github:go_default_library",
+        "//platform/metrics:go_default_library",
+        "//runway/extension/merger:go_default_library",
+        "@com_github_uber_go_tally//:go_default_library",
+        "@org_uber_go_zap//:go_default_library",
+    ],
+)
+
+go_test(
+    name = "go_default_test",
+    srcs = ["git_merger_test.go"],
+    data = [
+        "@git",
+        "@git//:git_receive_pack",
+        "@git//:git_upload_archive",
+        "@git//:git_upload_pack",
+        "@git//:templates",
+        "@git//:templates/description",
+    ],
+    embed = [":go_default_library"],
+    env = {
+        "SUBMITQUEUE_TEST_GIT": "$(location @git//:git)",
+        "SUBMITQUEUE_TEST_GIT_TEMPLATE_DESCRIPTION": "$(location @git//:templates/description)",
+    },
+    deps = [
+        "//api/base/change/protopb:go_default_library",
+        "//api/base/mergestrategy/protopb:go_default_library",
+        "//api/runway/messagequeue:go_default_library",
+        "//api/runway/messagequeue/protopb:go_default_library",
+        "//runway/extension/merger:go_default_library",
+        "@com_github_stretchr_testify//assert:go_default_library",
+        "@com_github_stretchr_testify//require:go_default_library",
+        "@com_github_uber_go_tally//:go_default_library",
+        "@org_uber_go_zap//zaptest:go_default_library",
+    ],
+)

runway/extension/merger/git/README.md

@@ -0,0 +1,59 @@
+# git merger
+
+A `merger.Merger` backed by the `git` CLI operating on a local checkout. It applies a merge request's ordered steps onto a target branch, honoring each step's strategy, and — for a committing merge — pushes the result. It is constructed by the wiring layer (see [`service/runway`](../../../../service/runway)) with the checkout path, remote, target branch, pinned git runtime, committer identity, and the default strategy; the request itself carries only a queue name and the changes, so the merger reads change URIs straight from the payload (no store, no resolver).
+
+## Model
+
+A request is an ordered list of steps; each step names a change (a set of provider URIs, each ending in a full head commit SHA) and a strategy. Steps are applied in order on top of the target tip — earlier steps are the in-flight base, the last step is the candidate. Each step yields one `StepResult`; the revisions a step produces on the target are its outputs, in application order.
+
+A URI pins a change to one head commit, but a change is routinely several commits. The full set is recovered locally rather than from the wire: the commits to replay are the range from the change's merge base with the target up to its head. Applying the head commit alone would apply only that commit's diff against its own parent — conflicting against context its predecessors would have established, or silently dropping them when they touch different files.
+
+## Change providers
+
+Every URI is reduced to three things: the commit to apply, the ref the provider publishes that commit under, and a short label for synthesized commit messages. Adding a provider is one case in that mapping, not a change to any apply path.
+
+| Scheme | Commit | Canonical ref | Label |
+|---|---|---|---|
+| `github://` | head commit SHA | `refs/pull/{n}/head` | `org/repo#n` |
+| `git://` | the URI's commit SHA | the URI's own ref | `repo@ref` |
+
+An unrecognized scheme is a terminal invalid request.
+
+## Object availability
+
+The default fetch refspec is `+refs/heads/*`, which does not cover a provider's change refs — a pull request head never also pushed as a branch, the normal case for a fork, is simply absent locally. Every referenced commit is therefore fetched and verified before any step is applied, so a request naming an unreachable commit fails without having touched the checkout.
+
+Commits are requested by SHA, which relies on the server serving a want for an object that is reachable but not advertised (`uploadpack.allowReachableSHA1InWant`, which github.com enables); the provider's canonical ref is the fallback. Neither fetch is shallow — the apply paths need ancestry, not just the commit. A remote that supports neither can supply explicit refspecs via configuration.
+
+A commit that cannot be fetched from a reachable remote is a terminal invalid request, not a conflict. If the remote itself is unreachable the error stays retryable.
+
+## Staleness
+
+Fetching by SHA guarantees the merger applies exactly the commit a URI names — not that the commit is still the change's head. A force-push leaves the superseded commit fetchable for some time on most hosts, so a successful fetch says nothing about freshness. When enabled, each change's canonical ref is read (one ref advertisement, no object transfer) and a mismatch is terminal. A ref that no longer exists yields no verdict.
+
+## Strategies
+
+| Strategy | What it does | Outputs |
+|---|---|---|
+| `REBASE` | Cherry-picks every commit each change introduces onto the tip, in order. A commit already present on the target is skipped (no output), as is one that was empty to begin with. | one revision per newly-created commit |
+| `DEFAULT` | Resolved to the instance's configured default strategy before any step runs. | per the resolved strategy |
+
+`REBASE` is the only strategy implemented so far. `SQUASH_REBASE`, `MERGE`, and `PROMOTE` are defined by the wire contract but not yet applied here — a step naming one is rejected as an invalid request.
+
+## Committing, dry-run, atomicity, contention
+
+`Merge` commits and reports outputs; `CheckMergeability` runs the identical apply but never pushes, then resets the checkout to discard the local commits and reports empty outputs. A multi-step check commits its intermediate steps locally so it sees the same conflict surface a real merge would.
+
+For a committing merge nothing reaches the remote until the final push. A step that fails to apply aborts its in-progress git operation and returns without pushing. If the push fails because the remote tip moved between reset and push, the whole reset/apply/push cycle is retried up to a bounded number of attempts; detection re-fetches the tip and compares it to the SHA the cycle was based on.
+
+## Failure classification
+
+A merge conflict surfaces as `merger.ErrConflict`. An unusable request surfaces as `merger.ErrInvalidRequest`: an unsupported strategy or URI scheme, a malformed URI, a commit a reachable remote cannot supply, a change whose head has moved on, or a change sharing no history with the target under a picking strategy. Both are terminal — the controller publishes a `FAILED` result rather than retrying. Everything else (network/auth/push faults, and an unreachable remote) is returned as a plain error for the consumer to retry.
+
+The distinction between the last two matters operationally: a commit that is missing while the remote answers is a property of the request, whereas a remote that will not answer is a property of the moment.
+
+## Runtime and identity
+
+Every git invocation uses the pinned runtime (explicit executable, exec-path, and template dir) and a scrubbed environment: no ambient configuration, no system or global git config, no interactive prompts. Because that leaves no ambient identity, the committer name and email are injected per-invocation, which the commit-creating `REBASE` strategy requires.
+
+See [Object availability](#object-availability) for how referenced commits are obtained.

runway/extension/merger/git/changeref.go

@@ -0,0 +1,96 @@
+// Copyright (c) 2025 Uber Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package git
+
+import (
+	"fmt"
+	"strings"
+
+	entitygit "github.com/uber/submitqueue/platform/base/change/git"
+	entitygithub "github.com/uber/submitqueue/platform/base/change/github"
+	"github.com/uber/submitqueue/runway/extension/merger"
+)
+
+// changeRef is everything the merger needs from a change URI, reduced to a
+// form that does not depend on which provider minted it. Adding a provider
+// means adding one case to resolveChange, not touching the apply paths.
+type changeRef struct {
+	// SHA is the full commit hash the URI pins the change to. This is the
+	// commit that gets fetched and applied.
+	SHA string
+	// Ref is the fully-qualified ref the provider publishes this change's head
+	// under (e.g. "refs/pull/12/head"). Used as a fetch fallback and as the
+	// staleness comparison point. Empty when the scheme has no such ref, in
+	// which case both are skipped.
+	Ref string
+	// Label is a short human-readable identifier for the change, used in
+	// commit messages the merger synthesizes.
+	Label string
+}
+
+// resolveChange maps a change URI onto the merger's provider-neutral view of
+// it. An unrecognized scheme is terminal: no retry produces a parser for it.
+func resolveChange(uri string) (changeRef, error) {
+	scheme, _, ok := strings.Cut(uri, "://")
+	if !ok {
+		return changeRef{}, fmt.Errorf("%w: change URI %q has no scheme", merger.ErrInvalidRequest, uri)
+	}
+
+	switch scheme {
+	case "github":
+		cid, err := entitygithub.ParseChangeID(uri)
+		if err != nil {
+			return changeRef{}, fmt.Errorf("%w: invalid change URI %q: %v", merger.ErrInvalidRequest, uri, err)
+		}
+		return changeRef{
+			SHA: cid.HeadCommitSHA,
+			// GitHub publishes every PR's head under refs/pull/<n>/head in the
+			// base repository, including PRs opened from a fork.
+			Ref:   fmt.Sprintf("refs/pull/%d/head", cid.PRNumber),
+			Label: fmt.Sprintf("%s#%d", cid.OwnerRepo(), cid.PRNumber),
+		}, nil
+
+	case "git":
+		cid, err := entitygit.ParseChangeID(uri)
+		if err != nil {
+			return changeRef{}, fmt.Errorf("%w: invalid change URI %q: %v", merger.ErrInvalidRequest, uri, err)
+		}
+		// A git:// URI already names its own fully-qualified ref, so the
+		// staleness check reads exactly the ref the caller pinned.
+		return changeRef{
+			SHA:   cid.CommitSHA,
+			Ref:   cid.Ref,
+			Label: fmt.Sprintf("%s@%s", cid.Repo, cid.Ref),
+		}, nil
+
+	default:
+		return changeRef{}, fmt.Errorf("%w: unsupported change URI scheme %q in %q", merger.ErrInvalidRequest, scheme, uri)
+	}
+}
+
+// resolveStepChanges resolves every URI of every step, in application order.
+func resolveStepChanges(steps []resolvedStep) ([]changeRef, error) {
+	var refs []changeRef
+	for _, rs := range steps {
+		for _, uri := range rs.step.GetChange().GetUris() {
+			ref, err := resolveChange(uri)
+			if err != nil {
+				return nil, err
+			}
+			refs = append(refs, ref)
+		}
+	}
+	return refs, nil
+}