Merge pull request #154 from buildkite-plugins/SUP-5965-env-config-map-format

Add map format support to env

Author: petetomasik

README.md

@@ -332,10 +332,89 @@ steps:
                 build:
                   message: "Deploying foo service"
                   env:
-                    - HELLO=123
-                    - AWS_REGION
+                    HELLO: 123
+                    AWS_REGION: ~  # Null literal reads from $AWS_REGION
 ```
 
+### Environment Variables
+
+Environment variables can be specified in two formats. Both formats are fully supported.
+
+#### Map Format (Recommended)
+
+The map format provides clean, readable syntax:
+
+```yaml
+steps:
+  - label: "Triggering pipelines"
+    plugins:
+      - monorepo-diff#v1.8.0:
+          env:
+            NODE_ENV: production
+            API_URL: https://api.example.com
+            PORT: 8080
+            DEBUG: false
+            AWS_REGION: ~         # Null literal reads from $AWS_REGION
+            EMPTY_STRING: ""      # Empty string sets to literal ""
+          watch:
+            - path: "services/"
+              config:
+                command: "npm test"
+                env:
+                  TEST_ENV: integration
+                  MAX_WORKERS: 4
+```
+
+Map format features:
+- Clean YAML syntax using key-value pairs
+- Supports non-string values (numbers, booleans) which are converted to strings automatically
+- Null values read from OS environment: use `KEY: ~` (recommended YAML null literal)
+- The explicit `~` ensures nothing is accidentally added during pipeline processing
+- Note: Unlike array format, you cannot use just `KEY` alone - you must use a null value
+- Empty string (`""`) is treated as a literal empty string value
+- Whitespace in values is preserved
+- Recommended for new configurations
+
+#### Array Format (Fully Supported)
+
+The array format uses key=value syntax:
+
+```yaml
+steps:
+  - label: "Triggering pipelines"
+    plugins:
+      - monorepo-diff#v1.8.0:
+          env:
+            - NODE_ENV=production
+            - API_URL=https://api.example.com
+            - AWS_REGION          # Key-only reads from $AWS_REGION
+          watch:
+            - path: "services/"
+              config:
+                command: "npm test"
+                env:
+                  - TEST_ENV=integration
+```
+
+Array format features:
+- Key-only entries (e.g., `AWS_REGION`) read from OS environment variables
+- Supports values with equals signs: `BUILD_ARGS=--arg1=val1`
+- Whitespace trimmed from keys and values automatically
+- Fully supported alongside map format
+
+#### Format Comparison
+
+| Feature | Map Format | Array Format |
+|---------|-----------|--------------|
+| Syntax | `KEY: value` | `KEY=value` |
+| OS env reading | Null literal (`KEY: ~`) | Key-only entries (`KEY`) |
+| Empty string | `KEY: ""` sets to `""` | `KEY=` sets to `""` |
+| Type support | Numbers, booleans | Strings only |
+| Whitespace | Preserved in values | Trimmed |
+| Readability | High | Medium |
+
+**Note:** The format is determined by YAML structure - you cannot mix array and map syntax at the same level. However, you can use different formats at different levels (e.g., map format at plugin level, array format at step level).
+
 ### `log_level` (optional)
 
 Add `log_level` property to set the log level. Supported log levels are `debug` and `info`. Defaults to `info`.
@@ -513,7 +592,7 @@ steps:
           diff: "git diff --name-only $(head -n 1 last_successful_build)"
           interpolation: false
           env:
-            - env1=env-1 # this will be appended to all env configuration
+            env1: env-1  # this will be appended to all env configuration
           hooks:
             - command: "echo $(git rev-parse HEAD) > last_successful_build"
           watch:
@@ -544,7 +623,7 @@ steps:
                 artifacts:
                   - "logs/*"
                 env:
-                  - FOO=bar
+                  FOO: bar
 
           wait: true
 ```

plugin.go

@@ -504,32 +504,79 @@ func appendMetadata(watch *WatchConfig, metadata map[string]string) {
 	}
 }
 
