feat(mergechecker): add GitHub MergeChecker implementation with multi-host routing

Implements a GitHub-specific MergeChecker that uses the GraphQL API to
validate PR mergeability and stack ordering. Adds a MultiChecker router
that dispatches by Change.Source for multi-host support.

- entity/github: ChangeID parser for {scheme}://{org}/{repo}/pull/{pr}/{sha}
- extension/mergechecker/github: GraphQL-based checker with stack validation
- extension/mergechecker: MultiChecker for source-based routing
- extension/mergechecker/mock: gomock mock for testing
- orchestrator/controller/request: wire merge check into pipeline
- example/server: configure GitHub checker via env vars

Author: behinddwalls

CLAUDE.md

@@ -186,6 +186,7 @@ make clean              # Clean Bazel cache
 
 ### Testing
 
+- **Table-driven tests** — prefer table-driven tests with `t.Run` subtests over individual test functions.
 - **Avoid asserting on error messages** — assert on error type or generic error.
 - **No `time.Sleep` for synchronization** — use channels, callbacks, condition variables.
 - **Use testify** — `assert`/`require` instead of `t.Fatal()`.

entity/github/BUILD.bazel

@@ -0,0 +1,18 @@
+load("@rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "github",
+    srcs = ["change_id.go"],
+    importpath = "github.com/uber/submitqueue/entity/github",
+    visibility = ["//visibility:public"],
+)
+
+go_test(
+    name = "github_test",
+    srcs = ["change_id_test.go"],
+    embed = [":github"],
+    deps = [
+        "@com_github_stretchr_testify//assert",
+        "@com_github_stretchr_testify//require",
+    ],
+)

entity/github/change_id.go

@@ -0,0 +1,88 @@
+package github
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// ChangeID represents a parsed GitHub-family change identifier.
+// Covers GitHub.com, GitHub Enterprise (GHE), and GitHub Enterprise Server (GHES)
+// since they share the same pull request model.
+// Format: {scheme}://{org}/{repo}/pull/{pr_number}/{head_commit_sha}
+type ChangeID struct {
+	// Scheme captures the source variant (e.g., "github", "ghe", "ghes").
+	Scheme string
+	// Org is the organization or owner of the repository.
+	Org string
+	// Repo is the repository name.
+	Repo string
+	// PRNumber is the pull request number.
+	PRNumber int
+	// HeadCommitSHA is the head commit SHA at the time of request creation.
+	HeadCommitSHA string
+}
+
+// ParseChangeID parses a raw change ID string into a ChangeID.
+// Expected format: {scheme}://{org}/{repo}/pull/{pr_number}/{head_commit_sha}
+func ParseChangeID(raw string) (ChangeID, error) {
+	// Split on "://" to get scheme and path
+	parts := strings.SplitN(raw, "://", 2)
+	if len(parts) != 2 {
+		return ChangeID{}, fmt.Errorf("invalid change ID format: missing '://' separator in %q", raw)
+	}
+
+	scheme := parts[0]
+	if scheme == "" {
+		return ChangeID{}, fmt.Errorf("invalid change ID format: empty scheme in %q", raw)
+	}
+
+	// Split the path into segments: org/repo/pull/pr_number/sha
+	segments := strings.Split(parts[1], "/")
+	if len(segments) != 5 {
+		return ChangeID{}, fmt.Errorf("invalid change ID format: expected 5 path segments, got %d in %q", len(segments), raw)
+	}
+
+	org := segments[0]
+	repo := segments[1]
+	keyword := segments[2]
+	prStr := segments[3]
+	sha := segments[4]
+
+	if org == "" {
+		return ChangeID{}, fmt.Errorf("invalid change ID format: empty org in %q", raw)
+	}
+	if repo == "" {
+		return ChangeID{}, fmt.Errorf("invalid change ID format: empty repo in %q", raw)
+	}
+	if keyword != "pull" {
+		return ChangeID{}, fmt.Errorf("invalid change ID format: expected 'pull' keyword, got %q in %q", keyword, raw)
+	}
+
+	prNumber, err := strconv.Atoi(prStr)
+	if err != nil {
+		return ChangeID{}, fmt.Errorf("invalid change ID format: PR number %q is not a valid integer in %q", prStr, raw)
+	}
+
+	if sha == "" {
+		return ChangeID{}, fmt.Errorf("invalid change ID format: empty head commit SHA in %q", raw)
+	}
+
+	return ChangeID{
+		Scheme:        scheme,
+		Org:           org,
+		Repo:          repo,
+		PRNumber:      prNumber,
+		HeadCommitSHA: sha,
+	}, nil
+}
+
+// String returns the canonical string representation for round-trip serialization.
+func (c ChangeID) String() string {
+	return fmt.Sprintf("%s://%s/%s/pull/%d/%s", c.Scheme, c.Org, c.Repo, c.PRNumber, c.HeadCommitSHA)
+}
+
+// OwnerRepo returns the "{org}/{repo}" string.
+func (c ChangeID) OwnerRepo() string {
+	return fmt.Sprintf("%s/%s", c.Org, c.Repo)
+}

