Skip to content

Commit 8d7a72f

Browse files
taharahtaharah
committed
chore(docs): include v4 branch protections
1 parent 2969be6 commit 8d7a72f

File tree

2 files changed

+296
-5
lines changed

2 files changed

+296
-5
lines changed

‎README.md‎

Lines changed: 133 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@ A [Terraform] module for creating a public or private repository on [Github].
2828
- [Collaborator Configuration](#collaborator-configuration)
2929
- [Branches Configuration](#branches-configuration)
3030
- [Deploy Keys Configuration](#deploy-keys-configuration)
31-
- [Branch Protections Configuration](#branch-protections-configuration)
31+
- [Branch Protections v3 Configuration](#branch-protections-v3-configuration)
32+
- [Branch Protections v4 Configuration](#branch-protections-v4-configuration)
3233
- [Issue Labels Configuration](#issue-labels-configuration)
3334
- [Projects Configuration](#projects-configuration)
3435
- [Webhooks Configuration](#webhooks-configuration)
@@ -528,11 +529,11 @@ This is due to some terraform limitation and we will update the module once terr
528529

529530
Default is `"md5(key)"`.
530531

531-
#### Branch Protections Configuration
532+
#### Branch Protections v3 Configuration
532533

533534
- [**`branch_protections_v3`**](#var-branch_protections_v3): *(Optional `list(branch_protection_v3)`)*<a name="var-branch_protections_v3"></a>
534535

535-
This resource allows you to configure branch protection for repositories in your organization.
536+
This resource allows you to configure v3 branch protection for repositories in your organization.
536537
When applied, the branch will be protected from forced pushes and deletion.
537538
Additional constraints, such as required status checks or restrictions on users and teams, can also be configured.
538539

@@ -652,6 +653,135 @@ This is due to some terraform limitation and we will update the module once terr
652653

653654
Default is `[]`.
654655

656+
#### Branch Protections v4 Configuration
657+
658+
- [**`branch_protections_v4`**](#var-branch_protections_v4): *(Optional `map(branch_protection_v4)`)*<a name="var-branch_protections_v4"></a>
659+
660+
This map allows you to configure v4 branch protection for repositories in your organization.
661+
662+
Each element in the map is a branch to be protected and the value the corresponding to the desired configuration for the branch.
663+
664+
When applied, the branch will be protected from forced pushes and deletion.
665+
Additional constraints, such as required status checks or restrictions on users and teams, can also be configured.
666+
667+
**_NOTE_** This will take precedence over v3 branch protections.
668+
669+
Default is `null`.
670+
671+
Each `branch_protection_v4` object in the map accepts the following attributes:
672+
673+
- [**`allows_deletions`**](#attr-branch_protections_v4-allows_deletions): *(Optional `bool`)*<a name="attr-branch_protections_v4-allows_deletions"></a>
674+
675+
Setting this to true to allow the branch to be deleted.
676+
677+
Default is `false`.
678+
679+
- [**`allows_force_pushes`**](#attr-branch_protections_v4-allows_force_pushes): *(Optional `bool`)*<a name="attr-branch_protections_v4-allows_force_pushes"></a>
680+
681+
Setting this to true to allow force pushes on the branch.
682+
683+
Default is `false`.
684+
685+
- [**`blocks_creations`**](#attr-branch_protections_v4-blocks_creations): *(Optional `bool`)*<a name="attr-branch_protections_v4-blocks_creations"></a>
686+
687+
Setting this to true will block creating the branch.
688+
689+
Default is `false`.
690+
691+
- [**`enforce_admins`**](#attr-branch_protections_v4-enforce_admins): *(Optional `bool`)*<a name="attr-branch_protections_v4-enforce_admins"></a>
692+
693+
Setting this to true enforces status checks for repository administrators.
694+
695+
Default is `false`.
696+
697+
- [**`push_restrictions`**](#attr-branch_protections_v4-push_restrictions): *(Optional `list(string)`)*<a name="attr-branch_protections_v4-push_restrictions"></a>
698+
699+
The list of actor Names/IDs that may push to the branch.
700+
Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams.
701+
702+
Default is `[]`.
703+
704+
- [**`require_conversation_resolution`**](#attr-branch_protections_v4-require_conversation_resolution): *(Optional `bool`)*<a name="attr-branch_protections_v4-require_conversation_resolution"></a>
705+
706+
Setting this to true requires all conversations on code must be resolved before a pull request can be merged.
707+
708+
Default is `false`.
709+
710+
- [**`require_signed_commits`**](#attr-branch_protections_v4-require_signed_commits): *(Optional `bool`)*<a name="attr-branch_protections_v4-require_signed_commits"></a>
711+
712+
Setting this to true requires all commits to be signed with GPG.
713+
714+
Default is `false`.
715+
716+
- [**`required_linear_history`**](#attr-branch_protections_v4-required_linear_history): *(Optional `bool`)*<a name="attr-branch_protections_v4-required_linear_history"></a>
717+
718+
Setting this to true enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch.
719+
720+
Default is `false`.
721+
722+
- [**`required_pull_request_reviews`**](#attr-branch_protections_v4-required_pull_request_reviews): *(Optional `object(required_pull_request_reviews)`)*<a name="attr-branch_protections_v4-required_pull_request_reviews"></a>
723+
724+
Enforce restrictions for pull request reviews.
725+
726+
Default is `null`.
727+
728+
The `required_pull_request_reviews` object accepts the following attributes:
729+
730+
- [**`dismiss_stale_reviews`**](#attr-branch_protections_v4-required_pull_request_reviews-dismiss_stale_reviews): *(Optional `bool`)*<a name="attr-branch_protections_v4-required_pull_request_reviews-dismiss_stale_reviews"></a>
731+
732+
Dismiss approved reviews automatically when a new commit is pushed.
733+
734+
Default is `true`.
735+
736+
- [**`dismissal_restrictions`**](#attr-branch_protections_v4-required_pull_request_reviews-dismissal_restrictions): *(Optional `list(string)`)*<a name="attr-branch_protections_v4-required_pull_request_reviews-dismissal_restrictions"></a>
737+
738+
The list of actor Names/IDs with dismissal access.
739+
If not empty, restrict_dismissals is ignored.
740+
Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams.
741+
742+
Default is `[]`.
743+
744+
- [**`pull_request_bypassers`**](#attr-branch_protections_v4-required_pull_request_reviews-pull_request_bypassers): *(Optional `list(string)`)*<a name="attr-branch_protections_v4-required_pull_request_reviews-pull_request_bypassers"></a>
745+
746+
The list of actor Names/IDs that are allowed to bypass pull request requirements.
747+
Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams.
748+
749+
Default is `[]`.
750+
751+
- [**`require_code_owner_reviews`**](#attr-branch_protections_v4-required_pull_request_reviews-require_code_owner_reviews): *(Optional `bool`)*<a name="attr-branch_protections_v4-required_pull_request_reviews-require_code_owner_reviews"></a>
752+
753+
Require an approved review in pull requests including files with a designated code owner.
754+
755+
Default is `false`.
756+
757+
- [**`required_approving_review_count`**](#attr-branch_protections_v4-required_pull_request_reviews-required_approving_review_count): *(Optional `number`)*<a name="attr-branch_protections_v4-required_pull_request_reviews-required_approving_review_count"></a>
758+
759+
Require x number of approvals to satisfy branch protection requirements.
760+
If this is specified it must be a number between 0-6.
761+
762+
Default is `0`.
763+
764+
- [**`required_status_checks`**](#attr-branch_protections_v4-required_status_checks): *(Optional `object(required_status_checks)`)*<a name="attr-branch_protections_v4-required_status_checks"></a>
765+
766+
Enforce restrictions for required status checks.
767+
See Required Status Checks below for details.
768+
769+
Default is `null`.
770+
771+
The `required_status_checks` object accepts the following attributes:
772+
773+
- [**`strict`**](#attr-branch_protections_v4-required_status_checks-strict): *(Optional `bool`)*<a name="attr-branch_protections_v4-required_status_checks-strict"></a>
774+
775+
Require branches to be up to date before merging.
776+
777+
Default is `false`.
778+
779+
- [**`contexts`**](#attr-branch_protections_v4-required_status_checks-contexts): *(Optional `list(string)`)*<a name="attr-branch_protections_v4-required_status_checks-contexts"></a>
780+
781+
The list of status checks to require in order to merge into this branch. If default is `[]` no status checks are required.
782+
783+
Default is `[]`.
784+
655785
#### Issue Labels Configuration
656786

657787
- [**`issue_labels`**](#var-issue_labels): *(Optional `list(issue_label)`)*<a name="var-issue_labels"></a>

‎README.tfdoc.hcl‎

Lines changed: 163 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -677,13 +677,13 @@ section {
677677
}
678678

679679
section {
680-
title = "Branch Protections Configuration"
680+
title = "Branch Protections v3 Configuration"
681681

682682
variable "branch_protections_v3" {
683683
type = list(branch_protection_v3)
684684
default = []
685685
description = <<-END
686-
This resource allows you to configure branch protection for repositories in your organization.
686+
This resource allows you to configure v3 branch protection for repositories in your organization.
687687
When applied, the branch will be protected from forced pushes and deletion.
688688
Additional constraints, such as required status checks or restrictions on users and teams, can also be configured.
689689
END
@@ -832,6 +832,167 @@ section {
832832
}
833833
}
834834

835+
section {
836+
title = "Branch Protections v4 Configuration"
837+
838+
variable "branch_protections_v4" {
839+
type = map(branch_protection_v4)
840+
default = null
841+
description = <<-END
842+
This map allows you to configure v4 branch protection for repositories in your organization.
843+
844+
Each element in the map is a branch to be protected and the value the corresponding to the desired configuration for the branch.
845+
846+
When applied, the branch will be protected from forced pushes and deletion.
847+
Additional constraints, such as required status checks or restrictions on users and teams, can also be configured.
848+
849+
**_NOTE_** This will take precedence over v3 branch protections.
850+
END
851+
852+
attribute "allows_deletions" {
853+
type = bool
854+
default = false
855+
description = <<-END
856+
Setting this to true to allow the branch to be deleted.
857+
END
858+
}
859+
860+
attribute "allows_force_pushes" {
861+
type = bool
862+
default = false
863+
description = <<-END
864+
Setting this to true to allow force pushes on the branch.
865+
END
866+
}
867+
868+
attribute "blocks_creations" {
869+
type = bool
870+
default = false
871+
description = <<-END
872+
Setting this to true will block creating the branch.
873+
END
874+
}
875+
876+
attribute "enforce_admins" {
877+
type = bool
878+
default = false
879+
description = <<-END
880+
Setting this to true enforces status checks for repository administrators.
881+
END
882+
}
883+
884+
attribute "push_restrictions" {
885+
type = list(string)
886+
default = []
887+
description = <<-END
888+
The list of actor Names/IDs that may push to the branch.
889+
Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams.
890+
END
891+
}
892+
893+
attribute "require_conversation_resolution" {
894+
type = bool
895+
default = false
896+
description = <<-END
897+
Setting this to true requires all conversations on code must be resolved before a pull request can be merged.
898+
END
899+
}
900+
901+
attribute "require_signed_commits" {
902+
type = bool
903+
default = false
904+
description = <<-END
905+
Setting this to true requires all commits to be signed with GPG.
906+
END
907+
}
908+
909+
attribute "required_linear_history" {
910+
type = bool
911+
default = false
912+
description = <<-END
913+
Setting this to true enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch.
914+
END
915+
}
916+
917+
attribute "required_pull_request_reviews" {
918+
type = object(required_pull_request_reviews)
919+
default = null
920+
description = <<-END
921+
Enforce restrictions for pull request reviews.
922+
END
923+
924+
attribute "dismiss_stale_reviews" {
925+
type = bool
926+
default = true
927+
description = <<-END
928+
Dismiss approved reviews automatically when a new commit is pushed.
929+
END
930+
}
931+
932+
attribute "dismissal_restrictions" {
933+
type = list(string)
934+
default = []
935+
description = <<-END
936+
The list of actor Names/IDs with dismissal access.
937+
If not empty, restrict_dismissals is ignored.
938+
Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams.
939+
END
940+
}
941+
942+
attribute "pull_request_bypassers" {
943+
type = list(string)
944+
default = []
945+
description = <<-END
946+
The list of actor Names/IDs that are allowed to bypass pull request requirements.
947+
Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams.
948+
END
949+
}
950+
951+
attribute "require_code_owner_reviews" {
952+
type = bool
953+
default = false
954+
description = <<-END
955+
Require an approved review in pull requests including files with a designated code owner.
956+
END
957+
}
958+
959+
attribute "required_approving_review_count" {
960+
type = number
961+
default = 0
962+
description = <<-END
963+
Require x number of approvals to satisfy branch protection requirements.
964+
If this is specified it must be a number between 0-6.
965+
END
966+
}
967+
}
968+
969+
attribute "required_status_checks" {
970+
type = object(required_status_checks)
971+
default = null
972+
description = <<-END
973+
Enforce restrictions for required status checks.
974+
See Required Status Checks below for details.
975+
END
976+
977+
attribute "strict" {
978+
type = bool
979+
default = false
980+
description = <<-END
981+
Require branches to be up to date before merging.
982+
END
983+
}
984+
985+
attribute "contexts" {
986+
type = list(string)
987+
default = []
988+
description = <<-END
989+
The list of status checks to require in order to merge into this branch. If default is `[]` no status checks are required.
990+
END
991+
}
992+
}
993+
}
994+
}
995+
835996
section {
836997
title = "Issue Labels Configuration"
837998

0 commit comments

Comments
 (0)