docs: clarify use of secret env vars for free plan users

docs/resources/environment_variable.md

@@ -94,7 +94,9 @@ resource "netlify_environment_variable" "astro_database_file" {
 
 ### Optional
 
-- `scopes` (Set of String) One or more of builds, functions, runtime, and post-processing
+- `scopes` (Set of String) One or more of builds, functions, runtime, and post-processing.
+
+Customizing scopes is not supported on free plans. However, free plan users managing a secret environment variable can and must explicitly set this to `["builds", "functions", "runtime"]`.
 - `secret_values` (Attributes Set) (see [below for nested schema](#nestedatt--secret_values))
 - `site_id` (String)
 - `team_id` (String) Required if a default team was not configured in the provider configuration.

internal/provider/environment_variable_resource.go

@@ -52,13 +52,15 @@ type environmentVariableValueModel struct {
 	ContextParameter types.String `tfsdk:"context_parameter"`
 }
 
-var allScopes = []string{"builds", "functions", "runtime", "post-processing"}
-var allScopesValues = []attr.Value{
-	types.StringValue("builds"),
-	types.StringValue("functions"),
-	types.StringValue("runtime"),
-	types.StringValue("post-processing"),
-}
+var (
+	allScopes       = []string{"builds", "functions", "runtime", "post-processing"}
+	allScopesValues = []attr.Value{
+		types.StringValue("builds"),
+		types.StringValue("functions"),
+		types.StringValue("runtime"),
+		types.StringValue("post-processing"),
+	}
+)
 
 func (r *environmentVariableResource) Metadata(_ context.Context, req resource.MetadataRequest, resp *resource.MetadataResponse) {
 	resp.TypeName = req.ProviderTypeName + "_environment_variable"
@@ -115,7 +117,7 @@ func (r *environmentVariableResource) Schema(_ context.Context, _ resource.Schem
 				Optional:    true,
 				Computed:    true,
 				ElementType: types.StringType,
-				Description: "One or more of builds, functions, runtime, and post-processing",
+				Description: "One or more of builds, functions, runtime, and post-processing.\n\nCustomizing scopes is not supported on free plans. However, free plan users managing a secret environment variable can and must explicitly set this to `[\"builds\", \"functions\", \"runtime\"]`.",
 				Validators: []validator.Set{
 					setvalidator.ValueStringsAre(
 						stringvalidator.OneOf(allScopes...),

internal/provider/free_plan_test.go

@@ -31,6 +31,31 @@ func TestAccFreeEnvVar(t *testing.T) {
 	}, func(s *terraform.State) error { return nil })
 }
 
+func TestAccFreeSecretEnvVar(t *testing.T) {
+	accTest(t, []resource.TestStep{
+		{
+			Config: `resource "netlify_environment_variable" "site_level_secret" {
+  team_id = "66e98216e3fe031846dc998a"
+  site_id = "fbba82b0-f1e9-4e92-9203-eefc62857545"
+  key     = "TEST_SITE_LEVEL_SECRET"
+	scopes  = ["functions", "builds", "runtime"]
+  secret_values = [
+    {
+      value   = "ill-never-tell",
+      context = "production",
+    }
+  ]
+}
+`,
+			Check: resource.ComposeAggregateTestCheckFunc(
+				resource.TestCheckResourceAttr("netlify_environment_variable.site_level_secret", "team_id", "66e98216e3fe031846dc998a"),
+				resource.TestCheckResourceAttr("netlify_environment_variable.site_level_secret", "site_id", "fbba82b0-f1e9-4e92-9203-eefc62857545"),
+				resource.TestCheckResourceAttr("netlify_environment_variable.site_level_secret", "key", "TEST_SITE_LEVEL_SECRET"),
+			),
+		},
+	}, func(s *terraform.State) error { return nil })
+}
+
 func TestAccFreeSiteBuildSettings(t *testing.T) {
 	accTest(t, []resource.TestStep{
 		{