entity/github/change_id_test.go

@@ -0,0 +1,188 @@
+package github
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestParseChangeID(t *testing.T) {
+	tests := []struct {
+		name    string
+		raw     string
+		want    ChangeID
+		wantErr bool
+	}{
+		{
+			name: "valid github scheme",
+			raw:  "github://uber/submitqueue/pull/123/abc123def",
+			want: ChangeID{
+				Scheme:        "github",
+				Org:           "uber",
+				Repo:          "submitqueue",
+				PRNumber:      123,
+				HeadCommitSHA: "abc123def",
+			},
+		},
+		{
+			name: "valid ghe scheme",
+			raw:  "ghe://uber/monorepo/pull/456/deadbeef",
+			want: ChangeID{
+				Scheme:        "ghe",
+				Org:           "uber",
+				Repo:          "monorepo",
+				PRNumber:      456,
+				HeadCommitSHA: "deadbeef",
+			},
+		},
+		{
+			name: "valid ghes scheme",
+			raw:  "ghes://org/repo/pull/1/sha1",
+			want: ChangeID{
+				Scheme:        "ghes",
+				Org:           "org",
+				Repo:          "repo",
+				PRNumber:      1,
+				HeadCommitSHA: "sha1",
+			},
+		},
+		{
+			name:    "missing separator",
+			raw:     "github/uber/submitqueue/pull/123/abc123",
+			wantErr: true,
+		},
+		{
+			name:    "empty scheme",
+			raw:     "://uber/submitqueue/pull/123/abc123",
+			wantErr: true,
+		},
+		{
+			name:    "wrong number of path segments",
+			raw:     "github://uber/submitqueue/pull/123",
+			wantErr: true,
+		},
+		{
+			name:    "too many path segments",
+			raw:     "github://uber/submitqueue/pull/123/abc/extra",
+			wantErr: true,
+		},
+		{
+			name:    "empty org",
+			raw:     "github:///submitqueue/pull/123/abc123",
+			wantErr: true,
+		},
+		{
+			name:    "empty repo",
+			raw:     "github://uber//pull/123/abc123",
+			wantErr: true,
+		},
+		{
+			name:    "missing pull keyword",
+			raw:     "github://uber/submitqueue/pr/123/abc123",
+			wantErr: true,
+		},
+		{
+			name:    "non-numeric PR number",
+			raw:     "github://uber/submitqueue/pull/abc/abc123",
+			wantErr: true,
+		},
+		{
+			name:    "empty SHA",
+			raw:     "github://uber/submitqueue/pull/123/",
+			wantErr: true,
+		},
+		{
+			name:    "empty string",
+			raw:     "",
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := ParseChangeID(tt.raw)
+			if tt.wantErr {
+				require.Error(t, err)
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestChangeID_String(t *testing.T) {
+	tests := []struct {
+		name string
+		id   ChangeID
+		want string
+	}{
+		{
+			name: "github round-trip",
+			id: ChangeID{
+				Scheme:        "github",
+				Org:           "uber",
+				Repo:          "submitqueue",
+				PRNumber:      123,
+				HeadCommitSHA: "abc123",
+			},
+			want: "github://uber/submitqueue/pull/123/abc123",
+		},
+		{
+			name: "ghe round-trip",
+			id: ChangeID{
+				Scheme:        "ghe",
+				Org:           "corp",
+				Repo:          "app",
+				PRNumber:      99,
+				HeadCommitSHA: "deadbeef",
+			},
+			want: "ghe://corp/app/pull/99/deadbeef",
+		},
+		{
+			name: "ghes round-trip",
+			id: ChangeID{
+				Scheme:        "ghes",
+				Org:           "org",
+				Repo:          "repo",
+				PRNumber:      1,
+				HeadCommitSHA: "sha1",
+			},
+			want: "ghes://org/repo/pull/1/sha1",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.want, tt.id.String())
+		})
+	}
+}
+
+func TestChangeID_OwnerRepo(t *testing.T) {
+	id := ChangeID{
+		Scheme:        "github",
+		Org:           "uber",
+		Repo:          "submitqueue",
+		PRNumber:      1,
+		HeadCommitSHA: "abc",
+	}
+	assert.Equal(t, "uber/submitqueue", id.OwnerRepo())
+}
+
+func TestParseChangeID_RoundTrip(t *testing.T) {
+	originals := []string{
+		"github://uber/submitqueue/pull/123/abc123def456",
+		"ghe://corp/monorepo/pull/99/deadbeef01234567",
+		"ghes://org/repo/pull/1/a1b2c3",
+	}
+
+	for _, raw := range originals {
+		t.Run(raw, func(t *testing.T) {
+			parsed, err := ParseChangeID(raw)
+			require.NoError(t, err)
+			assert.Equal(t, raw, parsed.String())
+		})
+	}
+}

example/server/orchestrator/BUILD.bazel

@@ -12,6 +12,8 @@ go_library(
     visibility = ["//visibility:private"],
     deps = [
         "//core/consumer",
+        "//extension/mergechecker",
+        "//extension/mergechecker/github",
         "//extension/queue",
         "//extension/queue/mysql",
         "//orchestrator/controller",

example/server/orchestrator/main.go

@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	"fmt"
 	"net"
+	"net/http"
 	"os"
 	"os/signal"
 	"sync"
@@ -14,6 +15,8 @@ import (
 	_ "github.com/go-sql-driver/mysql"
 	"github.com/uber-go/tally/v4"
 	"github.com/uber/submitqueue/core/consumer"
+	"github.com/uber/submitqueue/extension/mergechecker"
+	githubchecker "github.com/uber/submitqueue/extension/mergechecker/github"
 	extqueue "github.com/uber/submitqueue/extension/queue"
 	queueMySQL "github.com/uber/submitqueue/extension/queue/mysql"
 	"github.com/uber/submitqueue/orchestrator/controller"
@@ -128,8 +131,11 @@ func run() error {
 	// Create consumer
 	c := consumer.New(logger.Sugar(), scope.SubScope("consumer"), registry)
 
+	// Create merge checker
+	mc := newMergeChecker(logger, scope)
+
 	// Register controllers
-	if err := registerControllers(c, logger.Sugar(), scope, registry); err != nil {
+	if err := registerControllers(c, logger.Sugar(), scope, registry, mc); err != nil {
 		return err
 	}
 
@@ -253,11 +259,12 @@ func newTopicRegistry(q extqueue.Queue, subscriberName string) consumer.TopicReg
 //
 //	→ merge → merge-signal
 //	finalize (terminal)
-func registerControllers(c consumer.Consumer, logger *zap.SugaredLogger, scope tally.Scope, registry consumer.TopicRegistry) error {
+func registerControllers(c consumer.Consumer, logger *zap.SugaredLogger, scope tally.Scope, registry consumer.TopicRegistry, mc mergechecker.MergeChecker) error {
 	requestController := request.NewController(
 		logger,
 		scope,
 		registry,
+		mc,
 		consumer.TopicRequest,
 		"orchestrator-request",
 	)
@@ -344,3 +351,39 @@ func registerControllers(c consumer.Consumer, logger *zap.SugaredLogger, scope t
 
 	return nil
 }
+
+// newMergeChecker creates a MergeChecker for GitHub (github.com).
+// Configured via GITHUB_TOKEN and GITHUB_GRAPHQL_URL environment variables.
+func newMergeChecker(logger *zap.Logger, scope tally.Scope) mergechecker.MergeChecker {
+	graphQLURL := os.Getenv("GITHUB_GRAPHQL_URL")
+	if graphQLURL == "" {
+		graphQLURL = "https://api.github.com/graphql"
+	}
+
+	httpClient := &http.Client{}
+	if token := os.Getenv("GITHUB_TOKEN"); token != "" {
+		httpClient.Transport = &bearerTransport{token: token}
+	}
+
+	github := githubchecker.NewMergeChecker(githubchecker.Params{
+		HTTPClient:   httpClient,
+		GraphQLURL:   graphQLURL,
+		Logger:       logger.Sugar(),
+		MetricsScope: scope.SubScope("mergechecker"),
+	})
+
+	return mergechecker.NewMultiChecker(map[string]mergechecker.MergeChecker{
+		"github": github,
+	})
+}
+
+// bearerTransport is an http.RoundTripper that adds a Bearer token to requests.
+type bearerTransport struct {
+	token string
+}
+
+func (t *bearerTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	req = req.Clone(req.Context())
+	req.Header.Set("Authorization", "Bearer "+t.token)
+	return http.DefaultTransport.RoundTrip(req)
+}