Add unprotect_access_level and allowed_to_unprotect to branch protection

Adds the missing `unprotect_access_level` and `allowed_to_unprotect` attributes to the branch protection resource.  Updates the tests to test with required fields, then optional fields, as `push_access_level` and `merge_access_level` are not required in the API.

Author: beekeep

docs/resources/branch_protection.md

@@ -4,15 +4,15 @@ page_title: "gitlab_branch_protection Resource - terraform-provider-gitlab"
 subcategory: ""
 description: |-
   The gitlab_branch_protection resource allows to manage the lifecycle of a protected branch of a repository.
-  ~> The allowedtopush, allowedtomerge and codeownerapproval_required attributes require a GitLab Enterprise instance.
+  ~> The allowed_to_push, allowed_to_merge, allowed_to_unprotect, unprotect_access_level and code_owner_approval_required attributes require a GitLab Enterprise instance.
   Upstream API: GitLab REST API docs https://docs.gitlab.com/ee/api/protected_branches.html
 ---
 
 # gitlab_branch_protection (Resource)
 
 The `gitlab_branch_protection` resource allows to manage the lifecycle of a protected branch of a repository.
 
-~> The allowed_to_push, allowed_to_merge and code_owner_approval_required attributes require a GitLab Enterprise instance.
+~> The `allowed_to_push`, `allowed_to_merge`, `allowed_to_unprotect`, `unprotect_access_level` and `code_owner_approval_required` attributes require a GitLab Enterprise instance.
 
 **Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/protected_branches.html)
 
