terraform-github-repository

A Terraform module for creating a public or private repository on Github.

This module supports Terraform >=v1.3 and is compatible with the Official Terraform GitHub Provider v6.2 and above from integrations/github.

• terraform-github-repository
  • Module Features
  • Getting Started
  • Module Argument Reference
  • Main Resource Configuration
    • Requirements
    • Providers
    • Resources
    • Inputs
    • Outputs
    • Security And Analysis Configuration
  • External Documentation
    • Terraform Github Provider Documentation
  • Module Versioning
  • Reporting Issues
  • Contributing
  • Attribution
  • License

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, Rulesets, Repository Webhooks, GitHub App Installations

• Features not yet implemented: Project Columns support, Actions, Repository File

Getting Started

Most basic usage creating a new private github repository.

module "repository" {
  source  = "gaima8/repository/github"
  version = "~> 0.19.2"

  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

Requirements

Name	Version
terraform	>= 1.3
github	>= 6.2, < 6.9

Providers

Name	Version
github	>= 6.2, < 6.9

Resources

Name	Type
github_actions_environment_variable.this	resource
github_actions_secret.repository_secret	resource
github_actions_variable.repository_variable	resource
github_app_installation_repository.app_installation_repository	resource
github_branch.branch	resource
github_branch_default.default	resource
github_branch_protection.branch_protection	resource
github_branch_protection_v3.branch_protection	resource
github_issue_label.label	resource
github_repository.repository	resource
github_repository_autolink_reference.repository_autolink_reference	resource
github_repository_collaborator.collaborator	resource
github_repository_deploy_key.deploy_key	resource
github_repository_deploy_key.deploy_key_computed	resource
github_repository_deployment_branch_policy.this	resource
github_repository_environment.this	resource
github_repository_ruleset.ruleset	resource
github_repository_webhook.repository_webhook	resource
github_team_repository.team_repository	resource
github_team_repository.team_repository_by_slug	resource
github_organization_teams.all	data source
github_user.user	data source

Inputs

Name	Description	Type	Default	Required
admin_collaborators	(Optional) A list of users to add as collaborators granting them admin (full) permission.	list(string)	[]	no
admin_team_ids	(Optional) A list of teams (by id) to grant admin (full) permission to.	list(string)	[]	no
admin_teams	(Optional) A list of teams (by name/slug) to grant admin (full) permission to.	list(string)	[]	no
allow_auto_merge	(Optional) Set to true to allow auto-merging pull requests on the repository. If enabled for a pull request, the pull request will merge automatically when all required reviews are met and status checks have passed. (Default: false)	bool	null	no
allow_merge_commit	(Optional) Set to false to disable merge commits on the repository. (Default: true)	bool	null	no
allow_rebase_merge	(Optional) Set to true to enable rebase merges on the repository. (Default: false)	bool	null	no
allow_squash_merge	(Optional) Set to true to enable squash merges on the repository. (Default: false)	bool	null	no
allow_update_branch	(Optional) Set to true to suggest updating pull request branches. (Default: false)	bool	null	no
app_installations	(Optional) A list of GitHub App IDs to be installed in this repository.	set(string)	[]	no
archive_on_destroy	(Optional) Set to false to not archive the repository instead of deleting on destroy.	string	true	no
archived	(Optional) Specifies if the repository should be archived. (Default: false)	bool	false	no
auto_init	(Optional) Wether or not to produce an initial commit in the repository. (Default: true)	bool	null	no
autolink_references	(Optional) Configuring autolink references. For details please check: https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_autolink_reference	list(object({ key_prefix = string target_url_template = string }))	[]	no
branch_protections_v3	(Optional) A list of branch protections to apply to the repository. Default is [] unless branch_protections is set.	any	[]	no
branch_protections_v4	(Optional) A list of v4 branch protections to apply to the repository. Default is [].	any	[]	no
branches	(Optional) A list of branches to be created in this repository.	any	[]	no
default_branch	(Optional) The name of the default branch of the repository. NOTE: This can only be set after a repository has already been created, and after a correct reference has been created for the target branch inside the repository. This means a user will have to omit this parameter from the initial repository creation and create the target branch inside of the repository prior to setting this attribute.	string	null	no
defaults	(Deprecated) DEPRECATED. Please convert defaults to Terraform Module for_each	any	{}	no
delete_branch_on_merge	(Optional) Whether or not to delete the merged branch after merging a pull request. (Default: false)	bool	null	no
deploy_keys	(Optional) Configure a deploy key ( SSH key ) that grants access to a single GitHub repository. This key is attached directly to the repository instead of to a personal user account.	any	[]	no
deploy_keys_computed	(Optional) Configure a deploy key ( SSH key ) that grants access to a single GitHub repository. This key is attached directly to the repository instead of to a personal user account.	any	[]	no
description	(Optional) A description of the repository.	string	""	no
encrypted_secrets	(Optional) Configuring encrypted actions secrets. For details please check: https://www.terraform.io/docs/providers/github/r/actions_secret	map(string)	{}	no
environments	n/a	map(object({ reviewer_teams = optional(list(string), []) reviewer_users = optional(list(string), []) deployment_branch_policy = optional(object({ protected_branches = bool custom_branch_policies = optional(bool) })) branch_patterns = optional(list(string), []) variables = optional(map(string), {}) wait_timer = optional(number) prevent_self_review = optional(bool) }))	{}	no
extra_topics	(Optional) The list of additional topics of the repository. (Default: [])	list(string)	[]	no
gitignore_template	(Optional) Use the name of the template without the extension. For example, Haskell. Available templates: https://github.com/github/gitignore	string	null	no
has_downloads	(Optional) Set to true to enable the (deprecated) downloads features on the repository. (Default: false)	bool	null	no
has_issues	(Optional) Set to true to enable the GitHub Issues features on the repository. (Default: false)	bool	null	no
has_wiki	(Optional) Set to true to enable the GitHub Wiki features on the repository. (Default: false)	bool	null	no
homepage_url	(Optional) The website of the repository.	string	null	no
is_template	(Optional) Whether or not to tell GitHub that this is a template repository. ( Default: false)	bool	null	no
issue_labels	(Optional) Configure a GitHub issue label resource.	list(object({ name = string description = string color = string }))	[]	no
issue_labels_create	(Optional) Specify whether you want to force or suppress the creation of issues labels.	bool	null	no
issue_labels_merge_with_github_labels	(Optional) Specify if you want to merge and control githubs default set of issue labels.	bool	null	no
license_template	(Optional) Use the name of the template without the extension. For example, 'mit' or 'mpl-2.0'. Available licences: https://github.com/github/choosealicense.com/tree/gh-pages/_licenses	string	null	no
maintain_collaborators	(Optional) A list of users to add as collaborators granting them maintain permission.	list(string)	[]	no
maintain_team_ids	(Optional) A list of teams (by id) to grant maintain permission to.	list(string)	[]	no
maintain_teams	(Optional) A list of teams (by name/slug) to grant maintain permission to.	list(string)	[]	no
merge_commit_message	(Optional) Can be PR_BODY, PR_TITLE, or BLANK for a default merge commit message.	string	"PR_TITLE"	no
merge_commit_title	(Optional) Can be PR_TITLE or MERGE_MESSAGE for a default merge commit title.	string	"MERGE_MESSAGE"	no
module_depends_on	(Optional) Define resources this module indirectly depends_on.	any	[]	no
name	(Required) The name of the repository.	string	n/a	yes
pages	(Optional) The repository's GitHub Pages configuration. (Default: {})	object({ branch = optional(string) path = optional(string, null) cname = optional(string) build_type = optional(string, "legacy") # requires branch and optional path })	null	no
plaintext_secrets	(Optional) Configuring actions secrets. For details please check: https://www.terraform.io/docs/providers/github/r/actions_secret	map(string)	{}	no
private	(Optional) (DEPRECATED: use visibility)	bool	null	no
pull_collaborators	(Optional) A list of users to add as collaborators granting them pull (read-only) permission.	list(string)	[]	no
pull_team_ids	(Optional) A list of teams (by id) to grant pull (read-only) permission to.	list(string)	[]	no
pull_teams	(Optional) A list of teams (by name/slug) to grant pull (read-only) permission to.	list(string)	[]	no
push_collaborators	(Optional) A list of users to add as collaborators granting them push (read-write) permission.	list(string)	[]	no
push_team_ids	(Optional) A list of teams (by id) to grant push (read-write) permission to.	list(string)	[]	no
push_teams	(Optional) A list of teams (by name/slug) to grant push (read-write) permission to.	list(string)	[]	no
rulesets	(Optional) A list of branch rulesets to apply to the repository. Default is []. It is very likely removal of any section will require setting it to an empty list/map. This is due to limitations in the API whereby components are not destroyed upon removal.	list( object({ enforcement = string name = string target = string rules = list( object({ creation = optional(bool) deletion = optional(bool) non_fast_forward = optional(bool) required_signatures = optional(bool) required_linear_history = optional(bool) update = optional(bool) update_allows_fetch_and_merge = optional(bool) branch_name_pattern = optional( object({ operator = string pattern = string name = optional(string) negate = optional(bool) }) ) commit_author_email_pattern = optional( object({ operator = string pattern = string name = optional(string) negate = optional(bool) }) ) commit_message_pattern = optional( object({ operator = string pattern = string name = optional(string) negate = optional(bool) }) ) committer_email_pattern = optional( object({ operator = string pattern = string name = optional(string) negate = optional(bool) }) ) tag_name_pattern = optional( object({ operator = string pattern = string name = optional(string) negate = optional(bool) }) ) required_status_checks = optional( object({ strict_required_status_checks_policy = optional(bool) do_not_enforce_on_create = optional(bool) required_check = list( object({ context = string integration_id = optional(number) }) ) }) ) pull_request = optional( object({ dismiss_stale_reviews_on_push = optional(bool) require_code_owner_review = optional(bool) require_last_push_approval = optional(bool) required_approving_review_count = optional(number) required_review_thread_resolution = optional(bool) }) ) required_workflows = optional( object({ required_workflow = list( object({ repository_id = number ref = string path = string }) ) }) ) required_deployments = optional( object({ required_deployment_environments = list(string) }) ) required_code_scanning = optional( object({ required_code_scanning_tool = list( object({ tool = string alerts_threshold = string security_alerts_threshold = string }) ) }) ) merge_queue = optional( object({ check_response_timeout_minutes = optional(number) grouping_strategy = optional(string) max_entries_to_build = optional(number) max_entries_to_merge = optional(number) merge_method = optional(string) min_entries_to_merge = optional(number) min_entries_to_merge_wait_minutes = optional(number) }) ) }) ) bypass_actors = optional( list( object({ actor_id = optional(number) actor_type = string bypass_mode = optional(string) }) ) ) conditions = optional( object({ ref_name = object({ include = list(string) exclude = list(string) }) }) ) }) )	[]	no
security_and_analysis	(Optional) Security and analysis configuration for the repository. - All fields except org_advanced_security are strings: "enabled" or "disabled". - org_advanced_security is a bool indicating whether the org has split licensing for Advanced Security.	object({ org_advanced_security = optional(bool, false) advanced_security = optional(string, "disabled") code_security = optional(string, "disabled") secret_scanning = optional(string, "disabled") secret_scanning_push_protection = optional(string, "disabled") secret_scanning_ai_detection = optional(string, "disabled") secret_scanning_non_provider_patterns = optional(string, "disabled") })	null	no
squash_merge_commit_message	(Optional) Can be PR_BODY, COMMIT_MESSAGES, or BLANK for a default squash merge commit message.	string	"COMMIT_MESSAGES"	no
squash_merge_commit_title	(Optional) Can be PR_BODY, COMMIT_MESSAGES, or BLANK for a default squash merge commit message.	string	"COMMIT_OR_PR_TITLE"	no
template	(Optional) Template repository to use. (Default: {})	object({ owner = string repository = string })	null	no
topics	(Optional) The list of topics of the repository. (Default: [])	list(string)	null	no
triage_collaborators	(Optional) A list of users to add as collaborators granting them triage permission.	list(string)	[]	no
triage_team_ids	(Optional) A list of teams (by id) to grant triage permission to.	list(string)	[]	no
triage_teams	(Optional) A list of teams (by name/slug) to grant triage permission to.	list(string)	[]	no
variables	(Optional) Configure action variables. For full details please check: https://registry.terraform.io/providers/integrations/github/latest/docs/resources/actions_variable	map(string)	{}	no
visibility	(Optional) Can be 'public', 'private' or 'internal' (GHE only).The visibility parameter overrides the private parameter. Defaults to 'private' if neither private nor visibility are set, default to state of private parameter if it is set.	string	null	no
vulnerability_alerts	(Optional) Set to false to disable security alerts for vulnerable dependencies. Enabling requires alerts to be enabled on the owner level.	bool	null	no
web_commit_signoff_required	(Optional) Require contributors to sign off on web-based commits.	bool	null	no
webhooks	(Optional) Configuring webhooks. For details please check: https://www.terraform.io/docs/providers/github/r/repository_webhook.html	any	[]	no

Outputs

Name	Description
app_installations	A map of deploy app installations keyed by installation id.
branches	A map of branch objects keyed by branch name.
collaborators	A map of collaborator objects keyed by collaborator.name.
deploy_keys	A map of deploy keys keyed by input id.
full_name	A string of the form 'orgname/reponame'.
git_clone_url	URL that can be provided to git clone to clone the repository anonymously via the git protocol.
html_url	URL to the repository on the web.
http_clone_url	URL that can be provided to git clone to clone the repository via HTTPS.
issue_labels	A map of issue labels keyed by label input id or name.
repository	All attributes and arguments as returned by the github_repository resource.
secrets	List of secrets available.
ssh_clone_url	URL that can be provided to git clone to clone the repository via SSH.
webhooks	All attributes and arguments as returned by the github_repository_webhook resource.

Security And Analysis Configuration

• security_and_analysis: (Optional object(security_and_analysis))

