From 8d7a72f9ccb068e4bbd367943e906da0cebb9ce5 Mon Sep 17 00:00:00 2001 From: Trevor Wood Date: Tue, 1 Nov 2022 22:38:01 -0400 Subject: [PATCH] chore(docs): include v4 branch protections --- README.md | 136 +++++++++++++++++++++++++++++++++++++- README.tfdoc.hcl | 165 ++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 296 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index df15cc4..01b436f 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,8 @@ A [Terraform] module for creating a public or private repository on [Github]. - [Collaborator Configuration](#collaborator-configuration) - [Branches Configuration](#branches-configuration) - [Deploy Keys Configuration](#deploy-keys-configuration) - - [Branch Protections Configuration](#branch-protections-configuration) + - [Branch Protections v3 Configuration](#branch-protections-v3-configuration) + - [Branch Protections v4 Configuration](#branch-protections-v4-configuration) - [Issue Labels Configuration](#issue-labels-configuration) - [Projects Configuration](#projects-configuration) - [Webhooks Configuration](#webhooks-configuration) @@ -528,11 +529,11 @@ This is due to some terraform limitation and we will update the module once terr Default is `"md5(key)"`. -#### Branch Protections Configuration +#### Branch Protections v3 Configuration - [**`branch_protections_v3`**](#var-branch_protections_v3): *(Optional `list(branch_protection_v3)`)* - This resource allows you to configure branch protection for repositories in your organization. + This resource allows you to configure v3 branch protection for repositories in your organization. When applied, the branch will be protected from forced pushes and deletion. Additional constraints, such as required status checks or restrictions on users and teams, can also be configured. @@ -652,6 +653,135 @@ This is due to some terraform limitation and we will update the module once terr Default is `[]`. +#### Branch Protections v4 Configuration + +- [**`branch_protections_v4`**](#var-branch_protections_v4): *(Optional `map(branch_protection_v4)`)* + + This map allows you to configure v4 branch protection for repositories in your organization. + + Each element in the map is a branch to be protected and the value the corresponding to the desired configuration for the branch. + + When applied, the branch will be protected from forced pushes and deletion. + Additional constraints, such as required status checks or restrictions on users and teams, can also be configured. + + **_NOTE_** This will take precedence over v3 branch protections. + + Default is `null`. + + Each `branch_protection_v4` object in the map accepts the following attributes: + + - [**`allows_deletions`**](#attr-branch_protections_v4-allows_deletions): *(Optional `bool`)* + + Setting this to true to allow the branch to be deleted. + + Default is `false`. + + - [**`allows_force_pushes`**](#attr-branch_protections_v4-allows_force_pushes): *(Optional `bool`)* + + Setting this to true to allow force pushes on the branch. + + Default is `false`. + + - [**`blocks_creations`**](#attr-branch_protections_v4-blocks_creations): *(Optional `bool`)* + + Setting this to true will block creating the branch. + + Default is `false`. + + - [**`enforce_admins`**](#attr-branch_protections_v4-enforce_admins): *(Optional `bool`)* + + Setting this to true enforces status checks for repository administrators. + + Default is `false`. + + - [**`push_restrictions`**](#attr-branch_protections_v4-push_restrictions): *(Optional `list(string)`)* + + 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. + + Default is `[]`. + + - [**`require_conversation_resolution`**](#attr-branch_protections_v4-require_conversation_resolution): *(Optional `bool`)* + + Setting this to true requires all conversations on code must be resolved before a pull request can be merged. + + Default is `false`. + + - [**`require_signed_commits`**](#attr-branch_protections_v4-require_signed_commits): *(Optional `bool`)* + + Setting this to true requires all commits to be signed with GPG. + + Default is `false`. + + - [**`required_linear_history`**](#attr-branch_protections_v4-required_linear_history): *(Optional `bool`)* + + Setting this to true enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch. + + Default is `false`. + + - [**`required_pull_request_reviews`**](#attr-branch_protections_v4-required_pull_request_reviews): *(Optional `object(required_pull_request_reviews)`)* + + Enforce restrictions for pull request reviews. + + Default is `null`. + + The `required_pull_request_reviews` object accepts the following attributes: + + - [**`dismiss_stale_reviews`**](#attr-branch_protections_v4-required_pull_request_reviews-dismiss_stale_reviews): *(Optional `bool`)* + + Dismiss approved reviews automatically when a new commit is pushed. + + Default is `true`. + + - [**`dismissal_restrictions`**](#attr-branch_protections_v4-required_pull_request_reviews-dismissal_restrictions): *(Optional `list(string)`)* + + The list of actor Names/IDs with dismissal access. + If not empty, restrict_dismissals is ignored. + Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams. + + Default is `[]`. + + - [**`pull_request_bypassers`**](#attr-branch_protections_v4-required_pull_request_reviews-pull_request_bypassers): *(Optional `list(string)`)* + + The list of actor Names/IDs that are allowed to bypass pull request requirements. + Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams. + + Default is `[]`. + + - [**`require_code_owner_reviews`**](#attr-branch_protections_v4-required_pull_request_reviews-require_code_owner_reviews): *(Optional `bool`)* + + Require an approved review in pull requests including files with a designated code owner. + + Default is `false`. + + - [**`required_approving_review_count`**](#attr-branch_protections_v4-required_pull_request_reviews-required_approving_review_count): *(Optional `number`)* + + Require x number of approvals to satisfy branch protection requirements. + If this is specified it must be a number between 0-6. + + Default is `0`. + + - [**`required_status_checks`**](#attr-branch_protections_v4-required_status_checks): *(Optional `object(required_status_checks)`)* + + Enforce restrictions for required status checks. + See Required Status Checks below for details. + + Default is `null`. + + The `required_status_checks` object accepts the following attributes: + + - [**`strict`**](#attr-branch_protections_v4-required_status_checks-strict): *(Optional `bool`)* + + Require branches to be up to date before merging. + + Default is `false`. + + - [**`contexts`**](#attr-branch_protections_v4-required_status_checks-contexts): *(Optional `list(string)`)* + + The list of status checks to require in order to merge into this branch. If default is `[]` no status checks are required. + + Default is `[]`. + #### Issue Labels Configuration - [**`issue_labels`**](#var-issue_labels): *(Optional `list(issue_label)`)* diff --git a/README.tfdoc.hcl b/README.tfdoc.hcl index ab43b59..b6e97a7 100644 --- a/README.tfdoc.hcl +++ b/README.tfdoc.hcl @@ -677,13 +677,13 @@ section { } section { - title = "Branch Protections Configuration" + title = "Branch Protections v3 Configuration" variable "branch_protections_v3" { type = list(branch_protection_v3) default = [] description = <<-END - This resource allows you to configure branch protection for repositories in your organization. + This resource allows you to configure v3 branch protection for repositories in your organization. When applied, the branch will be protected from forced pushes and deletion. Additional constraints, such as required status checks or restrictions on users and teams, can also be configured. END @@ -832,6 +832,167 @@ section { } } + section { + title = "Branch Protections v4 Configuration" + + variable "branch_protections_v4" { + type = map(branch_protection_v4) + default = null + description = <<-END + This map allows you to configure v4 branch protection for repositories in your organization. + + Each element in the map is a branch to be protected and the value the corresponding to the desired configuration for the branch. + + When applied, the branch will be protected from forced pushes and deletion. + Additional constraints, such as required status checks or restrictions on users and teams, can also be configured. + + **_NOTE_** This will take precedence over v3 branch protections. + END + + attribute "allows_deletions" { + type = bool + default = false + description = <<-END + Setting this to true to allow the branch to be deleted. + END + } + + attribute "allows_force_pushes" { + type = bool + default = false + description = <<-END + Setting this to true to allow force pushes on the branch. + END + } + + attribute "blocks_creations" { + type = bool + default = false + description = <<-END + Setting this to true will block creating the branch. + END + } + + attribute "enforce_admins" { + type = bool + default = false + description = <<-END + Setting this to true enforces status checks for repository administrators. + END + } + + attribute "push_restrictions" { + type = list(string) + default = [] + description = <<-END + 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. + END + } + + attribute "require_conversation_resolution" { + type = bool + default = false + description = <<-END + Setting this to true requires all conversations on code must be resolved before a pull request can be merged. + END + } + + attribute "require_signed_commits" { + type = bool + default = false + description = <<-END + Setting this to true requires all commits to be signed with GPG. + END + } + + attribute "required_linear_history" { + type = bool + default = false + description = <<-END + Setting this to true enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch. + END + } + + attribute "required_pull_request_reviews" { + type = object(required_pull_request_reviews) + default = null + description = <<-END + Enforce restrictions for pull request reviews. + END + + attribute "dismiss_stale_reviews" { + type = bool + default = true + description = <<-END + Dismiss approved reviews automatically when a new commit is pushed. + END + } + + attribute "dismissal_restrictions" { + type = list(string) + default = [] + description = <<-END + The list of actor Names/IDs with dismissal access. + If not empty, restrict_dismissals is ignored. + Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams. + END + } + + attribute "pull_request_bypassers" { + type = list(string) + default = [] + description = <<-END + The list of actor Names/IDs that are allowed to bypass pull request requirements. + Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams. + END + } + + attribute "require_code_owner_reviews" { + type = bool + default = false + description = <<-END + Require an approved review in pull requests including files with a designated code owner. + END + } + + attribute "required_approving_review_count" { + type = number + default = 0 + description = <<-END + Require x number of approvals to satisfy branch protection requirements. + If this is specified it must be a number between 0-6. + END + } + } + + attribute "required_status_checks" { + type = object(required_status_checks) + default = null + description = <<-END + Enforce restrictions for required status checks. + See Required Status Checks below for details. + END + + attribute "strict" { + type = bool + default = false + description = <<-END + Require branches to be up to date before merging. + END + } + + attribute "contexts" { + type = list(string) + default = [] + description = <<-END + The list of status checks to require in order to merge into this branch. If default is `[]` no status checks are required. + END + } + } + } + } + section { title = "Issue Labels Configuration"