bundle: warn during deploy when workspace folder permissions exceed the bundle's

shreyas-goenka · shreyas-goenka · commit bf9f878a49c7 · 2026-06-10T12:37:20.000+02:00
ValidateFolderPermissions already compares the live workspace ACL against the
declared permissions, but it only runs during `bundle validate`. This brings the
same check to `bundle deploy` without adding any API latency: ApplyWorkspaceRoot-
Permissions already calls SetPermissions on each workspace path prefix (root_path
and, when separate, state_path), and the response carries the resulting ACL.

Reusing that response, we compare against the declared permissions. Because the
Set replaces the folder's direct ACL with the declared set, any principal still
showing higher access is inherited from a parent folder — the broader access that
actually persists after deploy, which is the scope mismatch worth surfacing.

Three telemetry signals are recorded in bool_values during deploy:
- state_path_acl_exceeds_permissions: whether the folder holding the deployment
  state grants more access than the permissions section declares. True by
  definition when no permissions are declared; determined statically for
  /Workspace/Shared state folders (all users have read/write) and from the live
  SetPermissions response otherwise.
- state_path_is_shared: state_path is under /Workspace/Shared.
- permissions_section_is_set: the bundle declares top-level permissions.

Covered by acceptance tests (no permissions / clean ACL / shared state path, and
an inherited-ACL mismatch staged via a server override) instead of unit tests.

Co-authored-by: Shreyas Goenka &lt;shreyas.goenka@databricks.com&gt;
diff --git a/NEXT_CHANGELOG.md b/NEXT_CHANGELOG.md
@@ -7,6 +7,7 @@
 ### CLI
 
 ### Bundles
+* Warn during `bundle deploy` when a workspace folder used by the bundle grants broader permissions than the bundle's top-level `permissions` section declares, for example through permissions inherited from a parent folder ([#5439](https://github.com/databricks/cli/pull/5439)).
 
 ### Dependency updates
 
diff --git a/acceptance/bundle/resource_deps/job_tasks/out.telemetry.direct.txt b/acceptance/bundle/resource_deps/job_tasks/out.telemetry.direct.txt
@@ -4,9 +4,12 @@ has_classic_job_compute false
 has_serverless_compute true
 local.cache.attempt true
 local.cache.miss true
+permissions_section_is_set false
 presets_name_prefix_is_set false
 python_wheel_wrapper_is_set false
 resref_jobs.tags.* true
 resreferr_jobs.task true
 run_as_set false
 skip_artifact_cleanup false
+state_path_acl_exceeds_permissions true
+state_path_is_shared false
diff --git a/acceptance/bundle/resource_deps/job_tasks/out.telemetry.terraform.txt b/acceptance/bundle/resource_deps/job_tasks/out.telemetry.terraform.txt
@@ -4,9 +4,12 @@ has_classic_job_compute false
 has_serverless_compute true
 local.cache.attempt true
 local.cache.miss true
+permissions_section_is_set false
 presets_name_prefix_is_set false
 python_wheel_wrapper_is_set false
 resref_jobs.tags.* true
 resreferr_jobs.task true
 run_as_set false
 skip_artifact_cleanup false
+state_path_acl_exceeds_permissions true
+state_path_is_shared false
diff --git a/acceptance/bundle/resource_deps/resources_var/output.txt b/acceptance/bundle/resource_deps/resources_var/output.txt
@@ -42,10 +42,13 @@ has_classic_job_compute false
 has_serverless_compute false
 local.cache.attempt true
 local.cache.hit true
+permissions_section_is_set false
 presets_name_prefix_is_set true
 python_wheel_wrapper_is_set false
 resref_volumes.catalog_name true
 resref_volumes.name true
 resref_volumes.schema_name true
 run_as_set false
 skip_artifact_cleanup false
+state_path_acl_exceeds_permissions true
+state_path_is_shared false
diff --git a/acceptance/bundle/resource_deps/tf_path_only_error/out.telemetry.terraform.txt b/acceptance/bundle/resource_deps/tf_path_only_error/out.telemetry.terraform.txt
@@ -5,8 +5,11 @@ has_serverless_compute false
 has_tf_only_references true
 local.cache.attempt true
 local.cache.hit true
+permissions_section_is_set false
 presets_name_prefix_is_set false
 python_wheel_wrapper_is_set false
 resref_jobs.always_running true
 run_as_set false
 skip_artifact_cleanup false
