From f117f6925d80a55dc7903a755056eddd5a0a2757 Mon Sep 17 00:00:00 2001 From: Cyb3r-Jak3 Date: Sun, 12 Mar 2023 17:08:30 -0400 Subject: [PATCH 1/2] Add use of new checks --- README.md | 2233 +++++++++++++------------- README.tfdoc.hcl | 3088 ++++++++++++++++++------------------ main.tf | 4 +- test/unit-complete/main.tf | 3 +- variables.tf | 3 + 5 files changed, 2669 insertions(+), 2662 deletions(-) diff --git a/README.md b/README.md index eed6135..e40a65c 100644 --- a/README.md +++ b/README.md @@ -1,1116 +1,1117 @@ -[](https://mineiros.io/?ref=terraform-github-repository) - -[![Build Status](https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg)](https://github.com/mineiros-io/terraform-github-repository/actions) -[![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver)](https://github.com/mineiros-io/terraform-github-repository/releases) -[![Terraform Version](https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform)](https://github.com/hashicorp/terraform/releases) -[![Github Provider Version](https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform)](https://github.com/terraform-providers/terraform-provider-github/releases) -[![Join Slack](https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack)](https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg) - -# terraform-github-repository - -A [Terraform] module for creating a public or private repository on [Github]. - -**_This module supports Terraform v1.x and is compatible with the Official Terraform GitHub Provider v4.20 and above from `integrations/github`._** - -**Attention: This module is incompatible with the Hashicorp GitHub Provider! The latest version of this module supporting `hashicorp/github` provider is `~> 0.10.0`** - -** Note: Versions 5.3.0, 5.4.0, and 5.5.0 of the Terraform Github Provider have broken branch protections support and should not be used.** - - -- [GitHub as Code](#github-as-code) -- [Module Features](#module-features) -- [Getting Started](#getting-started) -- [Module Argument Reference](#module-argument-reference) - - [Main Resource Configuration](#main-resource-configuration) - - [Extended Resource Configuration](#extended-resource-configuration) - - [Repository Creation Configuration](#repository-creation-configuration) - - [Teams Configuration](#teams-configuration) - - [Collaborator Configuration](#collaborator-configuration) - - [Branches Configuration](#branches-configuration) - - [Deploy Keys Configuration](#deploy-keys-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) - - [Secrets Configuration](#secrets-configuration) - - [Autolink References Configuration](#autolink-references-configuration) - - [App Installations](#app-installations) - - [Module Configuration](#module-configuration) -- [Module Outputs](#module-outputs) -- [External Documentation](#external-documentation) - - [Terraform Github Provider Documentation](#terraform-github-provider-documentation) -- [Module Versioning](#module-versioning) - - [Backwards compatibility in `0.0.z` and `0.y.z` version](#backwards-compatibility-in-00z-and-0yz-version) -- [About Mineiros](#about-mineiros) -- [Reporting Issues](#reporting-issues) -- [Contributing](#contributing) -- [Makefile Targets](#makefile-targets) -- [License](#license) - -## GitHub as Code - -[GitHub as Code][github-as-code] is a commercial solution built on top of -our open-source Terraform modules for GitHub. It helps our customers to -manage their GitHub organization more efficiently by enabling anyone in -their organization to **self-service** manage **on- and offboarding of users**, -**repositories**, and settings such as **branch protections**, **secrets**, and more -through code. GitHub as Code comes with **pre-configured GitHub Actions -pipelines** for **change pre-view in Pull Requests**, **fully automated -rollouts** and **rollbacks**. It's a comprehensive, ready-to-use blueprint -maintained by our team of platform engineering experts and saves -companies such as yours tons of time by building on top of a pre-configured -solution instead of building and maintaining it yourself. - -For details please see [https://mineiros.io/github-as-code][github-as-code]. - -## Module Features - -In contrast to the plain `github_repository` resource this module enables various other -features like Branch Protection or Collaborator Management. - -- **Default Security Settings**: - This module creates a `private` repository by default, - Deploy keys are `read-only` by default - -- **Standard Repository Features**: - Setting basic Metadata, - Merge Strategy, - Auto Init, - License Template, - Gitignore Template, - Template Repository - -- **Extended Repository Features**: - Branches, - Branch Protection, - Issue Labels, - Handle Github Default Issue Labels, - Collaborators, - Teams, - Deploy Keys, - Projects, - Repository Webhooks - -- _Features not yet implemented_: - Project Columns support, - Actions, - Repository File - -## Getting Started - -Most basic usage creating a new private github repository. - -```hcl -module "repository" { - source = "mineiros-io/repository/github" - version = "~> 0.18.0" - - name = "terraform-github-repository" - license_template = "apache-2.0" - gitignore_template = "Terraform" -} -``` - -## Module Argument Reference - -See [variables.tf] and [examples/] for details and use-cases. - -### Main Resource Configuration - -- [**`name`**](#var-name): *(**Required** `string`)* - - The name of the repository. - -- [**`defaults`**](#var-defaults): *(Optional `object(defaults)`)* - - DEPRECATED: - This variable will be removed in future releases. - It was needed in times when Terraform Module for each was not available to provide default values for multiple repositories. - Please convert your code accordingly to stay compatible with future releases. - - Default is `{}`. - -- [**`pages`**](#var-pages): *(Optional `object(pages)`)* - - A object of settings to configure GitHub Pages in this repository. - See below for a list of supported arguments. - - Default is `{}`. - - The `pages` object accepts the following attributes: - - - [**`branch`**](#attr-pages-branch): *(**Required** `string`)* - - The repository branch used to publish the site's source files. - - - [**`path`**](#attr-pages-path): *(Optional `string`)* - - The repository directory from which the site publishes. - - - [**`cname`**](#attr-pages-cname): *(Optional `string`)* - - The custom domain for the repository. This can only be set after the - repository has been created. - -- [**`allow_merge_commit`**](#var-allow_merge_commit): *(Optional `bool`)* - - Set to `false` to disable merge commits on the repository. - If you set this to `false` you have to enable either `allow_squash_merge` - or `allow_rebase_merge`. - - Default is `true`. - -- [**`allow_squash_merge`**](#var-allow_squash_merge): *(Optional `bool`)* - - Set to `true` to enable squash merges on the repository. - - Default is `false`. - -- [**`allow_rebase_merge`**](#var-allow_rebase_merge): *(Optional `bool`)* - - Set to `true` to enable rebase merges on the repository. - - Default is `false`. - -- [**`allow_auto_merge`**](#var-allow_auto_merge): *(Optional `bool`)* - - Set to `true` to allow [auto-merging](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request) - pull requests on the repository. If you enable auto-merge for a pull - request, the pull request will merge automatically when all required - reviews are met and status checks have passed. - - Default is `false`. - -- [**`description`**](#var-description): *(Optional `string`)* - - A description of the repository. - - Default is `""`. - -- [**`delete_branch_on_merge`**](#var-delete_branch_on_merge): *(Optional `bool`)* - - Set to `false` to disable the automatic deletion of head branches after pull requests are merged. - - Default is `true`. - -- [**`homepage_url`**](#var-homepage_url): *(Optional `string`)* - - URL of a page describing the project. - - Default is `""`. - -- [**`private`**](#var-private): *(Optional `bool`)* - - **_DEPRECATED_**: Please use `visibility` instead and update your code. parameter will be removed in a future version - -- [**`visibility`**](#var-visibility): *(Optional `string`)* - - Can be `public` or `private`. - If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, `visibility` can also be `internal`. - The `visibility` parameter overrides the deprecated `private` parameter. - - Default is `"private"`. - -- [**`has_issues`**](#var-has_issues): *(Optional `bool`)* - - Set to true to enable the GitHub Issues features on the repository. - - Default is `false`. - -- [**`has_projects`**](#var-has_projects): *(Optional `bool`)* - - Set to true to enable the GitHub Projects features on the repository. - - Default is `false`. - -- [**`has_wiki`**](#var-has_wiki): *(Optional `bool`)* - - Set to true to enable the GitHub Wiki features on the repository. - - Default is `false`. - -- [**`has_downloads`**](#var-has_downloads): *(Optional `bool`)* - - Set to `true` to enable the (deprecated) downloads features on the repository. - - Default is `false`. - -- [**`is_template`**](#var-is_template): *(Optional `bool`)* - - Set to `true` to tell GitHub that this is a template repository. - - Default is `false`. - -- [**`default_branch`**](#var-default_branch): *(Optional `string`)* - - The name of the default branch of the repository. - NOTE: The configured default branch must exist in the repository. - If the branch doesn't exist yet, or if you are creating a new - repository, please add the desired default branch to the `branches` - variable, which will cause Terraform to create it for you. - - Default is `""`. - -- [**`archived`**](#var-archived): *(Optional `bool`)* - - Specifies if the repository should be archived. - NOTE: Currently, the API does not support unarchiving. - - Default is `false`. - -- [**`topics`**](#var-topics): *(Optional `list(string)`)* - - The list of topics of the repository. - - Default is `[]`. - -- [**`extra_topics`**](#var-extra_topics): *(Optional `list(string)`)* - - A list of additional topics of the repository. Those topics will be added to the list of `topics`. This is useful if `default.topics` are used and the list should be extended with more topics. - - Default is `[]`. - -- [**`vulnerability_alerts`**](#var-vulnerability_alerts): *(Optional `bool`)* - - Set to `false` to disable security alerts for vulnerable dependencies. - Enabling requires alerts to be enabled on the owner level. - -- [**`archive_on_destroy`**](#var-archive_on_destroy): *(Optional `bool`)* - - Set to `false` to not archive the repository instead of deleting on destroy. - - Default is `true`. - -### Extended Resource Configuration - -#### Repository Creation Configuration - -The following four arguments can only be set at repository creation and -changes will be ignored for repository updates and -will not show a diff in plan or apply phase. - -- [**`auto_init`**](#var-auto_init): *(Optional `bool`)* - - Set to `false` to not produce an initial commit in the repository. - - Default is `true`. - -- [**`gitignore_template`**](#var-gitignore_template): *(Optional `string`)* - - Use the name of the template without the extension. - - Default is `""`. - -- [**`license_template`**](#var-license_template): *(Optional `string`)* - - Use the name of the template without the extension. - - Default is `""`. - -- [**`template`**](#var-template): *(Optional `object(template)`)* - - Use a template repository to create this resource. - - Default is `{}`. - - The `template` object accepts the following attributes: - - - [**`owner`**](#attr-template-owner): *(**Required** `string`)* - - The GitHub organization or user the template repository is owned by. - - - [**`repository`**](#attr-template-repository): *(**Required** `string`)* - - The name of the template repository. - -#### Teams Configuration - -Your can use non-computed (known at `terraform plan`) team names or slugs (`*_teams` Attributes) -or computed (only known in `terraform apply` phase) team IDs (`*_team_ids` Attributes). -**When using non-computed names/slugs teams need to exist before running plan.** -This is due to some terraform limitation and we will update the module once terraform removed this limitation. - -- [**`pull_teams`**](#var-pull_teams): *(Optional `list(string)`)* - - Can also be `pull_team_ids`. A list of teams to grant pull (read-only) permission. - Recommended for non-code contributors who want to view or discuss your project. - - Default is `[]`. - -- [**`triage_teams`**](#var-triage_teams): *(Optional `list(string)`)* - - Can also be `triage_team_ids`. A list of teams to grant triage permission. - Recommended for contributors who need to proactively manage issues and pull requests - without write access. - - Default is `[]`. - -- [**`push_teams`**](#var-push_teams): *(Optional `list(string)`)* - - Can also be `push_team_ids`. A list of teams to grant push (read-write) permission. - Recommended for contributors who actively push to your project. - - Default is `[]`. - -- [**`maintain_teams`**](#var-maintain_teams): *(Optional `list(string)`)* - - Can also be `maintain_team_ids`. A list of teams to grant maintain permission. - Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. - - Default is `[]`. - -- [**`admin_teams`**](#var-admin_teams): *(Optional `list(string)`)* - - Can also be `admin_team_ids`. A list of teams to grant admin (full) permission. - Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. - - Default is `[]`. - -#### Collaborator Configuration - -- [**`pull_collaborators`**](#var-pull_collaborators): *(Optional `list(string)`)* - - A list of user names to add as collaborators granting them pull (read-only) permission. - Recommended for non-code contributors who want to view or discuss your project. - - Default is `[]`. - -- [**`triage_collaborators`**](#var-triage_collaborators): *(Optional `list(string)`)* - - A list of user names to add as collaborators granting them triage permission. - Recommended for contributors who need to proactively manage issues and pull requests without write access. - - Default is `[]`. - -- [**`push_collaborators`**](#var-push_collaborators): *(Optional `list(string)`)* - - A list of user names to add as collaborators granting them push (read-write) permission. - Recommended for contributors who actively push to your project. - - Default is `[]`. - -- [**`maintain_collaborators`**](#var-maintain_collaborators): *(Optional `list(string)`)* - - A list of user names to add as collaborators granting them maintain permission. - Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. - - Default is `[]`. - -- [**`admin_collaborators`**](#var-admin_collaborators): *(Optional `list(string)`)* - - A list of user names to add as collaborators granting them admin (full) permission. - Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. - - Default is `[]`. - -#### Branches Configuration - -- [**`branches`**](#var-branches): *(Optional `list(branch)`)* - - Create and manage branches within your repository. - Additional constraints can be applied to ensure your branch is created from another branch or commit. - - Default is `[]`. - - Each `branch` object in the list accepts the following attributes: - - - [**`name`**](#attr-branches-name): *(**Required** `string`)* - - The name of the branch to create. - - - [**`source_branch`**](#attr-branches-source_branch): *(Optional `string`)* - - The branch name to start from. Uses the configured default branch per default. - - - [**`source_sha`**](#attr-branches-source_sha): *(Optional `bool`)* - - The commit hash to start from. Defaults to the tip of `source_branch`. If provided, `source_branch` is ignored. - - Default is `true`. - -#### Deploy Keys Configuration - -- [**`deploy_keys`**](#var-deploy_keys): *(Optional `list(deploy_key)`)* - - Can also be type `list(string)`. Specifies deploy keys and access-level of deploy keys used in this repository. - Every `string` in the list will be converted internally into the `object` representation with the `key` argument being set to the `string`. `object` details are explained below. - - Default is `[]`. - - Each `deploy_key` object in the list accepts the following attributes: - - - [**`key`**](#attr-deploy_keys-key): *(**Required** `string`)* - - The SSH public key. - - - [**`title`**](#attr-deploy_keys-title): *(Optional `string`)* - - A Title for the key. - Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. - - - [**`read_only`**](#attr-deploy_keys-read_only): *(Optional `bool`)* - - Specifies the level of access for the key. - - Default is `true`. - - - [**`id`**](#attr-deploy_keys-id): *(Optional `string`)* - - Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. - The ID must be unique between `deploy_keys` and `deploy_keys_computed`. - - Default is `"md5(key)"`. - -- [**`deploy_keys_computed`**](#var-deploy_keys_computed): *(Optional `list(deploy_key)`)* - - Can also be type `string`. Same as `deploy_keys` argument with the following differences: - Use this argument if you depend on computed keys that terraform can not use in resource `for_each` execution. Downside of this is the recreation of deploy key resources whenever the order in the list changes. **Prefer `deploy_keys` whenever possible.** - This argument does **not** conflict with `deploy_keys` and should exclusively be used for computed resources. - - Default is `[]`. - - Each `deploy_key` object in the list accepts the following attributes: - - - [**`key`**](#attr-deploy_keys_computed-key): *(**Required** `string`)* - - The SSH public key. - - - [**`title`**](#attr-deploy_keys_computed-title): *(Optional `string`)* - - A Title for the key. - Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. - - - [**`read_only`**](#attr-deploy_keys_computed-read_only): *(Optional `bool`)* - - Specifies the level of access for the key. - - Default is `true`. - - - [**`id`**](#attr-deploy_keys_computed-id): *(Optional `string`)* - - Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. - The ID must be unique between `deploy_keys` and `deploy_keys_computed`. - - Default is `"md5(key)"`. - -#### Branch Protections v3 Configuration - -- [**`branch_protections_v3`**](#var-branch_protections_v3): *(Optional `list(branch_protection_v3)`)* - - 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. - - Default is `[]`. - - Each `branch_protection_v3` object in the list accepts the following attributes: - - - [**`branch`**](#attr-branch_protections_v3-branch): *(**Required** `string`)* - - The Git branch to protect. - - - [**`enforce_admins`**](#attr-branch_protections_v3-enforce_admins): *(Optional `bool`)* - - Setting this to true enforces status checks for repository administrators. - - Default is `false`. - - - [**`require_conversation_resolution`**](#attr-branch_protections_v3-require_conversation_resolution): *(Optional `bool`)* - - Setting this to true requires all conversations to be resolved. - - Default is `false`. - - - [**`require_signed_commits`**](#attr-branch_protections_v3-require_signed_commits): *(Optional `bool`)* - - Setting this to true requires all commits to be signed with GPG. - - Default is `false`. - - - [**`required_status_checks`**](#attr-branch_protections_v3-required_status_checks): *(Optional `object(required_status_checks)`)* - - Enforce restrictions for required status checks. - See Required Status Checks below for details. - - Default is `{}`. - - The `required_status_checks` object accepts the following attributes: - - - [**`strict`**](#attr-branch_protections_v3-required_status_checks-strict): *(Optional `bool`)* - - Require branches to be up to date before merging. - - Default is `false`. - - - [**`contexts`**](#attr-branch_protections_v3-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 `[]`. - - - [**`required_pull_request_reviews`**](#attr-branch_protections_v3-required_pull_request_reviews): *(Optional `object(required_pull_request_reviews)`)* - - Enforce restrictions for pull request reviews. - - Default is `{}`. - - The `required_pull_request_reviews` object accepts the following attributes: - - - [**`dismiss_stale_reviews`**](#attr-branch_protections_v3-required_pull_request_reviews-dismiss_stale_reviews): *(Optional `bool`)* - - Dismiss approved reviews automatically when a new commit is pushed. - - Default is `true`. - - - [**`dismissal_users`**](#attr-branch_protections_v3-required_pull_request_reviews-dismissal_users): *(Optional `list(string)`)* - - The list of user logins with dismissal access - - Default is `[]`. - - - [**`dismissal_teams`**](#attr-branch_protections_v3-required_pull_request_reviews-dismissal_teams): *(Optional `list(string)`)* - - The list of team slugs with dismissal access. - Always use slug of the team, not its name. - Each team already has to have access to the repository. - - Default is `[]`. - - - [**`require_code_owner_reviews`**](#attr-branch_protections_v3-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`. - - - [**`restrictions`**](#attr-branch_protections_v3-restrictions): *(Optional `object(restrictions)`)* - - Enforce restrictions for the users and teams that may push to the branch - only available for organization-owned repositories. See Restrictions below for details. - - Default is `{}`. - - The `restrictions` object accepts the following attributes: - - - [**`users`**](#attr-branch_protections_v3-restrictions-users): *(Optional `list(string)`)* - - The list of user logins with push access. - - Default is `[]`. - - - [**`teams`**](#attr-branch_protections_v3-restrictions-teams): *(Optional `list(string)`)* - - The list of team slugs with push access. - Always use slug of the team, not its name. - Each team already has to have access to the repository. - - Default is `[]`. - - - [**`apps`**](#attr-branch_protections_v3-restrictions-apps): *(Optional `list(string)`)* - - The list of app slugs with push access. - - Default is `[]`. - -#### Branch Protections v4 Configuration - -- [**`branch_protections_v4`**](#var-branch_protections_v4): *(Optional `list(branch_protection_v4)`)* - - This resource allows you to configure v4 branch protection for repositories in your organization. - - Each element in the list 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:_** May conflict with v3 branch protections if used for the same branch. - - Default is `[]`. - - Each `branch_protection_v4` object in the list accepts the following attributes: - - - [**`pattern`**](#attr-branch_protections_v4-pattern): *(**Required** `string`)* - - Identifies the protection rule pattern. - - - [**`_key`**](#attr-branch_protections_v4-_key): *(Optional `string`)* - - An alternative key to use in `for_each` resource creation. - Defaults to the value of `var.pattern`. - - - [**`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`)* - - Keeping this as `true` enforces status checks for repository administrators. - - Default is `true`. - - - [**`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. - - 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`. - - - [**`restrict_dismissals`**](#attr-branch_protections_v4-required_pull_request_reviews-restrict_dismissals): *(Optional `bool`)* - - Restrict pull request review dismissals. - - - [**`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 `true`. - - - [**`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. - - 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)`)* - - This resource allows you to create and manage issue labels within your GitHub organization. - Issue labels are keyed off of their "name", so pre-existing issue labels result in a 422 HTTP error if they exist outside of Terraform. - Normally this would not be an issue, except new repositories are created with a "default" set of labels, and those labels easily conflict with custom ones. - This resource will first check if the label exists, and then issue an update, otherwise it will create. - - Default is `[]`. - - Each `issue_label` object in the list accepts the following attributes: - - - [**`name`**](#attr-issue_labels-name): *(**Required** `string`)* - - The name of the label. - - - [**`color`**](#attr-issue_labels-color): *(**Required** `string`)* - - A 6 character hex code, without the leading `#`, identifying the color of the label. - - - [**`description`**](#attr-issue_labels-description): *(Optional `string`)* - - A short description of the label. - - Default is `""`. - - - [**`id`**](#attr-issue_labels-id): *(Optional `string`)* - - Specifies an ID which is used to prevent resource recreation when the order in the list of issue labels changes. - - Default is `"name"`. - -- [**`issue_labels_merge_with_github_labels`**](#var-issue_labels_merge_with_github_labels): *(Optional `bool`)* - - Specify if github default labels will be handled by terraform. This should be decided on upon creation of the repository. If you later decide to disable this feature, github default labels will be destroyed if not replaced by labels set in `issue_labels` argument. - -- [**`issue_labels_create`**](#var-issue_labels_create): *(Optional `bool`)* - - Specify whether you want to force or suppress the creation of issues labels. - Default is `true` if `has_issues` is `true` or `issue_labels` is non-empty. - -#### Projects Configuration - -- [**`projects`**](#var-projects): *(Optional `list(project)`)* - - This resource allows you to create and manage projects for GitHub repository. - - Default is `[]`. - - Each `project` object in the list accepts the following attributes: - - - [**`name`**](#attr-projects-name): *(**Required** `string`)* - - The name of the project. - - - [**`body`**](#attr-projects-body): *(Optional `string`)* - - The body of the project. - - Default is `""`. - - - [**`id`**](#attr-projects-id): *(Optional `string`)* - - Specifies an ID which is used to prevent resource recreation when the order in the list of projects changes. - - Default is `"name"`. - -#### Webhooks Configuration - -- [**`webhooks`**](#var-webhooks): *(Optional `list(webhook)`)* - - This resource allows you to create and manage webhooks for repositories in your organization. - When applied, a webhook will be created which specifies a URL to receive events and which events to receieve. Additional constraints, such as SSL verification, pre-shared secret and content type can also be configured - - Default is `[]`. - - Each `webhook` object in the list accepts the following attributes: - - - [**`events`**](#attr-webhooks-events): *(**Required** `list(string)`)* - - A list of events which should trigger the webhook. [See a list of available events.](https://developer.github.com/v3/activity/events/types/) - - - [**`url`**](#attr-webhooks-url): *(**Required** `string`)* - - The URL to which the payloads will be delivered. - - - [**`active`**](#attr-webhooks-active): *(Optional `bool`)* - - Indicate if the webhook should receive events. Defaults to `true`. - - - [**`content_type`**](#attr-webhooks-content_type): *(Optional `string`)* - - The media type used to serialize the payloads. Supported values include `json` and `form`. - - Default is `"form"`. - - - [**`secret`**](#attr-webhooks-secret): *(Optional `string`)* - - If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value in the [X-Hub-Signature](https://developer.github.com/webhooks/#delivery-headers) header. - - - [**`insecure_ssl`**](#attr-webhooks-insecure_ssl): *(Optional `bool`)* - - Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. **We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.** - -#### Secrets Configuration - -- [**`plaintext_secrets`**](#var-plaintext_secrets): *(Optional `map(string)`)* - - This map allows you to create and manage secrets for repositories in your organization. - - Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding secret in plain text: - - When applied, a secret with the given key and value will be created in the repositories. - - The value of the secrets must be given in plain text, GitHub provider is in charge of encrypting it. - - **Attention:** You should treat state as sensitive always. It is also advised that you do not store plaintext values in your code but rather populate the encrypted_value using fields from a resource, data source or variable as, while encrypted in state, these will be easily accessible in your code. See below for an example of this abstraction. - - Default is `{}`. - - Example: - - ```hcl - plaintext_secrets = { - SECRET_NAME_1 = "plaintext_secret_value_1" - SECRET_NAME_2 = "plaintext_secret_value_2" - } - ``` - -- [**`encrypted_secrets`**](#var-encrypted_secrets): *(Optional `map(string)`)* - - This map allows you to create and manage encrypted secrets for repositories in your organization. - - Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding encrypted value of the secret using the Github public key in Base64 format.b - - When applied, a secret with the given key and value will be created in the repositories. - - Default is `{}`. - - Example: - - ```hcl - encrypted_secrets = { - SECRET_NAME_1 = "c2VjcmV0X3ZhbHVlXzE=" - SECRET_NAME_2 = "c2VjcmV0X3ZhbHVlXzI=" - } - ``` - -- [**`required_approving_review_count`**](#var-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 1-6. - This requirement matches Github's API, see the upstream documentation for more information. - Default is no approving reviews are required. - -#### Autolink References Configuration - -- [**`autolink_references`**](#var-autolink_references): *(Optional `list(autolink_reference)`)* - - This resource allows you to create and manage autolink references for GitHub repository. - - Default is `[]`. - - Each `autolink_reference` object in the list accepts the following attributes: - - - [**`key_prefix`**](#attr-autolink_references-key_prefix): *(**Required** `string`)* - - This prefix appended by a number will generate a link any time it is found in an issue, pull request, or commit. - - - [**`target_url_template`**](#attr-autolink_references-target_url_template): *(**Required** `string`)* - - The template of the target URL used for the links; must be a valid URL and contain `` for the reference number. - -#### App Installations - -- [**`app_installations`**](#var-app_installations): *(Optional `set(string)`)* - - A set of GitHub App IDs to be installed in this repository. - - Default is `{}`. - - Example: - - ```hcl - app_installations = ["05405144", "12556423"] - ``` - -### Module Configuration - -- [**`module_depends_on`**](#var-module_depends_on): *(Optional `list(dependency)`)* - - Due to the fact, that terraform does not offer `depends_on` on modules as of today (v0.12.24) - we might hit race conditions when dealing with team names instead of ids. - So when using the feature of [adding teams by slug/name](#teams-configuration) to the repository when creating it, - make sure to add all teams to this list as indirect dependencies. - - Default is `[]`. - -## Module Outputs - -The following attributes are exported by the module: - -- [**`repository`**](#output-repository): *(`object(repository)`)* - - All repository attributes as returned by the [`github_repository`] - resource containing all arguments as specified above and the other - attributes as specified below. - -- [**`branches`**](#output-branches): *(`object(branches)`)* - - All repository attributes as returned by the [`github_branch`] - resource containing all arguments as specified above and the other - attributes as specified below. - -- [**`full_name`**](#output-full_name): *(`string`)* - - A string of the form "orgname/reponame". - -- [**`html_url`**](#output-html_url): *(`string`)* - - URL to the repository on the web. - -- [**`ssh_clone_url`**](#output-ssh_clone_url): *(`string`)* - - URL that can be provided to git clone to clone the repository via SSH. - -- [**`http_clone_url`**](#output-http_clone_url): *(`string`)* - - URL that can be provided to git clone to clone the repository via HTTPS. - -- [**`git_clone_url`**](#output-git_clone_url): *(`string`)* - - URL that can be provided to git clone to clone the repository - anonymously via the git protocol. - -- [**`collaborators`**](#output-collaborators): *(`object(collaborators)`)* - - A map of Collaborator objects keyed by the `name` of the collaborator as - returned by the [`github_repository_collaborator`] resource. - -- [**`deploy_keys`**](#output-deploy_keys): *(`object(deploy_keys)`)* - - A merged map of deploy key objects for the keys originally passed via - `deploy_keys` and `deploy_keys_computed` as returned by the - [`github_repository_deploy_key`] resource keyed by the input `id` of the - key. - -- [**`projects`**](#output-projects): *(`object(project)`)* - - A map of Project objects keyed by the `id` of the project as returned by - the [`github_repository_project`] resource - -- [**`issue_labels`**](#output-issue_labels): *(`object(issue_label)`)* - - A map of issue labels keyed by label input id or name. - -- [**`webhooks`**](#output-webhooks): *(`object(webhook)`)* - - All attributes and arguments as returned by the - `github_repository_webhook` resource. - -- [**`secrets`**](#output-secrets): *(`object(secret)`)* - - List of secrets available. - -- [**`app_installations`**](#output-app_installations): *(`set(number)`)* - - A map of deploy app installations keyed by installation id. - -## External Documentation - -### Terraform Github Provider Documentation - -- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository -- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/branch -- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_collaborator -- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_deploy_key -- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_project -- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_autolink_reference - -## Module Versioning - -This Module follows the principles of [Semantic Versioning (SemVer)]. - -Given a version number `MAJOR.MINOR.PATCH`, we increment the: - -1. `MAJOR` version when we make incompatible changes, -2. `MINOR` version when we add functionality in a backwards compatible manner, and -3. `PATCH` version when we make backwards compatible bug fixes. - -### Backwards compatibility in `0.0.z` and `0.y.z` version - -- Backwards compatibility in versions `0.0.z` is **not guaranteed** when `z` is increased. (Initial development) -- Backwards compatibility in versions `0.y.z` is **not guaranteed** when `y` is increased. (Pre-release) - -## About Mineiros - -[Mineiros][homepage] is a remote-first company headquartered in Berlin, Germany -that solves development, automation and security challenges in cloud infrastructure. - -Our vision is to massively reduce time and overhead for teams to manage and -deploy production-grade and secure cloud infrastructure. - -We offer commercial support for all of our modules and encourage you to reach out -if you have any questions or need help. Feel free to email us at [hello@mineiros.io] or join our -[Community Slack channel][slack]. - -## Reporting Issues - -We use GitHub [Issues] to track community reported issues and missing features. - -## Contributing - -Contributions are always encouraged and welcome! For the process of accepting changes, we use -[Pull Requests]. If you'd like more information, please see our [Contribution Guidelines]. - -## Makefile Targets - -This repository comes with a handy [Makefile]. -Run `make help` to see details on each available target. - -## License - -[![license][badge-license]][apache20] - -This module is licensed under the Apache License Version 2.0, January 2004. -Please see [LICENSE] for full details. - -Copyright © 2020-2022 [Mineiros GmbH][homepage] - - - - -[github]: https://github.com/ -[`github_repository`]: https://www.terraform.io/docs/providers/github/r/repository.html#attributes-reference -[`github_repository_collaborator`]: https://www.terraform.io/docs/providers/github/r/repository_collaborator.html#attribute-reference -[`github_repository_deploy_key`]: https://www.terraform.io/docs/providers/github/r/repository_deploy_key.html#attributes-reference -[`github_repository_project`]: https://www.terraform.io/docs/providers/github/r/repository_project.html#attributes-reference -[`github_repository_autolink_reference`]: https://www.terraform.io/docs/providers/github/r/repository_autolink_reference.html#attributes-reference -[homepage]: https://mineiros.io/?ref=terraform-github-repository -[github-as-code]: https://mineiros.io/github-as-code?ref=terraform-github-repository -[hello@mineiros.io]: mailto:hello@mineiros.io -[badge-build]: https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg -[badge-semver]: https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver -[badge-license]: https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg -[badge-terraform]: https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform -[badge-slack]: https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack -[badge-tf-gh]: https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform -[releases-github-provider]: https://github.com/terraform-providers/terraform-provider-github/releases -[build-status]: https://github.com/mineiros-io/terraform-github-repository/actions -[releases-github]: https://github.com/mineiros-io/terraform-github-repository/releases -[releases-terraform]: https://github.com/hashicorp/terraform/releases -[apache20]: https://opensource.org/licenses/Apache-2.0 -[slack]: https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg -[terraform]: https://www.terraform.io -[aws]: https://aws.amazon.com/ -[semantic versioning (semver)]: https://semver.org/ -[variables.tf]: https://github.com/mineiros-io/terraform-github-repository/blob/main/variables.tf -[examples/]: https://github.com/mineiros-io/terraform-github-repository/blob/main/examples -[issues]: https://github.com/mineiros-io/terraform-github-repository/issues -[license]: https://github.com/mineiros-io/terraform-github-repository/blob/main/LICENSE -[makefile]: https://github.com/mineiros-io/terraform-github-repository/blob/main/Makefile -[pull requests]: https://github.com/mineiros-io/terraform-github-repository/pulls -[contribution guidelines]: https://github.com/mineiros-io/terraform-github-repository/blob/main/CONTRIBUTING.md +[](https://mineiros.io/?ref=terraform-github-repository) + +[![Build Status](https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg)](https://github.com/mineiros-io/terraform-github-repository/actions) +[![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver)](https://github.com/mineiros-io/terraform-github-repository/releases) +[![Terraform Version](https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform)](https://github.com/hashicorp/terraform/releases) +[![Github Provider Version](https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform)](https://github.com/terraform-providers/terraform-provider-github/releases) +[![Join Slack](https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack)](https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg) + +# terraform-github-repository + +A [Terraform] module for creating a public or private repository on [Github]. + +**_This module supports Terraform v1.x and is compatible with the Official Terraform GitHub Provider v4.20 and above from `integrations/github`._** + +**Attention: This module is incompatible with the Hashicorp GitHub Provider! The latest version of this module supporting `hashicorp/github` provider is `~> 0.10.0`** + +** Note: Versions 5.3.0, 5.4.0, and 5.5.0 of the Terraform Github Provider have broken branch protections support and should not be used.** + + +- [terraform-github-repository](#terraform-github-repository) + - [GitHub as Code](#github-as-code) + - [Module Features](#module-features) + - [Getting Started](#getting-started) + - [Module Argument Reference](#module-argument-reference) + - [Main Resource Configuration](#main-resource-configuration) + - [Extended Resource Configuration](#extended-resource-configuration) + - [Repository Creation Configuration](#repository-creation-configuration) + - [Teams Configuration](#teams-configuration) + - [Collaborator Configuration](#collaborator-configuration) + - [Branches Configuration](#branches-configuration) + - [Deploy Keys Configuration](#deploy-keys-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) + - [Secrets Configuration](#secrets-configuration) + - [Autolink References Configuration](#autolink-references-configuration) + - [App Installations](#app-installations) + - [Module Configuration](#module-configuration) + - [Module Outputs](#module-outputs) + - [External Documentation](#external-documentation) + - [Terraform Github Provider Documentation](#terraform-github-provider-documentation) + - [Module Versioning](#module-versioning) + - [Backwards compatibility in `0.0.z` and `0.y.z` version](#backwards-compatibility-in-00z-and-0yz-version) + - [About Mineiros](#about-mineiros) + - [Reporting Issues](#reporting-issues) + - [Contributing](#contributing) + - [Makefile Targets](#makefile-targets) + - [License](#license) + +## GitHub as Code + +[GitHub as Code][github-as-code] is a commercial solution built on top of +our open-source Terraform modules for GitHub. It helps our customers to +manage their GitHub organization more efficiently by enabling anyone in +their organization to **self-service** manage **on- and offboarding of users**, +**repositories**, and settings such as **branch protections**, **secrets**, and more +through code. GitHub as Code comes with **pre-configured GitHub Actions +pipelines** for **change pre-view in Pull Requests**, **fully automated +rollouts** and **rollbacks**. It's a comprehensive, ready-to-use blueprint +maintained by our team of platform engineering experts and saves +companies such as yours tons of time by building on top of a pre-configured +solution instead of building and maintaining it yourself. + +For details please see [https://mineiros.io/github-as-code][github-as-code]. + +## Module Features + +In contrast to the plain `github_repository` resource this module enables various other +features like Branch Protection or Collaborator Management. + +- **Default Security Settings**: + This module creates a `private` repository by default, + Deploy keys are `read-only` by default + +- **Standard Repository Features**: + Setting basic Metadata, + Merge Strategy, + Auto Init, + License Template, + Gitignore Template, + Template Repository + +- **Extended Repository Features**: + Branches, + Branch Protection, + Issue Labels, + Handle Github Default Issue Labels, + Collaborators, + Teams, + Deploy Keys, + Projects, + Repository Webhooks + +- _Features not yet implemented_: + Project Columns support, + Actions, + Repository File + +## Getting Started + +Most basic usage creating a new private github repository. + +```hcl +module "repository" { + source = "mineiros-io/repository/github" + version = "~> 0.18.0" + + name = "terraform-github-repository" + license_template = "apache-2.0" + gitignore_template = "Terraform" +} +``` + +## Module Argument Reference + +See [variables.tf] and [examples/] for details and use-cases. + +### Main Resource Configuration + +- [**`name`**](#var-name): *(**Required** `string`)* + + The name of the repository. + +- [**`defaults`**](#var-defaults): *(Optional `object(defaults)`)* + + DEPRECATED: + This variable will be removed in future releases. + It was needed in times when Terraform Module for each was not available to provide default values for multiple repositories. + Please convert your code accordingly to stay compatible with future releases. + + Default is `{}`. + +- [**`pages`**](#var-pages): *(Optional `object(pages)`)* + + A object of settings to configure GitHub Pages in this repository. + See below for a list of supported arguments. + + Default is `{}`. + + The `pages` object accepts the following attributes: + + - [**`branch`**](#attr-pages-branch): *(**Required** `string`)* + + The repository branch used to publish the site's source files. + + - [**`path`**](#attr-pages-path): *(Optional `string`)* + + The repository directory from which the site publishes. + + - [**`cname`**](#attr-pages-cname): *(Optional `string`)* + + The custom domain for the repository. This can only be set after the + repository has been created. + +- [**`allow_merge_commit`**](#var-allow_merge_commit): *(Optional `bool`)* + + Set to `false` to disable merge commits on the repository. + If you set this to `false` you have to enable either `allow_squash_merge` + or `allow_rebase_merge`. + + Default is `true`. + +- [**`allow_squash_merge`**](#var-allow_squash_merge): *(Optional `bool`)* + + Set to `true` to enable squash merges on the repository. + + Default is `false`. + +- [**`allow_rebase_merge`**](#var-allow_rebase_merge): *(Optional `bool`)* + + Set to `true` to enable rebase merges on the repository. + + Default is `false`. + +- [**`allow_auto_merge`**](#var-allow_auto_merge): *(Optional `bool`)* + + Set to `true` to allow [auto-merging](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request) + pull requests on the repository. If you enable auto-merge for a pull + request, the pull request will merge automatically when all required + reviews are met and status checks have passed. + + Default is `false`. + +- [**`description`**](#var-description): *(Optional `string`)* + + A description of the repository. + + Default is `""`. + +- [**`delete_branch_on_merge`**](#var-delete_branch_on_merge): *(Optional `bool`)* + + Set to `false` to disable the automatic deletion of head branches after pull requests are merged. + + Default is `true`. + +- [**`homepage_url`**](#var-homepage_url): *(Optional `string`)* + + URL of a page describing the project. + + Default is `""`. + +- [**`private`**](#var-private): *(Optional `bool`)* + + **_DEPRECATED_**: Please use `visibility` instead and update your code. parameter will be removed in a future version + +- [**`visibility`**](#var-visibility): *(Optional `string`)* + + Can be `public` or `private`. + If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, `visibility` can also be `internal`. + The `visibility` parameter overrides the deprecated `private` parameter. + + Default is `"private"`. + +- [**`has_issues`**](#var-has_issues): *(Optional `bool`)* + + Set to true to enable the GitHub Issues features on the repository. + + Default is `false`. + +- [**`has_projects`**](#var-has_projects): *(Optional `bool`)* + + Set to true to enable the GitHub Projects features on the repository. + + Default is `false`. + +- [**`has_wiki`**](#var-has_wiki): *(Optional `bool`)* + + Set to true to enable the GitHub Wiki features on the repository. + + Default is `false`. + +- [**`has_downloads`**](#var-has_downloads): *(Optional `bool`)* + + Set to `true` to enable the (deprecated) downloads features on the repository. + + Default is `false`. + +- [**`is_template`**](#var-is_template): *(Optional `bool`)* + + Set to `true` to tell GitHub that this is a template repository. + + Default is `false`. + +- [**`default_branch`**](#var-default_branch): *(Optional `string`)* + + The name of the default branch of the repository. + NOTE: The configured default branch must exist in the repository. + If the branch doesn't exist yet, or if you are creating a new + repository, please add the desired default branch to the `branches` + variable, which will cause Terraform to create it for you. + + Default is `""`. + +- [**`archived`**](#var-archived): *(Optional `bool`)* + + Specifies if the repository should be archived. + NOTE: Currently, the API does not support unarchiving. + + Default is `false`. + +- [**`topics`**](#var-topics): *(Optional `list(string)`)* + + The list of topics of the repository. + + Default is `[]`. + +- [**`extra_topics`**](#var-extra_topics): *(Optional `list(string)`)* + + A list of additional topics of the repository. Those topics will be added to the list of `topics`. This is useful if `default.topics` are used and the list should be extended with more topics. + + Default is `[]`. + +- [**`vulnerability_alerts`**](#var-vulnerability_alerts): *(Optional `bool`)* + + Set to `false` to disable security alerts for vulnerable dependencies. + Enabling requires alerts to be enabled on the owner level. + +- [**`archive_on_destroy`**](#var-archive_on_destroy): *(Optional `bool`)* + + Set to `false` to not archive the repository instead of deleting on destroy. + + Default is `true`. + +### Extended Resource Configuration + +#### Repository Creation Configuration + +The following four arguments can only be set at repository creation and +changes will be ignored for repository updates and +will not show a diff in plan or apply phase. + +- [**`auto_init`**](#var-auto_init): *(Optional `bool`)* + + Set to `false` to not produce an initial commit in the repository. + + Default is `true`. + +- [**`gitignore_template`**](#var-gitignore_template): *(Optional `string`)* + + Use the name of the template without the extension. + + Default is `""`. + +- [**`license_template`**](#var-license_template): *(Optional `string`)* + + Use the name of the template without the extension. + + Default is `""`. + +- [**`template`**](#var-template): *(Optional `object(template)`)* + + Use a template repository to create this resource. + + Default is `{}`. + + The `template` object accepts the following attributes: + + - [**`owner`**](#attr-template-owner): *(**Required** `string`)* + + The GitHub organization or user the template repository is owned by. + + - [**`repository`**](#attr-template-repository): *(**Required** `string`)* + + The name of the template repository. + +#### Teams Configuration + +Your can use non-computed (known at `terraform plan`) team names or slugs (`*_teams` Attributes) +or computed (only known in `terraform apply` phase) team IDs (`*_team_ids` Attributes). +**When using non-computed names/slugs teams need to exist before running plan.** +This is due to some terraform limitation and we will update the module once terraform removed this limitation. + +- [**`pull_teams`**](#var-pull_teams): *(Optional `list(string)`)* + + Can also be `pull_team_ids`. A list of teams to grant pull (read-only) permission. + Recommended for non-code contributors who want to view or discuss your project. + + Default is `[]`. + +- [**`triage_teams`**](#var-triage_teams): *(Optional `list(string)`)* + + Can also be `triage_team_ids`. A list of teams to grant triage permission. + Recommended for contributors who need to proactively manage issues and pull requests + without write access. + + Default is `[]`. + +- [**`push_teams`**](#var-push_teams): *(Optional `list(string)`)* + + Can also be `push_team_ids`. A list of teams to grant push (read-write) permission. + Recommended for contributors who actively push to your project. + + Default is `[]`. + +- [**`maintain_teams`**](#var-maintain_teams): *(Optional `list(string)`)* + + Can also be `maintain_team_ids`. A list of teams to grant maintain permission. + Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. + + Default is `[]`. + +- [**`admin_teams`**](#var-admin_teams): *(Optional `list(string)`)* + + Can also be `admin_team_ids`. A list of teams to grant admin (full) permission. + Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. + + Default is `[]`. + +#### Collaborator Configuration + +- [**`pull_collaborators`**](#var-pull_collaborators): *(Optional `list(string)`)* + + A list of user names to add as collaborators granting them pull (read-only) permission. + Recommended for non-code contributors who want to view or discuss your project. + + Default is `[]`. + +- [**`triage_collaborators`**](#var-triage_collaborators): *(Optional `list(string)`)* + + A list of user names to add as collaborators granting them triage permission. + Recommended for contributors who need to proactively manage issues and pull requests without write access. + + Default is `[]`. + +- [**`push_collaborators`**](#var-push_collaborators): *(Optional `list(string)`)* + + A list of user names to add as collaborators granting them push (read-write) permission. + Recommended for contributors who actively push to your project. + + Default is `[]`. + +- [**`maintain_collaborators`**](#var-maintain_collaborators): *(Optional `list(string)`)* + + A list of user names to add as collaborators granting them maintain permission. + Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. + + Default is `[]`. + +- [**`admin_collaborators`**](#var-admin_collaborators): *(Optional `list(string)`)* + + A list of user names to add as collaborators granting them admin (full) permission. + Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. + + Default is `[]`. + +#### Branches Configuration + +- [**`branches`**](#var-branches): *(Optional `list(branch)`)* + + Create and manage branches within your repository. + Additional constraints can be applied to ensure your branch is created from another branch or commit. + + Default is `[]`. + + Each `branch` object in the list accepts the following attributes: + + - [**`name`**](#attr-branches-name): *(**Required** `string`)* + + The name of the branch to create. + + - [**`source_branch`**](#attr-branches-source_branch): *(Optional `string`)* + + The branch name to start from. Uses the configured default branch per default. + + - [**`source_sha`**](#attr-branches-source_sha): *(Optional `bool`)* + + The commit hash to start from. Defaults to the tip of `source_branch`. If provided, `source_branch` is ignored. + + Default is `true`. + +#### Deploy Keys Configuration + +- [**`deploy_keys`**](#var-deploy_keys): *(Optional `list(deploy_key)`)* + + Can also be type `list(string)`. Specifies deploy keys and access-level of deploy keys used in this repository. + Every `string` in the list will be converted internally into the `object` representation with the `key` argument being set to the `string`. `object` details are explained below. + + Default is `[]`. + + Each `deploy_key` object in the list accepts the following attributes: + + - [**`key`**](#attr-deploy_keys-key): *(**Required** `string`)* + + The SSH public key. + + - [**`title`**](#attr-deploy_keys-title): *(Optional `string`)* + + A Title for the key. + Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. + + - [**`read_only`**](#attr-deploy_keys-read_only): *(Optional `bool`)* + + Specifies the level of access for the key. + + Default is `true`. + + - [**`id`**](#attr-deploy_keys-id): *(Optional `string`)* + + Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. + The ID must be unique between `deploy_keys` and `deploy_keys_computed`. + + Default is `"md5(key)"`. + +- [**`deploy_keys_computed`**](#var-deploy_keys_computed): *(Optional `list(deploy_key)`)* + + Can also be type `string`. Same as `deploy_keys` argument with the following differences: + Use this argument if you depend on computed keys that terraform can not use in resource `for_each` execution. Downside of this is the recreation of deploy key resources whenever the order in the list changes. **Prefer `deploy_keys` whenever possible.** + This argument does **not** conflict with `deploy_keys` and should exclusively be used for computed resources. + + Default is `[]`. + + Each `deploy_key` object in the list accepts the following attributes: + + - [**`key`**](#attr-deploy_keys_computed-key): *(**Required** `string`)* + + The SSH public key. + + - [**`title`**](#attr-deploy_keys_computed-title): *(Optional `string`)* + + A Title for the key. + Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. + + - [**`read_only`**](#attr-deploy_keys_computed-read_only): *(Optional `bool`)* + + Specifies the level of access for the key. + + Default is `true`. + + - [**`id`**](#attr-deploy_keys_computed-id): *(Optional `string`)* + + Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. + The ID must be unique between `deploy_keys` and `deploy_keys_computed`. + + Default is `"md5(key)"`. + +#### Branch Protections v3 Configuration + +- [**`branch_protections_v3`**](#var-branch_protections_v3): *(Optional `list(branch_protection_v3)`)* + + 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. + + Default is `[]`. + + Each `branch_protection_v3` object in the list accepts the following attributes: + + - [**`branch`**](#attr-branch_protections_v3-branch): *(**Required** `string`)* + + The Git branch to protect. + + - [**`enforce_admins`**](#attr-branch_protections_v3-enforce_admins): *(Optional `bool`)* + + Setting this to true enforces status checks for repository administrators. + + Default is `false`. + + - [**`require_conversation_resolution`**](#attr-branch_protections_v3-require_conversation_resolution): *(Optional `bool`)* + + Setting this to true requires all conversations to be resolved. + + Default is `false`. + + - [**`require_signed_commits`**](#attr-branch_protections_v3-require_signed_commits): *(Optional `bool`)* + + Setting this to true requires all commits to be signed with GPG. + + Default is `false`. + + - [**`required_status_checks`**](#attr-branch_protections_v3-required_status_checks): *(Optional `object(required_status_checks)`)* + + Enforce restrictions for required status checks. + See Required Status Checks below for details. + + Default is `{}`. + + The `required_status_checks` object accepts the following attributes: + + - [**`strict`**](#attr-branch_protections_v3-required_status_checks-strict): *(Optional `bool`)* + + Require branches to be up to date before merging. + + Default is `false`. + + - [**`contexts`**](#attr-branch_protections_v3-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 `[]`. + + - [**`required_pull_request_reviews`**](#attr-branch_protections_v3-required_pull_request_reviews): *(Optional `object(required_pull_request_reviews)`)* + + Enforce restrictions for pull request reviews. + + Default is `{}`. + + The `required_pull_request_reviews` object accepts the following attributes: + + - [**`dismiss_stale_reviews`**](#attr-branch_protections_v3-required_pull_request_reviews-dismiss_stale_reviews): *(Optional `bool`)* + + Dismiss approved reviews automatically when a new commit is pushed. + + Default is `true`. + + - [**`dismissal_users`**](#attr-branch_protections_v3-required_pull_request_reviews-dismissal_users): *(Optional `list(string)`)* + + The list of user logins with dismissal access + + Default is `[]`. + + - [**`dismissal_teams`**](#attr-branch_protections_v3-required_pull_request_reviews-dismissal_teams): *(Optional `list(string)`)* + + The list of team slugs with dismissal access. + Always use slug of the team, not its name. + Each team already has to have access to the repository. + + Default is `[]`. + + - [**`require_code_owner_reviews`**](#attr-branch_protections_v3-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`. + + - [**`restrictions`**](#attr-branch_protections_v3-restrictions): *(Optional `object(restrictions)`)* + + Enforce restrictions for the users and teams that may push to the branch - only available for organization-owned repositories. See Restrictions below for details. + + Default is `{}`. + + The `restrictions` object accepts the following attributes: + + - [**`users`**](#attr-branch_protections_v3-restrictions-users): *(Optional `list(string)`)* + + The list of user logins with push access. + + Default is `[]`. + + - [**`teams`**](#attr-branch_protections_v3-restrictions-teams): *(Optional `list(string)`)* + + The list of team slugs with push access. + Always use slug of the team, not its name. + Each team already has to have access to the repository. + + Default is `[]`. + + - [**`apps`**](#attr-branch_protections_v3-restrictions-apps): *(Optional `list(string)`)* + + The list of app slugs with push access. + + Default is `[]`. + +#### Branch Protections v4 Configuration + +- [**`branch_protections_v4`**](#var-branch_protections_v4): *(Optional `list(branch_protection_v4)`)* + + This resource allows you to configure v4 branch protection for repositories in your organization. + + Each element in the list 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:_** May conflict with v3 branch protections if used for the same branch. + + Default is `[]`. + + Each `branch_protection_v4` object in the list accepts the following attributes: + + - [**`pattern`**](#attr-branch_protections_v4-pattern): *(**Required** `string`)* + + Identifies the protection rule pattern. + + - [**`_key`**](#attr-branch_protections_v4-_key): *(Optional `string`)* + + An alternative key to use in `for_each` resource creation. + Defaults to the value of `var.pattern`. + + - [**`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`)* + + Keeping this as `true` enforces status checks for repository administrators. + + Default is `true`. + + - [**`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. + + 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`. + + - [**`restrict_dismissals`**](#attr-branch_protections_v4-required_pull_request_reviews-restrict_dismissals): *(Optional `bool`)* + + Restrict pull request review dismissals. + + - [**`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 `true`. + + - [**`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. + + 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)`)* + + This resource allows you to create and manage issue labels within your GitHub organization. + Issue labels are keyed off of their "name", so pre-existing issue labels result in a 422 HTTP error if they exist outside of Terraform. + Normally this would not be an issue, except new repositories are created with a "default" set of labels, and those labels easily conflict with custom ones. + This resource will first check if the label exists, and then issue an update, otherwise it will create. + + Default is `[]`. + + Each `issue_label` object in the list accepts the following attributes: + + - [**`name`**](#attr-issue_labels-name): *(**Required** `string`)* + + The name of the label. + + - [**`color`**](#attr-issue_labels-color): *(**Required** `string`)* + + A 6 character hex code, without the leading `#`, identifying the color of the label. + + - [**`description`**](#attr-issue_labels-description): *(Optional `string`)* + + A short description of the label. + + Default is `""`. + + - [**`id`**](#attr-issue_labels-id): *(Optional `string`)* + + Specifies an ID which is used to prevent resource recreation when the order in the list of issue labels changes. + + Default is `"name"`. + +- [**`issue_labels_merge_with_github_labels`**](#var-issue_labels_merge_with_github_labels): *(Optional `bool`)* + + Specify if github default labels will be handled by terraform. This should be decided on upon creation of the repository. If you later decide to disable this feature, github default labels will be destroyed if not replaced by labels set in `issue_labels` argument. + +- [**`issue_labels_create`**](#var-issue_labels_create): *(Optional `bool`)* + + Specify whether you want to force or suppress the creation of issues labels. + Default is `true` if `has_issues` is `true` or `issue_labels` is non-empty. + +#### Projects Configuration + +- [**`projects`**](#var-projects): *(Optional `list(project)`)* + + This resource allows you to create and manage projects for GitHub repository. + + Default is `[]`. + + Each `project` object in the list accepts the following attributes: + + - [**`name`**](#attr-projects-name): *(**Required** `string`)* + + The name of the project. + + - [**`body`**](#attr-projects-body): *(Optional `string`)* + + The body of the project. + + Default is `""`. + + - [**`id`**](#attr-projects-id): *(Optional `string`)* + + Specifies an ID which is used to prevent resource recreation when the order in the list of projects changes. + + Default is `"name"`. + +#### Webhooks Configuration + +- [**`webhooks`**](#var-webhooks): *(Optional `list(webhook)`)* + + This resource allows you to create and manage webhooks for repositories in your organization. + When applied, a webhook will be created which specifies a URL to receive events and which events to receieve. Additional constraints, such as SSL verification, pre-shared secret and content type can also be configured + + Default is `[]`. + + Each `webhook` object in the list accepts the following attributes: + + - [**`events`**](#attr-webhooks-events): *(**Required** `list(string)`)* + + A list of events which should trigger the webhook. [See a list of available events.](https://developer.github.com/v3/activity/events/types/) + + - [**`url`**](#attr-webhooks-url): *(**Required** `string`)* + + The URL to which the payloads will be delivered. + + - [**`active`**](#attr-webhooks-active): *(Optional `bool`)* + + Indicate if the webhook should receive events. Defaults to `true`. + + - [**`content_type`**](#attr-webhooks-content_type): *(Optional `string`)* + + The media type used to serialize the payloads. Supported values include `json` and `form`. + + Default is `"form"`. + + - [**`secret`**](#attr-webhooks-secret): *(Optional `string`)* + + If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value in the [X-Hub-Signature](https://developer.github.com/webhooks/#delivery-headers) header. + + - [**`insecure_ssl`**](#attr-webhooks-insecure_ssl): *(Optional `bool`)* + + Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. **We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.** + +#### Secrets Configuration + +- [**`plaintext_secrets`**](#var-plaintext_secrets): *(Optional `map(string)`)* + + This map allows you to create and manage secrets for repositories in your organization. + + Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding secret in plain text: + + When applied, a secret with the given key and value will be created in the repositories. + + The value of the secrets must be given in plain text, GitHub provider is in charge of encrypting it. + + **Attention:** You should treat state as sensitive always. It is also advised that you do not store plaintext values in your code but rather populate the encrypted_value using fields from a resource, data source or variable as, while encrypted in state, these will be easily accessible in your code. See below for an example of this abstraction. + + Default is `{}`. + + Example: + + ```hcl + plaintext_secrets = { + SECRET_NAME_1 = "plaintext_secret_value_1" + SECRET_NAME_2 = "plaintext_secret_value_2" + } + ``` + +- [**`encrypted_secrets`**](#var-encrypted_secrets): *(Optional `map(string)`)* + + This map allows you to create and manage encrypted secrets for repositories in your organization. + + Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding encrypted value of the secret using the Github public key in Base64 format.b + + When applied, a secret with the given key and value will be created in the repositories. + + Default is `{}`. + + Example: + + ```hcl + encrypted_secrets = { + SECRET_NAME_1 = "c2VjcmV0X3ZhbHVlXzE=" + SECRET_NAME_2 = "c2VjcmV0X3ZhbHVlXzI=" + } + ``` + +- [**`required_approving_review_count`**](#var-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 1-6. + This requirement matches Github's API, see the upstream documentation for more information. + Default is no approving reviews are required. + +#### Autolink References Configuration + +- [**`autolink_references`**](#var-autolink_references): *(Optional `list(autolink_reference)`)* + + This resource allows you to create and manage autolink references for GitHub repository. + + Default is `[]`. + + Each `autolink_reference` object in the list accepts the following attributes: + + - [**`key_prefix`**](#attr-autolink_references-key_prefix): *(**Required** `string`)* + + This prefix appended by a number will generate a link any time it is found in an issue, pull request, or commit. + + - [**`target_url_template`**](#attr-autolink_references-target_url_template): *(**Required** `string`)* + + The template of the target URL used for the links; must be a valid URL and contain `` for the reference number. + +#### App Installations + +- [**`app_installations`**](#var-app_installations): *(Optional `set(string)`)* + + A set of GitHub App IDs to be installed in this repository. + + Default is `{}`. + + Example: + + ```hcl + app_installations = ["05405144", "12556423"] + ``` + +### Module Configuration + +- [**`module_depends_on`**](#var-module_depends_on): *(Optional `list(dependency)`)* + + Due to the fact, that terraform does not offer `depends_on` on modules as of today (v0.12.24) + we might hit race conditions when dealing with team names instead of ids. + So when using the feature of [adding teams by slug/name](#teams-configuration) to the repository when creating it, + make sure to add all teams to this list as indirect dependencies. + + Default is `[]`. + +## Module Outputs + +The following attributes are exported by the module: + +- [**`repository`**](#output-repository): *(`object(repository)`)* + + All repository attributes as returned by the [`github_repository`] + resource containing all arguments as specified above and the other + attributes as specified below. + +- [**`branches`**](#output-branches): *(`object(branches)`)* + + All repository attributes as returned by the [`github_branch`] + resource containing all arguments as specified above and the other + attributes as specified below. + +- [**`full_name`**](#output-full_name): *(`string`)* + + A string of the form "orgname/reponame". + +- [**`html_url`**](#output-html_url): *(`string`)* + + URL to the repository on the web. + +- [**`ssh_clone_url`**](#output-ssh_clone_url): *(`string`)* + + URL that can be provided to git clone to clone the repository via SSH. + +- [**`http_clone_url`**](#output-http_clone_url): *(`string`)* + + URL that can be provided to git clone to clone the repository via HTTPS. + +- [**`git_clone_url`**](#output-git_clone_url): *(`string`)* + + URL that can be provided to git clone to clone the repository + anonymously via the git protocol. + +- [**`collaborators`**](#output-collaborators): *(`object(collaborators)`)* + + A map of Collaborator objects keyed by the `name` of the collaborator as + returned by the [`github_repository_collaborator`] resource. + +- [**`deploy_keys`**](#output-deploy_keys): *(`object(deploy_keys)`)* + + A merged map of deploy key objects for the keys originally passed via + `deploy_keys` and `deploy_keys_computed` as returned by the + [`github_repository_deploy_key`] resource keyed by the input `id` of the + key. + +- [**`projects`**](#output-projects): *(`object(project)`)* + + A map of Project objects keyed by the `id` of the project as returned by + the [`github_repository_project`] resource + +- [**`issue_labels`**](#output-issue_labels): *(`object(issue_label)`)* + + A map of issue labels keyed by label input id or name. + +- [**`webhooks`**](#output-webhooks): *(`object(webhook)`)* + + All attributes and arguments as returned by the + `github_repository_webhook` resource. + +- [**`secrets`**](#output-secrets): *(`object(secret)`)* + + List of secrets available. + +- [**`app_installations`**](#output-app_installations): *(`set(number)`)* + + A map of deploy app installations keyed by installation id. + +## External Documentation + +### Terraform Github Provider Documentation + +- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository +- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/branch +- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_collaborator +- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_deploy_key +- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_project +- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_autolink_reference + +## Module Versioning + +This Module follows the principles of [Semantic Versioning (SemVer)]. + +Given a version number `MAJOR.MINOR.PATCH`, we increment the: + +1. `MAJOR` version when we make incompatible changes, +2. `MINOR` version when we add functionality in a backwards compatible manner, and +3. `PATCH` version when we make backwards compatible bug fixes. + +### Backwards compatibility in `0.0.z` and `0.y.z` version + +- Backwards compatibility in versions `0.0.z` is **not guaranteed** when `z` is increased. (Initial development) +- Backwards compatibility in versions `0.y.z` is **not guaranteed** when `y` is increased. (Pre-release) + +## About Mineiros + +[Mineiros][homepage] is a remote-first company headquartered in Berlin, Germany +that solves development, automation and security challenges in cloud infrastructure. + +Our vision is to massively reduce time and overhead for teams to manage and +deploy production-grade and secure cloud infrastructure. + +We offer commercial support for all of our modules and encourage you to reach out +if you have any questions or need help. Feel free to email us at [hello@mineiros.io] or join our +[Community Slack channel][slack]. + +## Reporting Issues + +We use GitHub [Issues] to track community reported issues and missing features. + +## Contributing + +Contributions are always encouraged and welcome! For the process of accepting changes, we use +[Pull Requests]. If you'd like more information, please see our [Contribution Guidelines]. + +## Makefile Targets + +This repository comes with a handy [Makefile]. +Run `make help` to see details on each available target. + +## License + +[![license][badge-license]][apache20] + +This module is licensed under the Apache License Version 2.0, January 2004. +Please see [LICENSE] for full details. + +Copyright © 2020-2022 [Mineiros GmbH][homepage] + + + + +[github]: https://github.com/ +[`github_repository`]: https://www.terraform.io/docs/providers/github/r/repository.html#attributes-reference +[`github_repository_collaborator`]: https://www.terraform.io/docs/providers/github/r/repository_collaborator.html#attribute-reference +[`github_repository_deploy_key`]: https://www.terraform.io/docs/providers/github/r/repository_deploy_key.html#attributes-reference +[`github_repository_project`]: https://www.terraform.io/docs/providers/github/r/repository_project.html#attributes-reference +[`github_repository_autolink_reference`]: https://www.terraform.io/docs/providers/github/r/repository_autolink_reference.html#attributes-reference +[homepage]: https://mineiros.io/?ref=terraform-github-repository +[github-as-code]: https://mineiros.io/github-as-code?ref=terraform-github-repository +[hello@mineiros.io]: mailto:hello@mineiros.io +[badge-build]: https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg +[badge-semver]: https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver +[badge-license]: https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg +[badge-terraform]: https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform +[badge-slack]: https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack +[badge-tf-gh]: https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform +[releases-github-provider]: https://github.com/terraform-providers/terraform-provider-github/releases +[build-status]: https://github.com/mineiros-io/terraform-github-repository/actions +[releases-github]: https://github.com/mineiros-io/terraform-github-repository/releases +[releases-terraform]: https://github.com/hashicorp/terraform/releases +[apache20]: https://opensource.org/licenses/Apache-2.0 +[slack]: https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg +[terraform]: https://www.terraform.io +[aws]: https://aws.amazon.com/ +[semantic versioning (semver)]: https://semver.org/ +[variables.tf]: https://github.com/mineiros-io/terraform-github-repository/blob/main/variables.tf +[examples/]: https://github.com/mineiros-io/terraform-github-repository/blob/main/examples +[issues]: https://github.com/mineiros-io/terraform-github-repository/issues +[license]: https://github.com/mineiros-io/terraform-github-repository/blob/main/LICENSE +[makefile]: https://github.com/mineiros-io/terraform-github-repository/blob/main/Makefile +[pull requests]: https://github.com/mineiros-io/terraform-github-repository/pulls +[contribution guidelines]: https://github.com/mineiros-io/terraform-github-repository/blob/main/CONTRIBUTING.md diff --git a/README.tfdoc.hcl b/README.tfdoc.hcl index 1f75765..3b9c069 100644 --- a/README.tfdoc.hcl +++ b/README.tfdoc.hcl @@ -1,1544 +1,1544 @@ -header { - image = "https://raw.githubusercontent.com/mineiros-io/brand/3bffd30e8bdbbde32c143e2650b2faa55f1df3ea/mineiros-primary-logo.svg" - url = "https://mineiros.io/?ref=terraform-github-repository" - - badge "build" { - image = "https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg" - url = "https://github.com/mineiros-io/terraform-github-repository/actions" - text = "Build Status" - } - - badge "semver)" { - image = "https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver" - url = "https://github.com/mineiros-io/terraform-github-repository/releases" - text = "GitHub tag (latest SemVer)" - } - - badge "terraform" { - image = "https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform" - url = "https://github.com/hashicorp/terraform/releases" - text = "Terraform Version" - } - - badge "tf-gh" { - image = "https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform" - url = "https://github.com/terraform-providers/terraform-provider-github/releases" - text = "Github Provider Version" - } - - badge "slack" { - image = "https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack" - url = "https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg" - text = "Join Slack" - } -} - -section { - title = "terraform-github-repository" - toc = true - content = <<-END - A [Terraform] module for creating a public or private repository on [Github]. - - **_This module supports Terraform v1.x and is compatible with the Official Terraform GitHub Provider v4.20 and above from `integrations/github`._** - - **Attention: This module is incompatible with the Hashicorp GitHub Provider! The latest version of this module supporting `hashicorp/github` provider is `~> 0.10.0`** - - ** Note: Versions 5.3.0, 5.4.0, and 5.5.0 of the Terraform Github Provider have broken branch protections support and should not be used.** - END - - section { - title = "GitHub as Code" - content = <<-END - [GitHub as Code][github-as-code] is a commercial solution built on top of - our open-source Terraform modules for GitHub. It helps our customers to - manage their GitHub organization more efficiently by enabling anyone in - their organization to **self-service** manage **on- and offboarding of users**, - **repositories**, and settings such as **branch protections**, **secrets**, and more - through code. GitHub as Code comes with **pre-configured GitHub Actions - pipelines** for **change pre-view in Pull Requests**, **fully automated - rollouts** and **rollbacks**. It's a comprehensive, ready-to-use blueprint - maintained by our team of platform engineering experts and saves - companies such as yours tons of time by building on top of a pre-configured - solution instead of building and maintaining it yourself. - - For details please see [https://mineiros.io/github-as-code][github-as-code]. - END - } - - section { - title = "Module Features" - content = <<-END - In contrast to the plain `github_repository` resource this module enables various other - features like Branch Protection or Collaborator Management. - - - **Default Security Settings**: - This module creates a `private` repository by default, - Deploy keys are `read-only` by default - - - **Standard Repository Features**: - Setting basic Metadata, - Merge Strategy, - Auto Init, - License Template, - Gitignore Template, - Template Repository - - - **Extended Repository Features**: - Branches, - Branch Protection, - Issue Labels, - Handle Github Default Issue Labels, - Collaborators, - Teams, - Deploy Keys, - Projects, - Repository Webhooks - - - _Features not yet implemented_: - Project Columns support, - Actions, - Repository File - END - } - - section { - title = "Getting Started" - content = <<-END - Most basic usage creating a new private github repository. - - ```hcl - module "repository" { - source = "mineiros-io/repository/github" - version = "~> 0.18.0" - - name = "terraform-github-repository" - license_template = "apache-2.0" - gitignore_template = "Terraform" - } - ``` - END - } - - section { - title = "Module Argument Reference" - content = <<-END - See [variables.tf] and [examples/] for details and use-cases. - END - - section { - title = "Main Resource Configuration" - - variable "name" { - required = true - type = string - description = <<-END - The name of the repository. - END - } - - variable "defaults" { - type = object(defaults) - default = {} - description = <<-END - DEPRECATED: - This variable will be removed in future releases. - It was needed in times when Terraform Module for each was not available to provide default values for multiple repositories. - Please convert your code accordingly to stay compatible with future releases. - END - } - - variable "pages" { - type = object(pages) - default = {} - description = <<-END - A object of settings to configure GitHub Pages in this repository. - See below for a list of supported arguments. - END - - attribute "branch" { - required = true - type = string - description = <<-END - The repository branch used to publish the site's source files. - END - } - - attribute "path" { - type = string - description = <<-END - The repository directory from which the site publishes. - END - } - - attribute "cname" { - type = string - description = <<-END - The custom domain for the repository. This can only be set after the - repository has been created. - END - } - } - - variable "allow_merge_commit" { - type = bool - default = true - description = <<-END - Set to `false` to disable merge commits on the repository. - If you set this to `false` you have to enable either `allow_squash_merge` - or `allow_rebase_merge`. - END - } - - variable "allow_squash_merge" { - type = bool - default = false - description = <<-END - Set to `true` to enable squash merges on the repository. - END - } - - variable "allow_rebase_merge" { - type = bool - default = false - description = <<-END - Set to `true` to enable rebase merges on the repository. - END - } - - variable "allow_auto_merge" { - type = bool - default = false - description = <<-END - Set to `true` to allow [auto-merging](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request) - pull requests on the repository. If you enable auto-merge for a pull - request, the pull request will merge automatically when all required - reviews are met and status checks have passed. - END - } - - variable "description" { - type = string - default = "" - description = <<-END - A description of the repository. - END - } - - variable "delete_branch_on_merge" { - type = bool - default = true - description = <<-END - Set to `false` to disable the automatic deletion of head branches after pull requests are merged. - END - } - - variable "homepage_url" { - type = string - default = "" - description = <<-END - URL of a page describing the project. - END - } - - variable "private" { - type = bool - description = <<-END - **_DEPRECATED_**: Please use `visibility` instead and update your code. parameter will be removed in a future version - END - } - - variable "visibility" { - type = string - default = "private" - description = <<-END - Can be `public` or `private`. - If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, `visibility` can also be `internal`. - The `visibility` parameter overrides the deprecated `private` parameter. - END - } - - variable "has_issues" { - type = bool - default = false - description = <<-END - Set to true to enable the GitHub Issues features on the repository. - END - } - - variable "has_projects" { - type = bool - default = false - description = <<-END - Set to true to enable the GitHub Projects features on the repository. - END - } - - variable "has_wiki" { - type = bool - default = false - description = <<-END - Set to true to enable the GitHub Wiki features on the repository. - END - } - - variable "has_downloads" { - type = bool - default = false - description = <<-END - Set to `true` to enable the (deprecated) downloads features on the repository. - END - } - - variable "is_template" { - type = bool - default = false - description = <<-END - Set to `true` to tell GitHub that this is a template repository. - END - } - - variable "default_branch" { - type = string - default = "" - description = <<-END - The name of the default branch of the repository. - NOTE: The configured default branch must exist in the repository. - If the branch doesn't exist yet, or if you are creating a new - repository, please add the desired default branch to the `branches` - variable, which will cause Terraform to create it for you. - END - } - - variable "archived" { - type = bool - default = false - description = <<-END - Specifies if the repository should be archived. - NOTE: Currently, the API does not support unarchiving. - END - } - - variable "topics" { - type = list(string) - default = [] - description = <<-END - The list of topics of the repository. - END - } - - variable "extra_topics" { - type = list(string) - default = [] - description = <<-END - A list of additional topics of the repository. Those topics will be added to the list of `topics`. This is useful if `default.topics` are used and the list should be extended with more topics. - END - } - - variable "vulnerability_alerts" { - type = bool - description = <<-END - Set to `false` to disable security alerts for vulnerable dependencies. - Enabling requires alerts to be enabled on the owner level. - END - } - - variable "archive_on_destroy" { - type = bool - default = true - description = <<-END - Set to `false` to not archive the repository instead of deleting on destroy. - END - } - } - - section { - title = "Extended Resource Configuration" - - section { - title = "Repository Creation Configuration" - content = <<-END - The following four arguments can only be set at repository creation and - changes will be ignored for repository updates and - will not show a diff in plan or apply phase. - END - - variable "auto_init" { - type = bool - default = true - description = <<-END - Set to `false` to not produce an initial commit in the repository. - END - } - - variable "gitignore_template" { - type = string - default = "" - description = <<-END - Use the name of the template without the extension. - END - } - - variable "license_template" { - type = string - default = "" - description = <<-END - Use the name of the template without the extension. - END - } - - variable "template" { - type = object(template) - default = {} - description = <<-END - Use a template repository to create this resource. - END - - attribute "owner" { - required = true - type = string - description = <<-END - The GitHub organization or user the template repository is owned by. - END - } - - attribute "repository" { - required = true - type = string - description = <<-END - The name of the template repository. - END - } - } - } - - section { - title = "Teams Configuration" - content = <<-END - Your can use non-computed (known at `terraform plan`) team names or slugs (`*_teams` Attributes) - or computed (only known in `terraform apply` phase) team IDs (`*_team_ids` Attributes). - **When using non-computed names/slugs teams need to exist before running plan.** - This is due to some terraform limitation and we will update the module once terraform removed this limitation. - END - - variable "pull_teams" { - type = list(string) - default = [] - description = <<-END - Can also be `pull_team_ids`. A list of teams to grant pull (read-only) permission. - Recommended for non-code contributors who want to view or discuss your project. - END - } - - variable "triage_teams" { - type = list(string) - default = [] - description = <<-END - Can also be `triage_team_ids`. A list of teams to grant triage permission. - Recommended for contributors who need to proactively manage issues and pull requests - without write access. - END - } - - variable "push_teams" { - type = list(string) - default = [] - description = <<-END - Can also be `push_team_ids`. A list of teams to grant push (read-write) permission. - Recommended for contributors who actively push to your project. - END - } - - variable "maintain_teams" { - type = list(string) - default = [] - description = <<-END - Can also be `maintain_team_ids`. A list of teams to grant maintain permission. - Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. - END - } - - variable "admin_teams" { - type = list(string) - default = [] - description = <<-END - Can also be `admin_team_ids`. A list of teams to grant admin (full) permission. - Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. - END - } - } - - section { - title = "Collaborator Configuration" - - variable "pull_collaborators" { - type = list(string) - default = [] - description = <<-END - A list of user names to add as collaborators granting them pull (read-only) permission. - Recommended for non-code contributors who want to view or discuss your project. - END - } - - variable "triage_collaborators" { - type = list(string) - default = [] - description = <<-END - A list of user names to add as collaborators granting them triage permission. - Recommended for contributors who need to proactively manage issues and pull requests without write access. - END - } - - variable "push_collaborators" { - type = list(string) - default = [] - description = <<-END - A list of user names to add as collaborators granting them push (read-write) permission. - Recommended for contributors who actively push to your project. - END - } - - variable "maintain_collaborators" { - type = list(string) - default = [] - description = <<-END - A list of user names to add as collaborators granting them maintain permission. - Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. - END - } - - variable "admin_collaborators" { - type = list(string) - default = [] - description = <<-END - A list of user names to add as collaborators granting them admin (full) permission. - Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. - END - } - } - - section { - title = "Branches Configuration" - - variable "branches" { - type = list(branch) - default = [] - description = <<-END - Create and manage branches within your repository. - Additional constraints can be applied to ensure your branch is created from another branch or commit. - END - - attribute "name" { - required = true - type = string - description = <<-END - The name of the branch to create. - END - } - - attribute "source_branch" { - type = string - description = <<-END - The branch name to start from. Uses the configured default branch per default. - END - } - - attribute "source_sha" { - type = bool - default = true - description = <<-END - The commit hash to start from. Defaults to the tip of `source_branch`. If provided, `source_branch` is ignored. - END - } - } - } - - section { - title = "Deploy Keys Configuration" - - variable "deploy_keys" { - type = list(deploy_key) - default = [] - description = <<-END - Can also be type `list(string)`. Specifies deploy keys and access-level of deploy keys used in this repository. - Every `string` in the list will be converted internally into the `object` representation with the `key` argument being set to the `string`. `object` details are explained below. - END - - attribute "key" { - required = true - type = string - description = <<-END - The SSH public key. - END - } - - attribute "title" { - type = string - description = <<-END - A Title for the key. - Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. - END - } - - attribute "read_only" { - type = bool - default = true - description = <<-END - Specifies the level of access for the key. - END - } - - attribute "id" { - type = string - default = "md5(key)" - description = <<-END - Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. - The ID must be unique between `deploy_keys` and `deploy_keys_computed`. - END - } - } - - variable "deploy_keys_computed" { - type = list(deploy_key) - default = [] - description = <<-END - Can also be type `string`. Same as `deploy_keys` argument with the following differences: - Use this argument if you depend on computed keys that terraform can not use in resource `for_each` execution. Downside of this is the recreation of deploy key resources whenever the order in the list changes. **Prefer `deploy_keys` whenever possible.** - This argument does **not** conflict with `deploy_keys` and should exclusively be used for computed resources. - END - - attribute "key" { - required = true - type = string - description = <<-END - The SSH public key. - END - } - - attribute "title" { - type = string - description = <<-END - A Title for the key. - Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. - END - } - - attribute "read_only" { - type = bool - default = true - description = <<-END - Specifies the level of access for the key. - END - } - - attribute "id" { - type = string - default = "md5(key)" - description = <<-END - Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. - The ID must be unique between `deploy_keys` and `deploy_keys_computed`. - END - } - } - } - - section { - title = "Branch Protections v3 Configuration" - - variable "branch_protections_v3" { - type = list(branch_protection_v3) - default = [] - description = <<-END - 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 - - attribute "branch" { - required = true - type = string - description = <<-END - The Git branch to protect. - END - } - - attribute "enforce_admins" { - type = bool - default = false - description = <<-END - Setting this to true enforces status checks for repository administrators. - END - } - - attribute "require_conversation_resolution" { - type = bool - default = false - description = <<-END - Setting this to true requires all conversations to be resolved. - 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_status_checks" { - type = object(required_status_checks) - default = {} - 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 - } - } - - attribute "required_pull_request_reviews" { - type = object(required_pull_request_reviews) - default = {} - 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_users" { - type = list(string) - default = [] - description = <<-END - The list of user logins with dismissal access - END - } - - attribute "dismissal_teams" { - type = list(string) - default = [] - description = <<-END - The list of team slugs with dismissal access. - Always use slug of the team, not its name. - Each team already has to have access to the repository. - 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 "restrictions" { - type = object(restrictions) - default = {} - description = <<-END - Enforce restrictions for the users and teams that may push to the branch - only available for organization-owned repositories. See Restrictions below for details. - END - - attribute "users" { - type = list(string) - default = [] - description = <<-END - The list of user logins with push access. - END - } - - attribute "teams" { - type = list(string) - default = [] - description = <<-END - The list of team slugs with push access. - Always use slug of the team, not its name. - Each team already has to have access to the repository. - END - } - - attribute "apps" { - type = list(string) - default = [] - description = <<-END - The list of app slugs with push access. - END - } - } - } - } - - section { - title = "Branch Protections v4 Configuration" - - variable "branch_protections_v4" { - type = list(branch_protection_v4) - default = [] - description = <<-END - This resource allows you to configure v4 branch protection for repositories in your organization. - - Each element in the list 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:_** May conflict with v3 branch protections if used for the same branch. - END - - attribute "pattern" { - type = string - required = true - description = <<-END - Identifies the protection rule pattern. - END - } - - attribute "_key" { - type = string - description = <<-END - An alternative key to use in `for_each` resource creation. - Defaults to the value of `var.pattern`. - 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 = true - description = <<-END - Keeping this as `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) - 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 "restrict_dismissals" { - type = bool - description = <<-END - Restrict pull request review dismissals. - 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 = true - 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) - 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" - - variable "issue_labels" { - type = list(issue_label) - default = [] - description = <<-END - This resource allows you to create and manage issue labels within your GitHub organization. - Issue labels are keyed off of their "name", so pre-existing issue labels result in a 422 HTTP error if they exist outside of Terraform. - Normally this would not be an issue, except new repositories are created with a "default" set of labels, and those labels easily conflict with custom ones. - This resource will first check if the label exists, and then issue an update, otherwise it will create. - END - - attribute "name" { - required = true - type = string - description = <<-END - The name of the label. - END - } - - attribute "color" { - required = true - type = string - description = <<-END - A 6 character hex code, without the leading `#`, identifying the color of the label. - END - } - - attribute "description" { - type = string - default = "" - description = <<-END - A short description of the label. - END - } - - attribute "id" { - type = string - default = "name" - description = <<-END - Specifies an ID which is used to prevent resource recreation when the order in the list of issue labels changes. - END - } - } - - variable "issue_labels_merge_with_github_labels" { - type = bool - description = <<-END - Specify if github default labels will be handled by terraform. This should be decided on upon creation of the repository. If you later decide to disable this feature, github default labels will be destroyed if not replaced by labels set in `issue_labels` argument. - END - } - - variable "issue_labels_create" { - type = bool - description = <<-END - Specify whether you want to force or suppress the creation of issues labels. - Default is `true` if `has_issues` is `true` or `issue_labels` is non-empty. - END - } - } - - section { - title = "Projects Configuration" - - variable "projects" { - type = list(project) - default = [] - description = <<-END - This resource allows you to create and manage projects for GitHub repository. - END - - attribute "name" { - required = true - type = string - description = <<-END - The name of the project. - END - } - - attribute "body" { - type = string - default = "" - description = <<-END - The body of the project. - END - } - - attribute "id" { - type = string - default = "name" - description = <<-END - Specifies an ID which is used to prevent resource recreation when the order in the list of projects changes. - END - } - } - } - - section { - title = "Webhooks Configuration" - - variable "webhooks" { - type = list(webhook) - default = [] - description = <<-END - This resource allows you to create and manage webhooks for repositories in your organization. - When applied, a webhook will be created which specifies a URL to receive events and which events to receieve. Additional constraints, such as SSL verification, pre-shared secret and content type can also be configured - END - - attribute "events" { - required = true - type = list(string) - description = <<-END - A list of events which should trigger the webhook. [See a list of available events.](https://developer.github.com/v3/activity/events/types/) - END - } - - attribute "url" { - required = true - type = string - description = <<-END - The URL to which the payloads will be delivered. - END - } - - attribute "active" { - type = bool - description = <<-END - Indicate if the webhook should receive events. Defaults to `true`. - END - } - - attribute "content_type" { - type = string - default = "form" - description = <<-END - The media type used to serialize the payloads. Supported values include `json` and `form`. - END - } - - attribute "secret" { - type = string - description = <<-END - If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value in the [X-Hub-Signature](https://developer.github.com/webhooks/#delivery-headers) header. - END - } - - attribute "insecure_ssl" { - type = bool - description = <<-END - Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. **We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.** - END - } - } - } - - section { - title = "Secrets Configuration" - - variable "plaintext_secrets" { - type = map(string) - default = {} - description = <<-END - This map allows you to create and manage secrets for repositories in your organization. - - Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding secret in plain text: - - When applied, a secret with the given key and value will be created in the repositories. - - The value of the secrets must be given in plain text, GitHub provider is in charge of encrypting it. - - **Attention:** You should treat state as sensitive always. It is also advised that you do not store plaintext values in your code but rather populate the encrypted_value using fields from a resource, data source or variable as, while encrypted in state, these will be easily accessible in your code. See below for an example of this abstraction. - END - - readme_example = <<-END - plaintext_secrets = { - SECRET_NAME_1 = "plaintext_secret_value_1" - SECRET_NAME_2 = "plaintext_secret_value_2" - } - END - } - - variable "encrypted_secrets" { - type = map(string) - default = {} - description = <<-END - This map allows you to create and manage encrypted secrets for repositories in your organization. - - Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding encrypted value of the secret using the Github public key in Base64 format.b - - When applied, a secret with the given key and value will be created in the repositories. - END - - readme_example = <<-END - encrypted_secrets = { - SECRET_NAME_1 = "c2VjcmV0X3ZhbHVlXzE=" - SECRET_NAME_2 = "c2VjcmV0X3ZhbHVlXzI=" - } - END - } - - variable "required_approving_review_count" { - type = number - description = <<-END - Require x number of approvals to satisfy branch protection requirements. - If this is specified it must be a number between 1-6. - This requirement matches Github's API, see the upstream documentation for more information. - Default is no approving reviews are required. - END - } - } - - section { - title = "Autolink References Configuration" - - variable "autolink_references" { - type = list(autolink_reference) - default = [] - description = <<-END - This resource allows you to create and manage autolink references for GitHub repository. - END - - attribute "key_prefix" { - required = true - type = string - description = <<-END - This prefix appended by a number will generate a link any time it is found in an issue, pull request, or commit. - END - } - - attribute "target_url_template" { - required = true - type = string - description = <<-END - The template of the target URL used for the links; must be a valid URL and contain `` for the reference number. - END - } - } - } - - section { - title = "App Installations" - - variable "app_installations" { - type = set(string) - default = {} - description = <<-END - A set of GitHub App IDs to be installed in this repository. - END - - readme_example = <<-END - app_installations = ["05405144", "12556423"] - END - } - } - } - - section { - title = "Module Configuration" - - variable "module_depends_on" { - type = list(dependency) - default = [] - description = <<-END - Due to the fact, that terraform does not offer `depends_on` on modules as of today (v0.12.24) - we might hit race conditions when dealing with team names instead of ids. - So when using the feature of [adding teams by slug/name](#teams-configuration) to the repository when creating it, - make sure to add all teams to this list as indirect dependencies. - END - } - } - } - - section { - title = "Module Outputs" - content = <<-END - The following attributes are exported by the module: - END - - output "repository" { - type = object(repository) - description = <<-END - All repository attributes as returned by the [`github_repository`] - resource containing all arguments as specified above and the other - attributes as specified below. - END - } - - output "branches" { - type = object(branches) - description = <<-END - All repository attributes as returned by the [`github_branch`] - resource containing all arguments as specified above and the other - attributes as specified below. - END - } - - output "full_name" { - type = string - description = <<-END - A string of the form "orgname/reponame". - END - } - - output "html_url" { - type = string - description = <<-END - URL to the repository on the web. - END - } - - output "ssh_clone_url" { - type = string - description = <<-END - URL that can be provided to git clone to clone the repository via SSH. - END - } - - output "http_clone_url" { - type = string - description = <<-END - URL that can be provided to git clone to clone the repository via HTTPS. - END - } - - output "git_clone_url" { - type = string - description = <<-END - URL that can be provided to git clone to clone the repository - anonymously via the git protocol. - END - } - - output "collaborators" { - type = object(collaborators) - description = <<-END - A map of Collaborator objects keyed by the `name` of the collaborator as - returned by the [`github_repository_collaborator`] resource. - END - } - - output "deploy_keys" { - type = object(deploy_keys) - description = <<-END - A merged map of deploy key objects for the keys originally passed via - `deploy_keys` and `deploy_keys_computed` as returned by the - [`github_repository_deploy_key`] resource keyed by the input `id` of the - key. - END - } - - output "projects" { - type = object(project) - description = <<-END - A map of Project objects keyed by the `id` of the project as returned by - the [`github_repository_project`] resource - END - } - - output "issue_labels" { - type = object(issue_label) - description = <<-END - A map of issue labels keyed by label input id or name. - END - } - - output "webhooks" { - type = object(webhook) - description = <<-END - All attributes and arguments as returned by the - `github_repository_webhook` resource. - END - } - - output "secrets" { - type = object(secret) - description = <<-END - List of secrets available. - END - } - - output "app_installations" { - type = set(number) - description = <<-END - A map of deploy app installations keyed by installation id. - END - } - } - - section { - title = "External Documentation" - - section { - title = "Terraform Github Provider Documentation" - content = <<-END - - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository - - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/branch - - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_collaborator - - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_deploy_key - - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_project - - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_autolink_reference - END - } - } - - section { - title = "Module Versioning" - content = <<-END - This Module follows the principles of [Semantic Versioning (SemVer)]. - - Given a version number `MAJOR.MINOR.PATCH`, we increment the: - - 1. `MAJOR` version when we make incompatible changes, - 2. `MINOR` version when we add functionality in a backwards compatible manner, and - 3. `PATCH` version when we make backwards compatible bug fixes. - END - - section { - title = "Backwards compatibility in `0.0.z` and `0.y.z` version" - content = <<-END - - Backwards compatibility in versions `0.0.z` is **not guaranteed** when `z` is increased. (Initial development) - - Backwards compatibility in versions `0.y.z` is **not guaranteed** when `y` is increased. (Pre-release) - END - } - } - - section { - title = "About Mineiros" - content = <<-END - [Mineiros][homepage] is a remote-first company headquartered in Berlin, Germany - that solves development, automation and security challenges in cloud infrastructure. - - Our vision is to massively reduce time and overhead for teams to manage and - deploy production-grade and secure cloud infrastructure. - - We offer commercial support for all of our modules and encourage you to reach out - if you have any questions or need help. Feel free to email us at [hello@mineiros.io] or join our - [Community Slack channel][slack]. - END - } - - section { - title = "Reporting Issues" - content = <<-END - We use GitHub [Issues] to track community reported issues and missing features. - END - } - - section { - title = "Contributing" - content = <<-END - Contributions are always encouraged and welcome! For the process of accepting changes, we use - [Pull Requests]. If you'd like more information, please see our [Contribution Guidelines]. - END - } - - section { - title = "Makefile Targets" - content = <<-END - This repository comes with a handy [Makefile]. - Run `make help` to see details on each available target. - END - } - - section { - title = "License" - content = <<-END - [![license][badge-license]][apache20] - - This module is licensed under the Apache License Version 2.0, January 2004. - Please see [LICENSE] for full details. - - Copyright © 2020-2022 [Mineiros GmbH][homepage] - END - } -} - -references { - ref "github" { - value = "https://github.com/" - } - ref "`github_repository`" { - value = "https://www.terraform.io/docs/providers/github/r/repository.html#attributes-reference" - } - ref "`github_repository_collaborator`" { - value = "https://www.terraform.io/docs/providers/github/r/repository_collaborator.html#attribute-reference" - } - ref "`github_repository_deploy_key`" { - value = "https://www.terraform.io/docs/providers/github/r/repository_deploy_key.html#attributes-reference" - } - ref "`github_repository_project`" { - value = "https://www.terraform.io/docs/providers/github/r/repository_project.html#attributes-reference" - } - ref "`github_repository_autolink_reference`" { - value = "https://www.terraform.io/docs/providers/github/r/repository_autolink_reference.html#attributes-reference" - } - ref "homepage" { - value = "https://mineiros.io/?ref=terraform-github-repository" - } - ref "github-as-code" { - value = "https://mineiros.io/github-as-code?ref=terraform-github-repository" - } - ref "hello@mineiros.io" { - value = "mailto:hello@mineiros.io" - } - ref "badge-build" { - value = "https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg" - } - ref "badge-semver" { - value = "https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver" - } - ref "badge-license" { - value = "https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg" - } - ref "badge-terraform" { - value = "https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform" - } - ref "badge-slack" { - value = "https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack" - } - ref "badge-tf-gh" { - value = "https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform" - } - ref "releases-github-provider" { - value = "https://github.com/terraform-providers/terraform-provider-github/releases" - } - ref "build-status" { - value = "https://github.com/mineiros-io/terraform-github-repository/actions" - } - ref "releases-github" { - value = "https://github.com/mineiros-io/terraform-github-repository/releases" - } - ref "releases-terraform" { - value = "https://github.com/hashicorp/terraform/releases" - } - ref "apache20" { - value = "https://opensource.org/licenses/Apache-2.0" - } - ref "slack" { - value = "https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg" - } - ref "terraform" { - value = "https://www.terraform.io" - } - ref "aws" { - value = "https://aws.amazon.com/" - } - ref "semantic versioning (semver)" { - value = "https://semver.org/" - } - ref "variables.tf" { - value = "https://github.com/mineiros-io/terraform-github-repository/blob/main/variables.tf" - } - ref "examples/" { - value = "https://github.com/mineiros-io/terraform-github-repository/blob/main/examples" - } - ref "issues" { - value = "https://github.com/mineiros-io/terraform-github-repository/issues" - } - ref "license" { - value = "https://github.com/mineiros-io/terraform-github-repository/blob/main/LICENSE" - } - ref "makefile" { - value = "https://github.com/mineiros-io/terraform-github-repository/blob/main/Makefile" - } - ref "pull requests" { - value = "https://github.com/mineiros-io/terraform-github-repository/pulls" - } - ref "contribution guidelines" { - value = "https://github.com/mineiros-io/terraform-github-repository/blob/main/CONTRIBUTING.md" - } -} +header { + image = "https://raw.githubusercontent.com/mineiros-io/brand/3bffd30e8bdbbde32c143e2650b2faa55f1df3ea/mineiros-primary-logo.svg" + url = "https://mineiros.io/?ref=terraform-github-repository" + + badge "build" { + image = "https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg" + url = "https://github.com/mineiros-io/terraform-github-repository/actions" + text = "Build Status" + } + + badge "semver)" { + image = "https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver" + url = "https://github.com/mineiros-io/terraform-github-repository/releases" + text = "GitHub tag (latest SemVer)" + } + + badge "terraform" { + image = "https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform" + url = "https://github.com/hashicorp/terraform/releases" + text = "Terraform Version" + } + + badge "tf-gh" { + image = "https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform" + url = "https://github.com/terraform-providers/terraform-provider-github/releases" + text = "Github Provider Version" + } + + badge "slack" { + image = "https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack" + url = "https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg" + text = "Join Slack" + } +} + +section { + title = "terraform-github-repository" + toc = true + content = <<-END + A [Terraform] module for creating a public or private repository on [Github]. + + **_This module supports Terraform v1.x and is compatible with the Official Terraform GitHub Provider v4.20 and above from `integrations/github`._** + + **Attention: This module is incompatible with the Hashicorp GitHub Provider! The latest version of this module supporting `hashicorp/github` provider is `~> 0.10.0`** + + ** Note: Versions 5.3.0, 5.4.0, and 5.5.0 of the Terraform Github Provider have broken branch protections support and should not be used.** + END + + section { + title = "GitHub as Code" + content = <<-END + [GitHub as Code][github-as-code] is a commercial solution built on top of + our open-source Terraform modules for GitHub. It helps our customers to + manage their GitHub organization more efficiently by enabling anyone in + their organization to **self-service** manage **on- and offboarding of users**, + **repositories**, and settings such as **branch protections**, **secrets**, and more + through code. GitHub as Code comes with **pre-configured GitHub Actions + pipelines** for **change pre-view in Pull Requests**, **fully automated + rollouts** and **rollbacks**. It's a comprehensive, ready-to-use blueprint + maintained by our team of platform engineering experts and saves + companies such as yours tons of time by building on top of a pre-configured + solution instead of building and maintaining it yourself. + + For details please see [https://mineiros.io/github-as-code][github-as-code]. + END + } + + section { + title = "Module Features" + content = <<-END + In contrast to the plain `github_repository` resource this module enables various other + features like Branch Protection or Collaborator Management. + + - **Default Security Settings**: + This module creates a `private` repository by default, + Deploy keys are `read-only` by default + + - **Standard Repository Features**: + Setting basic Metadata, + Merge Strategy, + Auto Init, + License Template, + Gitignore Template, + Template Repository + + - **Extended Repository Features**: + Branches, + Branch Protection, + Issue Labels, + Handle Github Default Issue Labels, + Collaborators, + Teams, + Deploy Keys, + Projects, + Repository Webhooks + + - _Features not yet implemented_: + Project Columns support, + Actions, + Repository File + END + } + + section { + title = "Getting Started" + content = <<-END + Most basic usage creating a new private github repository. + + ```hcl + module "repository" { + source = "mineiros-io/repository/github" + version = "~> 0.18.0" + + name = "terraform-github-repository" + license_template = "apache-2.0" + gitignore_template = "Terraform" + } + ``` + END + } + + section { + title = "Module Argument Reference" + content = <<-END + See [variables.tf] and [examples/] for details and use-cases. + END + + section { + title = "Main Resource Configuration" + + variable "name" { + required = true + type = string + description = <<-END + The name of the repository. + END + } + + variable "defaults" { + type = object(defaults) + default = {} + description = <<-END + DEPRECATED: + This variable will be removed in future releases. + It was needed in times when Terraform Module for each was not available to provide default values for multiple repositories. + Please convert your code accordingly to stay compatible with future releases. + END + } + + variable "pages" { + type = object(pages) + default = {} + description = <<-END + A object of settings to configure GitHub Pages in this repository. + See below for a list of supported arguments. + END + + attribute "branch" { + required = true + type = string + description = <<-END + The repository branch used to publish the site's source files. + END + } + + attribute "path" { + type = string + description = <<-END + The repository directory from which the site publishes. + END + } + + attribute "cname" { + type = string + description = <<-END + The custom domain for the repository. This can only be set after the + repository has been created. + END + } + } + + variable "allow_merge_commit" { + type = bool + default = true + description = <<-END + Set to `false` to disable merge commits on the repository. + If you set this to `false` you have to enable either `allow_squash_merge` + or `allow_rebase_merge`. + END + } + + variable "allow_squash_merge" { + type = bool + default = false + description = <<-END + Set to `true` to enable squash merges on the repository. + END + } + + variable "allow_rebase_merge" { + type = bool + default = false + description = <<-END + Set to `true` to enable rebase merges on the repository. + END + } + + variable "allow_auto_merge" { + type = bool + default = false + description = <<-END + Set to `true` to allow [auto-merging](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request) + pull requests on the repository. If you enable auto-merge for a pull + request, the pull request will merge automatically when all required + reviews are met and status checks have passed. + END + } + + variable "description" { + type = string + default = "" + description = <<-END + A description of the repository. + END + } + + variable "delete_branch_on_merge" { + type = bool + default = true + description = <<-END + Set to `false` to disable the automatic deletion of head branches after pull requests are merged. + END + } + + variable "homepage_url" { + type = string + default = "" + description = <<-END + URL of a page describing the project. + END + } + + variable "private" { + type = bool + description = <<-END + **_DEPRECATED_**: Please use `visibility` instead and update your code. parameter will be removed in a future version + END + } + + variable "visibility" { + type = string + default = "private" + description = <<-END + Can be `public` or `private`. + If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, `visibility` can also be `internal`. + The `visibility` parameter overrides the deprecated `private` parameter. + END + } + + variable "has_issues" { + type = bool + default = false + description = <<-END + Set to true to enable the GitHub Issues features on the repository. + END + } + + variable "has_projects" { + type = bool + default = false + description = <<-END + Set to true to enable the GitHub Projects features on the repository. + END + } + + variable "has_wiki" { + type = bool + default = false + description = <<-END + Set to true to enable the GitHub Wiki features on the repository. + END + } + + variable "has_downloads" { + type = bool + default = false + description = <<-END + Set to `true` to enable the (deprecated) downloads features on the repository. + END + } + + variable "is_template" { + type = bool + default = false + description = <<-END + Set to `true` to tell GitHub that this is a template repository. + END + } + + variable "default_branch" { + type = string + default = "" + description = <<-END + The name of the default branch of the repository. + NOTE: The configured default branch must exist in the repository. + If the branch doesn't exist yet, or if you are creating a new + repository, please add the desired default branch to the `branches` + variable, which will cause Terraform to create it for you. + END + } + + variable "archived" { + type = bool + default = false + description = <<-END + Specifies if the repository should be archived. + NOTE: Currently, the API does not support unarchiving. + END + } + + variable "topics" { + type = list(string) + default = [] + description = <<-END + The list of topics of the repository. + END + } + + variable "extra_topics" { + type = list(string) + default = [] + description = <<-END + A list of additional topics of the repository. Those topics will be added to the list of `topics`. This is useful if `default.topics` are used and the list should be extended with more topics. + END + } + + variable "vulnerability_alerts" { + type = bool + description = <<-END + Set to `false` to disable security alerts for vulnerable dependencies. + Enabling requires alerts to be enabled on the owner level. + END + } + + variable "archive_on_destroy" { + type = bool + default = true + description = <<-END + Set to `false` to not archive the repository instead of deleting on destroy. + END + } + } + + section { + title = "Extended Resource Configuration" + + section { + title = "Repository Creation Configuration" + content = <<-END + The following four arguments can only be set at repository creation and + changes will be ignored for repository updates and + will not show a diff in plan or apply phase. + END + + variable "auto_init" { + type = bool + default = true + description = <<-END + Set to `false` to not produce an initial commit in the repository. + END + } + + variable "gitignore_template" { + type = string + default = "" + description = <<-END + Use the name of the template without the extension. + END + } + + variable "license_template" { + type = string + default = "" + description = <<-END + Use the name of the template without the extension. + END + } + + variable "template" { + type = object(template) + default = {} + description = <<-END + Use a template repository to create this resource. + END + + attribute "owner" { + required = true + type = string + description = <<-END + The GitHub organization or user the template repository is owned by. + END + } + + attribute "repository" { + required = true + type = string + description = <<-END + The name of the template repository. + END + } + } + } + + section { + title = "Teams Configuration" + content = <<-END + Your can use non-computed (known at `terraform plan`) team names or slugs (`*_teams` Attributes) + or computed (only known in `terraform apply` phase) team IDs (`*_team_ids` Attributes). + **When using non-computed names/slugs teams need to exist before running plan.** + This is due to some terraform limitation and we will update the module once terraform removed this limitation. + END + + variable "pull_teams" { + type = list(string) + default = [] + description = <<-END + Can also be `pull_team_ids`. A list of teams to grant pull (read-only) permission. + Recommended for non-code contributors who want to view or discuss your project. + END + } + + variable "triage_teams" { + type = list(string) + default = [] + description = <<-END + Can also be `triage_team_ids`. A list of teams to grant triage permission. + Recommended for contributors who need to proactively manage issues and pull requests + without write access. + END + } + + variable "push_teams" { + type = list(string) + default = [] + description = <<-END + Can also be `push_team_ids`. A list of teams to grant push (read-write) permission. + Recommended for contributors who actively push to your project. + END + } + + variable "maintain_teams" { + type = list(string) + default = [] + description = <<-END + Can also be `maintain_team_ids`. A list of teams to grant maintain permission. + Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. + END + } + + variable "admin_teams" { + type = list(string) + default = [] + description = <<-END + Can also be `admin_team_ids`. A list of teams to grant admin (full) permission. + Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. + END + } + } + + section { + title = "Collaborator Configuration" + + variable "pull_collaborators" { + type = list(string) + default = [] + description = <<-END + A list of user names to add as collaborators granting them pull (read-only) permission. + Recommended for non-code contributors who want to view or discuss your project. + END + } + + variable "triage_collaborators" { + type = list(string) + default = [] + description = <<-END + A list of user names to add as collaborators granting them triage permission. + Recommended for contributors who need to proactively manage issues and pull requests without write access. + END + } + + variable "push_collaborators" { + type = list(string) + default = [] + description = <<-END + A list of user names to add as collaborators granting them push (read-write) permission. + Recommended for contributors who actively push to your project. + END + } + + variable "maintain_collaborators" { + type = list(string) + default = [] + description = <<-END + A list of user names to add as collaborators granting them maintain permission. + Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. + END + } + + variable "admin_collaborators" { + type = list(string) + default = [] + description = <<-END + A list of user names to add as collaborators granting them admin (full) permission. + Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. + END + } + } + + section { + title = "Branches Configuration" + + variable "branches" { + type = list(branch) + default = [] + description = <<-END + Create and manage branches within your repository. + Additional constraints can be applied to ensure your branch is created from another branch or commit. + END + + attribute "name" { + required = true + type = string + description = <<-END + The name of the branch to create. + END + } + + attribute "source_branch" { + type = string + description = <<-END + The branch name to start from. Uses the configured default branch per default. + END + } + + attribute "source_sha" { + type = bool + default = true + description = <<-END + The commit hash to start from. Defaults to the tip of `source_branch`. If provided, `source_branch` is ignored. + END + } + } + } + + section { + title = "Deploy Keys Configuration" + + variable "deploy_keys" { + type = list(deploy_key) + default = [] + description = <<-END + Can also be type `list(string)`. Specifies deploy keys and access-level of deploy keys used in this repository. + Every `string` in the list will be converted internally into the `object` representation with the `key` argument being set to the `string`. `object` details are explained below. + END + + attribute "key" { + required = true + type = string + description = <<-END + The SSH public key. + END + } + + attribute "title" { + type = string + description = <<-END + A Title for the key. + Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. + END + } + + attribute "read_only" { + type = bool + default = true + description = <<-END + Specifies the level of access for the key. + END + } + + attribute "id" { + type = string + default = "md5(key)" + description = <<-END + Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. + The ID must be unique between `deploy_keys` and `deploy_keys_computed`. + END + } + } + + variable "deploy_keys_computed" { + type = list(deploy_key) + default = [] + description = <<-END + Can also be type `string`. Same as `deploy_keys` argument with the following differences: + Use this argument if you depend on computed keys that terraform can not use in resource `for_each` execution. Downside of this is the recreation of deploy key resources whenever the order in the list changes. **Prefer `deploy_keys` whenever possible.** + This argument does **not** conflict with `deploy_keys` and should exclusively be used for computed resources. + END + + attribute "key" { + required = true + type = string + description = <<-END + The SSH public key. + END + } + + attribute "title" { + type = string + description = <<-END + A Title for the key. + Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. + END + } + + attribute "read_only" { + type = bool + default = true + description = <<-END + Specifies the level of access for the key. + END + } + + attribute "id" { + type = string + default = "md5(key)" + description = <<-END + Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. + The ID must be unique between `deploy_keys` and `deploy_keys_computed`. + END + } + } + } + + section { + title = "Branch Protections v3 Configuration" + + variable "branch_protections_v3" { + type = list(branch_protection_v3) + default = [] + description = <<-END + 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 + + attribute "branch" { + required = true + type = string + description = <<-END + The Git branch to protect. + END + } + + attribute "enforce_admins" { + type = bool + default = false + description = <<-END + Setting this to true enforces status checks for repository administrators. + END + } + + attribute "require_conversation_resolution" { + type = bool + default = false + description = <<-END + Setting this to true requires all conversations to be resolved. + 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_status_checks" { + type = object(required_status_checks) + default = {} + 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 + } + } + + attribute "required_pull_request_reviews" { + type = object(required_pull_request_reviews) + default = {} + 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_users" { + type = list(string) + default = [] + description = <<-END + The list of user logins with dismissal access + END + } + + attribute "dismissal_teams" { + type = list(string) + default = [] + description = <<-END + The list of team slugs with dismissal access. + Always use slug of the team, not its name. + Each team already has to have access to the repository. + 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 "restrictions" { + type = object(restrictions) + default = {} + description = <<-END + Enforce restrictions for the users and teams that may push to the branch - only available for organization-owned repositories. See Restrictions below for details. + END + + attribute "users" { + type = list(string) + default = [] + description = <<-END + The list of user logins with push access. + END + } + + attribute "teams" { + type = list(string) + default = [] + description = <<-END + The list of team slugs with push access. + Always use slug of the team, not its name. + Each team already has to have access to the repository. + END + } + + attribute "apps" { + type = list(string) + default = [] + description = <<-END + The list of app slugs with push access. + END + } + } + } + } + + section { + title = "Branch Protections v4 Configuration" + + variable "branch_protections_v4" { + type = list(branch_protection_v4) + default = [] + description = <<-END + This resource allows you to configure v4 branch protection for repositories in your organization. + + Each element in the list 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:_** May conflict with v3 branch protections if used for the same branch. + END + + attribute "pattern" { + type = string + required = true + description = <<-END + Identifies the protection rule pattern. + END + } + + attribute "_key" { + type = string + description = <<-END + An alternative key to use in `for_each` resource creation. + Defaults to the value of `var.pattern`. + 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 = true + description = <<-END + Keeping this as `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) + 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 "restrict_dismissals" { + type = bool + description = <<-END + Restrict pull request review dismissals. + 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 = true + 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) + 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" + + variable "issue_labels" { + type = list(issue_label) + default = [] + description = <<-END + This resource allows you to create and manage issue labels within your GitHub organization. + Issue labels are keyed off of their "name", so pre-existing issue labels result in a 422 HTTP error if they exist outside of Terraform. + Normally this would not be an issue, except new repositories are created with a "default" set of labels, and those labels easily conflict with custom ones. + This resource will first check if the label exists, and then issue an update, otherwise it will create. + END + + attribute "name" { + required = true + type = string + description = <<-END + The name of the label. + END + } + + attribute "color" { + required = true + type = string + description = <<-END + A 6 character hex code, without the leading `#`, identifying the color of the label. + END + } + + attribute "description" { + type = string + default = "" + description = <<-END + A short description of the label. + END + } + + attribute "id" { + type = string + default = "name" + description = <<-END + Specifies an ID which is used to prevent resource recreation when the order in the list of issue labels changes. + END + } + } + + variable "issue_labels_merge_with_github_labels" { + type = bool + description = <<-END + Specify if github default labels will be handled by terraform. This should be decided on upon creation of the repository. If you later decide to disable this feature, github default labels will be destroyed if not replaced by labels set in `issue_labels` argument. + END + } + + variable "issue_labels_create" { + type = bool + description = <<-END + Specify whether you want to force or suppress the creation of issues labels. + Default is `true` if `has_issues` is `true` or `issue_labels` is non-empty. + END + } + } + + section { + title = "Projects Configuration" + + variable "projects" { + type = list(project) + default = [] + description = <<-END + This resource allows you to create and manage projects for GitHub repository. + END + + attribute "name" { + required = true + type = string + description = <<-END + The name of the project. + END + } + + attribute "body" { + type = string + default = "" + description = <<-END + The body of the project. + END + } + + attribute "id" { + type = string + default = "name" + description = <<-END + Specifies an ID which is used to prevent resource recreation when the order in the list of projects changes. + END + } + } + } + + section { + title = "Webhooks Configuration" + + variable "webhooks" { + type = list(webhook) + default = [] + description = <<-END + This resource allows you to create and manage webhooks for repositories in your organization. + When applied, a webhook will be created which specifies a URL to receive events and which events to receieve. Additional constraints, such as SSL verification, pre-shared secret and content type can also be configured + END + + attribute "events" { + required = true + type = list(string) + description = <<-END + A list of events which should trigger the webhook. [See a list of available events.](https://developer.github.com/v3/activity/events/types/) + END + } + + attribute "url" { + required = true + type = string + description = <<-END + The URL to which the payloads will be delivered. + END + } + + attribute "active" { + type = bool + description = <<-END + Indicate if the webhook should receive events. Defaults to `true`. + END + } + + attribute "content_type" { + type = string + default = "form" + description = <<-END + The media type used to serialize the payloads. Supported values include `json` and `form`. + END + } + + attribute "secret" { + type = string + description = <<-END + If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value in the [X-Hub-Signature](https://developer.github.com/webhooks/#delivery-headers) header. + END + } + + attribute "insecure_ssl" { + type = bool + description = <<-END + Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. **We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.** + END + } + } + } + + section { + title = "Secrets Configuration" + + variable "plaintext_secrets" { + type = map(string) + default = {} + description = <<-END + This map allows you to create and manage secrets for repositories in your organization. + + Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding secret in plain text: + + When applied, a secret with the given key and value will be created in the repositories. + + The value of the secrets must be given in plain text, GitHub provider is in charge of encrypting it. + + **Attention:** You should treat state as sensitive always. It is also advised that you do not store plaintext values in your code but rather populate the encrypted_value using fields from a resource, data source or variable as, while encrypted in state, these will be easily accessible in your code. See below for an example of this abstraction. + END + + readme_example = <<-END + plaintext_secrets = { + SECRET_NAME_1 = "plaintext_secret_value_1" + SECRET_NAME_2 = "plaintext_secret_value_2" + } + END + } + + variable "encrypted_secrets" { + type = map(string) + default = {} + description = <<-END + This map allows you to create and manage encrypted secrets for repositories in your organization. + + Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding encrypted value of the secret using the Github public key in Base64 format.b + + When applied, a secret with the given key and value will be created in the repositories. + END + + readme_example = <<-END + encrypted_secrets = { + SECRET_NAME_1 = "c2VjcmV0X3ZhbHVlXzE=" + SECRET_NAME_2 = "c2VjcmV0X3ZhbHVlXzI=" + } + END + } + + variable "required_approving_review_count" { + type = number + description = <<-END + Require x number of approvals to satisfy branch protection requirements. + If this is specified it must be a number between 1-6. + This requirement matches Github's API, see the upstream documentation for more information. + Default is no approving reviews are required. + END + } + } + + section { + title = "Autolink References Configuration" + + variable "autolink_references" { + type = list(autolink_reference) + default = [] + description = <<-END + This resource allows you to create and manage autolink references for GitHub repository. + END + + attribute "key_prefix" { + required = true + type = string + description = <<-END + This prefix appended by a number will generate a link any time it is found in an issue, pull request, or commit. + END + } + + attribute "target_url_template" { + required = true + type = string + description = <<-END + The template of the target URL used for the links; must be a valid URL and contain `` for the reference number. + END + } + } + } + + section { + title = "App Installations" + + variable "app_installations" { + type = set(string) + default = {} + description = <<-END + A set of GitHub App IDs to be installed in this repository. + END + + readme_example = <<-END + app_installations = ["05405144", "12556423"] + END + } + } + } + + section { + title = "Module Configuration" + + variable "module_depends_on" { + type = list(dependency) + default = [] + description = <<-END + Due to the fact, that terraform does not offer `depends_on` on modules as of today (v0.12.24) + we might hit race conditions when dealing with team names instead of ids. + So when using the feature of [adding teams by slug/name](#teams-configuration) to the repository when creating it, + make sure to add all teams to this list as indirect dependencies. + END + } + } + } + + section { + title = "Module Outputs" + content = <<-END + The following attributes are exported by the module: + END + + output "repository" { + type = object(repository) + description = <<-END + All repository attributes as returned by the [`github_repository`] + resource containing all arguments as specified above and the other + attributes as specified below. + END + } + + output "branches" { + type = object(branches) + description = <<-END + All repository attributes as returned by the [`github_branch`] + resource containing all arguments as specified above and the other + attributes as specified below. + END + } + + output "full_name" { + type = string + description = <<-END + A string of the form "orgname/reponame". + END + } + + output "html_url" { + type = string + description = <<-END + URL to the repository on the web. + END + } + + output "ssh_clone_url" { + type = string + description = <<-END + URL that can be provided to git clone to clone the repository via SSH. + END + } + + output "http_clone_url" { + type = string + description = <<-END + URL that can be provided to git clone to clone the repository via HTTPS. + END + } + + output "git_clone_url" { + type = string + description = <<-END + URL that can be provided to git clone to clone the repository + anonymously via the git protocol. + END + } + + output "collaborators" { + type = object(collaborators) + description = <<-END + A map of Collaborator objects keyed by the `name` of the collaborator as + returned by the [`github_repository_collaborator`] resource. + END + } + + output "deploy_keys" { + type = object(deploy_keys) + description = <<-END + A merged map of deploy key objects for the keys originally passed via + `deploy_keys` and `deploy_keys_computed` as returned by the + [`github_repository_deploy_key`] resource keyed by the input `id` of the + key. + END + } + + output "projects" { + type = object(project) + description = <<-END + A map of Project objects keyed by the `id` of the project as returned by + the [`github_repository_project`] resource + END + } + + output "issue_labels" { + type = object(issue_label) + description = <<-END + A map of issue labels keyed by label input id or name. + END + } + + output "webhooks" { + type = object(webhook) + description = <<-END + All attributes and arguments as returned by the + `github_repository_webhook` resource. + END + } + + output "secrets" { + type = object(secret) + description = <<-END + List of secrets available. + END + } + + output "app_installations" { + type = set(number) + description = <<-END + A map of deploy app installations keyed by installation id. + END + } + } + + section { + title = "External Documentation" + + section { + title = "Terraform Github Provider Documentation" + content = <<-END + - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository + - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/branch + - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_collaborator + - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_deploy_key + - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_project + - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_autolink_reference + END + } + } + + section { + title = "Module Versioning" + content = <<-END + This Module follows the principles of [Semantic Versioning (SemVer)]. + + Given a version number `MAJOR.MINOR.PATCH`, we increment the: + + 1. `MAJOR` version when we make incompatible changes, + 2. `MINOR` version when we add functionality in a backwards compatible manner, and + 3. `PATCH` version when we make backwards compatible bug fixes. + END + + section { + title = "Backwards compatibility in `0.0.z` and `0.y.z` version" + content = <<-END + - Backwards compatibility in versions `0.0.z` is **not guaranteed** when `z` is increased. (Initial development) + - Backwards compatibility in versions `0.y.z` is **not guaranteed** when `y` is increased. (Pre-release) + END + } + } + + section { + title = "About Mineiros" + content = <<-END + [Mineiros][homepage] is a remote-first company headquartered in Berlin, Germany + that solves development, automation and security challenges in cloud infrastructure. + + Our vision is to massively reduce time and overhead for teams to manage and + deploy production-grade and secure cloud infrastructure. + + We offer commercial support for all of our modules and encourage you to reach out + if you have any questions or need help. Feel free to email us at [hello@mineiros.io] or join our + [Community Slack channel][slack]. + END + } + + section { + title = "Reporting Issues" + content = <<-END + We use GitHub [Issues] to track community reported issues and missing features. + END + } + + section { + title = "Contributing" + content = <<-END + Contributions are always encouraged and welcome! For the process of accepting changes, we use + [Pull Requests]. If you'd like more information, please see our [Contribution Guidelines]. + END + } + + section { + title = "Makefile Targets" + content = <<-END + This repository comes with a handy [Makefile]. + Run `make help` to see details on each available target. + END + } + + section { + title = "License" + content = <<-END + [![license][badge-license]][apache20] + + This module is licensed under the Apache License Version 2.0, January 2004. + Please see [LICENSE] for full details. + + Copyright © 2020-2022 [Mineiros GmbH][homepage] + END + } +} + +references { + ref "github" { + value = "https://github.com/" + } + ref "`github_repository`" { + value = "https://www.terraform.io/docs/providers/github/r/repository.html#attributes-reference" + } + ref "`github_repository_collaborator`" { + value = "https://www.terraform.io/docs/providers/github/r/repository_collaborator.html#attribute-reference" + } + ref "`github_repository_deploy_key`" { + value = "https://www.terraform.io/docs/providers/github/r/repository_deploy_key.html#attributes-reference" + } + ref "`github_repository_project`" { + value = "https://www.terraform.io/docs/providers/github/r/repository_project.html#attributes-reference" + } + ref "`github_repository_autolink_reference`" { + value = "https://www.terraform.io/docs/providers/github/r/repository_autolink_reference.html#attributes-reference" + } + ref "homepage" { + value = "https://mineiros.io/?ref=terraform-github-repository" + } + ref "github-as-code" { + value = "https://mineiros.io/github-as-code?ref=terraform-github-repository" + } + ref "hello@mineiros.io" { + value = "mailto:hello@mineiros.io" + } + ref "badge-build" { + value = "https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg" + } + ref "badge-semver" { + value = "https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver" + } + ref "badge-license" { + value = "https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg" + } + ref "badge-terraform" { + value = "https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform" + } + ref "badge-slack" { + value = "https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack" + } + ref "badge-tf-gh" { + value = "https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform" + } + ref "releases-github-provider" { + value = "https://github.com/terraform-providers/terraform-provider-github/releases" + } + ref "build-status" { + value = "https://github.com/mineiros-io/terraform-github-repository/actions" + } + ref "releases-github" { + value = "https://github.com/mineiros-io/terraform-github-repository/releases" + } + ref "releases-terraform" { + value = "https://github.com/hashicorp/terraform/releases" + } + ref "apache20" { + value = "https://opensource.org/licenses/Apache-2.0" + } + ref "slack" { + value = "https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg" + } + ref "terraform" { + value = "https://www.terraform.io" + } + ref "aws" { + value = "https://aws.amazon.com/" + } + ref "semantic versioning (semver)" { + value = "https://semver.org/" + } + ref "variables.tf" { + value = "https://github.com/mineiros-io/terraform-github-repository/blob/main/variables.tf" + } + ref "examples/" { + value = "https://github.com/mineiros-io/terraform-github-repository/blob/main/examples" + } + ref "issues" { + value = "https://github.com/mineiros-io/terraform-github-repository/issues" + } + ref "license" { + value = "https://github.com/mineiros-io/terraform-github-repository/blob/main/LICENSE" + } + ref "makefile" { + value = "https://github.com/mineiros-io/terraform-github-repository/blob/main/Makefile" + } + ref "pull requests" { + value = "https://github.com/mineiros-io/terraform-github-repository/pulls" + } + ref "contribution guidelines" { + value = "https://github.com/mineiros-io/terraform-github-repository/blob/main/CONTRIBUTING.md" + } +} diff --git a/main.tf b/main.tf index 587e1bb..e8b4359 100644 --- a/main.tf +++ b/main.tf @@ -57,7 +57,8 @@ locals { length(keys(b.required_status_checks)) > 0 ? [ merge({ strict = null - contexts = [] + contexts = [], + checks = [] }, b.required_status_checks)] : [] ] @@ -261,6 +262,7 @@ resource "github_branch_protection_v3" "branch_protection" { content { strict = required_status_checks.value.strict contexts = required_status_checks.value.contexts + checks = required_status_checks.value.checks } } diff --git a/test/unit-complete/main.tf b/test/unit-complete/main.tf index f307097..13f3ff9 100644 --- a/test/unit-complete/main.tf +++ b/test/unit-complete/main.tf @@ -119,7 +119,8 @@ module "repository" { required_status_checks = { strict = true - contexts = ["ci/travis"] + contexts = ["ci/travis"], + checks = ["ci/travis:20258468"] } required_pull_request_reviews = { diff --git a/variables.tf b/variables.tf index 7599034..affb6f5 100644 --- a/variables.tf +++ b/variables.tf @@ -280,6 +280,7 @@ variable "branch_protections_v3" { # required_status_checks = object({ # strict = bool # contexts = list(string) + # checks = list(string) # }) # required_pull_request_reviews = object({ # dismiss_stale_reviews = bool @@ -306,6 +307,8 @@ variable "branch_protections_v3" { # required_status_checks = { # strict = false # contexts = ["ci/travis"] + # checks = ["ci/travis:20258468"] + # })) # } # # required_pull_request_reviews = { From 6d9e41f690306c0067683fc76654672285a74606 Mon Sep 17 00:00:00 2001 From: Cyb3r-Jak3 Date: Sun, 12 Mar 2023 17:50:50 -0400 Subject: [PATCH 2/2] Fix README info --- README.md | 1882 +++++++++++++++++++++++----------------------- README.tfdoc.hcl | 11 +- 2 files changed, 954 insertions(+), 939 deletions(-) diff --git a/README.md b/README.md index e40a65c..a6b7bf0 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,55 @@ -[](https://mineiros.io/?ref=terraform-github-repository) - -[![Build Status](https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg)](https://github.com/mineiros-io/terraform-github-repository/actions) -[![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver)](https://github.com/mineiros-io/terraform-github-repository/releases) -[![Terraform Version](https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform)](https://github.com/hashicorp/terraform/releases) -[![Github Provider Version](https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform)](https://github.com/terraform-providers/terraform-provider-github/releases) -[![Join Slack](https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack)](https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg) - -# terraform-github-repository - +[](https://mineiros.io/?ref=terraform-github-repository) + +[![Build Status](https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg)](https://github.com/mineiros-io/terraform-github-repository/actions) +[![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver)](https://github.com/mineiros-io/terraform-github-repository/releases) +[![Terraform Version](https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform)](https://github.com/hashicorp/terraform/releases) +[![Github Provider Version](https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform)](https://github.com/terraform-providers/terraform-provider-github/releases) +[![Join Slack](https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack)](https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg) + +# terraform-github-repository + A [Terraform] module for creating a public or private repository on [Github]. **_This module supports Terraform v1.x and is compatible with the Official Terraform GitHub Provider v4.20 and above from `integrations/github`._** **Attention: This module is incompatible with the Hashicorp GitHub Provider! The latest version of this module supporting `hashicorp/github` provider is `~> 0.10.0`** -** Note: Versions 5.3.0, 5.4.0, and 5.5.0 of the Terraform Github Provider have broken branch protections support and should not be used.** - - -- [terraform-github-repository](#terraform-github-repository) - - [GitHub as Code](#github-as-code) - - [Module Features](#module-features) - - [Getting Started](#getting-started) - - [Module Argument Reference](#module-argument-reference) - - [Main Resource Configuration](#main-resource-configuration) - - [Extended Resource Configuration](#extended-resource-configuration) - - [Repository Creation Configuration](#repository-creation-configuration) - - [Teams Configuration](#teams-configuration) - - [Collaborator Configuration](#collaborator-configuration) - - [Branches Configuration](#branches-configuration) - - [Deploy Keys Configuration](#deploy-keys-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) - - [Secrets Configuration](#secrets-configuration) - - [Autolink References Configuration](#autolink-references-configuration) - - [App Installations](#app-installations) - - [Module Configuration](#module-configuration) - - [Module Outputs](#module-outputs) - - [External Documentation](#external-documentation) - - [Terraform Github Provider Documentation](#terraform-github-provider-documentation) - - [Module Versioning](#module-versioning) - - [Backwards compatibility in `0.0.z` and `0.y.z` version](#backwards-compatibility-in-00z-and-0yz-version) - - [About Mineiros](#about-mineiros) - - [Reporting Issues](#reporting-issues) - - [Contributing](#contributing) - - [Makefile Targets](#makefile-targets) - - [License](#license) - -## GitHub as Code - +** Note: Versions 5.3.0, 5.4.0, and 5.5.0 of the Terraform Github Provider have broken branch protections support and should not be used.** + + +- [GitHub as Code](#github-as-code) +- [Module Features](#module-features) +- [Getting Started](#getting-started) +- [Module Argument Reference](#module-argument-reference) + - [Main Resource Configuration](#main-resource-configuration) + - [Extended Resource Configuration](#extended-resource-configuration) + - [Repository Creation Configuration](#repository-creation-configuration) + - [Teams Configuration](#teams-configuration) + - [Collaborator Configuration](#collaborator-configuration) + - [Branches Configuration](#branches-configuration) + - [Deploy Keys Configuration](#deploy-keys-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) + - [Secrets Configuration](#secrets-configuration) + - [Autolink References Configuration](#autolink-references-configuration) + - [App Installations](#app-installations) + - [Module Configuration](#module-configuration) +- [Module Outputs](#module-outputs) +- [External Documentation](#external-documentation) + - [Terraform Github Provider Documentation](#terraform-github-provider-documentation) +- [Module Versioning](#module-versioning) + - [Backwards compatibility in `0.0.z` and `0.y.z` version](#backwards-compatibility-in-00z-and-0yz-version) +- [About Mineiros](#about-mineiros) +- [Reporting Issues](#reporting-issues) +- [Contributing](#contributing) +- [Makefile Targets](#makefile-targets) +- [License](#license) + +## GitHub as Code + [GitHub as Code][github-as-code] is a commercial solution built on top of our open-source Terraform modules for GitHub. It helps our customers to manage their GitHub organization more efficiently by enabling anyone in @@ -63,10 +62,10 @@ maintained by our team of platform engineering experts and saves companies such as yours tons of time by building on top of a pre-configured solution instead of building and maintaining it yourself. -For details please see [https://mineiros.io/github-as-code][github-as-code]. - -## Module Features - +For details please see [https://mineiros.io/github-as-code][github-as-code]. + +## Module Features + In contrast to the plain `github_repository` resource this module enables various other features like Branch Protection or Collaborator Management. @@ -96,10 +95,10 @@ features like Branch Protection or Collaborator Management. - _Features not yet implemented_: Project Columns support, Actions, - Repository File - -## Getting Started - + Repository File + +## Getting Started + Most basic usage creating a new private github repository. ```hcl @@ -111,943 +110,950 @@ module "repository" { license_template = "apache-2.0" gitignore_template = "Terraform" } -``` - -## Module Argument Reference - -See [variables.tf] and [examples/] for details and use-cases. - -### Main Resource Configuration - -- [**`name`**](#var-name): *(**Required** `string`)* - - The name of the repository. - -- [**`defaults`**](#var-defaults): *(Optional `object(defaults)`)* - +``` + +## Module Argument Reference + +See [variables.tf] and [examples/] for details and use-cases. + +### Main Resource Configuration + +- [**`name`**](#var-name): *(**Required** `string`)* + + The name of the repository. + +- [**`defaults`**](#var-defaults): *(Optional `object(defaults)`)* + DEPRECATED: This variable will be removed in future releases. It was needed in times when Terraform Module for each was not available to provide default values for multiple repositories. - Please convert your code accordingly to stay compatible with future releases. - - Default is `{}`. - -- [**`pages`**](#var-pages): *(Optional `object(pages)`)* - + Please convert your code accordingly to stay compatible with future releases. + + Default is `{}`. + +- [**`pages`**](#var-pages): *(Optional `object(pages)`)* + A object of settings to configure GitHub Pages in this repository. - See below for a list of supported arguments. - - Default is `{}`. - - The `pages` object accepts the following attributes: - - - [**`branch`**](#attr-pages-branch): *(**Required** `string`)* - - The repository branch used to publish the site's source files. - - - [**`path`**](#attr-pages-path): *(Optional `string`)* - - The repository directory from which the site publishes. - - - [**`cname`**](#attr-pages-cname): *(Optional `string`)* - + See below for a list of supported arguments. + + Default is `{}`. + + The `pages` object accepts the following attributes: + + - [**`branch`**](#attr-pages-branch): *(**Required** `string`)* + + The repository branch used to publish the site's source files. + + - [**`path`**](#attr-pages-path): *(Optional `string`)* + + The repository directory from which the site publishes. + + - [**`cname`**](#attr-pages-cname): *(Optional `string`)* + The custom domain for the repository. This can only be set after the - repository has been created. - -- [**`allow_merge_commit`**](#var-allow_merge_commit): *(Optional `bool`)* - + repository has been created. + +- [**`allow_merge_commit`**](#var-allow_merge_commit): *(Optional `bool`)* + Set to `false` to disable merge commits on the repository. If you set this to `false` you have to enable either `allow_squash_merge` - or `allow_rebase_merge`. - - Default is `true`. - -- [**`allow_squash_merge`**](#var-allow_squash_merge): *(Optional `bool`)* - - Set to `true` to enable squash merges on the repository. - - Default is `false`. - -- [**`allow_rebase_merge`**](#var-allow_rebase_merge): *(Optional `bool`)* - - Set to `true` to enable rebase merges on the repository. - - Default is `false`. - -- [**`allow_auto_merge`**](#var-allow_auto_merge): *(Optional `bool`)* - + or `allow_rebase_merge`. + + Default is `true`. + +- [**`allow_squash_merge`**](#var-allow_squash_merge): *(Optional `bool`)* + + Set to `true` to enable squash merges on the repository. + + Default is `false`. + +- [**`allow_rebase_merge`**](#var-allow_rebase_merge): *(Optional `bool`)* + + Set to `true` to enable rebase merges on the repository. + + Default is `false`. + +- [**`allow_auto_merge`**](#var-allow_auto_merge): *(Optional `bool`)* + Set to `true` to allow [auto-merging](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/automatically-merging-a-pull-request) pull requests on the repository. If you enable auto-merge for a pull request, the pull request will merge automatically when all required - reviews are met and status checks have passed. - - Default is `false`. - -- [**`description`**](#var-description): *(Optional `string`)* - - A description of the repository. - - Default is `""`. - -- [**`delete_branch_on_merge`**](#var-delete_branch_on_merge): *(Optional `bool`)* - - Set to `false` to disable the automatic deletion of head branches after pull requests are merged. - - Default is `true`. - -- [**`homepage_url`**](#var-homepage_url): *(Optional `string`)* - - URL of a page describing the project. - - Default is `""`. - -- [**`private`**](#var-private): *(Optional `bool`)* - - **_DEPRECATED_**: Please use `visibility` instead and update your code. parameter will be removed in a future version - -- [**`visibility`**](#var-visibility): *(Optional `string`)* - + reviews are met and status checks have passed. + + Default is `false`. + +- [**`description`**](#var-description): *(Optional `string`)* + + A description of the repository. + + Default is `""`. + +- [**`delete_branch_on_merge`**](#var-delete_branch_on_merge): *(Optional `bool`)* + + Set to `false` to disable the automatic deletion of head branches after pull requests are merged. + + Default is `true`. + +- [**`homepage_url`**](#var-homepage_url): *(Optional `string`)* + + URL of a page describing the project. + + Default is `""`. + +- [**`private`**](#var-private): *(Optional `bool`)* + + **_DEPRECATED_**: Please use `visibility` instead and update your code. parameter will be removed in a future version + +- [**`visibility`**](#var-visibility): *(Optional `string`)* + Can be `public` or `private`. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, `visibility` can also be `internal`. - The `visibility` parameter overrides the deprecated `private` parameter. - - Default is `"private"`. - -- [**`has_issues`**](#var-has_issues): *(Optional `bool`)* - - Set to true to enable the GitHub Issues features on the repository. - - Default is `false`. - -- [**`has_projects`**](#var-has_projects): *(Optional `bool`)* - - Set to true to enable the GitHub Projects features on the repository. - - Default is `false`. - -- [**`has_wiki`**](#var-has_wiki): *(Optional `bool`)* - - Set to true to enable the GitHub Wiki features on the repository. - - Default is `false`. - -- [**`has_downloads`**](#var-has_downloads): *(Optional `bool`)* - - Set to `true` to enable the (deprecated) downloads features on the repository. - - Default is `false`. - -- [**`is_template`**](#var-is_template): *(Optional `bool`)* - - Set to `true` to tell GitHub that this is a template repository. - - Default is `false`. - -- [**`default_branch`**](#var-default_branch): *(Optional `string`)* - + The `visibility` parameter overrides the deprecated `private` parameter. + + Default is `"private"`. + +- [**`has_issues`**](#var-has_issues): *(Optional `bool`)* + + Set to true to enable the GitHub Issues features on the repository. + + Default is `false`. + +- [**`has_projects`**](#var-has_projects): *(Optional `bool`)* + + Set to true to enable the GitHub Projects features on the repository. + + Default is `false`. + +- [**`has_wiki`**](#var-has_wiki): *(Optional `bool`)* + + Set to true to enable the GitHub Wiki features on the repository. + + Default is `false`. + +- [**`has_downloads`**](#var-has_downloads): *(Optional `bool`)* + + Set to `true` to enable the (deprecated) downloads features on the repository. + + Default is `false`. + +- [**`is_template`**](#var-is_template): *(Optional `bool`)* + + Set to `true` to tell GitHub that this is a template repository. + + Default is `false`. + +- [**`default_branch`**](#var-default_branch): *(Optional `string`)* + The name of the default branch of the repository. NOTE: The configured default branch must exist in the repository. If the branch doesn't exist yet, or if you are creating a new repository, please add the desired default branch to the `branches` - variable, which will cause Terraform to create it for you. - - Default is `""`. - -- [**`archived`**](#var-archived): *(Optional `bool`)* - + variable, which will cause Terraform to create it for you. + + Default is `""`. + +- [**`archived`**](#var-archived): *(Optional `bool`)* + Specifies if the repository should be archived. - NOTE: Currently, the API does not support unarchiving. - - Default is `false`. - -- [**`topics`**](#var-topics): *(Optional `list(string)`)* - - The list of topics of the repository. - - Default is `[]`. - -- [**`extra_topics`**](#var-extra_topics): *(Optional `list(string)`)* - - A list of additional topics of the repository. Those topics will be added to the list of `topics`. This is useful if `default.topics` are used and the list should be extended with more topics. - - Default is `[]`. - -- [**`vulnerability_alerts`**](#var-vulnerability_alerts): *(Optional `bool`)* - + NOTE: Currently, the API does not support unarchiving. + + Default is `false`. + +- [**`topics`**](#var-topics): *(Optional `list(string)`)* + + The list of topics of the repository. + + Default is `[]`. + +- [**`extra_topics`**](#var-extra_topics): *(Optional `list(string)`)* + + A list of additional topics of the repository. Those topics will be added to the list of `topics`. This is useful if `default.topics` are used and the list should be extended with more topics. + + Default is `[]`. + +- [**`vulnerability_alerts`**](#var-vulnerability_alerts): *(Optional `bool`)* + Set to `false` to disable security alerts for vulnerable dependencies. - Enabling requires alerts to be enabled on the owner level. - -- [**`archive_on_destroy`**](#var-archive_on_destroy): *(Optional `bool`)* - - Set to `false` to not archive the repository instead of deleting on destroy. - - Default is `true`. - -### Extended Resource Configuration - -#### Repository Creation Configuration - + Enabling requires alerts to be enabled on the owner level. + +- [**`archive_on_destroy`**](#var-archive_on_destroy): *(Optional `bool`)* + + Set to `false` to not archive the repository instead of deleting on destroy. + + Default is `true`. + +### Extended Resource Configuration + +#### Repository Creation Configuration + The following four arguments can only be set at repository creation and changes will be ignored for repository updates and -will not show a diff in plan or apply phase. - -- [**`auto_init`**](#var-auto_init): *(Optional `bool`)* - - Set to `false` to not produce an initial commit in the repository. - - Default is `true`. - -- [**`gitignore_template`**](#var-gitignore_template): *(Optional `string`)* - - Use the name of the template without the extension. - - Default is `""`. - -- [**`license_template`**](#var-license_template): *(Optional `string`)* - - Use the name of the template without the extension. - - Default is `""`. - -- [**`template`**](#var-template): *(Optional `object(template)`)* - - Use a template repository to create this resource. - - Default is `{}`. - - The `template` object accepts the following attributes: - - - [**`owner`**](#attr-template-owner): *(**Required** `string`)* - - The GitHub organization or user the template repository is owned by. - - - [**`repository`**](#attr-template-repository): *(**Required** `string`)* - - The name of the template repository. - -#### Teams Configuration - +will not show a diff in plan or apply phase. + +- [**`auto_init`**](#var-auto_init): *(Optional `bool`)* + + Set to `false` to not produce an initial commit in the repository. + + Default is `true`. + +- [**`gitignore_template`**](#var-gitignore_template): *(Optional `string`)* + + Use the name of the template without the extension. + + Default is `""`. + +- [**`license_template`**](#var-license_template): *(Optional `string`)* + + Use the name of the template without the extension. + + Default is `""`. + +- [**`template`**](#var-template): *(Optional `object(template)`)* + + Use a template repository to create this resource. + + Default is `{}`. + + The `template` object accepts the following attributes: + + - [**`owner`**](#attr-template-owner): *(**Required** `string`)* + + The GitHub organization or user the template repository is owned by. + + - [**`repository`**](#attr-template-repository): *(**Required** `string`)* + + The name of the template repository. + +#### Teams Configuration + Your can use non-computed (known at `terraform plan`) team names or slugs (`*_teams` Attributes) or computed (only known in `terraform apply` phase) team IDs (`*_team_ids` Attributes). **When using non-computed names/slugs teams need to exist before running plan.** -This is due to some terraform limitation and we will update the module once terraform removed this limitation. - -- [**`pull_teams`**](#var-pull_teams): *(Optional `list(string)`)* - +This is due to some terraform limitation and we will update the module once terraform removed this limitation. + +- [**`pull_teams`**](#var-pull_teams): *(Optional `list(string)`)* + Can also be `pull_team_ids`. A list of teams to grant pull (read-only) permission. - Recommended for non-code contributors who want to view or discuss your project. - - Default is `[]`. - -- [**`triage_teams`**](#var-triage_teams): *(Optional `list(string)`)* - + Recommended for non-code contributors who want to view or discuss your project. + + Default is `[]`. + +- [**`triage_teams`**](#var-triage_teams): *(Optional `list(string)`)* + Can also be `triage_team_ids`. A list of teams to grant triage permission. Recommended for contributors who need to proactively manage issues and pull requests - without write access. - - Default is `[]`. - -- [**`push_teams`**](#var-push_teams): *(Optional `list(string)`)* - + without write access. + + Default is `[]`. + +- [**`push_teams`**](#var-push_teams): *(Optional `list(string)`)* + Can also be `push_team_ids`. A list of teams to grant push (read-write) permission. - Recommended for contributors who actively push to your project. - - Default is `[]`. - -- [**`maintain_teams`**](#var-maintain_teams): *(Optional `list(string)`)* - + Recommended for contributors who actively push to your project. + + Default is `[]`. + +- [**`maintain_teams`**](#var-maintain_teams): *(Optional `list(string)`)* + Can also be `maintain_team_ids`. A list of teams to grant maintain permission. - Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. - - Default is `[]`. - -- [**`admin_teams`**](#var-admin_teams): *(Optional `list(string)`)* - + Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. + + Default is `[]`. + +- [**`admin_teams`**](#var-admin_teams): *(Optional `list(string)`)* + Can also be `admin_team_ids`. A list of teams to grant admin (full) permission. - Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. - - Default is `[]`. - -#### Collaborator Configuration - -- [**`pull_collaborators`**](#var-pull_collaborators): *(Optional `list(string)`)* - + Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. + + Default is `[]`. + +#### Collaborator Configuration + +- [**`pull_collaborators`**](#var-pull_collaborators): *(Optional `list(string)`)* + A list of user names to add as collaborators granting them pull (read-only) permission. - Recommended for non-code contributors who want to view or discuss your project. - - Default is `[]`. - -- [**`triage_collaborators`**](#var-triage_collaborators): *(Optional `list(string)`)* - + Recommended for non-code contributors who want to view or discuss your project. + + Default is `[]`. + +- [**`triage_collaborators`**](#var-triage_collaborators): *(Optional `list(string)`)* + A list of user names to add as collaborators granting them triage permission. - Recommended for contributors who need to proactively manage issues and pull requests without write access. - - Default is `[]`. - -- [**`push_collaborators`**](#var-push_collaborators): *(Optional `list(string)`)* - + Recommended for contributors who need to proactively manage issues and pull requests without write access. + + Default is `[]`. + +- [**`push_collaborators`**](#var-push_collaborators): *(Optional `list(string)`)* + A list of user names to add as collaborators granting them push (read-write) permission. - Recommended for contributors who actively push to your project. - - Default is `[]`. - -- [**`maintain_collaborators`**](#var-maintain_collaborators): *(Optional `list(string)`)* - + Recommended for contributors who actively push to your project. + + Default is `[]`. + +- [**`maintain_collaborators`**](#var-maintain_collaborators): *(Optional `list(string)`)* + A list of user names to add as collaborators granting them maintain permission. - Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. - - Default is `[]`. - -- [**`admin_collaborators`**](#var-admin_collaborators): *(Optional `list(string)`)* - + Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. + + Default is `[]`. + +- [**`admin_collaborators`**](#var-admin_collaborators): *(Optional `list(string)`)* + A list of user names to add as collaborators granting them admin (full) permission. - Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. - - Default is `[]`. - -#### Branches Configuration - -- [**`branches`**](#var-branches): *(Optional `list(branch)`)* - + Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository. + + Default is `[]`. + +#### Branches Configuration + +- [**`branches`**](#var-branches): *(Optional `list(branch)`)* + Create and manage branches within your repository. - Additional constraints can be applied to ensure your branch is created from another branch or commit. - - Default is `[]`. - - Each `branch` object in the list accepts the following attributes: - - - [**`name`**](#attr-branches-name): *(**Required** `string`)* - - The name of the branch to create. - - - [**`source_branch`**](#attr-branches-source_branch): *(Optional `string`)* - - The branch name to start from. Uses the configured default branch per default. - - - [**`source_sha`**](#attr-branches-source_sha): *(Optional `bool`)* - - The commit hash to start from. Defaults to the tip of `source_branch`. If provided, `source_branch` is ignored. - - Default is `true`. - -#### Deploy Keys Configuration - -- [**`deploy_keys`**](#var-deploy_keys): *(Optional `list(deploy_key)`)* - + Additional constraints can be applied to ensure your branch is created from another branch or commit. + + Default is `[]`. + + Each `branch` object in the list accepts the following attributes: + + - [**`name`**](#attr-branches-name): *(**Required** `string`)* + + The name of the branch to create. + + - [**`source_branch`**](#attr-branches-source_branch): *(Optional `string`)* + + The branch name to start from. Uses the configured default branch per default. + + - [**`source_sha`**](#attr-branches-source_sha): *(Optional `bool`)* + + The commit hash to start from. Defaults to the tip of `source_branch`. If provided, `source_branch` is ignored. + + Default is `true`. + +#### Deploy Keys Configuration + +- [**`deploy_keys`**](#var-deploy_keys): *(Optional `list(deploy_key)`)* + Can also be type `list(string)`. Specifies deploy keys and access-level of deploy keys used in this repository. - Every `string` in the list will be converted internally into the `object` representation with the `key` argument being set to the `string`. `object` details are explained below. - - Default is `[]`. - - Each `deploy_key` object in the list accepts the following attributes: - - - [**`key`**](#attr-deploy_keys-key): *(**Required** `string`)* - - The SSH public key. - - - [**`title`**](#attr-deploy_keys-title): *(Optional `string`)* - + Every `string` in the list will be converted internally into the `object` representation with the `key` argument being set to the `string`. `object` details are explained below. + + Default is `[]`. + + Each `deploy_key` object in the list accepts the following attributes: + + - [**`key`**](#attr-deploy_keys-key): *(**Required** `string`)* + + The SSH public key. + + - [**`title`**](#attr-deploy_keys-title): *(Optional `string`)* + A Title for the key. - Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. - - - [**`read_only`**](#attr-deploy_keys-read_only): *(Optional `bool`)* - - Specifies the level of access for the key. - - Default is `true`. - - - [**`id`**](#attr-deploy_keys-id): *(Optional `string`)* - + Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. + + - [**`read_only`**](#attr-deploy_keys-read_only): *(Optional `bool`)* + + Specifies the level of access for the key. + + Default is `true`. + + - [**`id`**](#attr-deploy_keys-id): *(Optional `string`)* + Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. - The ID must be unique between `deploy_keys` and `deploy_keys_computed`. - - Default is `"md5(key)"`. - -- [**`deploy_keys_computed`**](#var-deploy_keys_computed): *(Optional `list(deploy_key)`)* - + The ID must be unique between `deploy_keys` and `deploy_keys_computed`. + + Default is `"md5(key)"`. + +- [**`deploy_keys_computed`**](#var-deploy_keys_computed): *(Optional `list(deploy_key)`)* + Can also be type `string`. Same as `deploy_keys` argument with the following differences: Use this argument if you depend on computed keys that terraform can not use in resource `for_each` execution. Downside of this is the recreation of deploy key resources whenever the order in the list changes. **Prefer `deploy_keys` whenever possible.** - This argument does **not** conflict with `deploy_keys` and should exclusively be used for computed resources. - - Default is `[]`. - - Each `deploy_key` object in the list accepts the following attributes: - - - [**`key`**](#attr-deploy_keys_computed-key): *(**Required** `string`)* - - The SSH public key. - - - [**`title`**](#attr-deploy_keys_computed-title): *(Optional `string`)* - + This argument does **not** conflict with `deploy_keys` and should exclusively be used for computed resources. + + Default is `[]`. + + Each `deploy_key` object in the list accepts the following attributes: + + - [**`key`**](#attr-deploy_keys_computed-key): *(**Required** `string`)* + + The SSH public key. + + - [**`title`**](#attr-deploy_keys_computed-title): *(Optional `string`)* + A Title for the key. - Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. - - - [**`read_only`**](#attr-deploy_keys_computed-read_only): *(Optional `bool`)* - - Specifies the level of access for the key. - - Default is `true`. - - - [**`id`**](#attr-deploy_keys_computed-id): *(Optional `string`)* - + Default is the comment field of SSH public key if it is not empty else it defaults to `md5(key)`. + + - [**`read_only`**](#attr-deploy_keys_computed-read_only): *(Optional `bool`)* + + Specifies the level of access for the key. + + Default is `true`. + + - [**`id`**](#attr-deploy_keys_computed-id): *(Optional `string`)* + Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. - The ID must be unique between `deploy_keys` and `deploy_keys_computed`. - - Default is `"md5(key)"`. - -#### Branch Protections v3 Configuration - -- [**`branch_protections_v3`**](#var-branch_protections_v3): *(Optional `list(branch_protection_v3)`)* - + The ID must be unique between `deploy_keys` and `deploy_keys_computed`. + + Default is `"md5(key)"`. + +#### Branch Protections v3 Configuration + +- [**`branch_protections_v3`**](#var-branch_protections_v3): *(Optional `list(branch_protection_v3)`)* + 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. - - Default is `[]`. - - Each `branch_protection_v3` object in the list accepts the following attributes: - - - [**`branch`**](#attr-branch_protections_v3-branch): *(**Required** `string`)* - - The Git branch to protect. - - - [**`enforce_admins`**](#attr-branch_protections_v3-enforce_admins): *(Optional `bool`)* - - Setting this to true enforces status checks for repository administrators. - - Default is `false`. - - - [**`require_conversation_resolution`**](#attr-branch_protections_v3-require_conversation_resolution): *(Optional `bool`)* - - Setting this to true requires all conversations to be resolved. - - Default is `false`. - - - [**`require_signed_commits`**](#attr-branch_protections_v3-require_signed_commits): *(Optional `bool`)* - - Setting this to true requires all commits to be signed with GPG. - - Default is `false`. - - - [**`required_status_checks`**](#attr-branch_protections_v3-required_status_checks): *(Optional `object(required_status_checks)`)* - + Additional constraints, such as required status checks or restrictions on users and teams, can also be configured. + + Default is `[]`. + + Each `branch_protection_v3` object in the list accepts the following attributes: + + - [**`branch`**](#attr-branch_protections_v3-branch): *(**Required** `string`)* + + The Git branch to protect. + + - [**`enforce_admins`**](#attr-branch_protections_v3-enforce_admins): *(Optional `bool`)* + + Setting this to true enforces status checks for repository administrators. + + Default is `false`. + + - [**`require_conversation_resolution`**](#attr-branch_protections_v3-require_conversation_resolution): *(Optional `bool`)* + + Setting this to true requires all conversations to be resolved. + + Default is `false`. + + - [**`require_signed_commits`**](#attr-branch_protections_v3-require_signed_commits): *(Optional `bool`)* + + Setting this to true requires all commits to be signed with GPG. + + Default is `false`. + + - [**`required_status_checks`**](#attr-branch_protections_v3-required_status_checks): *(Optional `object(required_status_checks)`)* + Enforce restrictions for required status checks. - See Required Status Checks below for details. - - Default is `{}`. - - The `required_status_checks` object accepts the following attributes: - - - [**`strict`**](#attr-branch_protections_v3-required_status_checks-strict): *(Optional `bool`)* - - Require branches to be up to date before merging. - - Default is `false`. - - - [**`contexts`**](#attr-branch_protections_v3-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 `[]`. - - - [**`required_pull_request_reviews`**](#attr-branch_protections_v3-required_pull_request_reviews): *(Optional `object(required_pull_request_reviews)`)* - - Enforce restrictions for pull request reviews. - - Default is `{}`. - - The `required_pull_request_reviews` object accepts the following attributes: - - - [**`dismiss_stale_reviews`**](#attr-branch_protections_v3-required_pull_request_reviews-dismiss_stale_reviews): *(Optional `bool`)* - - Dismiss approved reviews automatically when a new commit is pushed. - - Default is `true`. - - - [**`dismissal_users`**](#attr-branch_protections_v3-required_pull_request_reviews-dismissal_users): *(Optional `list(string)`)* - - The list of user logins with dismissal access - - Default is `[]`. - - - [**`dismissal_teams`**](#attr-branch_protections_v3-required_pull_request_reviews-dismissal_teams): *(Optional `list(string)`)* - + See Required Status Checks below for details. + + Default is `{}`. + + The `required_status_checks` object accepts the following attributes: + + - [**`strict`**](#attr-branch_protections_v3-required_status_checks-strict): *(Optional `bool`)* + + Require branches to be up to date before merging. + + Default is `false`. + + - [**`contexts`**](#attr-branch_protections_v3-required_status_checks-contexts): *(Optional `list(string)`)* + + **_DEPRECATED_**: Use `checks` instead. The list of status checks to require in order to merge into this branch. If default is `[]` no status checks are required. + + Default is `[]`. + + - [**`checks`**](#attr-branch_protections_v3-required_status_checks-checks): *(Optional `list(string)`)* + + The list of status checks to require in order to merge into this branch. + Checks should be strings containing the context and app_id like so "context:app_id". If default is `[]` no status checks are required. + + Default is `[]`. + + - [**`required_pull_request_reviews`**](#attr-branch_protections_v3-required_pull_request_reviews): *(Optional `object(required_pull_request_reviews)`)* + + Enforce restrictions for pull request reviews. + + Default is `{}`. + + The `required_pull_request_reviews` object accepts the following attributes: + + - [**`dismiss_stale_reviews`**](#attr-branch_protections_v3-required_pull_request_reviews-dismiss_stale_reviews): *(Optional `bool`)* + + Dismiss approved reviews automatically when a new commit is pushed. + + Default is `true`. + + - [**`dismissal_users`**](#attr-branch_protections_v3-required_pull_request_reviews-dismissal_users): *(Optional `list(string)`)* + + The list of user logins with dismissal access + + Default is `[]`. + + - [**`dismissal_teams`**](#attr-branch_protections_v3-required_pull_request_reviews-dismissal_teams): *(Optional `list(string)`)* + The list of team slugs with dismissal access. Always use slug of the team, not its name. - Each team already has to have access to the repository. - - Default is `[]`. - - - [**`require_code_owner_reviews`**](#attr-branch_protections_v3-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`. - - - [**`restrictions`**](#attr-branch_protections_v3-restrictions): *(Optional `object(restrictions)`)* - - Enforce restrictions for the users and teams that may push to the branch - only available for organization-owned repositories. See Restrictions below for details. - - Default is `{}`. - - The `restrictions` object accepts the following attributes: - - - [**`users`**](#attr-branch_protections_v3-restrictions-users): *(Optional `list(string)`)* - - The list of user logins with push access. - - Default is `[]`. - - - [**`teams`**](#attr-branch_protections_v3-restrictions-teams): *(Optional `list(string)`)* - + Each team already has to have access to the repository. + + Default is `[]`. + + - [**`require_code_owner_reviews`**](#attr-branch_protections_v3-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`. + + - [**`restrictions`**](#attr-branch_protections_v3-restrictions): *(Optional `object(restrictions)`)* + + Enforce restrictions for the users and teams that may push to the branch - only available for organization-owned repositories. See Restrictions below for details. + + Default is `{}`. + + The `restrictions` object accepts the following attributes: + + - [**`users`**](#attr-branch_protections_v3-restrictions-users): *(Optional `list(string)`)* + + The list of user logins with push access. + + Default is `[]`. + + - [**`teams`**](#attr-branch_protections_v3-restrictions-teams): *(Optional `list(string)`)* + The list of team slugs with push access. Always use slug of the team, not its name. - Each team already has to have access to the repository. - - Default is `[]`. - - - [**`apps`**](#attr-branch_protections_v3-restrictions-apps): *(Optional `list(string)`)* - - The list of app slugs with push access. - - Default is `[]`. - -#### Branch Protections v4 Configuration - -- [**`branch_protections_v4`**](#var-branch_protections_v4): *(Optional `list(branch_protection_v4)`)* - + Each team already has to have access to the repository. + + Default is `[]`. + + - [**`apps`**](#attr-branch_protections_v3-restrictions-apps): *(Optional `list(string)`)* + + The list of app slugs with push access. + + Default is `[]`. + +#### Branch Protections v4 Configuration + +- [**`branch_protections_v4`**](#var-branch_protections_v4): *(Optional `list(branch_protection_v4)`)* + This resource allows you to configure v4 branch protection for repositories in your organization. - + Each element in the list 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:_** May conflict with v3 branch protections if used for the same branch. - - Default is `[]`. - - Each `branch_protection_v4` object in the list accepts the following attributes: - - - [**`pattern`**](#attr-branch_protections_v4-pattern): *(**Required** `string`)* - - Identifies the protection rule pattern. - - - [**`_key`**](#attr-branch_protections_v4-_key): *(Optional `string`)* - + + **_NOTE:_** May conflict with v3 branch protections if used for the same branch. + + Default is `[]`. + + Each `branch_protection_v4` object in the list accepts the following attributes: + + - [**`pattern`**](#attr-branch_protections_v4-pattern): *(**Required** `string`)* + + Identifies the protection rule pattern. + + - [**`_key`**](#attr-branch_protections_v4-_key): *(Optional `string`)* + An alternative key to use in `for_each` resource creation. - Defaults to the value of `var.pattern`. - - - [**`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`)* - - Keeping this as `true` enforces status checks for repository administrators. - - Default is `true`. - - - [**`push_restrictions`**](#attr-branch_protections_v4-push_restrictions): *(Optional `list(string)`)* - + Defaults to the value of `var.pattern`. + + - [**`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`)* + + Keeping this as `true` enforces status checks for repository administrators. + + Default is `true`. + + - [**`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. - - 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`. - - - [**`restrict_dismissals`**](#attr-branch_protections_v4-required_pull_request_reviews-restrict_dismissals): *(Optional `bool`)* - - Restrict pull request review dismissals. - - - [**`dismissal_restrictions`**](#attr-branch_protections_v4-required_pull_request_reviews-dismissal_restrictions): *(Optional `list(string)`)* - + 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. + + 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`. + + - [**`restrict_dismissals`**](#attr-branch_protections_v4-required_pull_request_reviews-restrict_dismissals): *(Optional `bool`)* + + Restrict pull request review dismissals. + + - [**`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)`)* - + 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 `true`. - - - [**`required_approving_review_count`**](#attr-branch_protections_v4-required_pull_request_reviews-required_approving_review_count): *(Optional `number`)* - + 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 `true`. + + - [**`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)`)* - + 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. - - 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)`)* - + See Required Status Checks below for details. + + 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)`)* + This resource allows you to create and manage issue labels within your GitHub organization. Issue labels are keyed off of their "name", so pre-existing issue labels result in a 422 HTTP error if they exist outside of Terraform. Normally this would not be an issue, except new repositories are created with a "default" set of labels, and those labels easily conflict with custom ones. - This resource will first check if the label exists, and then issue an update, otherwise it will create. - - Default is `[]`. - - Each `issue_label` object in the list accepts the following attributes: - - - [**`name`**](#attr-issue_labels-name): *(**Required** `string`)* - - The name of the label. - - - [**`color`**](#attr-issue_labels-color): *(**Required** `string`)* - - A 6 character hex code, without the leading `#`, identifying the color of the label. - - - [**`description`**](#attr-issue_labels-description): *(Optional `string`)* - - A short description of the label. - - Default is `""`. - - - [**`id`**](#attr-issue_labels-id): *(Optional `string`)* - - Specifies an ID which is used to prevent resource recreation when the order in the list of issue labels changes. - - Default is `"name"`. - -- [**`issue_labels_merge_with_github_labels`**](#var-issue_labels_merge_with_github_labels): *(Optional `bool`)* - - Specify if github default labels will be handled by terraform. This should be decided on upon creation of the repository. If you later decide to disable this feature, github default labels will be destroyed if not replaced by labels set in `issue_labels` argument. - -- [**`issue_labels_create`**](#var-issue_labels_create): *(Optional `bool`)* - + This resource will first check if the label exists, and then issue an update, otherwise it will create. + + Default is `[]`. + + Each `issue_label` object in the list accepts the following attributes: + + - [**`name`**](#attr-issue_labels-name): *(**Required** `string`)* + + The name of the label. + + - [**`color`**](#attr-issue_labels-color): *(**Required** `string`)* + + A 6 character hex code, without the leading `#`, identifying the color of the label. + + - [**`description`**](#attr-issue_labels-description): *(Optional `string`)* + + A short description of the label. + + Default is `""`. + + - [**`id`**](#attr-issue_labels-id): *(Optional `string`)* + + Specifies an ID which is used to prevent resource recreation when the order in the list of issue labels changes. + + Default is `"name"`. + +- [**`issue_labels_merge_with_github_labels`**](#var-issue_labels_merge_with_github_labels): *(Optional `bool`)* + + Specify if github default labels will be handled by terraform. This should be decided on upon creation of the repository. If you later decide to disable this feature, github default labels will be destroyed if not replaced by labels set in `issue_labels` argument. + +- [**`issue_labels_create`**](#var-issue_labels_create): *(Optional `bool`)* + Specify whether you want to force or suppress the creation of issues labels. - Default is `true` if `has_issues` is `true` or `issue_labels` is non-empty. - -#### Projects Configuration - -- [**`projects`**](#var-projects): *(Optional `list(project)`)* - - This resource allows you to create and manage projects for GitHub repository. - - Default is `[]`. - - Each `project` object in the list accepts the following attributes: - - - [**`name`**](#attr-projects-name): *(**Required** `string`)* - - The name of the project. - - - [**`body`**](#attr-projects-body): *(Optional `string`)* - - The body of the project. - - Default is `""`. - - - [**`id`**](#attr-projects-id): *(Optional `string`)* - - Specifies an ID which is used to prevent resource recreation when the order in the list of projects changes. - - Default is `"name"`. - -#### Webhooks Configuration - -- [**`webhooks`**](#var-webhooks): *(Optional `list(webhook)`)* - + Default is `true` if `has_issues` is `true` or `issue_labels` is non-empty. + +#### Projects Configuration + +- [**`projects`**](#var-projects): *(Optional `list(project)`)* + + This resource allows you to create and manage projects for GitHub repository. + + Default is `[]`. + + Each `project` object in the list accepts the following attributes: + + - [**`name`**](#attr-projects-name): *(**Required** `string`)* + + The name of the project. + + - [**`body`**](#attr-projects-body): *(Optional `string`)* + + The body of the project. + + Default is `""`. + + - [**`id`**](#attr-projects-id): *(Optional `string`)* + + Specifies an ID which is used to prevent resource recreation when the order in the list of projects changes. + + Default is `"name"`. + +#### Webhooks Configuration + +- [**`webhooks`**](#var-webhooks): *(Optional `list(webhook)`)* + This resource allows you to create and manage webhooks for repositories in your organization. - When applied, a webhook will be created which specifies a URL to receive events and which events to receieve. Additional constraints, such as SSL verification, pre-shared secret and content type can also be configured - - Default is `[]`. - - Each `webhook` object in the list accepts the following attributes: - - - [**`events`**](#attr-webhooks-events): *(**Required** `list(string)`)* - - A list of events which should trigger the webhook. [See a list of available events.](https://developer.github.com/v3/activity/events/types/) - - - [**`url`**](#attr-webhooks-url): *(**Required** `string`)* - - The URL to which the payloads will be delivered. - - - [**`active`**](#attr-webhooks-active): *(Optional `bool`)* - - Indicate if the webhook should receive events. Defaults to `true`. - - - [**`content_type`**](#attr-webhooks-content_type): *(Optional `string`)* - - The media type used to serialize the payloads. Supported values include `json` and `form`. - - Default is `"form"`. - - - [**`secret`**](#attr-webhooks-secret): *(Optional `string`)* - - If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value in the [X-Hub-Signature](https://developer.github.com/webhooks/#delivery-headers) header. - - - [**`insecure_ssl`**](#attr-webhooks-insecure_ssl): *(Optional `bool`)* - - Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. **We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.** - -#### Secrets Configuration - -- [**`plaintext_secrets`**](#var-plaintext_secrets): *(Optional `map(string)`)* - + When applied, a webhook will be created which specifies a URL to receive events and which events to receieve. Additional constraints, such as SSL verification, pre-shared secret and content type can also be configured + + Default is `[]`. + + Each `webhook` object in the list accepts the following attributes: + + - [**`events`**](#attr-webhooks-events): *(**Required** `list(string)`)* + + A list of events which should trigger the webhook. [See a list of available events.](https://developer.github.com/v3/activity/events/types/) + + - [**`url`**](#attr-webhooks-url): *(**Required** `string`)* + + The URL to which the payloads will be delivered. + + - [**`active`**](#attr-webhooks-active): *(Optional `bool`)* + + Indicate if the webhook should receive events. Defaults to `true`. + + - [**`content_type`**](#attr-webhooks-content_type): *(Optional `string`)* + + The media type used to serialize the payloads. Supported values include `json` and `form`. + + Default is `"form"`. + + - [**`secret`**](#attr-webhooks-secret): *(Optional `string`)* + + If provided, the `secret` will be used as the `key` to generate the HMAC hex digest value in the [X-Hub-Signature](https://developer.github.com/webhooks/#delivery-headers) header. + + - [**`insecure_ssl`**](#attr-webhooks-insecure_ssl): *(Optional `bool`)* + + Determines whether the SSL certificate of the host for `url` will be verified when delivering payloads. Supported values include `0` (verification is performed) and `1` (verification is not performed). The default is `0`. **We strongly recommend not setting this to `1` as you are subject to man-in-the-middle and other attacks.** + +#### Secrets Configuration + +- [**`plaintext_secrets`**](#var-plaintext_secrets): *(Optional `map(string)`)* + This map allows you to create and manage secrets for repositories in your organization. - + Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding secret in plain text: - + When applied, a secret with the given key and value will be created in the repositories. - + The value of the secrets must be given in plain text, GitHub provider is in charge of encrypting it. - - **Attention:** You should treat state as sensitive always. It is also advised that you do not store plaintext values in your code but rather populate the encrypted_value using fields from a resource, data source or variable as, while encrypted in state, these will be easily accessible in your code. See below for an example of this abstraction. - - Default is `{}`. - - Example: - - ```hcl + + **Attention:** You should treat state as sensitive always. It is also advised that you do not store plaintext values in your code but rather populate the encrypted_value using fields from a resource, data source or variable as, while encrypted in state, these will be easily accessible in your code. See below for an example of this abstraction. + + Default is `{}`. + + Example: + + ```hcl plaintext_secrets = { SECRET_NAME_1 = "plaintext_secret_value_1" SECRET_NAME_2 = "plaintext_secret_value_2" - } - ``` - -- [**`encrypted_secrets`**](#var-encrypted_secrets): *(Optional `map(string)`)* - + } + ``` + +- [**`encrypted_secrets`**](#var-encrypted_secrets): *(Optional `map(string)`)* + This map allows you to create and manage encrypted secrets for repositories in your organization. - + Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding encrypted value of the secret using the Github public key in Base64 format.b - - When applied, a secret with the given key and value will be created in the repositories. - - Default is `{}`. - - Example: - - ```hcl + + When applied, a secret with the given key and value will be created in the repositories. + + Default is `{}`. + + Example: + + ```hcl encrypted_secrets = { SECRET_NAME_1 = "c2VjcmV0X3ZhbHVlXzE=" SECRET_NAME_2 = "c2VjcmV0X3ZhbHVlXzI=" - } - ``` - -- [**`required_approving_review_count`**](#var-required_approving_review_count): *(Optional `number`)* - + } + ``` + +- [**`required_approving_review_count`**](#var-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 1-6. This requirement matches Github's API, see the upstream documentation for more information. - Default is no approving reviews are required. - -#### Autolink References Configuration - -- [**`autolink_references`**](#var-autolink_references): *(Optional `list(autolink_reference)`)* - - This resource allows you to create and manage autolink references for GitHub repository. - - Default is `[]`. - - Each `autolink_reference` object in the list accepts the following attributes: - - - [**`key_prefix`**](#attr-autolink_references-key_prefix): *(**Required** `string`)* - - This prefix appended by a number will generate a link any time it is found in an issue, pull request, or commit. - - - [**`target_url_template`**](#attr-autolink_references-target_url_template): *(**Required** `string`)* - - The template of the target URL used for the links; must be a valid URL and contain `` for the reference number. - -#### App Installations - -- [**`app_installations`**](#var-app_installations): *(Optional `set(string)`)* - - A set of GitHub App IDs to be installed in this repository. - - Default is `{}`. - - Example: - - ```hcl - app_installations = ["05405144", "12556423"] - ``` - -### Module Configuration - -- [**`module_depends_on`**](#var-module_depends_on): *(Optional `list(dependency)`)* - + Default is no approving reviews are required. + +#### Autolink References Configuration + +- [**`autolink_references`**](#var-autolink_references): *(Optional `list(autolink_reference)`)* + + This resource allows you to create and manage autolink references for GitHub repository. + + Default is `[]`. + + Each `autolink_reference` object in the list accepts the following attributes: + + - [**`key_prefix`**](#attr-autolink_references-key_prefix): *(**Required** `string`)* + + This prefix appended by a number will generate a link any time it is found in an issue, pull request, or commit. + + - [**`target_url_template`**](#attr-autolink_references-target_url_template): *(**Required** `string`)* + + The template of the target URL used for the links; must be a valid URL and contain `` for the reference number. + +#### App Installations + +- [**`app_installations`**](#var-app_installations): *(Optional `set(string)`)* + + A set of GitHub App IDs to be installed in this repository. + + Default is `{}`. + + Example: + + ```hcl + app_installations = ["05405144", "12556423"] + ``` + +### Module Configuration + +- [**`module_depends_on`**](#var-module_depends_on): *(Optional `list(dependency)`)* + Due to the fact, that terraform does not offer `depends_on` on modules as of today (v0.12.24) we might hit race conditions when dealing with team names instead of ids. So when using the feature of [adding teams by slug/name](#teams-configuration) to the repository when creating it, - make sure to add all teams to this list as indirect dependencies. - - Default is `[]`. - -## Module Outputs - -The following attributes are exported by the module: - -- [**`repository`**](#output-repository): *(`object(repository)`)* - + make sure to add all teams to this list as indirect dependencies. + + Default is `[]`. + +## Module Outputs + +The following attributes are exported by the module: + +- [**`repository`**](#output-repository): *(`object(repository)`)* + All repository attributes as returned by the [`github_repository`] resource containing all arguments as specified above and the other - attributes as specified below. - -- [**`branches`**](#output-branches): *(`object(branches)`)* - + attributes as specified below. + +- [**`branches`**](#output-branches): *(`object(branches)`)* + All repository attributes as returned by the [`github_branch`] resource containing all arguments as specified above and the other - attributes as specified below. - -- [**`full_name`**](#output-full_name): *(`string`)* - - A string of the form "orgname/reponame". - -- [**`html_url`**](#output-html_url): *(`string`)* - - URL to the repository on the web. - -- [**`ssh_clone_url`**](#output-ssh_clone_url): *(`string`)* - - URL that can be provided to git clone to clone the repository via SSH. - -- [**`http_clone_url`**](#output-http_clone_url): *(`string`)* - - URL that can be provided to git clone to clone the repository via HTTPS. - -- [**`git_clone_url`**](#output-git_clone_url): *(`string`)* - + attributes as specified below. + +- [**`full_name`**](#output-full_name): *(`string`)* + + A string of the form "orgname/reponame". + +- [**`html_url`**](#output-html_url): *(`string`)* + + URL to the repository on the web. + +- [**`ssh_clone_url`**](#output-ssh_clone_url): *(`string`)* + + URL that can be provided to git clone to clone the repository via SSH. + +- [**`http_clone_url`**](#output-http_clone_url): *(`string`)* + + URL that can be provided to git clone to clone the repository via HTTPS. + +- [**`git_clone_url`**](#output-git_clone_url): *(`string`)* + URL that can be provided to git clone to clone the repository - anonymously via the git protocol. - -- [**`collaborators`**](#output-collaborators): *(`object(collaborators)`)* - + anonymously via the git protocol. + +- [**`collaborators`**](#output-collaborators): *(`object(collaborators)`)* + A map of Collaborator objects keyed by the `name` of the collaborator as - returned by the [`github_repository_collaborator`] resource. - -- [**`deploy_keys`**](#output-deploy_keys): *(`object(deploy_keys)`)* - + returned by the [`github_repository_collaborator`] resource. + +- [**`deploy_keys`**](#output-deploy_keys): *(`object(deploy_keys)`)* + A merged map of deploy key objects for the keys originally passed via `deploy_keys` and `deploy_keys_computed` as returned by the [`github_repository_deploy_key`] resource keyed by the input `id` of the - key. - -- [**`projects`**](#output-projects): *(`object(project)`)* - + key. + +- [**`projects`**](#output-projects): *(`object(project)`)* + A map of Project objects keyed by the `id` of the project as returned by - the [`github_repository_project`] resource - -- [**`issue_labels`**](#output-issue_labels): *(`object(issue_label)`)* - - A map of issue labels keyed by label input id or name. - -- [**`webhooks`**](#output-webhooks): *(`object(webhook)`)* - + the [`github_repository_project`] resource + +- [**`issue_labels`**](#output-issue_labels): *(`object(issue_label)`)* + + A map of issue labels keyed by label input id or name. + +- [**`webhooks`**](#output-webhooks): *(`object(webhook)`)* + All attributes and arguments as returned by the - `github_repository_webhook` resource. - -- [**`secrets`**](#output-secrets): *(`object(secret)`)* - - List of secrets available. - -- [**`app_installations`**](#output-app_installations): *(`set(number)`)* - - A map of deploy app installations keyed by installation id. - -## External Documentation - -### Terraform Github Provider Documentation - + `github_repository_webhook` resource. + +- [**`secrets`**](#output-secrets): *(`object(secret)`)* + + List of secrets available. + +- [**`app_installations`**](#output-app_installations): *(`set(number)`)* + + A map of deploy app installations keyed by installation id. + +## External Documentation + +### Terraform Github Provider Documentation + - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/branch - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_collaborator - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_deploy_key - https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_project -- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_autolink_reference - -## Module Versioning - +- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_autolink_reference + +## Module Versioning + This Module follows the principles of [Semantic Versioning (SemVer)]. Given a version number `MAJOR.MINOR.PATCH`, we increment the: 1. `MAJOR` version when we make incompatible changes, 2. `MINOR` version when we add functionality in a backwards compatible manner, and -3. `PATCH` version when we make backwards compatible bug fixes. - -### Backwards compatibility in `0.0.z` and `0.y.z` version - +3. `PATCH` version when we make backwards compatible bug fixes. + +### Backwards compatibility in `0.0.z` and `0.y.z` version + - Backwards compatibility in versions `0.0.z` is **not guaranteed** when `z` is increased. (Initial development) -- Backwards compatibility in versions `0.y.z` is **not guaranteed** when `y` is increased. (Pre-release) - -## About Mineiros - +- Backwards compatibility in versions `0.y.z` is **not guaranteed** when `y` is increased. (Pre-release) + +## About Mineiros + [Mineiros][homepage] is a remote-first company headquartered in Berlin, Germany that solves development, automation and security challenges in cloud infrastructure. @@ -1056,62 +1062,62 @@ deploy production-grade and secure cloud infrastructure. We offer commercial support for all of our modules and encourage you to reach out if you have any questions or need help. Feel free to email us at [hello@mineiros.io] or join our -[Community Slack channel][slack]. - -## Reporting Issues - -We use GitHub [Issues] to track community reported issues and missing features. - -## Contributing - +[Community Slack channel][slack]. + +## Reporting Issues + +We use GitHub [Issues] to track community reported issues and missing features. + +## Contributing + Contributions are always encouraged and welcome! For the process of accepting changes, we use -[Pull Requests]. If you'd like more information, please see our [Contribution Guidelines]. - -## Makefile Targets - +[Pull Requests]. If you'd like more information, please see our [Contribution Guidelines]. + +## Makefile Targets + This repository comes with a handy [Makefile]. -Run `make help` to see details on each available target. - -## License - +Run `make help` to see details on each available target. + +## License + [![license][badge-license]][apache20] This module is licensed under the Apache License Version 2.0, January 2004. Please see [LICENSE] for full details. -Copyright © 2020-2022 [Mineiros GmbH][homepage] - - - - -[github]: https://github.com/ -[`github_repository`]: https://www.terraform.io/docs/providers/github/r/repository.html#attributes-reference -[`github_repository_collaborator`]: https://www.terraform.io/docs/providers/github/r/repository_collaborator.html#attribute-reference -[`github_repository_deploy_key`]: https://www.terraform.io/docs/providers/github/r/repository_deploy_key.html#attributes-reference -[`github_repository_project`]: https://www.terraform.io/docs/providers/github/r/repository_project.html#attributes-reference -[`github_repository_autolink_reference`]: https://www.terraform.io/docs/providers/github/r/repository_autolink_reference.html#attributes-reference -[homepage]: https://mineiros.io/?ref=terraform-github-repository -[github-as-code]: https://mineiros.io/github-as-code?ref=terraform-github-repository -[hello@mineiros.io]: mailto:hello@mineiros.io -[badge-build]: https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg -[badge-semver]: https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver -[badge-license]: https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg -[badge-terraform]: https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform -[badge-slack]: https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack -[badge-tf-gh]: https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform -[releases-github-provider]: https://github.com/terraform-providers/terraform-provider-github/releases -[build-status]: https://github.com/mineiros-io/terraform-github-repository/actions -[releases-github]: https://github.com/mineiros-io/terraform-github-repository/releases -[releases-terraform]: https://github.com/hashicorp/terraform/releases -[apache20]: https://opensource.org/licenses/Apache-2.0 -[slack]: https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg -[terraform]: https://www.terraform.io -[aws]: https://aws.amazon.com/ -[semantic versioning (semver)]: https://semver.org/ -[variables.tf]: https://github.com/mineiros-io/terraform-github-repository/blob/main/variables.tf -[examples/]: https://github.com/mineiros-io/terraform-github-repository/blob/main/examples -[issues]: https://github.com/mineiros-io/terraform-github-repository/issues -[license]: https://github.com/mineiros-io/terraform-github-repository/blob/main/LICENSE -[makefile]: https://github.com/mineiros-io/terraform-github-repository/blob/main/Makefile -[pull requests]: https://github.com/mineiros-io/terraform-github-repository/pulls -[contribution guidelines]: https://github.com/mineiros-io/terraform-github-repository/blob/main/CONTRIBUTING.md +Copyright © 2020-2022 [Mineiros GmbH][homepage] + + + + +[github]: https://github.com/ +[`github_repository`]: https://www.terraform.io/docs/providers/github/r/repository.html#attributes-reference +[`github_repository_collaborator`]: https://www.terraform.io/docs/providers/github/r/repository_collaborator.html#attribute-reference +[`github_repository_deploy_key`]: https://www.terraform.io/docs/providers/github/r/repository_deploy_key.html#attributes-reference +[`github_repository_project`]: https://www.terraform.io/docs/providers/github/r/repository_project.html#attributes-reference +[`github_repository_autolink_reference`]: https://www.terraform.io/docs/providers/github/r/repository_autolink_reference.html#attributes-reference +[homepage]: https://mineiros.io/?ref=terraform-github-repository +[github-as-code]: https://mineiros.io/github-as-code?ref=terraform-github-repository +[hello@mineiros.io]: mailto:hello@mineiros.io +[badge-build]: https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg +[badge-semver]: https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver +[badge-license]: https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg +[badge-terraform]: https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform +[badge-slack]: https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack +[badge-tf-gh]: https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform +[releases-github-provider]: https://github.com/terraform-providers/terraform-provider-github/releases +[build-status]: https://github.com/mineiros-io/terraform-github-repository/actions +[releases-github]: https://github.com/mineiros-io/terraform-github-repository/releases +[releases-terraform]: https://github.com/hashicorp/terraform/releases +[apache20]: https://opensource.org/licenses/Apache-2.0 +[slack]: https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg +[terraform]: https://www.terraform.io +[aws]: https://aws.amazon.com/ +[semantic versioning (semver)]: https://semver.org/ +[variables.tf]: https://github.com/mineiros-io/terraform-github-repository/blob/main/variables.tf +[examples/]: https://github.com/mineiros-io/terraform-github-repository/blob/main/examples +[issues]: https://github.com/mineiros-io/terraform-github-repository/issues +[license]: https://github.com/mineiros-io/terraform-github-repository/blob/main/LICENSE +[makefile]: https://github.com/mineiros-io/terraform-github-repository/blob/main/Makefile +[pull requests]: https://github.com/mineiros-io/terraform-github-repository/pulls +[contribution guidelines]: https://github.com/mineiros-io/terraform-github-repository/blob/main/CONTRIBUTING.md diff --git a/README.tfdoc.hcl b/README.tfdoc.hcl index 3b9c069..4a39d46 100644 --- a/README.tfdoc.hcl +++ b/README.tfdoc.hcl @@ -705,7 +705,16 @@ section { 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. + **_DEPRECATED_**: Use `checks` instead. The list of status checks to require in order to merge into this branch. If default is `[]` no status checks are required. + END + } + + attribute "checks" { + type = list(string) + default = [] + description = <<-END + The list of status checks to require in order to merge into this branch. + Checks should be strings containing the context and app_id like so "context:app_id". If default is `[]` no status checks are required. END } }