resource/gitlab_branch_protection: Allow to manage branch protection for default branch

This change to the `gitlab_branch_protection` resource will allow to
protect the default branch of a project without importing. It basically
works by unprotecting and protecting the default branch again in case it
already exists when the resource is created. This allows the following
code to properly work:

```hcl
resource "gitlab_project" "example" {
    name = "example"
    initialize_with_readme = true
}

resource "gitlab_branch_protection" "default_branch" {
    project = gitlab_project.example.id
    branch = gitlab_project.example.default_branch

    // ... whatever settings ...
}
```

The drawback of this is that it quickly unprotects the default branch to
protect it again in the above scenario. However, it already does that
for pretty much any update to the resource attributes, because of the
lack of a proper upstream update API. In addition, it's just a special
case and maintenance effort - but I guess that's what docs are for and the
suppose that the benefits for the users outweigh the maintenance burden.

If tried to implement something along the lines of https://github.com/gitlabhq/terraform-provider-gitlab/issues/792#issuecomment-1029148287
but it turns out it's harder to implement than expected.

The problems are:

* lack of diff / plan customization on the schema: https://discuss.hashicorp.com/t/ignore-the-order-of-a-complex-typed-list/42242
* when implementing the possibility to protect branches in the
  `gitlab_project` resource we'd also need to allow to share the
  projects with groups in add members in the resource, because those
  groups or users maybe used in the branch protection. There again, we
  need better plan / diff control then what the provider sdk provides us
  at the moment.
* it basically would mean an integration / duplication / re-use of the
  `gitlab_project_share_group`, `gitlab_project_membership` and
  `gitlab_branch_protection` in the `gitlab_project` resource. Which I
  guess would be okay with the proper implementation, but then again the
  currently proposed "solution" in this PR may be good enough.

Refs: #792

Closes: #671

Author: timofurrer

docs/resources/branch_protection.md

@@ -4,6 +4,13 @@ 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.
+  ~> Branch Protection Behavior for the default branch
+     Depending on the GitLab instance, group or project setting the default branch of a project is created automatically by GitLab behind the scenes.
+     Due to some https://github.com/gitlabhq/terraform-provider-gitlab/issues/792 limitations https://discuss.hashicorp.com/t/ignore-the-order-of-a-complex-typed-list/42242 in the Terraform Provider SDK and the GitLab API,
+     when creating a new project and trying to manage the branch protection setting for its default branch the gitlab_branch_protection resource will
+     automatically take ownership of the default branch without an explicit import by unprotecting and properly protecting it again.
+     Having multiple gitlab_branch_protection resources for the same project and default branch will result in them overriding each other - make sure to only have a single one.
+     This behavior might change in the future.
   ~> 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
 ---
@@ -12,6 +19,14 @@ description: |-
 
 The `gitlab_branch_protection` resource allows to manage the lifecycle of a protected branch of a repository.
 
+~> **Branch Protection Behavior for the default branch**
+   Depending on the GitLab instance, group or project setting the default branch of a project is created automatically by GitLab behind the scenes.
+   Due to [some](https://github.com/gitlabhq/terraform-provider-gitlab/issues/792) [limitations](https://discuss.hashicorp.com/t/ignore-the-order-of-a-complex-typed-list/42242) in the Terraform Provider SDK and the GitLab API,
+   when creating a new project and trying to manage the branch protection setting for its default branch the `gitlab_branch_protection` resource will
+   automatically take ownership of the default branch without an explicit import by unprotecting and properly protecting it again.
+   Having multiple `gitlab_branch_protection` resources for the same project and default branch will result in them overriding each other - make sure to only have a single one.
+   This behavior might change in the future.
+
 ~> 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)

internal/provider/resource_gitlab_branch_protection.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"fmt"
 	"log"
-	"net/http"
 
 	"github.com/hashicorp/terraform-plugin-sdk/v2/diag"
 	"github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
@@ -43,6 +42,14 @@ 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.
 