+state_path_acl_exceeds_permissions true
+state_path_is_shared false
diff --git a/acceptance/bundle/telemetry/deploy-app-lifecycle-started/output.txt b/acceptance/bundle/telemetry/deploy-app-lifecycle-started/output.txt
@@ -37,6 +37,18 @@ Deployment complete!
       "key": "skip_artifact_cleanup",
       "value": false
     },
+    {
+      "key": "permissions_section_is_set",
+      "value": false
+    },
+    {
+      "key": "state_path_is_shared",
+      "value": false
+    },
+    {
+      "key": "state_path_acl_exceeds_permissions",
+      "value": true
+    },
     {
       "key": "has_serverless_compute",
       "value": false
diff --git a/acceptance/bundle/telemetry/deploy-compute-type/output.txt b/acceptance/bundle/telemetry/deploy-compute-type/output.txt
@@ -41,6 +41,18 @@ Deployment complete!
     "key": "skip_artifact_cleanup",
     "value": false
   },
+  {
+    "key": "permissions_section_is_set",
+    "value": false
+  },
+  {
+    "key": "state_path_is_shared",
+    "value": false
+  },
+  {
+    "key": "state_path_acl_exceeds_permissions",
+    "value": true
+  },
   {
     "key": "has_serverless_compute",
     "value": true
@@ -83,6 +95,18 @@ Deployment complete!
     "key": "skip_artifact_cleanup",
     "value": false
   },
+  {
+    "key": "permissions_section_is_set",
+    "value": false
+  },
+  {
+    "key": "state_path_is_shared",
+    "value": false
+  },
+  {
+    "key": "state_path_acl_exceeds_permissions",
+    "value": true
+  },
   {
     "key": "has_serverless_compute",
     "value": true
diff --git a/acceptance/bundle/telemetry/deploy-experimental/output.txt b/acceptance/bundle/telemetry/deploy-experimental/output.txt
@@ -40,6 +40,18 @@ Deployment complete!
       "key": "skip_artifact_cleanup",
       "value": false
     },
+    {
+      "key": "permissions_section_is_set",
+      "value": false
+    },
+    {
+      "key": "state_path_is_shared",
+      "value": false
+    },
+    {
+      "key": "state_path_acl_exceeds_permissions",
+      "value": true
+    },
     {
       "key": "has_serverless_compute",
       "value": false
diff --git a/acceptance/bundle/telemetry/deploy-name-prefix/custom/output.txt b/acceptance/bundle/telemetry/deploy-name-prefix/custom/output.txt
@@ -36,6 +36,18 @@ Deployment complete!
       "key": "skip_artifact_cleanup",
       "value": false
     },
+    {
+      "key": "permissions_section_is_set",
+      "value": false
+    },
+    {
+      "key": "state_path_is_shared",
+      "value": false
+    },
+    {
+      "key": "state_path_acl_exceeds_permissions",
+      "value": true
+    },
     {
       "key": "has_serverless_compute",
       "value": false
diff --git a/acceptance/bundle/telemetry/deploy-name-prefix/mode-development/output.txt b/acceptance/bundle/telemetry/deploy-name-prefix/mode-development/output.txt
@@ -36,6 +36,18 @@ Deployment complete!
       "key": "skip_artifact_cleanup",
       "value": false
     },
+    {
+      "key": "permissions_section_is_set",
+      "value": false
+    },
+    {
+      "key": "state_path_is_shared",
+      "value": false
+    },
+    {
+      "key": "state_path_acl_exceeds_permissions",
+      "value": true
+    },
     {
       "key": "has_serverless_compute",
       "value": false
diff --git a/acceptance/bundle/telemetry/deploy-whl-artifacts/output.txt b/acceptance/bundle/telemetry/deploy-whl-artifacts/output.txt
@@ -40,6 +40,18 @@ Deployment complete!
       "key": "skip_artifact_cleanup",
       "value": false
     },
+    {
+      "key": "permissions_section_is_set",
+      "value": false
+    },
+    {
+      "key": "state_path_is_shared",
+      "value": false
+    },
+    {
+      "key": "state_path_acl_exceeds_permissions",
+      "value": true
+    },
     {
       "key": "has_serverless_compute",
       "value": false
@@ -84,6 +96,18 @@ Deployment complete!
       "key": "skip_artifact_cleanup",
       "value": true
     },