-// parse env in format from env=env-value to map[env] = env-value
+// parseEnv converts env configuration from various formats to map[string]string.
+// Supports two formats:
+//   - Array format: ["KEY=value", "KEY2"] - existing format, KEY2 reads from OS env
+//   - Map format: {"KEY": "value", "KEY2": nil} - new format, only nil reads from OS env
 func parseEnv(raw interface{}) (map[string]string, error) {
 	if raw == nil {
 		return nil, nil
 	}
 
-	if _, ok := raw.([]interface{}); !ok {
-		return nil, errors.New("failed to parse plugin configuration")
-	}
-
-	result := make(map[string]string)
-	for _, v := range raw.([]interface{}) {
-		split := strings.SplitN(v.(string), "=", 2)
-		key := strings.TrimSpace(split[0])
+	switch v := raw.(type) {
+	case map[string]string:
+		// Direct string map - all values are literal (including empty strings)
+		result := make(map[string]string, len(v))
+		for k, val := range v {
+			key := strings.TrimSpace(k)
+			if key == "" {
+				continue
+			}
+			// Preserve all values including empty strings
+			result[key] = val
+		}
+		return result, nil
 
-		// only key exists. set value from env
-		if len(key) > 0 && len(split) == 1 {
-			result[key] = env(key, "")
+	case map[string]interface{}:
+		// Generic map - only nil reads from OS environment
+		result := make(map[string]string, len(v))
+		for k, val := range v {
+			key := strings.TrimSpace(k)
+			if key == "" {
+				continue
+			}
+			// Only null values read from OS environment
+			if val == nil {
+				result[key] = env(key, "")
+			} else {
+				// Convert to string, preserving empty strings
+				result[key] = fmt.Sprintf("%v", val)
+			}
 		}
+		return result, nil
+
+	case []interface{}:
+		// Array format - preserve existing behavior exactly
+		result := make(map[string]string)
+		for _, item := range v {
+			str, ok := item.(string)
+			if !ok {
+				continue
+			}
+
+			split := strings.SplitN(str, "=", 2)
+			key := strings.TrimSpace(split[0])
+
+			if key == "" {
+				continue
+			}
 
-		if len(split) == 2 {
-			result[key] = strings.TrimSpace(split[1])
+			// Only key exists - read from OS environment
+			if len(split) == 1 {
+				result[key] = env(key, "")
+				continue
+			}
+
+			// Key=value - trim both (backwards compatibility)
+			if len(split) == 2 {
+				result[key] = strings.TrimSpace(split[1])
+			}
 		}
-	}
+		return result, nil
 
-	return result, nil
+	default:
+		return nil, errors.New("env configuration must be an array of strings (e.g., ['KEY=value']) or a map (e.g., {KEY: 'value'})")
+	}
 }
 
 // parse metadata in format from key:value to map[key] = value

plugin.yml

@@ -16,7 +16,10 @@ configuration:
     interpolation:
       type: boolean
     env:
-      type: array
+      type: [array, object]
+      description: >
+        Environment variables. Array: ["KEY=value", "KEY"] or Map: {KEY: "value", KEY2: ~}
+        Array format: KEY-only reads from OS. Map format: use "KEY: ~" (null literal) to read from OS, "KEY: ''" for empty string.
     binary_folder:
       type: string
     notify:
@@ -86,7 +89,10 @@ configuration:
                 branch:
                   type: string
                 env:
-                  type: array
+                  type: [array, object]
+                  description: >
+                    Environment variables. Array: ["KEY=value", "KEY"] or Map: {KEY: "value", KEY2: ~}
+                    Array: KEY-only reads from OS. Map: use "KEY: ~" (null literal) to read from OS, "KEY: ''" for empty string.
             agents:
               type: object
               properties:
@@ -101,7 +107,10 @@ configuration:
               type: array
               description: Artifact paths to upload (preferred field name)
             env:
-              type: array
+              type: [array, object]
+              description: >
+                Environment variables. Array: ["KEY=value", "KEY"] or Map: {KEY: "value", KEY2: ~}
+                Array: KEY-only reads from OS. Map: use "KEY: ~" (null literal) to read from OS, "KEY: ''" for empty string.
     wait:
       type: boolean
     hooks: