Add meta-data set-batch command

AGENT.md

@@ -28,7 +28,7 @@ Go CLI application with main packages:
 - Formatting with `gofumpt` in extra mode: `go tool gofumpt -extra -w .`
 - Struct-based configuration patterns (e.g., `AgentWorkerConfig`, `JobRunnerConfig`)
 - Context-aware functions: `func Name(ctx context.Context, ...)`
-- Import organization: stdlib, external deps, internal packages
+- Import organization: stdlib, then everything else (gofumpt groups all non-stdlib imports together)
 - Error handling: explicit errors, wrapped with context
 - Naming: PascalCase for exported, camelCase for private, ALL_CAPS for constants
 - Interface types end with -er suffix where appropriate

api/meta_data.go

@@ -18,6 +18,11 @@ type MetaDataExists struct {
 	Exists bool `json:"exists"`
 }
 
+// MetaDataBatch represents a batch of key/value pairs for the set-batch endpoint.
+type MetaDataBatch struct {
+	Items []MetaData `json:"items"`
+}
+
 // Sets the meta data value
 func (c *Client) SetMetaData(ctx context.Context, jobId string, metaData *MetaData) (*Response, error) {
 	u := fmt.Sprintf("jobs/%s/data/set", railsPathEscape(jobId))
@@ -30,6 +35,19 @@ func (c *Client) SetMetaData(ctx context.Context, jobId string, metaData *MetaDa
 	return c.doRequest(req, nil)
 }
 
+// SetMetaDataBatch sets multiple meta data key/value pairs in a single request.
+// The operation is transactional: all items succeed or none do.
+func (c *Client) SetMetaDataBatch(ctx context.Context, jobId string, batch *MetaDataBatch) (*Response, error) {
+	u := fmt.Sprintf("jobs/%s/data/set-batch", railsPathEscape(jobId))
+
+	req, err := c.newRequest(ctx, "POST", u, batch)
+	if err != nil {
+		return nil, err
+	}
+
+	return c.doRequest(req, nil)
+}
+
 // Gets the meta data value
 func (c *Client) GetMetaData(ctx context.Context, scope, id, key string) (*MetaData, *Response, error) {
 	if scope != "job" && scope != "build" {

clicommand/commands.go

@@ -99,6 +99,7 @@ var BuildkiteAgentCommands = []cli.Command{
 		Usage:    "Get/set metadata from Buildkite jobs",
 		Subcommands: []cli.Command{
 			MetaDataSetCommand,
+			MetaDataSetBatchCommand,
 			MetaDataGetCommand,
 			MetaDataExistsCommand,
 			MetaDataKeysCommand,

clicommand/config_completeness_test.go

@@ -45,6 +45,7 @@ var commandConfigPairs = []configCommandPair{
 	{Config: MetaDataGetConfig{}, Command: MetaDataGetCommand},
 	{Config: MetaDataKeysConfig{}, Command: MetaDataKeysCommand},
 	{Config: MetaDataSetConfig{}, Command: MetaDataSetCommand},
+	{Config: MetaDataSetBatchConfig{}, Command: MetaDataSetBatchCommand},
 	{Config: OIDCTokenConfig{}, Command: OIDCRequestTokenCommand},
 	{Config: PipelineUploadConfig{}, Command: PipelineUploadCommand},
 	{Config: RedactorAddConfig{}, Command: RedactorAddCommand},

clicommand/meta_data_set_batch.go

@@ -0,0 +1,147 @@
+package clicommand
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"slices"
+	"strings"
+	"time"
+
+	"github.com/buildkite/agent/v3/api"
+	"github.com/buildkite/agent/v3/internal/redact"
+	"github.com/buildkite/agent/v3/logger"
+	"github.com/buildkite/roko"
+	"github.com/urfave/cli"
+)
+
+const metaDataSetBatchHelpDescription = `Usage:
+
+    buildkite-agent meta-data set-batch <key=value>... [options...]
+
+Description:
+
+Set multiple meta-data key/value pairs on a build in a single request.
+
+Each argument must be in key=value format.
+
+Keys and values must be non-empty strings, and strings containing only
+whitespace characters are not allowed.
+
+Example:
+
+    $ buildkite-agent meta-data set-batch foo=bar "greeting=hello world"
+    $ buildkite-agent meta-data set-batch duration:spec/a.rb=2.341 duration:spec/b.rb=5.672`
+
+type MetaDataSetBatchConfig struct {
+	GlobalConfig
+	APIConfig
+
+	Job          string   `cli:"job" validate:"required"`
+	RedactedVars []string `cli:"redacted-vars" normalize:"list"`
+}
+
+var MetaDataSetBatchCommand = cli.Command{
+	Name:        "set-batch",
+	Usage:       "Set multiple meta-data key/value pairs on a build",
+	Description: metaDataSetBatchHelpDescription,
+	Flags: slices.Concat(globalFlags(), apiFlags(), []cli.Flag{
+		cli.StringFlag{
+			Name:   "job",
+			Value:  "",
+			Usage:  "Which job's build should the meta-data be set on",
+			EnvVar: "BUILDKITE_JOB_ID",
+		},
+		RedactedVars,
+	}),
+	Action: func(c *cli.Context) error {
+		ctx := context.Background()
+		ctx, cfg, l, _, done := setupLoggerAndConfig[MetaDataSetBatchConfig](ctx, c)
+		defer done()
+
+		args := c.Args()
+		if len(args) == 0 {
+			return errors.New("at least one key=value argument is required")
+		}
+
+		items, err := parseMetaDataBatchArgs(args)
+		if err != nil {
+			return err
+		}
+
+		needles, _, err := redact.NeedlesFromEnv(cfg.RedactedVars)
+		if err != nil {
+			return err
+		}
+
+		for i := range items {
+			if redactedValue := redact.String(items[i].Value, needles); redactedValue != items[i].Value {
+				l.Warnf("Meta-data value for key %q contained one or more secrets from environment variables that have been redacted. If this is deliberate, pass --redacted-vars='' or a list of patterns that does not match the variable containing the secret", items[i].Key)
+				items[i].Value = redactedValue
+			}
+		}
+
+		return setMetaDataBatch(ctx, cfg, l, items)
+	},
+}
+
+type invalidFormatError struct{ arg string }
+
+func (e invalidFormatError) Error() string {
+	return fmt.Sprintf("invalid argument %q: must be in key=value format", e.arg)
+}
+
+type emptyKeyError struct{ arg string }
+
+func (e emptyKeyError) Error() string {
+	return fmt.Sprintf("invalid argument %q: key cannot be empty, or composed of only whitespace characters", e.arg)
+}
+
+type emptyValueError struct{ arg string }
+
+func (e emptyValueError) Error() string {
+	return fmt.Sprintf("invalid argument %q: value cannot be empty, or composed of only whitespace characters", e.arg)
+}
+
+func parseMetaDataBatchArgs(args []string) ([]api.MetaData, error) {
+	items := make([]api.MetaData, 0, len(args))
+	for _, arg := range args {
+		key, value, ok := strings.Cut(arg, "=")
+		if !ok {
+			return nil, invalidFormatError{arg: arg}
+		}
+		if strings.TrimSpace(key) == "" {
+			return nil, emptyKeyError{arg: arg}
+		}
+		if strings.TrimSpace(value) == "" {
+			return nil, emptyValueError{arg: arg}
+		}
+		items = append(items, api.MetaData{Key: key, Value: value})
+	}
+	return items, nil
+}
+
+func setMetaDataBatch(ctx context.Context, cfg MetaDataSetBatchConfig, l logger.Logger, items []api.MetaData) error {
+	client := api.NewClient(l, loadAPIClientConfig(cfg, "AgentAccessToken"))
+
+	batch := &api.MetaDataBatch{Items: items}
+
+	if err := roko.NewRetrier(
+		roko.WithMaxAttempts(10),
+		roko.WithStrategy(roko.ExponentialSubsecond(2*time.Second)),
+	).DoWithContext(ctx, func(r *roko.Retrier) error {
+		resp, err := client.SetMetaDataBatch(ctx, cfg.Job, batch)
+		if resp != nil && (resp.StatusCode == 401 || resp.StatusCode == 404) {
+			r.Break()
+		}
+		if err != nil {
+			l.Warnf("%s (%s)", err, r)
+			return err
+		}
+		return nil
+	}); err != nil {
+		return fmt.Errorf("failed to set meta-data batch: %w", err)
+	}
+
+	return nil
+}