GitHub Repository Terraform module

A Terraform module for comprehensive GitHub repository management. This module offers complete lifecycle control for repositories, including permissions, GitHub Actions configuration, deploy keys, repository properties, user and team access management, autolink references, advanced security features, and ruleset configurations.

The module enables infrastructure-as-code practices for GitHub repositories, supporting key features such as:

• Repository creation with customizable settings (visibility, branch protection, merge strategies)
• Team and user permission management with granular access control
• GitHub Actions integration with secrets and variables management
• Deploy keys configuration for automated deployments
• Autolink references for connecting external resources
• Advanced security features configuration
• Custom ruleset implementation for repository governance
• Branch protection policies with required checks

Usage

module "repo" {
  source         = "github.com/vmvarela/terraform-github-repository"
  name           = "my-repo"
  visibility     = "public"
  default_branch = "main"
  template       = "MarketingPipeline/Awesome-Repo-Template"
  rulesets = {
    "codeql-scanning-required" = {
      target  = "branch"
      include = ["~DEFAULT_BRANCH"]
      required_code_scanning = {
        "CodeQL" = "none:errors_and_warnings"
      }
    }
  }
}

Examples

• simple - Basic repository with minimal configuration
• complete - Comprehensive example showcasing all module features

Requirements

Name	Version
terraform	>= 1.6
github	>= 6.6.0
local	>= 2.5.2
null	>= 3.2.3
tls	>= 4.0.6

Providers

Name	Version
github	>= 6.6.0
local	>= 2.5.2
null	>= 3.2.3
tls	>= 4.0.6

Modules

Name	Source	Version
environment	./modules/environment	n/a
file	./modules/file	n/a
ruleset	./modules/ruleset	n/a
webhook	./modules/webhook	n/a

Resources

Name	Type
github_actions_repository_access_level.this	resource
github_actions_repository_permissions.this	resource
github_actions_secret.encrypted	resource
github_actions_secret.plaintext	resource
github_actions_variable.this	resource
github_branch.this	resource
github_branch_default.this	resource
github_dependabot_secret.encrypted	resource
github_dependabot_secret.plaintext	resource
github_issue_labels.this	resource
github_repository.this	resource
github_repository_autolink_reference.this	resource
github_repository_collaborators.this	resource
github_repository_custom_property.this	resource
github_repository_dependabot_security_updates.this	resource
github_repository_deploy_key.this	resource
local_file.private_key_file	resource
null_resource.create_subfolder	resource
tls_private_key.this	resource

Inputs

