From 8044e344e9f98df25a16b9c2c2b943842bda6293 Mon Sep 17 00:00:00 2001
From: Shreyas Goenka <shreyas.goenka@databricks.com>
Date: Thu, 21 May 2026 15:43:06 +0200
Subject: [PATCH 1/3] Add env section to bundle scripts for DABs interpolation

scripts.<name> now accepts an env: map whose values may reference
${bundle.*}, ${workspace.*}, and ${var.*}. The script content is still
passed to the shell as-is (no DABs interpolation), removing the ambiguity
between bundle variables and shell variables that previously forced all
${...} usage to be rejected.

When an env value references an unsupported prefix (e.g. ${resources.*}),
validation reports a clear error pointing at the field. The content-side
error now suggests the new env section instead of just stating ${...} is
unsupported.

Fixes #4179

Co-authored-by: Isaac
---
 NEXT_CHANGELOG.md                             |  1 +
 .../run/scripts/env-bad-prefix/databricks.yml | 14 ++++
 .../run/scripts/env-bad-prefix/out.test.toml  |  3 +
 .../run/scripts/env-bad-prefix/output.txt     | 16 ++++
 .../bundle/run/scripts/env-bad-prefix/script  |  1 +
 .../run/scripts/env-bad-prefix/test.toml      |  5 ++
 .../run/scripts/env-section/databricks.yml    | 21 +++++
 .../run/scripts/env-section/out.test.toml     |  3 +
 .../bundle/run/scripts/env-section/output.txt |  6 ++
 .../bundle/run/scripts/env-section/script     |  1 +
 .../bundle/run/scripts/env-section/test.toml  |  5 ++
 .../run/scripts/no-interpolation/output.txt   | 56 +++++++++----
 bundle/config/root.go                         |  7 ++
 bundle/config/validate/scripts.go             | 82 +++++++++++++++----
 bundle/internal/schema/annotations.yml        |  3 +
 bundle/schema/jsonschema.json                 |  3 +
 cmd/bundle/run.go                             | 13 ++-
 17 files changed, 203 insertions(+), 37 deletions(-)
 create mode 100644 acceptance/bundle/run/scripts/env-bad-prefix/databricks.yml
 create mode 100644 acceptance/bundle/run/scripts/env-bad-prefix/out.test.toml
 create mode 100644 acceptance/bundle/run/scripts/env-bad-prefix/output.txt
 create mode 100644 acceptance/bundle/run/scripts/env-bad-prefix/script
 create mode 100644 acceptance/bundle/run/scripts/env-bad-prefix/test.toml
 create mode 100644 acceptance/bundle/run/scripts/env-section/databricks.yml
 create mode 100644 acceptance/bundle/run/scripts/env-section/out.test.toml
 create mode 100644 acceptance/bundle/run/scripts/env-section/output.txt
 create mode 100644 acceptance/bundle/run/scripts/env-section/script
 create mode 100644 acceptance/bundle/run/scripts/env-section/test.toml