+    {
+      "key": "permissions_section_is_set",
+      "value": false
+    },
+    {
+      "key": "state_path_is_shared",
+      "value": false
+    },
+    {
+      "key": "state_path_acl_exceeds_permissions",
+      "value": true
+    },
     {
       "key": "has_serverless_compute",
       "value": false
diff --git a/acceptance/bundle/telemetry/deploy-workspace-folder-permissions-acl-mismatch/databricks.yml b/acceptance/bundle/telemetry/deploy-workspace-folder-permissions-acl-mismatch/databricks.yml
@@ -0,0 +1,6 @@
+bundle:
+  name: test-bundle
+
+permissions:
+  - user_name: ${workspace.current_user.userName}
+    level: CAN_MANAGE
diff --git a/acceptance/bundle/telemetry/deploy-workspace-folder-permissions-acl-mismatch/out.test.toml b/acceptance/bundle/telemetry/deploy-workspace-folder-permissions-acl-mismatch/out.test.toml
diff --git a/acceptance/bundle/telemetry/deploy-workspace-folder-permissions-acl-mismatch/output.txt b/acceptance/bundle/telemetry/deploy-workspace-folder-permissions-acl-mismatch/output.txt
@@ -0,0 +1,18 @@
+
+>>> [CLI] bundle deploy
+Uploading bundle files to /Workspace/Users/[USERNAME]/.bundle/test-bundle/default/files...
+Warning: workspace folder has permissions not configured in bundle
+
+The following permissions apply to the workspace folder at "/Workspace/Users/[USERNAME]/.bundle/test-bundle/default" but are not configured in the bundle:
+- level: CAN_MANAGE, group_name: data-engineers
+
+Add them to your bundle permissions or remove them from the folder.
+See https://docs.databricks.com/dev-tools/bundles/permissions
+
+Deploying resources...
+Deployment complete!
+
+>>> print_telemetry_bool_values
+permissions_section_is_set true
+state_path_acl_exceeds_permissions true
+state_path_is_shared false
diff --git a/acceptance/bundle/telemetry/deploy-workspace-folder-permissions-acl-mismatch/script b/acceptance/bundle/telemetry/deploy-workspace-folder-permissions-acl-mismatch/script
@@ -0,0 +1,3 @@
+trace $CLI bundle deploy
+trace print_telemetry_bool_values | grep -E "state_path|permissions_section"
+rm out.requests.txt
diff --git a/acceptance/bundle/telemetry/deploy-workspace-folder-permissions-acl-mismatch/test.toml b/acceptance/bundle/telemetry/deploy-workspace-folder-permissions-acl-mismatch/test.toml
@@ -0,0 +1,25 @@
+# Simulate a workspace folder that inherits broader access from a parent folder:
+# SetPermissions replaces the direct ACL with the declared permissions, but the
+# response still shows an inherited CAN_MANAGE for a group the bundle does not
+# declare. The default test server echoes the request ACL back, so this scenario
+# requires a custom response.
+[[Server]]
+Pattern = "PUT /api/2.0/permissions/directories/{object_id}"
+Response.Body = '''
+{
+  "object_id": "/directories/1234",
+  "object_type": "directory",
+  "access_control_list": [
+    {
+      "group_name": "data-engineers",
+      "all_permissions": [
+        {
+          "permission_level": "CAN_MANAGE",
+          "inherited": true,
+          "inherited_from_object": ["/directories/42"]
+        }
+      ]
+    }
+  ]
+}
+'''
diff --git a/acceptance/bundle/telemetry/deploy-workspace-folder-permissions/databricks.yml b/acceptance/bundle/telemetry/deploy-workspace-folder-permissions/databricks.yml
@@ -0,0 +1,35 @@
+bundle:
+  name: test-bundle
+
+targets:
+  # No top-level permissions: the workspace folder permission sync is skipped
+  # entirely, so only the static signals are recorded.
+  no_permissions:
+    default: true
+
+  # Permissions configured: the deploy sets folder ACLs and compares the response
+  # against the declared permissions. The test server echoes the request ACL back,
+  # so the live check finds no mismatch.
+  with_permissions:
+    permissions:
+      - user_name: ${workspace.current_user.userName}
+        level: CAN_MANAGE
+
+  # state_path is a separate folder in /Workspace/Shared: permission sync skips
+  # shared folders, so the scope verdict is determined statically. All workspace
+  # users can write to the state and that is not declared in permissions.
+  shared_state_path:
+    permissions:
+      - user_name: ${workspace.current_user.userName}
+        level: CAN_MANAGE
+    workspace:
+      state_path: /Workspace/Shared/test-bundle-state
+
+  # state_path explicitly set to a separate, non-shared folder: the live ACL check
+  # runs against state_path's own folder instead of root_path.
+  custom_state_path:
+    permissions:
+      - user_name: ${workspace.current_user.userName}
+        level: CAN_MANAGE
+    workspace:
+      state_path: /Workspace/Users/${workspace.current_user.userName}/custom-test-bundle-state
diff --git a/acceptance/bundle/telemetry/deploy-workspace-folder-permissions/out.test.toml b/acceptance/bundle/telemetry/deploy-workspace-folder-permissions/out.test.toml
diff --git a/acceptance/bundle/telemetry/deploy-workspace-folder-permissions/output.txt b/acceptance/bundle/telemetry/deploy-workspace-folder-permissions/output.txt
@@ -0,0 +1,44 @@
+
+>>> [CLI] bundle deploy -t no_permissions
+Uploading bundle files to /Workspace/Users/[USERNAME]/.bundle/test-bundle/no_permissions/files...
+Deploying resources...
+Deployment complete!
+
+>>> print_telemetry_bool_values
+permissions_section_is_set false
+state_path_acl_exceeds_permissions true
+state_path_is_shared false
+
+>>> [CLI] bundle deploy -t with_permissions
+Uploading bundle files to /Workspace/Users/[USERNAME]/.bundle/test-bundle/with_permissions/files...
+Deploying resources...
+Deployment complete!
+
+>>> print_telemetry_bool_values
+permissions_section_is_set true
+state_path_acl_exceeds_permissions false
+state_path_is_shared false
+
+>>> [CLI] bundle deploy -t shared_state_path
+Warning: the bundle state path /Workspace/Shared/test-bundle-state is writable by all workspace users
+
+The bundle state path is in /Workspace/Shared, giving read/write access to all workspace users that is not reflected in the permissions section. If this is intentional, add CAN_MANAGE for 'group_name: users' to your bundle permissions. Otherwise, move the state path to a restricted location such as /Workspace/Users/<username>.
+
+Uploading bundle files to /Workspace/Users/[USERNAME]/.bundle/test-bundle/shared_state_path/files...
+Deploying resources...
+Deployment complete!
+
+>>> print_telemetry_bool_values
+permissions_section_is_set true
+state_path_acl_exceeds_permissions true
+state_path_is_shared true
+
+>>> [CLI] bundle deploy -t custom_state_path
+Uploading bundle files to /Workspace/Users/[USERNAME]/.bundle/test-bundle/custom_state_path/files...
+Deploying resources...
+Deployment complete!
+
+>>> print_telemetry_bool_values
+permissions_section_is_set true
+state_path_acl_exceeds_permissions false
+state_path_is_shared false
diff --git a/acceptance/bundle/telemetry/deploy-workspace-folder-permissions/script b/acceptance/bundle/telemetry/deploy-workspace-folder-permissions/script
@@ -0,0 +1,15 @@
+trace $CLI bundle deploy -t no_permissions
+trace print_telemetry_bool_values | grep -E "state_path|permissions_section"
+rm out.requests.txt
+
+trace $CLI bundle deploy -t with_permissions
+trace print_telemetry_bool_values | grep -E "state_path|permissions_section"
+rm out.requests.txt
+
+trace $CLI bundle deploy -t shared_state_path
+trace print_telemetry_bool_values | grep -E "state_path|permissions_section"
+rm out.requests.txt
+
+trace $CLI bundle deploy -t custom_state_path
+trace print_telemetry_bool_values | grep -E "state_path|permissions_section"
+rm out.requests.txt
diff --git a/acceptance/bundle/telemetry/deploy/out.telemetry.txt b/acceptance/bundle/telemetry/deploy/out.telemetry.txt
@@ -70,6 +70,18 @@
               "key": "skip_artifact_cleanup",
               "value": false
             },
+            {
+              "key": "permissions_section_is_set",
+              "value": false
+            },
+            {
+              "key": "state_path_is_shared",
+              "value": false
+            },
+            {
+              "key": "state_path_acl_exceeds_permissions",
+              "value": true
+            },
             {
               "key": "has_serverless_compute",
               "value": false
diff --git a/bundle/metrics/metrics.go b/bundle/metrics/metrics.go
diff --git a/bundle/permissions/workspace_root.go b/bundle/permissions/workspace_root.go
diff --git a/bundle/permissions/workspace_root_test.go b/bundle/permissions/workspace_root_test.go
