bktec upload: upload test results to Test Engine

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## Unreleased
+- Add `bktec upload <path>` to upload JUnit XML or JSON test results to Buildkite Test Engine. Authenticated via `--token` (env: `BUILDKITE_ANALYTICS_TOKEN`); upload format is inferred from the filename extension or set explicitly with `--format junit|json`. Requests carry the standard bktec User-Agent and retry on transient network errors and 5xx responses.
+
 ## 2.4.0 - 2026-04-17
 - Automatically collect git commit metadata on `bktec plan` when `--selection-strategy` is set. Commit info, diff stats, and context fields are sent with the plan request so test selection has the signal it needs without the caller shelling out to git. Preview; gated behind `BKTEC_PREVIEW_SELECTION`.
 - Add `--collect-git-metadata` flag (env: `BUILDKITE_TEST_ENGINE_COLLECT_GIT_METADATA`) to `bktec plan` so pipelines can opt in to git metadata collection without using test selection. Preview; gated behind `BKTEC_PREVIEW_SELECTION`.

cli.go

@@ -6,9 +6,38 @@ import (
 	"os"
 	"strings"
 
+	"github.com/buildkite/test-engine-client/internal/upload"
 	"github.com/urfave/cli/v3"
 )
 
+// uploadConfig is populated by upload subcommand cli flags.
+var uploadConfig upload.Config
+
+var uploadTokenFlag = &cli.StringFlag{
+	Name:        "token",
+	Category:    "TEST ENGINE",
+	Usage:       "Buildkite Test Engine suite token used to authenticate uploads",
+	Sources:     cli.EnvVars("BUILDKITE_ANALYTICS_TOKEN"),
+	Destination: &uploadConfig.SuiteToken,
+}
+
+var uploadFormatFlag = &cli.StringFlag{
+	Name:     "format",
+	Category: "TEST ENGINE",
+	Usage:    "Upload format: junit or json. When unset, inferred from filename extension.",
+	Sources:  cli.EnvVars("BUILDKITE_TEST_ENGINE_UPLOAD_FORMAT"),
+}
+
+var uploadUrlFlag = &cli.StringFlag{
+	Name:        "upload-url",
+	Category:    "TEST ENGINE",
+	Usage:       "Buildkite Test Engine upload API endpoint",
+	Value:       upload.DefaultUploadUrl,
+	Sources:     cli.EnvVars("BUILDKITE_TEST_ENGINE_UPLOAD_URL"),
+	Destination: &uploadConfig.UploadUrl,
+	Hidden:      true,
+}
+
 const (
 	previewSelectionEnvVar = "BKTEC_PREVIEW_SELECTION"
 )
@@ -106,6 +135,42 @@ var jobIDFlag = &cli.StringFlag{
 	Hidden:      true,
 }
 
+var commitFlag = &cli.StringFlag{
+	Name:        "commit",
+	Category:    "BUILD ENVIRONMENT",
+	Usage:       "Git commit SHA being built",
+	Sources:     cli.EnvVars("BUILDKITE_COMMIT"),
+	Destination: &cfg.Commit,
+	Hidden:      true,
+}
+
+var messageFlag = &cli.StringFlag{
+	Name:        "message",
+	Category:    "BUILD ENVIRONMENT",
+	Usage:       "Buildkite build message",
+	Sources:     cli.EnvVars("BUILDKITE_MESSAGE"),
+	Destination: &cfg.Message,
+	Hidden:      true,
+}
+
+var buildNumberFlag = &cli.StringFlag{
+	Name:        "build-number",
+	Category:    "BUILD ENVIRONMENT",
+	Usage:       "Buildkite build number",
+	Sources:     cli.EnvVars("BUILDKITE_BUILD_NUMBER"),
+	Destination: &cfg.BuildNumber,
+	Hidden:      true,
+}
+
+var buildUrlFlag = &cli.StringFlag{
+	Name:        "build-url",
+	Category:    "BUILD ENVIRONMENT",
+	Usage:       "Buildkite build URL",
+	Sources:     cli.EnvVars("BUILDKITE_BUILD_URL"),
+	Destination: &cfg.BuildUrl,
+	Hidden:      true,
+}
+
 var stepIDFlag = &cli.StringFlag{
 	Name:        "step-id",
 	Category:    "BUILD ENVIRONMENT",
@@ -563,6 +628,25 @@ var cliCommand = &cli.Command{
 				},
 			},
 		},
+		{
+			Name:      "upload",
+			Usage:     "Upload test results to Test Engine",
+			ArgsUsage: "<path-to-junit.xml-or-results.json>",
+			Action:    uploadAction,
+			Flags: []cli.Flag{
+				uploadTokenFlag,
+				uploadFormatFlag,
+				uploadUrlFlag,
+				// Build environment values used to populate run_env on uploads.
+				buildIDFlag,
+				branchFlag,
+				commitFlag,
+				jobIDFlag,
+				messageFlag,
+				buildNumberFlag,
+				buildUrlFlag,
+			},
+		},
 		{
 			Name:   "tools",
 			Usage:  "Utility tools",

go.mod

@@ -9,6 +9,7 @@ require (
 
 require (
 	drjosh.dev/zzglob v0.4.3
+	github.com/google/uuid v1.6.0
 	github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51
 	github.com/olekukonko/tablewriter v0.0.5
 	github.com/pact-foundation/pact-go/v2 v2.4.2

internal/config/config.go

@@ -7,8 +7,12 @@ type Config struct {
 	// AccessToken is the access token for the API.
 	AccessToken string `json:"-"`
 	// Branch is the string value of the git branch name, used by Buildkite only.
-	Branch  string `json:"BUILDKITE_BRANCH"`
-	BuildId string `json:"BUILDKITE_BUILD_ID"`
+	Branch      string `json:"BUILDKITE_BRANCH"`
+	BuildId     string `json:"BUILDKITE_BUILD_ID"`
+	BuildNumber string `json:"BUILDKITE_BUILD_NUMBER"`
+	BuildUrl    string `json:"BUILDKITE_BUILD_URL"`
+	// Commit is the git commit SHA being built.
+	Commit string `json:"BUILDKITE_COMMIT"`
 	// CollectGitMetadata enables git metadata auto-collection on plan without requiring --selection-strategy to be set.
 	CollectGitMetadata bool `json:"-"`
 	// Concurrency is the number of concurrent git operations for diff collection (default 10).
@@ -22,6 +26,7 @@ type Config struct {
 	// Identifier is the identifier of the build.
 	Identifier string `json:"BUILDKITE_TEST_ENGINE_IDENTIFIER"`
 	JobId      string `json:"BUILDKITE_JOB_ID"`
+	Message    string `json:"BUILDKITE_MESSAGE"`
 	// JobRetryCount is the count of the number of times the job has been retried.
 	JobRetryCount int `json:"BUILDKITE_RETRY_COUNT"`
 	// LocationPrefix is prepended to test file paths when requesting a test plan.