docs(group): fix writable_environment_categories and clean up dbtcloud_group descriptions

gravelbit · gravelbit · commit ea679c57efac · 2026-05-08T18:29:04.000+03:00
Omitting writable_environment_categories grants no Write access — not
Write access to all environments as the docs claimed. Use ["all"] to
grant Write access everywhere. Same fix applied to group_partial_permissions,
the two SCIM resources, and service_token.

Also fixed copy-paste leftovers on dbtcloud_group: bad cross-reference
to a non-existent partial resource, partial-permissions wording in the
group_permissions block description, and a self-referential
permission_set description.
diff --git a/.changes/unreleased/Documentation-20260508-182833.yaml b/.changes/unreleased/Documentation-20260508-182833.yaml
@@ -0,0 +1,3 @@
+kind: Documentation
+body: Fixed `writable_environment_categories` description on group, partial permissions, SCIM and service token resources to reflect that omitting the value grants no Write access (use `["all"]` instead). Also cleaned up a few copy-paste doc strings on `dbtcloud_group`.
+time: 2026-05-08T18:28:33.548537+03:00
diff --git a/docs/data-sources/service_token.md b/docs/data-sources/service_token.md
@@ -37,5 +37,5 @@ Read-Only:
 - `writable_environment_categories` (Set of String) What types of environments to apply Write permissions to.
 Even if Write access is restricted to some environment types, the permission set will have Read access to all environments.
 The values allowed are `all`, `development`, `staging`, `production` and `other`.
-Not setting a value is the same as selecting `all`.
+Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to `["all"]`.
 Not all permission sets support environment level write settings, only `analyst`, `database_admin`, `developer`, `git_admin` and `team_admin`.
diff --git a/docs/resources/group.md b/docs/resources/group.md
@@ -2,7 +2,7 @@
 page_title: "dbtcloud_group Resource - dbtcloud"
 subcategory: ""
 description: |-
-  Provide a complete set of permissions for a group. This is different from dbt_cloud_partial_group_permissions.
+  Provide a complete set of permissions for a group. This is different from dbtcloud_group_partial_permissions.
   With this resource type only one resource can be used to manage the permissions for a given group.
 ---
 
