docs: Clarify how allows_force_pushes works

fix doc for #2054: Clarify how allows_force_pushes is working

Author: nickfloyd

github/resource_github_branch_protection_test.go

@@ -615,6 +615,65 @@ func TestAccGithubBranchProtection(t *testing.T) {
 
 	})
 
+	t.Run("configures allow force push with a team as bypasser", func(t *testing.T) {
+
+		config := fmt.Sprintf(`
+
+			resource "github_repository" "test" {
+			  name      = "tf-acc-test-%s"
+			  auto_init = true
+			}
+
+			resource "github_team" "test" {
+				name = "tf-acc-test-%s"
+			}
+
+			resource "github_team_repository" "test" {
+				team_id    = github_team.test.id
+				repository = github_repository.test.name
+				permission = "admin"
+			}
+
+			resource "github_branch_protection" "test" {
+			  repository_id  = github_repository.test.node_id
+			  pattern        = "main"
+
+			  force_push_bypassers = [
+				  "%s/${github_team.test.slug}"
+	]
+			}
+
+	`, randomID, randomID, testOrganization)
+
+		check := resource.ComposeAggregateTestCheckFunc(
+			resource.TestCheckResourceAttr(
+				"github_branch_protection.test", "force_push_bypassers.#", "1",
+			),
+			resource.TestCheckResourceAttr(
+				"github_branch_protection.test", "allows_force_pushes", "false",
+			),
+		)
+
+		testCase := func(t *testing.T, mode string) {
+			resource.Test(t, resource.TestCase{
+				PreCheck:  func() { skipUnlessMode(t, mode) },
+				Providers: testAccProviders,
+				Steps: []resource.TestStep{
+					{
+						Config: config,
+						Check:  check,
+					},
+				},
+			})
+		}
+
+		// This test only works with an organization account
+		t.Run("with an organization account", func(t *testing.T) {
+			testCase(t, organization)
+		})
+
+	})
+
 	t.Run("configures empty list of force push bypassers", func(t *testing.T) {
 
 		config := fmt.Sprintf(`

website/docs/r/branch_protection.html.markdown

@@ -98,9 +98,9 @@ The following arguments are supported:
 * `required_status_checks` - (Optional) Enforce restrictions for required status checks. See [Required Status Checks](#required-status-checks) below for details.
 * `required_pull_request_reviews` - (Optional) Enforce restrictions for pull request reviews. See [Required Pull Request Reviews](#required-pull-request-reviews) below for details.
 * `push_restrictions` - (Optional) The list of actor Names/IDs that may push to the branch. Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams.
-* `force_push_bypassers` - (Optional) The list of actor Names/IDs that are allowed to bypass force push restrictions. Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams.
+* `force_push_bypassers` - (Optional) The list of actor Names/IDs that are allowed to bypass force push restrictions. Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams. If the list is not empty, `allows_force_pushes` should be set to `false`.
 * `allows_deletions` - (Optional) Boolean, setting this to `true` to allow the branch to be deleted.
-* `allows_force_pushes` - (Optional) Boolean, setting this to `true` to allow force pushes on the branch.
+* `allows_force_pushes` - (Optional) Boolean, setting this to `true` to allow force pushes on the branch to everyone. Set it to `false` if you specify `force_push_bypassers`.
 * `blocks_creations` - (Optional) Boolean, setting this to `true` to block creating the branch.
 * `lock_branch` - (Optional) Boolean, Setting this to `true` will make the branch read-only and preventing any pushes to it. Defaults to `false`