+~> **Branch Protection Behavior for the default branch**
+   Depending on the GitLab instance, group or project setting the default branch of a project is created automatically by GitLab behind the scenes.
+   Due to [some](https://github.com/gitlabhq/terraform-provider-gitlab/issues/792) [limitations](https://discuss.hashicorp.com/t/ignore-the-order-of-a-complex-typed-list/42242) in the Terraform Provider SDK and the GitLab API,
+   when creating a new project and trying to manage the branch protection setting for its default branch the ` + "`gitlab_branch_protection`" + ` resource will
+   automatically take ownership of the default branch without an explicit import by unprotecting and properly protecting it again.
+   Having multiple ` + "`gitlab_branch_protection`" + ` resources for the same project and default branch will result in them overriding each other - make sure to only have a single one.
+   This behavior might change in the future.
+
 ~> 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)`,
@@ -124,12 +131,25 @@ func resourceGitlabBranchProtectionCreate(ctx context.Context, d *schema.Resourc
 	log.Printf("[DEBUG] create gitlab branch protection on branch %q for project %s", branch, project)
 
 	if d.IsNewResource() {
-		existing, resp, err := client.ProtectedBranches.GetProtectedBranch(project, branch, gitlab.WithContext(ctx))
-		if err != nil && resp.StatusCode != http.StatusNotFound {
-			return diag.Errorf("error looking up protected branch %q on project %q: %v", branch, project, err)
+		existing, _, err := client.ProtectedBranches.GetProtectedBranch(project, branch, gitlab.WithContext(ctx))
+		if err == nil {
+			projectDetails, _, err := client.Projects.GetProject(project, nil, gitlab.WithContext(ctx))
+			if err != nil {
+				return diag.Errorf("Failed to get project details for %q to get the name of the default branch: %v", project, err)
+			}
+
+			if projectDetails.DefaultBranch == branch {
+				log.Printf("[DEBUG] this branch protection is for the default branch %q in project %q, thus we allow configuring it even though this is a new resource! We do this by quickly unprotect it, because it's not editable ...!", branch, project)
+				_, err := client.ProtectedBranches.UnprotectRepositoryBranches(project, branch, gitlab.WithContext(ctx))
+				if err != nil {
+					return diag.Errorf("Failed to unprotect default branch %q in project %q while trying to 'import' it: %v", branch, project, err)
+				}
+			} else {
+				return diag.Errorf("protected branch %q on project %q already exists: %+v", branch, project, *existing)
+			}
 		}
-		if resp.StatusCode != http.StatusNotFound {
-			return diag.Errorf("protected branch %q on project %q already exists: %+v", branch, project, *existing)
+		if err != nil && !is404(err) {
+			return diag.Errorf("error looking up protected branch %q on project %q: %v", branch, project, err)
 		}
 	}
 

internal/provider/resource_gitlab_branch_protection_test.go

@@ -383,6 +383,44 @@ func TestAccGitlabBranchProtection_createWithMultipleAccessLevels(t *testing.T)
 	})
 }
 
+func TestAccGitlabBranchProtection_createForProjectDefaultBranch(t *testing.T) {
+	testProjectName := acctest.RandomWithPrefix("tf-acc-test")
+	var protectedBranch gitlab.ProtectedBranch
+
+	resource.ParallelTest(t, resource.TestCase{
+		ProviderFactories: providerFactories,
+		CheckDestroy:      testAccCheckGitlabBranchProtectionDestroy,
+		Steps: []resource.TestStep{
+			// Create a project and protect its default branch with custom settings
+			{
+				Config: fmt.Sprintf(`
+					resource "gitlab_project" "this" {
+						name = "%s"
+						initialize_with_readme = true
+					}
+
+					resource "gitlab_branch_protection" "default_branch" {
+						project = gitlab_project.this.id
+						branch = gitlab_project.this.default_branch
+
+						// non-default setting
+						allow_force_push = true
+					}
+				`, testProjectName),
+				Check: resource.ComposeTestCheckFunc(
+					testAccCheckGitlabBranchProtectionExists("gitlab_branch_protection.default_branch", &protectedBranch),
+					func(_ *terraform.State) error {
+						if protectedBranch.AllowForcePush != true {
+							return fmt.Errorf("allow_force_push is not set to true")
+						}
+						return nil
+					},
+				),
+			},
+		},
+	})
+}
+
 func testAccCheckGitlabBranchProtectionPersistsInStateCorrectly(n string, pb *gitlab.ProtectedBranch) resource.TestCheckFunc {
 	return func(s *terraform.State) error {
 		rs, ok := s.RootModule().Resources[n]