Name	Description	Type	Default	Required
actions_access_level	The access level for the repository. Must be one of none, user, organization, or enterprise. Default: none	string	null	no
actions_allowed_github	Whether GitHub-owned actions are allowed in the repository. Only available when actions_allowed_policy = selected.	bool	true	no
actions_allowed_patterns	Specifies a list of string-matching patterns to allow specific action(s). Wildcards, tags, and SHAs are allowed. For example, monalisa/octocat@, monalisa/octocat@v2, monalisa/.	set(string)	[]	no
actions_allowed_policy	The permissions policy that controls the actions that are allowed to run. Can be one of: all, local_only, or selected.	string	null	no
actions_allowed_verified	Whether actions in GitHub Marketplace from verified creators are allowed. Set to true to allow all GitHub Marketplace actions by verified creators. Only available when actions_allowed_policy = selected.	bool	null	no
alias	The original name of the repository (useful for renaming)	string	null	no
allow_auto_merge	Set to true to allow auto-merging pull requests on the repository.	bool	null	no
allow_merge_commit	Either true to allow merging pull requests with a merge commit, or false to prevent merging pull requests with merge commits.	bool	null	no
allow_rebase_merge	Either true to allow rebase-merging pull requests, or false to prevent rebase-merging.	bool	null	no
allow_squash_merge	Either true to allow squash-merging pull requests, or false to prevent squash-merging.	bool	null	no
allow_update_branch	Either true to always allow a pull request head branch that is behind its base branch to be updated even if it is not required to be up to date before merging, or false otherwise.	bool	null	no
archive_on_destroy	Set to true to archive the repository instead of deleting on destroy.	bool	null	no
archived	Whether to archive this repository. false will unarchive a previously archived repository.	bool	null	no
auto_init	Set to true to produce an initial commit in the repository	bool	null	no
autolink_references	The list of autolink references of the repository (key: key_prefix, value: target_url_template - valid URL and contain <num> for the reference number)	map(string)	{}	no
branches	The list of branches to create (map of name and source branch)	map(string)	{}	no
custom_properties	The custom properties for the new repository. The keys are the custom property names, and the values are the corresponding custom property values.	any	{}	no
custom_properties_types	The list of types associated to properties (key: property_name)	map(string)	{}	no
default_branch	Updates the default branch for this repository.	string	null	no
delete_branch_on_merge	Either true to enable automatic deletion of branches on merge, or false to disable.	bool	null	no
dependabot_copy_secrets	If dependabot uses same repository secrets (plaintext or encrypted). Makes a copy.	bool	false	no
dependabot_secrets	The list of secrets configuration of the repository (key: secret_name). Only plaintext secrets.	map(string)	{}	no
dependabot_secrets_encrypted	The list of secrets configuration of the repository (key: secret_name). Only encrypted secrets.	map(string)	{}	no
deploy_keys	The list of deploy keys of the repository. Each key can have: public_key (public key content, if null will be auto-generated) and read_only (bool, defaults to true)	map(object({ public_key = optional(string, null) read_only = optional(bool, true) }))	{}	no
deploy_keys_path	The path to the auto-generated deploy keys for this repository	string	null	no
description	A short description of the repository that will show up on GitHub	string	null	no
enable_actions	Either true to enable Github Actions, or false to disable.	bool	null	no
enable_advanced_security	Use to enable or disable GitHub Advanced Security for this repository.	bool	null	no
enable_dependabot_security_updates	Set to true to enable the automated security fixes.	bool	null	no
enable_secret_scanning	Use to enable or disable secret scanning for this repository. If set to true, the repository's visibility must be public or enable_advanced_security must also be true.	bool	null	no
enable_secret_scanning_push_protection	Use to enable or disable secret scanning push protection for this repository. If set to true, the repository's visibility must be public or enable_advanced_security must also be true.	bool	null	no
enable_vulnerability_alerts	Either true to enable vulnerability alerts, or false to disable vulnerability alerts.	bool	null	no
environments	The list of environments configuration of the repository (key: environment_name). See environment sub-module for details.	any	{}	no
files	The list of files of the repository (key: file_path). See file sub-module for details.	any	{}	no
gitignore_template	Use the name of the template without the extension. For example, Haskell.	string	null	no
has_issues	Either true to enable issues for this repository or false to disable them.	bool	null	no
has_projects	Either true to enable projects for this repository or false to disable them. Note: If you're creating a repository in an organization that has disabled repository projects, the default is false, and if you pass true, the API returns an error.	bool	null	no
has_wiki	Either true to enable the wiki for this repository, false to disable it.	bool	null	no
homepage	A URL with more information about the repository	string	null	no
is_template	Either true to make this repo available as a template repository or false to prevent it.	bool	null	no
issue_labels	The list of issue labels of the repository (key: label_name, argument: description)	map(string)	{}	no
issue_labels_colors	The list of issue labels and associated color (key: label_name, arguments color)	map(string)	{}	no
license_template	Use the name of the template without the extension. For example, mit or mpl-2.0.	string	null	no
merge_commit_message	Can be PR_BODY, PR_TITLE, or BLANK for a default merge commit message. Applicable only if allow_merge_commit is true.	string	null	no
merge_commit_title	Can be PR_TITLE or MERGE_MESSAGE for a default merge commit title. Applicable only if allow_merge_commit is true.	string	null	no
name	The name of the repository. Changing this will rename the repository	string	n/a	yes
pages_build_type	The type of GitHub Pages site to build. Can be legacy or workflow. If you use legacy as build type you need to set the option pages_source_branch.	string	null	no
pages_cname	The custom domain for the repository. This can only be set after the repository has been created.	string	null	no
pages_source_branch	The repository branch used to publish the site's source files. (i.e. main or gh-pages)	string	null	no
pages_source_path	The repository directory from which the site publishes (Default: /).	string	null	no
private	Either true to make the repository private or false to make it public. Default: false. Note: You will get a 422 error if the organization restricts changing repository visibility to organization owners and a non-owner tries to change the value of private.	bool	null	no
rulesets	Repository rules (key: rule_name). See ruleset sub-module for details.	any	{}	no
secrets	The list of secrets configuration of the repository (key: secret_name). Only plaintext secrets.	map(string)	{}	no
secrets_encrypted	The list of secrets configuration of the repository (key: secret_name). Only encrypted secrets.	map(string)	{}	no
squash_merge_commit_message	Can be PR_BODY, COMMIT_MESSAGES, or BLANK for a default squash merge commit message. Applicable only if allow_squash_merge is true.	string	null	no
squash_merge_commit_title	Can be PR_TITLE or COMMIT_OR_PR_TITLE for a default squash merge commit title. Applicable only if allow_squash_merge is true.	string	null	no
teams	The map of collaborators (teams) of the repository and their permissions (pull, push, maintain, triage, admin or an existing custom repository role) )	map(string)	{}	no
template	Use a template repository to create this resource (owner/repo)	string	null	no
template_include_all_branches	Whether the new repository should include all the branches from the template repository (defaults to false, which includes only the default branch from the template).	bool	null	no
topics	A list of topics to set on the repository	set(string)	[]	no
users	The map of collaborators (users) of the repository and their permissions (pull, push, maintain, triage, admin or an existing custom repository role) )	map(string)	{}	no
variables	The list of variables configuration of the repository (key: variable_name)	map(string)	{}	no
visibility	Can be public or private (or internal if your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+). The visibility parameter overrides the private parameter.	string	null	no
web_commit_signoff_required	Require contributors to sign off on web-based commits. Defaults to false	bool	null	no
webhooks	The list of webhooks of the repository. See webhook sub-module for details.	any	{}	no

Outputs

Name	Description
alias	Alias (used for renaming)
private_keys	Autogenerated private keys
repository	Created repository

Authors

Module is maintained by Victor M. Varela.

License

Apache 2 Licensed. See LICENSE for full details.