[FEAT]: Add RequiredStatusChecks "checks" to github_branch_protection (GraphQL)

[martimmatias]

Describe the need

Problem Statement

The github_branch_protection resource uses the GraphQL API underneath and allows users to define required status checks via the required_status_checks.contexts field . This field is defined as a list of strings and does not allow specifying which GitHub APPs are responsible for reporting these status checks. GitHub automatically selects the APPs according to recent runs, but this isn't always desirable - especially in environments where 2 different apps may report the same status check or where workflows aren't run frequently.

The GitHub GraphQL API supports a richer configuration: a list of RequiredStatusCheckInput; which allows users to explicitly assign a GitHub APP to a status checks. However, the current Terraform resource schema does not have this field.

This issue is similar to the now closed issue #1212 where this feature was added for the github_branch_protection_v3 resource, which uses the REST API.

Although this issue was already resolved for the github_branch_protection_v3 resource, my use-case remains unresolved since this resource does not support wildcard patterns.

Implementation Options

Option A: New repeatable check block

Add a new repeatable check block under required_status_checks, allowing users to explicitly define both the context name and the GitHub App ID:

resource "github_branch_protection" "example" {
  repository_id = github_repository.example.node_id
  pattern       = "example*"

  required_status_checks {
    strict = true
    check {
      context = "foobar"
      app_id  = data.github_app.my_app.node_id
    }
    check {
      context = "barfoo"
      app_id  = null
    }
  }
}

Option B: New checks list

Mirror the approach used by github_branch_protection_v3 (see #1415), where the GitHub App ID is optionally encoded into each string element of a new checks list:

resource "github_branch_protection" "example" {
  repository_id = github_repository.example.node_id
  pattern       = "example*"

  required_status_checks {
    strict = true
    checks = ["foobar:${data.github_app.my_app.node_id}", "barfoo"] {
  }
}

Open Questions

• How do we ensure mutual exclusivity between the new fields and the existing contexts field?
  • The challenge lies in updating existing schemas without causing state drift due to the internal populating of the new field.
• Should the contexts field be fully deprecated?
  • In this scenario, the schema version would be increased and a migration function would have to be written.
  • Is backwards compatibility a requirement?
• Is parity with the REST API resource a requirement?

SDK Version

No response

API Version

No response

Relevant log output

Code of Conduct

• I agree to follow this project's Code of Conduct

[github-actions]

👋 Hi! Thank you for this contribution! Just to let you know, our GitHub SDK team does a round of issue and PR reviews twice a week, every Monday and Friday! We have a process in place for prioritizing and responding to your input. Because you are a part of this community please feel free to comment, add to, or pick up any issues/PRs that are labeled with Status: Up for grabs. You & others like you are the reason all of this works! So thank you & happy coding! 🚀

[martimmatias]

I have already been experimenting with a solution that is like option A, but I have not been able to implement the new field in such a way that it does not cause state drift, due to it being automatically populated during the import step of the tests. This happens because the GitHub GraphQL API returns both the contexts and checks, even if the user's configuration only defines one of the two fields.

[martimmatias]

This is also similar to #985