feat: widen Pusher interface with QueueTarget and PushItem

Consolidate QueueTarget into the shared entity/ package and update
all pushqueue imports accordingly. Widen Pusher.Push to accept
entity.QueueTarget and []PushItem (Change + Strategy). Add
queueconfig.Store dependency to the merge controller for resolving
queue names to VCS targets.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kevinlnew

entity/BUILD.bazel

@@ -2,7 +2,10 @@ load("@rules_go//go:def.bzl", "go_library")
 
 go_library(
     name = "entity",
-    srcs = ["entity.go"],
+    srcs = [
+        "entity.go",
+        "queue_target.go",
+    ],
     importpath = "github.com/uber/submitqueue/entity",
     visibility = ["//visibility:public"],
 )

entity/queue_target.go

@@ -0,0 +1,25 @@
+// 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 entity
+
+// QueueTarget identifies a landing destination in a version control system.
+type QueueTarget struct {
+	// Name is an optional logical identifier for correlation and config lookup.
+	Name string
+	// Address is the VCS repository address (remote URL, depot path).
+	Address string
+	// Target is the landing ref (branch name, stream path).
+	Target string
+}

example/pushqueue/gateway/server/BUILD.bazel

@@ -6,6 +6,7 @@ go_library(
     importpath = "github.com/uber/submitqueue/example/pushqueue/gateway/server",
     visibility = ["//visibility:private"],
     deps = [
+        "//entity",
         "//pushqueue/entity",
         "//pushqueue/extension/landqueue",
         "//pushqueue/extension/vcs",

example/pushqueue/gateway/server/main.go

@@ -26,7 +26,8 @@ import (
 	"time"
 
 	"github.com/uber-go/tally/v4"
-	"github.com/uber/submitqueue/pushqueue/entity"
+	"github.com/uber/submitqueue/entity"
+	pqentity "github.com/uber/submitqueue/pushqueue/entity"
 	"github.com/uber/submitqueue/pushqueue/extension/landqueue"
 	"github.com/uber/submitqueue/pushqueue/extension/vcs"
 	"github.com/uber/submitqueue/pushqueue/gateway/controller"
@@ -162,23 +163,23 @@ func run() error {
 // noopVCS is a placeholder VCS that errors on every operation.
 type noopVCS struct{}
 
-func (noopVCS) CheckMergeability(_ context.Context, _ entity.QueueTarget, items []entity.LandItem) ([]vcs.MergeabilityResult, error) {
+func (noopVCS) CheckMergeability(_ context.Context, _ entity.QueueTarget, items []pqentity.LandItem) ([]vcs.MergeabilityResult, error) {
 	results := make([]vcs.MergeabilityResult, len(items))
 	for i := range results {
 		results[i] = vcs.MergeabilityResult{Mergeable: false, Reason: "noop VCS: not configured"}
 	}
 	return results, nil
 }
 
-func (noopVCS) Prepare(_ context.Context, _ entity.QueueTarget, _ []entity.LandItem) error {
+func (noopVCS) Prepare(_ context.Context, _ entity.QueueTarget, _ []pqentity.LandItem) error {
 	return fmt.Errorf("noop VCS: not configured")
 }
 
-func (noopVCS) Push(_ context.Context, _ entity.QueueTarget, _ []entity.LandItem) (vcs.PushResult, error) {
+func (noopVCS) Push(_ context.Context, _ entity.QueueTarget, _ []pqentity.LandItem) (vcs.PushResult, error) {
 	return vcs.PushResult{}, fmt.Errorf("noop VCS: not configured")
 }
 
-func (noopVCS) Finalize(_ context.Context, _ entity.QueueTarget, _ []entity.LandItem) error {
+func (noopVCS) Finalize(_ context.Context, _ entity.QueueTarget, _ []pqentity.LandItem) error {
 	return fmt.Errorf("noop VCS: not configured")
 }
 
@@ -187,7 +188,7 @@ type noopQueue struct{}
 
 var _ landqueue.Queue = noopQueue{}
 
-func (noopQueue) Enqueue(_ context.Context, _ entity.QueueTarget, _ []entity.LandItem) error {
+func (noopQueue) Enqueue(_ context.Context, _ entity.QueueTarget, _ []pqentity.LandItem) error {
 	return nil
 }
 

example/submitqueue/orchestrator/server/BUILD.bazel

@@ -14,6 +14,7 @@ go_library(
         "//core/errs/generic",
         "//core/errs/mysql",
         "//core/httpclient",
+        "//entity",
         "//extension/queue",
         "//extension/queue/mysql",
         "//submitqueue/core/consumer",
@@ -31,6 +32,8 @@ go_library(
         "//submitqueue/extension/mergechecker/github",
         "//submitqueue/extension/pusher",
         "//submitqueue/extension/pusher/git",
+        "//submitqueue/extension/queueconfig",
+        "//submitqueue/extension/queueconfig/yaml",
         "//submitqueue/extension/scorer/heuristic",
         "//submitqueue/extension/storage",
         "//submitqueue/extension/storage/mysql",

example/submitqueue/orchestrator/server/main.go

@@ -33,6 +33,7 @@ import (
 	genericerrs "github.com/uber/submitqueue/core/errs/generic"
 	mysqlerrs "github.com/uber/submitqueue/core/errs/mysql"
 	"github.com/uber/submitqueue/core/httpclient"
+	sharedentity "github.com/uber/submitqueue/entity"
 	extqueue "github.com/uber/submitqueue/extension/queue"
 	queueMySQL "github.com/uber/submitqueue/extension/queue/mysql"
 	"github.com/uber/submitqueue/submitqueue/core/consumer"
@@ -50,6 +51,8 @@ import (
 	githubchecker "github.com/uber/submitqueue/submitqueue/extension/mergechecker/github"
 	"github.com/uber/submitqueue/submitqueue/extension/pusher"
 	gitpusher "github.com/uber/submitqueue/submitqueue/extension/pusher/git"
+	"github.com/uber/submitqueue/submitqueue/extension/queueconfig"
+	yamlqueueconfig "github.com/uber/submitqueue/submitqueue/extension/queueconfig/yaml"
 	"github.com/uber/submitqueue/submitqueue/extension/scorer/heuristic"
 	"github.com/uber/submitqueue/submitqueue/extension/storage"
 	mysqlstorage "github.com/uber/submitqueue/submitqueue/extension/storage/mysql"
@@ -231,8 +234,14 @@ func run() error {
 	// (every build immediately succeeds) until a real backend is wired in.
 	br := buildnoop.New()
 
+	// Create queue config store
+	qcfg, err := newQueueConfigStore(logger)
+	if err != nil {
+		return fmt.Errorf("failed to create queue config store: %w", err)
+	}
+
 	// Register controllers
-	if err := registerControllers(c, logger.Sugar(), scope, registry, mc, cp, psh, br, cnt, store, changeStore); err != nil {
+	if err := registerControllers(c, logger.Sugar(), scope, registry, mc, cp, psh, br, cnt, store, changeStore, qcfg); err != nil {
 		return err
 	}
 
@@ -425,7 +434,7 @@ func newTopicRegistry(q extqueue.Queue, subscriberName string) (consumer.TopicRe
 //                                        │        │                       │
 //                                        └────────┴───────────────────────┘
 
-func registerControllers(c consumer.Consumer, logger *zap.SugaredLogger, scope tally.Scope, registry consumer.TopicRegistry, mc mergechecker.MergeChecker, cp changeprovider.ChangeProvider, psh pusher.Pusher, br buildrunner.BuildRunner, cnt counter.Counter, store storage.Storage, changeStore changestore.ChangeStore) error {
+func registerControllers(c consumer.Consumer, logger *zap.SugaredLogger, scope tally.Scope, registry consumer.TopicRegistry, mc mergechecker.MergeChecker, cp changeprovider.ChangeProvider, psh pusher.Pusher, br buildrunner.BuildRunner, cnt counter.Counter, store storage.Storage, changeStore changestore.ChangeStore, qcfg queueconfig.Store) error {
 	requestController := start.NewController(
 		logger,
 		scope,
@@ -551,6 +560,7 @@ func registerControllers(c consumer.Consumer, logger *zap.SugaredLogger, scope t
 		store,
 		registry,
 		psh,
+		qcfg,
 		consumer.TopicKeyMerge,
 		"orchestrator-merge",
 	)
@@ -675,6 +685,18 @@ func newPusher(logger *zap.Logger, scope tally.Scope) (pusher.Pusher, error) {
 	}), nil
 }
 
+// newQueueConfigStore loads queue configuration from a YAML file pointed to by
+// QUEUE_CONFIG_PATH. If the env var is not set, returns an empty store — the
+// merge controller will fail to resolve any queue target.
+func newQueueConfigStore(logger *zap.Logger) (queueconfig.Store, error) {
+	path := os.Getenv("QUEUE_CONFIG_PATH")
+	if path == "" {
+		logger.Warn("QUEUE_CONFIG_PATH not set; merge controller will fail to resolve queue targets")
+		return yamlqueueconfig.Store{}, nil
+	}
+	return yamlqueueconfig.NewStore(path)
+}
+
 // noopPusher is a fallback Pusher used when PUSHER_CHECKOUT_PATH is not
 // configured. It returns an error on every Push so the merge controller
 // (which treats non-ErrConflict errors as transient and nacks the message)
@@ -683,6 +705,6 @@ func newPusher(logger *zap.Logger, scope tally.Scope) (pusher.Pusher, error) {
 // that don't run the merge step.
 type noopPusher struct{}
 
-func (noopPusher) Push(_ context.Context, _ []entity.Change) (pusher.Result, error) {
+func (noopPusher) Push(_ context.Context, _ sharedentity.QueueTarget, _ []pusher.PushItem) (pusher.Result, error) {
 	return pusher.Result{}, fmt.Errorf("pusher not configured: set PUSHER_CHECKOUT_PATH to enable pushing")
 }

pushqueue/entity/land.go

@@ -14,17 +14,6 @@
 
 package entity
 
-// QueueTarget identifies a landing destination in a version control system.
-// Defined locally in pushqueue; consolidated into shared entity/ by Chunk 2.
-type QueueTarget struct {
-	// Name is an optional logical identifier for correlation and config lookup.
-	Name string
-	// Address is the VCS repository address (remote URL, depot path).
-	Address string
-	// Target is the landing ref (branch name, stream path).
-	Target string
-}
-
 // LandStrategy defines the possible landing methods for a code change.
 type LandStrategy string
 

pushqueue/extension/landqueue/BUILD.bazel

@@ -5,5 +5,8 @@ go_library(
     srcs = ["landqueue.go"],
     importpath = "github.com/uber/submitqueue/pushqueue/extension/landqueue",
     visibility = ["//visibility:public"],
-    deps = ["//pushqueue/entity"],
+    deps = [
+        "//entity",
+        "//pushqueue/entity",
+    ],
 )

pushqueue/extension/landqueue/landqueue.go

@@ -19,15 +19,16 @@ package landqueue
 import (
 	"context"
 
-	"github.com/uber/submitqueue/pushqueue/entity"
+	"github.com/uber/submitqueue/entity"
+	pqentity "github.com/uber/submitqueue/pushqueue/entity"
 )
 
 // Preparer performs pre-push preparation for a set of land items.
 // Implementations are typically backed by a VCS extension. The Queue
 // receives a Preparer at construction time and may invoke it between
 // Enqueue and Wait to pipeline preparation with queue wait time.
 type Preparer interface {
-	Prepare(ctx context.Context, target entity.QueueTarget, items []entity.LandItem) error
+	Prepare(ctx context.Context, target entity.QueueTarget, items []pqentity.LandItem) error
 }
 
 // Queue serializes access to a landing target, ensuring only one request
@@ -44,7 +45,7 @@ type Preparer interface {
 //   - Implementations decide when to call Preparer.Prepare — during the
 //     wait (pipelined) or synchronously before Wait returns (simple).
 type Queue interface {
-	Enqueue(ctx context.Context, target entity.QueueTarget, items []entity.LandItem) error
+	Enqueue(ctx context.Context, target entity.QueueTarget, items []pqentity.LandItem) error
 	Wait(ctx context.Context, target entity.QueueTarget) error
 	Dequeue(ctx context.Context, target entity.QueueTarget) error
 }

pushqueue/extension/landqueue/mock/BUILD.bazel

@@ -6,6 +6,7 @@ go_library(
     importpath = "github.com/uber/submitqueue/pushqueue/extension/landqueue/mock",
     visibility = ["//visibility:public"],
     deps = [
+        "//entity",
         "//pushqueue/entity",
         "@org_uber_go_mock//gomock",
     ],