feat(orchestrator): let a queue select the git change provider

## Summary

### Why?

The previous change added a change provider that reads a git repository. Nothing could select it: `profiles.yaml` had no `type: git`, and the wiring had no case for one. This connects the two.

### What?

`changeProvider: {type: git, git: {…}}` in `profiles.yaml`, nested under a named block like `github` and `phabricator` are, carrying what a copy of a repository needs: `remoteUrl`, `target`, `repoPath`, and optionally `tokenEnv`/`tokenUser`. `remote` defaults to `origin`, `tokenUser` to `x-access-token`.

Three values are required because none has a default that could be right: there is no public git remote to fall back on, no universal trunk name, and nowhere obvious to keep a copy. The block deliberately reads like Runway's merger block — each service says for itself where its copy fetches from, so a queue's provider and its merger can name the same remote while being configured independently.

**Two queues may share a `repoPath`, and should when they are on the same repository** — that is how they come to share one copy and one lock. Sharing a path while disagreeing about the remote or target is rejected at startup, because whichever queue was built first would silently decide what the other one reads.

**The default `Auth` lives here, not in the extension.** `tokenAuth` reads a named environment variable and writes git an `http.extraheader` fragment inside the repository, mode 0600, included from its config — never into the remote URL, which git echoes back into error messages and from there into logs and dead-letter payloads. The extension only knows it has an `Auth` and calls it; a deployment that mints short-lived tokens or reads a secrets manager replaces this one file's worth of behaviour and changes nothing else. It is applied before each fetch rather than once, which is what lets an expiring credential be refreshed.

A remote that needs no credential gets a nil `Auth` — a local path, or SSH served by the host's own configuration and agent.

**Provisioning now fetches.** It runs at wiring time, and the reason given for that was to fail the misconfigured service rather than bury the failure in a queue's retry loop. Writing the test for it showed the claim was not yet true: initializing a directory and recording a remote succeeds whether or not the remote exists, so a wrong URL would have surfaced later, per message, as a validate failure. Provisioning fetches the target branch, which is the step that actually proves the remote is reachable and the credential works — and it warms the copy, so the first request does not pay for a clone.

`newProfiles` takes a context so that provisioning can be cancelled: it reaches the network during startup, and a shutdown then should stop it rather than wait it out.

Still nothing selects it — no demo queue is switched over and the orchestrator image has no git binary yet. Those are the next two steps.

## Test Plan

- ✅ the seam test: configuration in, a provider out that reports `pkg/a/one.go` with 2 added lines from a repository the test built — which only passes if the config block, provisioning, the injected auth and the factory case all line up
- ✅ an unreachable remote fails `newProfiles`. This is the test that found the gap above; before provisioning fetched, it passed startup and would have failed per message instead
- ✅ defaults applied (`remote`, `tokenUser`) and each of the three required values rejected when missing
- ✅ two queues sharing a `repoPath` with different remotes are rejected; two that agree are allowed, since sharing a copy is the point
- ✅ `make test`, `make lint`, `make gazelle`

The config block is nested under `git:` rather than flat as the plan sketched. Flat would have matched `merge.yaml` more literally, but this file's own grammar is a named block per provider, and consistency inside the file a reader is editing seemed worth more than symmetry with a file in another service.

Author: behinddwalls

service/submitqueue/orchestrator/server/BUILD.bazel