  (Optional) The repository's security and analysis configuration. See Security and Analysis Configuration below for details.

  Default is null.

  The security_and_analysis object accepts the following attributes:

  • [org_advanced_security](#attr-security_and_analysis-org_advanced_security: (Optional bool)

    If your GitHub Organization has split licensing for Advanced Security you can have Security and Analysis on non-public repositories. Otherwise Security and Analysis operates on all public repositories. Currently there is no known way to automatically detect this.

    Define org_advanced_security as true to give more visibility options.

  • advanced_security: (Optional string)

    The advanced security configuration for the repository. See Advanced Security Configuration below for details.

    Default is "disabled", except if org_advanced_security is not true when it is "enabled".

  • secret_scanning: (Optional string)

    The secret scanning configuration for the repository. See Secret Scanning Configuration below for details.

    Default is "disabled".

  • secret_scanning_push_protection: (Optional string)

    The secret scanning push protection configuration for the repository. See Secret Scanning Push Protection Configuration below for details.

    Default is "disabled".

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_ruleset
• 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.

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.

Attribution

This repository is derived from the Mineiros GmbH open-source project terraform-github-repository, licensed under the Apache License 2.0. This fork introduces changes.

License

This module is licensed under the Apache License Version 2.0, January 2004. Please see LICENSE for full details.