feat(buildrunner): add GitHub Actions backend

Author: albertywu

example/submitqueue/orchestrator/server/BUILD.bazel

@@ -21,6 +21,7 @@ go_library(
         "//submitqueue/core/consumer",
         "//submitqueue/entity",
         "//submitqueue/extension/buildrunner",
+        "//submitqueue/extension/buildrunner/githubactions",
         "//submitqueue/extension/buildrunner/noop",
         "//submitqueue/extension/changeprovider",
         "//submitqueue/extension/changeprovider/github",

example/submitqueue/orchestrator/server/main.go

@@ -20,8 +20,10 @@ import (
 	"errors"
 	"fmt"
 	"net"
+	"net/http"
 	"os"
 	"os/signal"
+	"strings"
 	"sync"
 	"syscall"
 	"time"
@@ -40,6 +42,7 @@ import (
 	"github.com/uber/submitqueue/submitqueue/core/consumer"
 	"github.com/uber/submitqueue/submitqueue/entity"
 	"github.com/uber/submitqueue/submitqueue/extension/buildrunner"
+	"github.com/uber/submitqueue/submitqueue/extension/buildrunner/githubactions"
 	buildnoop "github.com/uber/submitqueue/submitqueue/extension/buildrunner/noop"
 	"github.com/uber/submitqueue/submitqueue/extension/changeprovider"
 	githubprovider "github.com/uber/submitqueue/submitqueue/extension/changeprovider/github"
@@ -226,8 +229,12 @@ func run() error {
 	}
 
 	// Create build runner. The noop runner is the pass-through default
-	// (every build immediately succeeds) until a real backend is wired in.
-	br := buildnoop.New()
+	// (every build immediately succeeds); BUILD_RUNNER=githubactions enables
+	// the GitHub Actions proof-of-architecture backend.
+	br, err := newBuildRunnerFactory(logger)
+	if err != nil {
+		return fmt.Errorf("failed to create build runner: %w", err)
+	}
 
 	// Register controllers
 	if err := registerControllers(c, logger.Sugar(), scope, registry, mc, cp, psh, br, cnt, store); err != nil {
@@ -456,7 +463,7 @@ type conflictFactory struct{ impl conflict.Analyzer }
 
 func (f conflictFactory) For(conflict.Config) (conflict.Analyzer, error) { return f.impl, nil }
 
-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) 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.Factory, cnt counter.Counter, store storage.Storage) error {
 	requestController := start.NewController(
 		logger,
 		scope,
@@ -553,7 +560,7 @@ func registerControllers(c consumer.Consumer, logger *zap.SugaredLogger, scope t
 		logger,
 		scope,
 		store,
-		buildRunnerFactory{impl: br},
+		br,
 		registry,
 		consumer.TopicKeyBuild,
 		"orchestrator-build",
@@ -566,7 +573,7 @@ func registerControllers(c consumer.Consumer, logger *zap.SugaredLogger, scope t
 		logger,
 		scope,
 		store,
-		buildRunnerFactory{impl: br},
+		br,
 		registry,
 		consumer.TopicKeyBuildSignal,
 		"orchestrator-buildsignal",
@@ -701,6 +708,82 @@ func newPusher(logger *zap.Logger, scope tally.Scope) (pusher.Pusher, error) {
 	}), nil
 }
 
+// newBuildRunnerFactory creates the BuildRunner factory selected by
+// BUILD_RUNNER. Defaults to noop for local development. Use
+// BUILD_RUNNER=githubactions to dispatch a GitHub Actions workflow via
+// workflow_dispatch.
+func newBuildRunnerFactory(logger *zap.Logger) (buildrunner.Factory, error) {
+	switch strings.ToLower(getEnv("BUILD_RUNNER", "noop")) {
+	case "noop":
+		logger.Info("using noop build runner")
+		return buildRunnerFactory{impl: buildnoop.New()}, nil
+	case "githubactions", "github-actions":
+		client, err := newGitHubHTTPClient()
+		if err != nil {
+			return nil, err
+		}
+		f, err := githubactions.NewFactory(githubactions.FactoryParams{
+			HTTPClient: client,
+			Logger:     logger.Sugar(),
+			Owner:      os.Getenv("GITHUB_ACTIONS_OWNER"),
+			Repo:       os.Getenv("GITHUB_ACTIONS_REPO"),
+			WorkflowID: os.Getenv("GITHUB_ACTIONS_WORKFLOW"),
+			Ref:        getEnv("GITHUB_ACTIONS_REF", "main"),
+			ExtraInputs: parseKeyValueList(
+				os.Getenv("GITHUB_ACTIONS_EXTRA_INPUTS"),
+			),
+		})
+		if err != nil {
+			return nil, err
+		}
+		logger.Info("using GitHub Actions build runner",
+			zap.String("owner", os.Getenv("GITHUB_ACTIONS_OWNER")),
+			zap.String("repo", os.Getenv("GITHUB_ACTIONS_REPO")),
+			zap.String("workflow", os.Getenv("GITHUB_ACTIONS_WORKFLOW")),
+			zap.String("ref", getEnv("GITHUB_ACTIONS_REF", "main")),
+		)
+		return f, nil
+	default:
+		return nil, fmt.Errorf("unsupported BUILD_RUNNER %q (supported: noop, githubactions)", os.Getenv("BUILD_RUNNER"))
+	}
+}
+
+func newGitHubHTTPClient() (*http.Client, error) {
+	client, err := httpclient.NewClient(getEnv("GITHUB_BASE_URL", "https://api.github.com"))
+	if err != nil {
+		return nil, fmt.Errorf("failed to build GitHub HTTP client: %w", err)
+	}
+
+	if token := os.Getenv("GITHUB_TOKEN"); token != "" {
+		ts := oauth2.StaticTokenSource(&oauth2.Token{AccessToken: token})
+		client.Transport = &oauth2.Transport{Source: ts, Base: client.Transport}
+	}
+
+	client.Timeout = parseTimeout(os.Getenv("GITHUB_TIMEOUT"), 30*time.Second)
+	return client, nil
+}
+
+// parseKeyValueList parses comma-separated key=value entries. Invalid entries
+// are ignored so optional configuration cannot prevent the server from
+// starting.
+func parseKeyValueList(raw string) map[string]string {
+	if raw == "" {
+		return nil
+	}
+	out := make(map[string]string)
+	for _, part := range strings.Split(raw, ",") {
+		key, value, ok := strings.Cut(strings.TrimSpace(part), "=")
+		if !ok || key == "" {
+			continue
+		}
+		out[key] = value
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
 // 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)

submitqueue/extension/buildrunner/README.md

@@ -10,3 +10,11 @@ See [`doc/rfc/submitqueue/build-runner.md`](../../../doc/rfc/submitqueue/build-r
 2. Map the `base` and `head` change slices onto the backend's build primitives (apply `base`, apply `head`, validate the result).
 3. Map the runner's lifecycle states down to the `BuildStatus` values: `Accepted` (accepted for execution), `Running` (executing), and the terminal `Succeeded` / `Failed` / `Cancelled`.
 4. Implement internal reconnect / retry so transient failures surface as plain errors without blocking the caller.
+
+## Backends
+
+- `noop`: local-development backend that immediately succeeds every build.
+- `githubactions`: proof-of-architecture backend that dispatches a GitHub
+  Actions workflow. See [`githubactions/README.md`](githubactions/README.md)
+  for the workflow inputs and example orchestrator environment variables.
+- `buildkite`: Buildkite-backed backend.

submitqueue/extension/buildrunner/githubactions/BUILD.bazel

@@ -0,0 +1,30 @@
+load("@rules_go//go:def.bzl", "go_library", "go_test")
+
+go_library(
+    name = "githubactions",
+    srcs = [
+        "client.go",
+        "githubactions.go",
+    ],
+    importpath = "github.com/uber/submitqueue/submitqueue/extension/buildrunner/githubactions",
+    visibility = ["//visibility:public"],
+    deps = [
+        "//submitqueue/entity",
+        "//submitqueue/extension/buildrunner",
+        "@org_uber_go_zap//:zap",
+    ],
+)
+
+go_test(
+    name = "githubactions_test",
+    srcs = ["githubactions_test.go"],
+    embed = [":githubactions"],
+    deps = [
+        "//core/httpclient",
+        "//submitqueue/entity",
+        "//submitqueue/extension/buildrunner",
+        "@com_github_stretchr_testify//assert",
+        "@com_github_stretchr_testify//require",
+        "@org_uber_go_zap//:zap",
+    ],
+)

submitqueue/extension/buildrunner/githubactions/README.md

@@ -0,0 +1,99 @@
+# GitHub Actions BuildRunner
+
+`githubactions` implements `buildrunner.BuildRunner` with GitHub Actions
+`workflow_dispatch`. It is intended to prove the SubmitQueue BuildRunner
+architecture against a common CI system without adding local state.
+
+## How it works
+
+1. `Trigger` dispatches the configured workflow on a trusted ref, usually
+   `main`, and returns GitHub's workflow run ID as the SubmitQueue build ID.
+2. SubmitQueue passes these workflow inputs:
+   - `sq_build_id`
+   - `sq_base_uris`
+   - `sq_head_uris`
+   - `sq_queue`
+   - `sq_metadata`
+3. `Status` calls GitHub's get-workflow-run endpoint with that run ID.
+4. `Cancel` calls GitHub's cancel-workflow-run endpoint with that run ID.
+
+`sq_build_id` is a generated SubmitQueue trace ID passed to the workflow for
+logs and human correlation. It is not used to poll or cancel the run.
+
+## Minimal workflow
+
+Create a workflow on the target repository's default branch:
+
+```yaml
+name: SubmitQueue CI
+run-name: SubmitQueue ${{ inputs.sq_build_id }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      sq_build_id:
+        required: true
+        type: string
+      sq_base_uris:
+        required: true
+        type: string
+      sq_head_uris:
+        required: true
+        type: string
+      sq_queue:
+        required: true
+        type: string
+      sq_metadata:
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Inspect SubmitQueue payload
+        run: |
+          echo '${{ inputs.sq_base_uris }}'
+          echo '${{ inputs.sq_head_uris }}'
+          echo '${{ inputs.sq_queue }}'
+      # Prototype: add a script here that applies sq_base_uris, then
+      # sq_head_uris, then runs the repository's real CI command.
+```
+
+The workflow definition should live on a trusted ref. The untrusted changes
+should be represented by `sq_base_uris` and `sq_head_uris` and applied inside
+the job.
+
+## Example server configuration
+
+Set these environment variables on the example orchestrator:
+
+```sh
+BUILD_RUNNER=githubactions
+GITHUB_BASE_URL=https://api.github.com
+GITHUB_TOKEN=<token with actions:read/actions:write>
+GITHUB_ACTIONS_OWNER=uber
+GITHUB_ACTIONS_REPO=submitqueue
+GITHUB_ACTIONS_WORKFLOW=submitqueue-ci.yml
+GITHUB_ACTIONS_REF=main
+GITHUB_ACTIONS_EXTRA_INPUTS=runner=ubuntu-latest,test_command=make test
+```
+
+`GITHUB_ACTIONS_REF` defaults to `main`. `GITHUB_ACTIONS_EXTRA_INPUTS` is
+optional comma-separated `key=value` data copied into every dispatch request;
+use it for workflow-specific knobs like runner labels or test commands.
+
+## Practical setup notes
+
+- Use a trusted workflow definition from the target repository's default branch.
+- Include `sq_build_id` in `run-name` if you want the generated SubmitQueue
+  trace ID visible in the Actions UI.
+- Keep workflow permissions minimal. The job may apply untrusted changes before
+  running tests, so avoid broad secrets in this workflow.
+- The backend proves the BuildRunner architecture. It does not prescribe how
+  your workflow materializes `sq_base_uris` and `sq_head_uris`; wire that to the
+  repository's existing patch/PR application logic.