github_branch_protection Example Usage - multiple errors

[cpswan]

Terraform Version

Terraform v1.2.6
on linux_amd64

Affected Resource(s)

• github_branch_protection

Terraform Configuration Files

N/A - these docs problems impact a potential user before they get as far as config.

Debug Output

N/A

Panic Output

N/A

Expected Behavior

The example should provide a usable template for the resource that isn't littered with flaws, errors and mystery.

Actual Behavior

It took far too long to figure out how to use the resource.

Steps to Reproduce

1. Browse to the Example Usage
2. Try to make it work
3. Wonder why such an obviously flawed piece of documentation that can't ever have been used made it through the review process

Important Factoids

The example opens with:

# Protect the main branch of the foo repository.

Yet there is no further mention of foo, as it actually references a repository by node_id

Most people won't know the node_id of their repository unless they've waded into the GitHub GraphQL API (and they're probably using this resource to avoid that). So perhaps name would be a more workable example and the comment could be adjusted to say # also accepts repository node_id.

The intro continues:

# the "ci/travis" context to be passing and only allow the engineers team merge
# to the branch.

What does "ci/travis" context have to do with any of this? Feels like left over copy pasta staining the napkin of what should be a clean example.

The example then goes on to provide:

resource "github_repository" "example" {
  name = "test"
}

So we've now switched from foo to test, but we're using name instead of node_id.

Furthermore there's:

data "github_user" "example" {
  username = "example"
}

But this wouldn't get used by data.github_user.example.node_id above.

and it's a similar story for:

resource "github_team" "example" {
  name = "Example Name"
}

Where that name wouldn't be used by github_team.example.node_id

Finally there's:

resource "github_team_repository" "example" {
  team_id    = github_team.example.id
  repository = github_repository.example.name
  permission = "pull"
}

But no reference elsewhere to github_team_repository

Giving an overall impression that somebody's taken the v3 (REST) API example and just thrown in some random node_id references to make it GraphQLy without actually joining them to appropriate resources elsewhere in the example.

FWIW this is the config I eventually used (to get something that will pass Allstar checks):

main.tf

terraform {
  required_providers {
    github = {
      source  = "integrations/github"
      version = "~> 4.0"
    }
  }
}

# Configure the GitHub Provider
provider "github" {
  owner = var.gh_org
}

# Set protection
resource "github_branch_protection" "gh_repos" {
  count                         = "${length(var.gh_repos)}"
  repository_id                 = "${var.gh_repos[count.index]}"
  pattern                       = "main"
  enforce_admins                = "true"
  required_pull_request_reviews {
    dismiss_stale_reviews  = true
    required_approving_review_count = 1
  }
}

variables.tf

variable "gh_org" {
  type = string
}

variable "gh_repos" {
  type = list
}

terraform.tfvars

gh_org = "my-organisation"
gh_repos = [
"example_repo_1",
"example_repo_2",
"final_example",
]

There are probably a bunch of rookie errors in that, but it got the job done. If only I had some good examples to work from...