@@ -8,6 +8,7 @@ exports_files(
 go_library(
     name = "orchestrator_lib",
     srcs = [
+        "changerepo.go",
         "config.go",
         "main.go",
         "profiles.go",
@@ -36,6 +37,7 @@ go_library(
         "//submitqueue/extension/buildrunner/githubactions:go_default_library",
         "//submitqueue/extension/changeprovider:go_default_library",
         "//submitqueue/extension/changeprovider/fake:go_default_library",
+        "//submitqueue/extension/changeprovider/git:go_default_library",
         "//submitqueue/extension/changeprovider/github:go_default_library",
         "//submitqueue/extension/changeprovider/phabricator:go_default_library",
         "//submitqueue/extension/changeprovider/routing:go_default_library",
@@ -101,8 +103,16 @@ go_test(
         "config_test.go",
         "profiles_test.go",
     ],
+    # The pinned git, for the tests that resolve a git change provider against a
+    # real repository.
+    data = ["@git"],
     embed = [":orchestrator_lib"],  # keep
+    env = {
+        "SUBMITQUEUE_TEST_GIT": "$(location @git//:git)",
+    },
     deps = [
+        "//platform/base/change:go_default_library",
+        "//platform/gitexec/gitexectest:go_default_library",
         "//submitqueue/entity:go_default_library",
         "//submitqueue/extension/buildrunner:go_default_library",
         "//submitqueue/extension/changeprovider:go_default_library",

service/submitqueue/orchestrator/server/changerepo.go

@@ -0,0 +1,110 @@
+// 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 main
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	gitprovider "github.com/uber/submitqueue/submitqueue/extension/changeprovider/git"
+)
+
+// credentialFile holds the git configuration fragment carrying a token. It is
+// written inside the repository and included from its config, so the token
+// never appears in a remote URL — which git echoes back into error messages,
+// and from there into logs and dead-letter payloads.
+const credentialFile = "submitqueue-changeprovider-credentials.config"
+
+// tokenAuth is the default gitprovider.Auth: a credential read from an
+// environment variable and presented to git as an HTTP header.
+//
+// It is deliberately here rather than in the extension. The extension takes an
+// Auth and calls it; what a credential is and where it comes from is a
+// deployment's business, so a deployment that mints short-lived tokens or
+// reads a secrets manager supplies its own implementation instead of this one
+// and changes nothing else.
+type tokenAuth struct {
+	tokenEnv  string
+	tokenUser string
+}
+
+// Apply writes the credential fragment, or removes it when the remote needs
+// none, so a repository that stops using a token stops carrying one.
+//
+// Called before every fetch rather than once, which is what lets a short-lived
+// credential be refreshed — reading the variable again each time is the whole
+// mechanism for that.
+func (a tokenAuth) Apply(ctx context.Context, repoPath, remoteURL string) error {
+	path := filepath.Join(repoPath, credentialFile)
+
+	if !isHTTPRemote(remoteURL) {
+		if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+			return fmt.Errorf("could not remove stale credential %q: %w", path, err)
+		}
+		return nil
+	}
+
+	token, ok := os.LookupEnv(a.tokenEnv)
+	if !ok || token == "" {
+		return fmt.Errorf("environment variable %q named by tokenEnv is not set", a.tokenEnv)
+	}
+
+	basic := base64.StdEncoding.EncodeToString([]byte(a.tokenUser + ":" + token))
+	fragment := fmt.Sprintf("[http %q]\n\textraheader = Authorization: Basic %s\n", remoteURL, basic)
+	if err := os.WriteFile(path, []byte(fragment), 0o600); err != nil {
+		return fmt.Errorf("could not write credential %q: %w", path, err)
+	}
+
+	// include.path resolves relative to the config file holding it, so the bare
+	// filename lands beside it. A bare repository's config is at its root.
+	return gitprovider.SetConfig(ctx, repoPath, "include.path", credentialFile)
+}
+
+func isHTTPRemote(remoteURL string) bool {
+	return strings.HasPrefix(remoteURL, "http://") || strings.HasPrefix(remoteURL, "https://")
+}
+
+// newChangeRepo builds the local copy a git change provider reads through, and
+// provisions it.
+//
+// Provisioning happens here, at wiring time, rather than on first use: a change
+// provider is resolved once per message on the validate path, so a clone
+// started there would sit inside a retry loop and report an unreachable remote
+// as a queue processing failure instead of a service that is misconfigured.
+func newChangeRepo(ctx context.Context, cfg gitProviderConfig) (*gitprovider.Repo, error) {
+	var auth gitprovider.Auth
+	if cfg.TokenEnv != "" {
+		auth = tokenAuth{tokenEnv: cfg.TokenEnv, tokenUser: cfg.TokenUser}
+	}
+
+	repo, err := gitprovider.NewRepo(gitprovider.RepoConfig{
+		Path:      cfg.RepoPath,
+		RemoteURL: cfg.RemoteURL,
+		Remote:    cfg.Remote,
+		Target:    cfg.Target,
+		Auth:      auth,
+	})
+	if err != nil {
+		return nil, err
+	}
+	if err := repo.Provision(ctx); err != nil {
+		return nil, fmt.Errorf("could not provision change repository %q: %w", cfg.RepoPath, err)
+	}
+	return repo, nil
+}

service/submitqueue/orchestrator/server/config.go

@@ -25,6 +25,7 @@ import (
 // Change provider types selectable from configuration.
 const (
 	changeProviderTypeFake        = "fake"
+	changeProviderTypeGit         = "git"
 	changeProviderTypeGitHub      = "github"
 	changeProviderTypePhabricator = "phabricator"
 	changeProviderTypeRouting     = "routing"
@@ -74,6 +75,10 @@ const defaultBuildBudget = 4
 
 // Defaults for the provider integrations, matching each vendor's convention.
 const (
+	// defaultGitRemote and defaultGitTokenUser match git's own convention and
+	// the username a forge expects a token to be presented under.
+	defaultGitRemote      = "origin"
+	defaultGitTokenUser   = "x-access-token"
 	defaultGitHubTokenEnv = "GITHUB_TOKEN"
 	defaultGitHubBaseURL  = "https://api.github.com"
 	defaultPhabTokenEnv   = "PHAB_API_TOKEN"
@@ -121,10 +126,37 @@ type queueProfileConfig struct {
 // dispatches between them on the change URI's scheme.
 type changeProviderConfig struct {
 	Type        string                `yaml:"type"`
+	Git         *gitProviderConfig    `yaml:"git"`
 	GitHub      *githubProviderConfig `yaml:"github"`
 	Phabricator *phabProviderConfig   `yaml:"phabricator"`
 }
 
+// gitProviderConfig configures the git change provider, which derives change
+// metadata from a repository rather than asking a service for it.
+//
+// It mirrors Runway's merger block deliberately: each service keeps its own
+// copy of a queue's repository and says for itself where that copy fetches
+// from, so the two are configured independently even when they name the same
+// remote.
+type gitProviderConfig struct {
+	// RemoteURL is where this service's copy fetches from. A URL or a local
+	// path; a bind-mounted bare repository and a remote host differ only here.
+	RemoteURL string `yaml:"remoteUrl"`
+	// Remote is the name the copy records RemoteURL under.
+	Remote string `yaml:"remote"`
+	// Target is the branch a change's first commit is measured against.
+	Target string `yaml:"target"`
+	// RepoPath is where this service keeps its copy. It belongs to this service
+	// alone — another service reading the same remote keeps its own.
+	RepoPath string `yaml:"repoPath"`
+	// TokenEnv names the environment variable holding a credential for an
+	// http(s) remote. Empty means the remote needs none, which is the case for a
+	// local path and for SSH served by the host's own configuration.
+	TokenEnv string `yaml:"tokenEnv"`
+	// TokenUser is the username the credential is presented under.
+	TokenUser string `yaml:"tokenUser"`
+}
+
 // githubProviderConfig configures the GitHub change provider.
 type githubProviderConfig struct {
 	// TokenEnv names the environment variable holding the API token.
@@ -269,6 +301,41 @@ func (c *profilesConfig) normalizeAndValidate() error {
 			}
 		}
 	}
+	return c.validateGitRepoPaths()
+}
+
+// validateGitRepoPaths rejects two queues keeping their copies in one directory
+// while disagreeing about what that copy is.
+//
+// A shared path is legitimate — two queues on the same repository should share
+// one copy, and sharing it is what makes them share its lock. Sharing it with a
+// different remote or target is not: whichever queue was built first silently
+// decides what the other one reads.
+func (c profilesConfig) validateGitRepoPaths() error {
+	type owner struct {
+		queue string
+		cfg   gitProviderConfig
+	}
+	byPath := make(map[string]owner)
+
+	for _, q := range c.Queues {
+		resolved := c.resolve(q)
+		if resolved.ChangeProvider.Type != changeProviderTypeGit || resolved.ChangeProvider.Git == nil {
+			continue
+		}
+		git := *resolved.ChangeProvider.Git
+		previous, seen := byPath[git.RepoPath]
+		if !seen {
+			byPath[git.RepoPath] = owner{queue: q.Name, cfg: git}
+			continue
+		}
+		if previous.cfg.RemoteURL != git.RemoteURL || previous.cfg.Target != git.Target {
+			return fmt.Errorf(
+				"queues %q and %q share repoPath %q but read different repositories (%s@%s vs %s@%s); give each its own path",
+				previous.queue, q.Name, git.RepoPath,
+				previous.cfg.RemoteURL, previous.cfg.Target, git.RemoteURL, git.Target)
+		}
+	}
 	return nil
 }
 
@@ -317,6 +384,8 @@ func (c *changeProviderConfig) normalizeAndValidate(where string) error {
 	switch c.Type {
 	case changeProviderTypeFake:
 		return nil
+	case changeProviderTypeGit:
+		return c.ensureGit(where)
 	case changeProviderTypeGitHub:
 		c.ensureGitHub()
 	case changeProviderTypePhabricator:
@@ -343,6 +412,31 @@ func (c *changeProviderConfig) normalizeAndValidate(where string) error {
 	return nil
 }
 
+// ensureGit defaults and checks the git block. Three values have no sensible
+// default and are required: there is no public git remote to fall back on, no
+// universal trunk name, and nowhere obvious to keep a copy.
+func (c *changeProviderConfig) ensureGit(where string) error {
+	if c.Git == nil {
+		c.Git = &gitProviderConfig{}
+	}
+	if c.Git.Remote == "" {
+		c.Git.Remote = defaultGitRemote
+	}
+	if c.Git.TokenUser == "" {
+		c.Git.TokenUser = defaultGitTokenUser
+	}
+	if c.Git.RemoteURL == "" {
+		return fmt.Errorf("%s: git change provider requires remoteUrl", where)
+	}
+	if c.Git.Target == "" {
+		return fmt.Errorf("%s: git change provider requires target", where)
+	}
+	if c.Git.RepoPath == "" {
+		return fmt.Errorf("%s: git change provider requires repoPath", where)
+	}
+	return nil
+}
+
 func (c *changeProviderConfig) ensureGitHub() {
 	if c.GitHub == nil {
 		c.GitHub = &githubProviderConfig{}