@@ -39,7 +39,7 @@ The mapping of permission names [from the docs](https://docs.getdbt.com/docs/clo
 |Webhooks Only | webhooks_only|
 
 
-Provide a complete set of permissions for a group. This is different from `dbt_cloud_partial_group_permissions`.
+Provide a complete set of permissions for a group. This is different from `dbtcloud_group_partial_permissions`.
 
 With this resource type only one resource can be used to manage the permissions for a given group.
 
@@ -71,7 +71,7 @@ resource "dbtcloud_group" "tf_group_1" {
 ### Optional
 
 - `assign_by_default` (Boolean) Whether the group will be assigned by default to users. The value needs to be the same for all partial permissions for the same group.
-- `group_permissions` (Block Set) Partial permissions for the group. Those permissions will be added/removed when config is added/removed. (see [below for nested schema](#nestedblock--group_permissions))
+- `group_permissions` (Block Set) The complete set of permissions to apply to the group. Each block defines one permission set; remove or modify blocks to adjust the group's permissions. (see [below for nested schema](#nestedblock--group_permissions))
 - `sso_mapping_groups` (Set of String) Mapping groups from the IdP. At the moment the complete list needs to be provided in each partial permission for the same group.
 
 ### Read-Only
@@ -84,15 +84,15 @@ resource "dbtcloud_group" "tf_group_1" {
 Required:
 
 - `all_projects` (Boolean) Whether access should be provided for all projects or not.
-- `permission_set` (String) Set of permissions to apply. The permissions allowed are the same as the ones for the `dbtcloud_group` resource.
+- `permission_set` (String) The permission set to apply (e.g. `developer`, `analyst`, `account_admin`). See the table at the top of this page for the full list of permission codes.
 
 Optional:
 
 - `project_id` (Number) Project ID to apply this permission to for this group.
-- `writable_environment_categories` (Set of String) What types of environments to apply Write permissions to. 
-Even if Write access is restricted to some environment types, the permission set will have Read access to all environments. 
-The values allowed are `all`, `development`, `staging`, `production` and `other`. 
-Not setting a value is the same as selecting `all`. 
+- `writable_environment_categories` (Set of String) What types of environments to apply Write permissions to.
+Even if Write access is restricted to some environment types, the permission set will have Read access to all environments.
+The values allowed are `all`, `development`, `staging`, `production` and `other`.
+Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to `["all"]`.
 Not all permission sets support environment level write settings, only `analyst`, `database_admin`, `developer`, `git_admin` and `team_admin`.
 
 ## Import
diff --git a/docs/resources/group_partial_permissions.md b/docs/resources/group_partial_permissions.md
@@ -100,5 +100,5 @@ Optional:
 - `writable_environment_categories` (Set of String) What types of environments to apply Write permissions to. 
 Even if Write access is restricted to some environment types, the permission set will have Read access to all environments. 
 The values allowed are `all`, `development`, `staging`, `production` and `other`. 
-Not setting a value is the same as selecting `all`. 
+Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to `["all"]`. 
 Not all permission sets support environment level write settings, only `analyst`, `database_admin`, `developer`, `git_admin` and `team_admin`.
diff --git a/docs/resources/scim_group_partial_permissions.md b/docs/resources/scim_group_partial_permissions.md
@@ -292,7 +292,7 @@ Optional:
 - `writable_environment_categories` (Set of String) What types of environments to apply Write permissions to. 
 Even if Write access is restricted to some environment types, the permission set will have Read access to all environments. 
 The values allowed are `all`, `development`, `staging`, `production` and `other`. 
-Not setting a value is the same as selecting `all`. 
+Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to `["all"]`. 
 Not all permission sets support environment level write settings, only `analyst`, `database_admin`, `developer`, `git_admin` and `team_admin`.
 
 ## Import
diff --git a/docs/resources/scim_group_permissions.md b/docs/resources/scim_group_permissions.md
@@ -63,5 +63,5 @@ Optional:
 - `writable_environment_categories` (Set of String) What types of environments to apply Write permissions to. 
 Even if Write access is restricted to some environment types, the permission set will have Read access to all environments. 
 The values allowed are `all`, `development`, `staging`, `production` and `other`. 
-Not setting a value is the same as selecting `all`. 
+Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to `["all"]`. 
 Not all permission sets support environment level write settings, only `analyst`, `database_admin`, `developer`, `git_admin` and `team_admin`.
diff --git a/docs/resources/service_token.md b/docs/resources/service_token.md
@@ -107,7 +107,7 @@ Optional:
 - `writable_environment_categories` (Set of String) What types of environments to apply Write permissions to.
 Even if Write access is restricted to some environment types, the permission set will have Read access to all environments.
 The values allowed are `all`, `development`, `staging`, `production` and `other`.
-Not setting a value is the same as selecting `all`.
+Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to `["all"]`.
 Not all permission sets support environment level write settings, only `analyst`, `database_admin`, `developer`, `git_admin` and `team_admin`.
 
 ## Import
diff --git a/pkg/framework/objects/group/schema.go b/pkg/framework/objects/group/schema.go
@@ -25,7 +25,7 @@ func (r *groupResource) Schema(
 ) {
 	resp.Schema = resource_schema.Schema{
 		Description: helper.DocString(
-			`Provide a complete set of permissions for a group. This is different from ~~~dbt_cloud_partial_group_permissions~~~.
+			`Provide a complete set of permissions for a group. This is different from ~~~dbtcloud_group_partial_permissions~~~.
 
 			With this resource type only one resource can be used to manage the permissions for a given group.
 			`,
@@ -97,15 +97,15 @@ func (r *groupResource) Schema(
 		// For now we use a Block to move from SDKv2 to PLugin Framework, but we might change to a SetAttribute in the future, using the code from above
 		Blocks: map[string]resource_schema.Block{
 			"group_permissions": resource_schema.SetNestedBlock{
-				Description: "Partial permissions for the group. Those permissions will be added/removed when config is added/removed.",
+				Description: "The complete set of permissions to apply to the group. Each block defines one permission set; remove or modify blocks to adjust the group's permissions.",
 				NestedObject: resource_schema.NestedBlockObject{
 					Attributes: map[string]resource_schema.Attribute{
 						"permission_set": resource_schema.StringAttribute{
 							Required: true,
 							Validators: []validator.String{
 								stringvalidator.OneOf(dbt_cloud.PermissionSets...),
 							},
-							Description: "Set of permissions to apply. The permissions allowed are the same as the ones for the `dbtcloud_group` resource.",
+							Description: "The permission set to apply (e.g. `developer`, `analyst`, `account_admin`). See the table at the top of this page for the full list of permission codes.",
 						},
 						"project_id": resource_schema.Int64Attribute{
 							Optional:    true,
@@ -121,10 +121,10 @@ func (r *groupResource) Schema(
 							Computed:    true,
 							Default:     helper.EmptySetDefault(types.StringType),
 							Description: helper.DocString(
-								`What types of environments to apply Write permissions to. 
-								Even if Write access is restricted to some environment types, the permission set will have Read access to all environments. 
-								The values allowed are ~~~all~~~, ~~~development~~~, ~~~staging~~~, ~~~production~~~ and ~~~other~~~. 
-								Not setting a value is the same as selecting ~~~all~~~. 
+								`What types of environments to apply Write permissions to.
+								Even if Write access is restricted to some environment types, the permission set will have Read access to all environments.
+								The values allowed are ~~~all~~~, ~~~development~~~, ~~~staging~~~, ~~~production~~~ and ~~~other~~~.
+								Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to ~~~["all"]~~~.
 								Not all permission sets support environment level write settings, only ~~~analyst~~~, ~~~database_admin~~~, ~~~developer~~~, ~~~git_admin~~~ and ~~~team_admin~~~.`,
 							),
 						},
diff --git a/pkg/framework/objects/group_partial_permissions/schema.go b/pkg/framework/objects/group_partial_permissions/schema.go
@@ -98,7 +98,7 @@ func (r *groupPartialPermissionsResource) Schema(
 								`What types of environments to apply Write permissions to. 
 								Even if Write access is restricted to some environment types, the permission set will have Read access to all environments. 
 								The values allowed are ~~~all~~~, ~~~development~~~, ~~~staging~~~, ~~~production~~~ and ~~~other~~~. 
-								Not setting a value is the same as selecting ~~~all~~~. 
+								Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to ~~~["all"]~~~. 
 								Not all permission sets support environment level write settings, only ~~~analyst~~~, ~~~database_admin~~~, ~~~developer~~~, ~~~git_admin~~~ and ~~~team_admin~~~.`,
 							),
 						},
diff --git a/pkg/framework/objects/scim_group_partial_permissions/schema.go b/pkg/framework/objects/scim_group_partial_permissions/schema.go
@@ -92,7 +92,7 @@ func (r *scimGroupPartialPermissionsResource) Schema(
 								`What types of environments to apply Write permissions to. 
 								Even if Write access is restricted to some environment types, the permission set will have Read access to all environments. 
 								The values allowed are ~~~all~~~, ~~~development~~~, ~~~staging~~~, ~~~production~~~ and ~~~other~~~. 
-								Not setting a value is the same as selecting ~~~all~~~. 
+								Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to ~~~["all"]~~~. 
 								Not all permission sets support environment level write settings, only ~~~analyst~~~, ~~~database_admin~~~, ~~~developer~~~, ~~~git_admin~~~ and ~~~team_admin~~~.`,
 							),
 						},
diff --git a/pkg/framework/objects/scim_group_permissions/schema.go b/pkg/framework/objects/scim_group_permissions/schema.go
@@ -79,7 +79,7 @@ func (r *scimGroupPermissionsResource) Schema(
 								`What types of environments to apply Write permissions to. 
 								Even if Write access is restricted to some environment types, the permission set will have Read access to all environments. 
 								The values allowed are ~~~all~~~, ~~~development~~~, ~~~staging~~~, ~~~production~~~ and ~~~other~~~. 
-								Not setting a value is the same as selecting ~~~all~~~. 
+								Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to ~~~["all"]~~~. 
 								Not all permission sets support environment level write settings, only ~~~analyst~~~, ~~~database_admin~~~, ~~~developer~~~, ~~~git_admin~~~ and ~~~team_admin~~~.`,
 							),
 						},
diff --git a/pkg/framework/objects/service_token/data_source.go b/pkg/framework/objects/service_token/data_source.go
@@ -89,7 +89,7 @@ func (st *serviceTokenDataSource) Schema(ctx context.Context, req datasource.Sch
 								`What types of environments to apply Write permissions to.
 								Even if Write access is restricted to some environment types, the permission set will have Read access to all environments.
 								The values allowed are ~~~all~~~, ~~~development~~~, ~~~staging~~~, ~~~production~~~ and ~~~other~~~.
-								Not setting a value is the same as selecting ~~~all~~~.
+								Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to ~~~["all"]~~~.
 								Not all permission sets support environment level write settings, only ~~~analyst~~~, ~~~database_admin~~~, ~~~developer~~~, ~~~git_admin~~~ and ~~~team_admin~~~.`,
 							),
 							Computed:    true,
diff --git a/pkg/framework/objects/service_token/resource.go b/pkg/framework/objects/service_token/resource.go
@@ -127,7 +127,7 @@ func (st *serviceTokenResource) Schema(_ context.Context, _ resource.SchemaReque
 								`What types of environments to apply Write permissions to.
 								Even if Write access is restricted to some environment types, the permission set will have Read access to all environments.
 								The values allowed are ~~~all~~~, ~~~development~~~, ~~~staging~~~, ~~~production~~~ and ~~~other~~~.
-								Not setting a value is the same as selecting ~~~all~~~.
+								Not setting a value (or setting an empty list) means the permission set has no Write access to any environment — only Read access. To grant Write access to all environments, set this to ~~~["all"]~~~.
 								Not all permission sets support environment level write settings, only ~~~analyst~~~, ~~~database_admin~~~, ~~~developer~~~, ~~~git_admin~~~ and ~~~team_admin~~~.`,
 							),
 							Optional: true,

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+kind: Documentation`
	`2`	+body: Fixed `writable_environment_categories` description on group, partial permissions, SCIM and service token resources to reflect that omitting the value grants no Write access (use `["all"]` instead). Also cleaned up a few copy-paste doc strings on `dbtcloud_group`.
	`3`	`+time: 2026-05-08T18:28:33.548537+03:00`