@@ -24,6 +24,7 @@ resource "gitlab_branch_protection" "BranchProtect" {
   branch                       = "BranchProtected"
   push_access_level            = "developer"
   merge_access_level           = "developer"
+  unprotect_access_level       = "developer"
   allow_force_push             = true
   code_owner_approval_required = true
   allowed_to_push {
@@ -38,14 +39,21 @@ resource "gitlab_branch_protection" "BranchProtect" {
   allowed_to_merge {
     user_id = 37
   }
+  allowed_to_unprotect {
+    user_id = 15
+  }
+  allowed_to_unprotect {
+    group_id = 42
+  }
 }
 
 # Example using dynamic block
 resource "gitlab_branch_protection" "main" {
-  project            = "12345"
-  branch             = "main"
-  push_access_level  = "maintainer"
-  merge_access_level = "maintainer"
+  project                = "12345"
+  branch                 = "main"
+  push_access_level      = "maintainer"
+  merge_access_level     = "maintainer"
+  unprotect_access_level = "maintainer"
 
   dynamic "allowed_to_push" {
     for_each = [50, 55, 60]
@@ -62,17 +70,19 @@ resource "gitlab_branch_protection" "main" {
 ### Required
 
 - **branch** (String) Name of the branch.
-- **merge_access_level** (String) Access levels allowed to merge. Valid values are: `no one`, `developer`, `maintainer`.
 - **project** (String) The id of the project.
-- **push_access_level** (String) Access levels allowed to push. Valid values are: `no one`, `developer`, `maintainer`.
 
 ### Optional
 
 - **allow_force_push** (Boolean) Can be set to true to allow users with push access to force push.
 - **allowed_to_merge** (Block Set) Defines permissions for action. (see [below for nested schema](#nestedblock--allowed_to_merge))
 - **allowed_to_push** (Block Set) Defines permissions for action. (see [below for nested schema](#nestedblock--allowed_to_push))
+- **allowed_to_unprotect** (Block Set) Defines permissions for action. (see [below for nested schema](#nestedblock--allowed_to_unprotect))
 - **code_owner_approval_required** (Boolean) Can be set to true to require code owner approval before merging.
 - **id** (String) The ID of this resource.
+- **merge_access_level** (String) Access levels allowed to merge. Valid values are: `no one`, `developer`, `maintainer`.
+- **push_access_level** (String) Access levels allowed to push. Valid values are: `no one`, `developer`, `maintainer`.
+- **unprotect_access_level** (String) Access levels allowed to unprotect. Valid values are: `developer`, `maintainer`.
 
 ### Read-Only
 
@@ -105,6 +115,20 @@ Read-Only:
 - **access_level** (String) Level of access.
 - **access_level_description** (String) Readable description of level of access.
 
+
+<a id="nestedblock--allowed_to_unprotect"></a>
+### Nested Schema for `allowed_to_unprotect`
+
+Optional:
+
+- **group_id** (Number) The ID of a GitLab group allowed to perform the relevant action. Mutually exclusive with `user_id`.
+- **user_id** (Number) The ID of a GitLab user allowed to perform the relevant action. Mutually exclusive with `group_id`.
+
+Read-Only:
+
+- **access_level** (String) Level of access.
+- **access_level_description** (String) Readable description of level of access.
+
 ## Import
 
 Import is supported using the following syntax:

examples/resources/gitlab_branch_protection/resource.tf

@@ -3,6 +3,7 @@ resource "gitlab_branch_protection" "BranchProtect" {
   branch                       = "BranchProtected"
   push_access_level            = "developer"
   merge_access_level           = "developer"
+  unprotect_access_level       = "developer"
   allow_force_push             = true
   code_owner_approval_required = true
   allowed_to_push {
@@ -17,14 +18,21 @@ resource "gitlab_branch_protection" "BranchProtect" {
   allowed_to_merge {
     user_id = 37
   }
+  allowed_to_unprotect {
+    user_id = 15
+  }
+  allowed_to_unprotect {
+    group_id = 42
+  }
 }
 
 # Example using dynamic block
 resource "gitlab_branch_protection" "main" {
-  project            = "12345"
-  branch             = "main"
-  push_access_level  = "maintainer"
-  merge_access_level = "maintainer"
+  project                = "12345"
+  branch                 = "main"
+  push_access_level      = "maintainer"
+  merge_access_level     = "maintainer"
+  unprotect_access_level = "maintainer"
 
   dynamic "allowed_to_push" {
     for_each = [50, 55, 60]

internal/provider/access_level_helpers.go

@@ -49,6 +49,12 @@ var validProtectedBranchTagAccessLevelNames = []string{
 	"no one", "developer", "maintainer",
 }
 
+// The only access levels allowed to be configured to unprotect a protected branch
+// The API states the others are either forbidden (via 403) or invalid
+var validProtectedBranchUnprotectAccessLevelNames = []string{
+	"developer", "maintainer",
+}
+
 var accessLevelNameToValue = map[string]gitlab.AccessLevelValue{
 	"no one":     gitlab.NoPermissions,
 	"minimal":    gitlab.MinimalAccessPermissions,

internal/provider/resource_gitlab_branch_protection.go

@@ -43,7 +43,7 @@ var _ = registerResource("gitlab_branch_protection", func() *schema.Resource {
 	return &schema.Resource{
 		Description: `The ` + "`gitlab_branch_protection`" + ` resource allows to manage the lifecycle of a protected branch of a repository.
 
-~> The allowed_to_push, allowed_to_merge and code_owner_approval_required attributes require a GitLab Enterprise instance.
+~> The ` + "`allowed_to_push`" + `, ` + "`allowed_to_merge`" + `, ` + "`allowed_to_unprotect`" + `, ` + "`unprotect_access_level`" + ` and ` + "`code_owner_approval_required`" + ` attributes require a GitLab Enterprise instance.
 
 **Upstream API**: [GitLab REST API docs](https://docs.gitlab.com/ee/api/protected_branches.html)`,
 
@@ -83,15 +83,24 @@ var _ = registerResource("gitlab_branch_protection", func() *schema.Resource {
 				Default:          accessLevelValueToName[gitlab.MaintainerPermissions],
 				ForceNew:         true,
 			},
+			"unprotect_access_level": {
+				Description:      fmt.Sprintf("Access levels allowed to unprotect. Valid values are: %s.", renderValueListForDocs(validProtectedBranchUnprotectAccessLevelNames)),
+				Type:             schema.TypeString,
+				ValidateDiagFunc: validation.ToDiagFunc(validation.StringInSlice(validProtectedBranchUnprotectAccessLevelNames, false)),
+				Optional:         true,
+				Default:          accessLevelValueToName[gitlab.MaintainerPermissions],
+				ForceNew:         true,
+			},
 			"allow_force_push": {
 				Description: "Can be set to true to allow users with push access to force push.",
 				Type:        schema.TypeBool,
 				Optional:    true,
 				Default:     false,
 				ForceNew:    true,
 			},
-			"allowed_to_push":  schemaAllowedTo(),
-			"allowed_to_merge": schemaAllowedTo(),
+			"allowed_to_push":      schemaAllowedTo(),
+			"allowed_to_merge":     schemaAllowedTo(),
+			"allowed_to_unprotect": schemaAllowedTo(),
 			"code_owner_approval_required": {
 				Description: "Can be set to true to require code owner approval before merging.",
 				Type:        schema.TypeBool,
@@ -126,19 +135,24 @@ func resourceGitlabBranchProtectionCreate(ctx context.Context, d *schema.Resourc
 
 	mergeAccessLevel := accessLevelNameToValue[d.Get("merge_access_level").(string)]
 	pushAccessLevel := accessLevelNameToValue[d.Get("push_access_level").(string)]
+	unprotectAccessLevel := accessLevelNameToValue[d.Get("unprotect_access_level").(string)]
+
 	allowForcePush := d.Get("allow_force_push").(bool)
 	codeOwnerApprovalRequired := d.Get("code_owner_approval_required").(bool)
 
 	allowedToPush := expandBranchPermissionOptions(d.Get("allowed_to_push").(*schema.Set).List())
 	allowedToMerge := expandBranchPermissionOptions(d.Get("allowed_to_merge").(*schema.Set).List())
+	allowedToUnprotect := expandBranchPermissionOptions(d.Get("allowed_to_unprotect").(*schema.Set).List())
 
 	pb, _, err := client.ProtectedBranches.ProtectRepositoryBranches(project, &gitlab.ProtectRepositoryBranchesOptions{
 		Name:                      &branch,
 		PushAccessLevel:           &pushAccessLevel,
 		MergeAccessLevel:          &mergeAccessLevel,
+		UnprotectAccessLevel:      &unprotectAccessLevel,
 		AllowForcePush:            &allowForcePush,
 		AllowedToPush:             &allowedToPush,
 		AllowedToMerge:            &allowedToMerge,
+		AllowedToUnprotect:        &allowedToUnprotect,
 		CodeOwnerApprovalRequired: &codeOwnerApprovalRequired,
 	}, gitlab.WithContext(ctx))
 	if err != nil {
@@ -186,6 +200,12 @@ func resourceGitlabBranchProtectionRead(ctx context.Context, d *schema.ResourceD
 		}
 	}
 
+	if unprotectAccessLevels, err := firstValidAccessLevel(pb.UnprotectAccessLevels); err == nil {
+		if err := d.Set("unprotect_access_level", accessLevelValueToName[*unprotectAccessLevels]); err != nil {
+			return diag.Errorf("error setting unprotect_access_level: %v", err)
+		}
+	}
+
 	if err := d.Set("allow_force_push", pb.AllowForcePush); err != nil {
 		return diag.Errorf("error setting allow_force_push: %v", err)
 	}
@@ -197,6 +217,10 @@ func resourceGitlabBranchProtectionRead(ctx context.Context, d *schema.ResourceD
 		return diag.Errorf("error setting allowed_to_merge: %v", err)
 	}
 
+	if err := d.Set("allowed_to_unprotect", flattenNonZeroBranchAccessDescriptions(pb.UnprotectAccessLevels)); err != nil {
+		return diag.Errorf("error setting allowed_to_unprotect: %v", err)
+	}
+
 	if err := d.Set("code_owner_approval_required", pb.CodeOwnerApprovalRequired); err != nil {
 		return diag.Errorf("error setting code_owner_approval_required: %v", err)
 	}