diff --git a/NEXT_CHANGELOG.md b/NEXT_CHANGELOG.md
index d8046549017..b307b6e9b91 100644
--- a/NEXT_CHANGELOG.md
+++ b/NEXT_CHANGELOG.md
@@ -19,6 +19,7 @@
 * engine/direct: Fix WAL corruption after two consecutive failed deploys ([#5606](https://github.com/databricks/cli/pull/5606)).
 * engine/direct: Don't open the deployment state WAL when a deploy's plan fails ([#5607](https://github.com/databricks/cli/pull/5607)).
 * Ignore unity catalog managed schema property defaults to avoid unnecessary drift ([#5195](https://github.com/databricks/cli/pull/5195)).
+* Added an `env:` section to `scripts.<name>` for declaring environment variables that may reference `${bundle.*}`, `${workspace.*}`, and `${var.*}` ([#4179](https://github.com/databricks/cli/issues/4179)).
 
 ### Dependency updates
 
diff --git a/acceptance/bundle/run/scripts/env-bad-prefix/databricks.yml b/acceptance/bundle/run/scripts/env-bad-prefix/databricks.yml
new file mode 100644
index 00000000000..c771fb55473
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-bad-prefix/databricks.yml
@@ -0,0 +1,14 @@
+bundle:
+  name: script-env-bad-prefix
+
+resources:
+  jobs:
+    my_job:
+      name: my-job
+
+scripts:
+  bad:
+    env:
+      JOB_ID: ${resources.jobs.my_job.id}
+      UNKNOWN: ${something.else}
+    content: echo "$JOB_ID $UNKNOWN"
diff --git a/acceptance/bundle/run/scripts/env-bad-prefix/out.test.toml b/acceptance/bundle/run/scripts/env-bad-prefix/out.test.toml
new file mode 100644
index 00000000000..f784a183258
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-bad-prefix/out.test.toml
@@ -0,0 +1,3 @@
+Local = true
+Cloud = false
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["terraform", "direct"]
diff --git a/acceptance/bundle/run/scripts/env-bad-prefix/output.txt b/acceptance/bundle/run/scripts/env-bad-prefix/output.txt
new file mode 100644
index 00000000000..239578fe563
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-bad-prefix/output.txt
@@ -0,0 +1,16 @@
+
+>>> [CLI] bundle validate
+Error: ${resources.jobs.my_job.id} cannot be used in scripts.bad.env.JOB_ID; only ${bundle.*}, ${workspace.*}, and ${var.*} are resolved before scripts execute
+  at scripts.bad.env.JOB_ID
+  in databricks.yml:12:15
+
+Error: ${something.else} cannot be used in scripts.bad.env.UNKNOWN; only ${bundle.*}, ${workspace.*}, and ${var.*} are resolved before scripts execute
+  at scripts.bad.env.UNKNOWN
+  in databricks.yml:13:16
+
+Name: script-env-bad-prefix
+Target: default
+
+Found 2 errors
+
+Exit code: 1
diff --git a/acceptance/bundle/run/scripts/env-bad-prefix/script b/acceptance/bundle/run/scripts/env-bad-prefix/script
new file mode 100644
index 00000000000..f52b452ee67
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-bad-prefix/script
@@ -0,0 +1 @@
+errcode trace $CLI bundle validate
diff --git a/acceptance/bundle/run/scripts/env-bad-prefix/test.toml b/acceptance/bundle/run/scripts/env-bad-prefix/test.toml
new file mode 100644
index 00000000000..c2bbdaa30cf
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-bad-prefix/test.toml
@@ -0,0 +1,5 @@
+Local = true
+Cloud = false
+
+[EnvMatrix]
+DATABRICKS_BUNDLE_ENGINE = ["terraform", "direct"]
diff --git a/acceptance/bundle/run/scripts/env-section/databricks.yml b/acceptance/bundle/run/scripts/env-section/databricks.yml
new file mode 100644
index 00000000000..3938b15deb5
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-section/databricks.yml
@@ -0,0 +1,21 @@
+bundle:
+  name: script-env-section
+
+variables:
+  region:
+    default: us-west-2
+  database:
+    default: mydb
+
+scripts:
+  show_env:
+    env:
+      BUNDLE_NAME: ${bundle.name}
+      REGION: ${var.region}
+      DATABASE: ${var.database}
+      MIXED: "region=${var.region};db=${var.database}"
+    content: |-
+      echo "bundle=$BUNDLE_NAME"
+      echo "region=$REGION"
+      echo "database=$DATABASE"
+      echo "mixed=$MIXED"
diff --git a/acceptance/bundle/run/scripts/env-section/out.test.toml b/acceptance/bundle/run/scripts/env-section/out.test.toml
new file mode 100644
index 00000000000..f784a183258
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-section/out.test.toml
@@ -0,0 +1,3 @@
+Local = true
+Cloud = false
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["terraform", "direct"]
diff --git a/acceptance/bundle/run/scripts/env-section/output.txt b/acceptance/bundle/run/scripts/env-section/output.txt
new file mode 100644
index 00000000000..335d9028fbe
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-section/output.txt
@@ -0,0 +1,6 @@
+
+>>> [CLI] bundle run show_env
+bundle=script-env-section
+region=us-west-2
+database=mydb
+mixed=region=us-west-2;db=mydb
diff --git a/acceptance/bundle/run/scripts/env-section/script b/acceptance/bundle/run/scripts/env-section/script
new file mode 100644
index 00000000000..e25d0638fb7
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-section/script
@@ -0,0 +1 @@
+trace $CLI bundle run show_env
diff --git a/acceptance/bundle/run/scripts/env-section/test.toml b/acceptance/bundle/run/scripts/env-section/test.toml
new file mode 100644
index 00000000000..c2bbdaa30cf
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-section/test.toml
@@ -0,0 +1,5 @@
+Local = true
+Cloud = false
+
+[EnvMatrix]
+DATABRICKS_BUNDLE_ENGINE = ["terraform", "direct"]
diff --git a/acceptance/bundle/run/scripts/no-interpolation/output.txt b/acceptance/bundle/run/scripts/no-interpolation/output.txt
index 45bc397bdb7..16c28a71706 100644
--- a/acceptance/bundle/run/scripts/no-interpolation/output.txt
+++ b/acceptance/bundle/run/scripts/no-interpolation/output.txt
@@ -1,40 +1,64 @@
 
 >>> [CLI] bundle deploy
-Error: Found ${FOO} in script one. Interpolation syntax ${...} is not allowed in scripts
+Error: Found ${FOO} in script one.content. Interpolation syntax ${...} is not supported in script content
   at scripts.one.content
   in databricks.yml:6:14
 
-We do not support the ${...} interpolation syntax in scripts because
-it's ambiguous whether it's a variable reference or reference to an
-environment variable.
+The ${...} syntax is not allowed in script content. To use a bundle value,
+declare an environment variable in the script's "env:" section and reference it
+from "content" with $NAME:
 
-Error: Found ${var.BAR} in script two. Interpolation syntax ${...} is not allowed in scripts
+  scripts:
+    one:
+      env:
+        MY_VAR: ${var.foo}
+      content: echo "$MY_VAR"
+
+Error: Found ${var.BAR} in script two.content. Interpolation syntax ${...} is not supported in script content
   at scripts.two.content
   in databricks.yml:8:14
 
-We do not support the ${...} interpolation syntax in scripts because
-it's ambiguous whether it's a variable reference or reference to an
-environment variable.
+The ${...} syntax is not allowed in script content. To use a bundle value,
+declare an environment variable in the script's "env:" section and reference it
+from "content" with $NAME:
+
+  scripts:
+    two:
+      env:
+        MY_VAR: ${var.foo}
+      content: echo "$MY_VAR"
 
 
 Exit code: 1
 
 >>> [CLI] bundle run foo
-Error: Found ${FOO} in script one. Interpolation syntax ${...} is not allowed in scripts
+Error: Found ${FOO} in script one.content. Interpolation syntax ${...} is not supported in script content
   at scripts.one.content
   in databricks.yml:6:14
 
-We do not support the ${...} interpolation syntax in scripts because
-it's ambiguous whether it's a variable reference or reference to an
-environment variable.
+The ${...} syntax is not allowed in script content. To use a bundle value,
+declare an environment variable in the script's "env:" section and reference it
+from "content" with $NAME:
 
-Error: Found ${var.BAR} in script two. Interpolation syntax ${...} is not allowed in scripts
+  scripts:
+    one:
+      env:
+        MY_VAR: ${var.foo}
+      content: echo "$MY_VAR"
+
+Error: Found ${var.BAR} in script two.content. Interpolation syntax ${...} is not supported in script content
   at scripts.two.content
   in databricks.yml:8:14
 
-We do not support the ${...} interpolation syntax in scripts because
-it's ambiguous whether it's a variable reference or reference to an
-environment variable.
+The ${...} syntax is not allowed in script content. To use a bundle value,
+declare an environment variable in the script's "env:" section and reference it
+from "content" with $NAME:
+
+  scripts:
+    two:
+      env:
+        MY_VAR: ${var.foo}
+      content: echo "$MY_VAR"
 
 
 Exit code: 1
diff --git a/bundle/config/root.go b/bundle/config/root.go
index caca8e1f1ad..e13bf78bf15 100644
--- a/bundle/config/root.go
+++ b/bundle/config/root.go
@@ -24,6 +24,13 @@ import (
 type Script struct {
 	// Content of the script to be executed.
 	Content string `json:"content"`
+
+	// Env is a map of environment variables exported when running the script.
+	// Values may reference ${bundle.*}, ${workspace.*}, ${var.*} (or
+	// ${variables.*}); other prefixes are rejected at validation time.
+	// Use this to pass bundle configuration into a script's shell environment
+	// without polluting the script content with DABs interpolation syntax.
+	Env map[string]string `json:"env,omitempty"`
 }
 
 type Root struct { //nolint:recvcheck // value receivers for read-only accessors, pointer for mutators
diff --git a/bundle/config/validate/scripts.go b/bundle/config/validate/scripts.go
index 04c6045bb42..b0f25ee5368 100644
--- a/bundle/config/validate/scripts.go
+++ b/bundle/config/validate/scripts.go
@@ -4,12 +4,13 @@ import (
 	"context"
 	"fmt"
 	"maps"
-	"regexp"
 	"slices"
+	"strings"
 
 	"github.com/databricks/cli/bundle"
 	"github.com/databricks/cli/libs/diag"
 	"github.com/databricks/cli/libs/dyn"
+	"github.com/databricks/cli/libs/dyn/dynvar"
 )
 
 type validateScripts struct{}
@@ -22,10 +23,14 @@ func (f *validateScripts) Name() string {
 	return "validate:scripts"
 }
 
-func (f *validateScripts) Apply(ctx context.Context, b *bundle.Bundle) diag.Diagnostics {
-	diags := diag.Diagnostics{}
+// allowedEnvRefPrefixes are the variable prefixes that may appear in a
+// script's "env:" section. These match the prefixes resolved before scripts
+// execute (defaultPrefixes in resolve_variable_references.go); "var" is the
+// shorthand for "variables".
+var allowedEnvRefPrefixes = []string{"bundle", "workspace", "var", "variables"}
 
-	re := regexp.MustCompile(`\$\{.*\}`)
+func (f *validateScripts) Apply(ctx context.Context, b *bundle.Bundle) diag.Diagnostics {
+	var diags diag.Diagnostics
 
 	// Sort the scripts to have a deterministic order for the
 	// generated diagnostics.
@@ -33,33 +38,74 @@ func (f *validateScripts) Apply(ctx context.Context, b *bundle.Bundle) diag.Diag
 
 	for _, k := range scriptKeys {
 		script := b.Config.Scripts[k]
-		p := dyn.NewPath(dyn.Key("scripts"), dyn.Key(k), dyn.Key("content"))
+		contentPath := dyn.NewPath(dyn.Key("scripts"), dyn.Key(k), dyn.Key("content"))
 
 		if script.Content == "" {
 			diags = append(diags, diag.Diagnostic{
 				Severity: diag.Error,
 				Summary:  fmt.Sprintf("Script %s has no content", k),
-				Paths:    []dyn.Path{p},
+				Paths:    []dyn.Path{contentPath},
 			})
 			continue
 		}
 
-		v, err := dyn.GetByPath(b.Config.Value(), p)
-		if err != nil {
-			return diags.Extend(diag.FromErr(err))
+		diags = diags.Extend(validateScriptContent(b, k, script.Content, contentPath))
+		diags = diags.Extend(validateScriptEnv(b, k, script.Env))
+	}
+
+	return diags
+}
+
+// validateScriptContent rejects any ${...} reference in a script's content.
+// Content is passed to the shell as-is, so ${...} would be ambiguous with a
+// bundle reference; reference a declared env entry with $NAME instead.
+func validateScriptContent(b *bundle.Bundle, key, content string, p dyn.Path) diag.Diagnostics {
+	ref, ok := dynvar.NewRef(dyn.V(content))
+	if !ok {
+		return nil
+	}
+
+	first := ref.Matches[0][0]
+	v, _ := dyn.GetByPath(b.Config.Value(), p)
+	return diag.Diagnostics{{
+		Severity: diag.Error,
+		Summary:  fmt.Sprintf("Found %s in script %s.content. Interpolation syntax ${...} is not supported in script content", first, key),
+		Detail: `The ${...} syntax is not allowed in script content. To use a bundle value,
+declare an environment variable in the script's "env:" section and reference it
+from "content" with $NAME:
+
+  scripts:
+    ` + key + `:
+      env:
+        MY_VAR: ${var.foo}
+      content: echo "$MY_VAR"`,
+		Locations: v.Locations(),
+		Paths:     []dyn.Path{p},
+	}}
+}
+
+func validateScriptEnv(b *bundle.Bundle, key string, env map[string]string) diag.Diagnostics {
+	var diags diag.Diagnostics
+
+	for _, name := range slices.Sorted(maps.Keys(env)) {
+		ref, ok := dynvar.NewRef(dyn.V(env[name]))
+		if !ok {
+			continue
 		}
 
-		// Check for interpolation syntax
-		match := re.FindString(script.Content)
-		if match != "" {
+		envValuePath := dyn.NewPath(dyn.Key("scripts"), dyn.Key(key), dyn.Key("env"), dyn.Key(name))
+		v, _ := dyn.GetByPath(b.Config.Value(), envValuePath)
+
+		for _, refPath := range ref.References() {
+			prefix, _, _ := strings.Cut(refPath, ".")
+			if slices.Contains(allowedEnvRefPrefixes, prefix) {
+				continue
+			}
 			diags = append(diags, diag.Diagnostic{
-				Severity: diag.Error,
-				Summary:  fmt.Sprintf("Found %s in script %s. Interpolation syntax ${...} is not allowed in scripts", match, k),
-				Detail: `We do not support the ${...} interpolation syntax in scripts because
-it's ambiguous whether it's a variable reference or reference to an
-environment variable.`,
+				Severity:  diag.Error,
+				Summary:   fmt.Sprintf("${%s} cannot be used in scripts.%s.env.%s; only ${bundle.*}, ${workspace.*}, and ${var.*} are resolved before scripts execute", refPath, key, name),
 				Locations: v.Locations(),
-				Paths:     []dyn.Path{p},
+				Paths:     []dyn.Path{envValuePath},
 			})
 		}
 	}
diff --git a/bundle/internal/schema/annotations.yml b/bundle/internal/schema/annotations.yml
index 69d7c9d025d..467cefea3e8 100644
--- a/bundle/internal/schema/annotations.yml
+++ b/bundle/internal/schema/annotations.yml
@@ -373,6 +373,9 @@ github.com/databricks/cli/bundle/config.Script:
   "content":
     "description": |-
       PLACEHOLDER
+  "env":
+    "description": |-
+      PLACEHOLDER
 github.com/databricks/cli/bundle/config.Sync:
   "exclude":
     "description": |-
diff --git a/bundle/schema/jsonschema.json b/bundle/schema/jsonschema.json
index f88a9389348..b9c06d0e4d2 100644
--- a/bundle/schema/jsonschema.json
+++ b/bundle/schema/jsonschema.json
@@ -2823,6 +2823,9 @@
                   "properties": {
                     "content": {
                       "$ref": "#/$defs/string"
+                    },
+                    "env": {
+                      "$ref": "#/$defs/map/string"
                     }
                   },
                   "additionalProperties": false,
diff --git a/cmd/bundle/run.go b/cmd/bundle/run.go
index e98fe59ac4e..684acd3567f 100644
--- a/cmd/bundle/run.go
+++ b/cmd/bundle/run.go
@@ -10,6 +10,7 @@ import (
 	"slices"
 
 	"github.com/databricks/cli/bundle"
+	"github.com/databricks/cli/bundle/config"
 	"github.com/databricks/cli/bundle/env"
 	"github.com/databricks/cli/bundle/resources"
 	"github.com/databricks/cli/bundle/run"
@@ -165,7 +166,7 @@ Example usage:
 					if len(runArgs) > 0 {
 						return fmt.Errorf("additional arguments are not supported for scripts. Got: %v. We recommend using environment variables to pass runtime arguments to a script. For example: FOO=bar databricks bundle run my_script", runArgs)
 					}
-					return executeScript(b.Config.Scripts[key].Content, cmd, b)
+					return executeScript(b.Config.Scripts[key], cmd, b)
 				}
 
 				return nil
@@ -276,8 +277,14 @@ func scriptEnv(cmd *cobra.Command, b *bundle.Bundle) []string {
 	return out
 }
 
-func executeScript(content string, cmd *cobra.Command, b *bundle.Bundle) error {
-	return execv.Shell(content, b.BundleRootPath, scriptEnv(cmd, b))
+func executeScript(script config.Script, cmd *cobra.Command, b *bundle.Bundle) error {
+	env := scriptEnv(cmd, b)
+	// Append after the auth/target variables so a script's env: section takes
+	// precedence on collision (os/exec uses the last value for a duplicate key).
+	for _, name := range slices.Sorted(maps.Keys(script.Env)) {
+		env = append(env, name+"="+script.Env[name])
+	}
+	return execv.Shell(script.Content, b.BundleRootPath, env)
 }
 
 func executeInline(cmd *cobra.Command, args []string, b *bundle.Bundle) error {

From 46a34af273e579e80db53c13b9a59fc4dcf585ae Mon Sep 17 00:00:00 2001
From: Shreyas Goenka <shreyas.goenka@databricks.com>
Date: Tue, 7 Jul 2026 00:33:09 +0200
Subject: [PATCH 2/3] Merge origin/main into script-env-section

Fix the earlier bad merge in NEXT_CHANGELOG.md: the prior merge
resurrected Bundles entries that had already been swept into the
v1.6.0 release. Reset the changelog to origin/main and re-added only
the scripts env entry.

Co-authored-by: Isaac
---
 NEXT_CHANGELOG.md | 11 ++---------
 1 file changed, 2 insertions(+), 9 deletions(-)

diff --git a/NEXT_CHANGELOG.md b/NEXT_CHANGELOG.md
index e369b1937d6..b8ed0ddf880 100644
--- a/NEXT_CHANGELOG.md
+++ b/NEXT_CHANGELOG.md
@@ -9,18 +9,11 @@
 * An explicitly selected profile (`--profile` or a bundle's `workspace.profile`) now takes precedence over auth environment variables (`DATABRICKS_HOST`, `DATABRICKS_TOKEN`, etc.) instead of being silently shadowed by them; env vars still fill auth fields the profile leaves empty ([#5096](https://github.com/databricks/cli/issues/5096)).
 
 ### Bundles
-* Remove API enum values and types that are still in development from the `databricks-bundles` Python package; these were never accepted by the backend ([#5484](https://github.com/databricks/cli/pull/5484)).
-* direct: Fix resolving a resource reference that is used more than once within the same field ([#5558](https://github.com/databricks/cli/pull/5558)).
-* Bundle variable references now accept Unicode letters in path segments (e.g. `${var.变量}`). ([#5532](https://github.com/databricks/cli/pull/5532))
-* Ignore remote changes for vector search direct_access_index_spec.schema_json to prevent drift when the backend normalizes the schema ([#5481](https://github.com/databricks/cli/pull/5481)).
-* Remove hidden, never-functional `--existing-dashboard-id`, `--existing-dashboard-path`, `--existing-alert-id`, and `--existing-genie-space-id` alias flags from `bundle generate`; use the documented `--existing-id` / `--existing-path` flags instead ([#5591](https://github.com/databricks/cli/pull/5591)).
-* engine/direct: Fix WAL corruption after two consecutive failed deploys ([#5606](https://github.com/databricks/cli/pull/5606)).
-* engine/direct: Don't open the deployment state WAL when a deploy's plan fails ([#5607](https://github.com/databricks/cli/pull/5607)).
-* Ignore unity catalog managed schema property defaults to avoid unnecessary drift ([#5195](https://github.com/databricks/cli/pull/5195)).
-* Added an `env:` section to `scripts.<name>` for declaring environment variables that may reference `${bundle.*}`, `${workspace.*}`, and `${var.*}` ([#4179](https://github.com/databricks/cli/issues/4179)).
+
 * Fix permissions added to a job or pipeline by a Python (PyDABs) mutator failing to deploy with "must have exactly one owner"; the deploying identity is now set as owner, matching resources whose permissions are declared in YAML ([#5821](https://github.com/databricks/cli/pull/5821)).
 * Remove duplicate enum values for jsonschema.json ([#5839](https://github.com/databricks/cli/pull/5839)).
 * direct: volumes: support `volume_path` property ([#5550](https://github.com/databricks/cli/pull/5550)).
+* Added an `env:` section to `scripts.<name>` for declaring environment variables that may reference `${bundle.*}`, `${workspace.*}`, and `${var.*}` ([#4179](https://github.com/databricks/cli/issues/4179)).
 
 ### Dependency updates
 

From 7b31901b3d7f7d101c639375e1891bcf89a42db5 Mon Sep 17 00:00:00 2001
From: Shreyas Goenka <shreyas.goenka@databricks.com>
Date: Fri, 10 Jul 2026 11:48:10 +0200
Subject: [PATCH 3/3] Address review: env schema description, musterr, env
 precedence test

- Add a real description for scripts.<name>.env in annotations.yml so it
  surfaces in jsonschema tooltips (regenerated jsonschema.json).
- Use musterr instead of errcode in the env-bad-prefix script to assert
  the command must fail.
- Add an env-precedence acceptance test proving a script's env: entry
  overrides a CLI-injected variable (DATABRICKS_BUNDLE_TARGET).

Co-authored-by: Isaac
---
 .../bundle/run/scripts/env-bad-prefix/output.txt   |  2 --
 .../bundle/run/scripts/env-bad-prefix/script       |  2 +-
 .../run/scripts/env-precedence/databricks.yml      | 14 ++++++++++++++
 .../run/scripts/env-precedence/out.test.toml       |  3 +++
 .../bundle/run/scripts/env-precedence/output.txt   |  3 +++
 .../bundle/run/scripts/env-precedence/script       |  1 +
 .../bundle/run/scripts/env-precedence/test.toml    |  5 +++++
 bundle/internal/schema/annotations.yml             |  2 +-
 bundle/schema/jsonschema.json                      |  1 +
 9 files changed, 29 insertions(+), 4 deletions(-)
 create mode 100644 acceptance/bundle/run/scripts/env-precedence/databricks.yml
 create mode 100644 acceptance/bundle/run/scripts/env-precedence/out.test.toml
 create mode 100644 acceptance/bundle/run/scripts/env-precedence/output.txt
 create mode 100644 acceptance/bundle/run/scripts/env-precedence/script
 create mode 100644 acceptance/bundle/run/scripts/env-precedence/test.toml

diff --git a/acceptance/bundle/run/scripts/env-bad-prefix/output.txt b/acceptance/bundle/run/scripts/env-bad-prefix/output.txt
index 239578fe563..fe3b3f27bfc 100644
--- a/acceptance/bundle/run/scripts/env-bad-prefix/output.txt
+++ b/acceptance/bundle/run/scripts/env-bad-prefix/output.txt
@@ -12,5 +12,3 @@ Name: script-env-bad-prefix
 Target: default
 
 Found 2 errors
-
-Exit code: 1
diff --git a/acceptance/bundle/run/scripts/env-bad-prefix/script b/acceptance/bundle/run/scripts/env-bad-prefix/script
index f52b452ee67..277355fe918 100644
--- a/acceptance/bundle/run/scripts/env-bad-prefix/script
+++ b/acceptance/bundle/run/scripts/env-bad-prefix/script
@@ -1 +1 @@
-errcode trace $CLI bundle validate
+musterr trace $CLI bundle validate
diff --git a/acceptance/bundle/run/scripts/env-precedence/databricks.yml b/acceptance/bundle/run/scripts/env-precedence/databricks.yml
new file mode 100644
index 00000000000..504d7dc07d8
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-precedence/databricks.yml
@@ -0,0 +1,14 @@
+bundle:
+  name: script-env-precedence
+
+targets:
+  default:
+    default: true
+
+# A script's env: entry must win over the DATABRICKS_BUNDLE_TARGET variable the
+# CLI injects into the script process (executeScript appends env: last).
+scripts:
+  show_target:
+    env:
+      DATABRICKS_BUNDLE_TARGET: from-script-env
+    content: echo "target=$DATABRICKS_BUNDLE_TARGET"
diff --git a/acceptance/bundle/run/scripts/env-precedence/out.test.toml b/acceptance/bundle/run/scripts/env-precedence/out.test.toml
new file mode 100644
index 00000000000..f784a183258
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-precedence/out.test.toml
@@ -0,0 +1,3 @@
+Local = true
+Cloud = false
+EnvMatrix.DATABRICKS_BUNDLE_ENGINE = ["terraform", "direct"]
diff --git a/acceptance/bundle/run/scripts/env-precedence/output.txt b/acceptance/bundle/run/scripts/env-precedence/output.txt
new file mode 100644
index 00000000000..6155dd27777
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-precedence/output.txt
@@ -0,0 +1,3 @@
+
+>>> [CLI] bundle run show_target
+target=from-script-env
diff --git a/acceptance/bundle/run/scripts/env-precedence/script b/acceptance/bundle/run/scripts/env-precedence/script
new file mode 100644
index 00000000000..d3972eef664
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-precedence/script
@@ -0,0 +1 @@
+trace $CLI bundle run show_target
diff --git a/acceptance/bundle/run/scripts/env-precedence/test.toml b/acceptance/bundle/run/scripts/env-precedence/test.toml
new file mode 100644
index 00000000000..c2bbdaa30cf
--- /dev/null
+++ b/acceptance/bundle/run/scripts/env-precedence/test.toml
@@ -0,0 +1,5 @@
+Local = true
+Cloud = false
+
+[EnvMatrix]
+DATABRICKS_BUNDLE_ENGINE = ["terraform", "direct"]
diff --git a/bundle/internal/schema/annotations.yml b/bundle/internal/schema/annotations.yml
index 242dfed1839..1ba942b5bfc 100644
--- a/bundle/internal/schema/annotations.yml
+++ b/bundle/internal/schema/annotations.yml
@@ -1973,7 +1973,7 @@ scripts:
         PLACEHOLDER
     "env":
       "description": |-
-        PLACEHOLDER
+        A map of environment variables to export when running the script. Values may reference `${bundle.*}`, `${workspace.*}`, and `${var.*}` and are resolved before the script runs; reference them from `content` with `$NAME`.
 sync:
   "description": |-
     The files and file paths to include or exclude in the bundle.
diff --git a/bundle/schema/jsonschema.json b/bundle/schema/jsonschema.json
index 5a3f1890ecc..2528ca11cc1 100644
--- a/bundle/schema/jsonschema.json
+++ b/bundle/schema/jsonschema.json
@@ -3074,6 +3074,7 @@
                       "$ref": "#/$defs/string"
                     },
                     "env": {
+                      "description": "A map of environment variables to export when running the script. Values may reference `${bundle.*}`, `${workspace.*}`, and `${var.*}` and are resolved before the script runs; reference them from `content` with `$NAME`.",
                       "$ref": "#/$defs/map/string"
                     }
                   },