GitHub Repository Module

This Terraform module manages GitHub repositories.

Example Usage

Create private repository

module "my_pets_website_repo" {
  source = "github.com/flaconi/terraform-github-repository.git?ref=master"

  name        = "my-pets-website"
  description = "My pets codebase."
  visibility  = "private"

  gitignore_template = "Node"

  default_branch_protection_enabled = false
}

Create public (e.g. open source) repository

module "terraform_my_pets_repo" {
  source  = "github.com/flaconi/terraform-github-repository.git?ref=master"

  namespace   = "terraform"
  tenant      = "my"
  name        = "pets"
  description = "Terraform configuration for my pets."
  visibility  = "public"

  gitignore_template = "Terraform"
  license_template   = "mit"
}

Add collaborators and teams

data "github_team" "developers" {
  slug = "developers"
}

module "example_repo" {
  source  = "github.com/flaconi/terraform-github-repository.git?ref=master"

  name        = "example"
  description = "My example codebase"

  visibility = "private"

  teams = [
    {
      name      = "security"
      permisson = "admin"
    },
    {
      # Specify Team ID to use external data source
      id         = data.github_team.developers.id
      name       = "developers"
      permission = "push"
    }
  ]
}

Set branch protection options

module "example_repo" {
  source  = "github.com/flaconi/terraform-github-repository.git?ref=master"

  name        = "example"
  description = "My example codebase"

  visibility = "private"
  
  # Overwrite some settings for default branch
  default_branch_protection = {
    required_status_checks = {
      contexts = ["ci/travis"]
    }
    required_pull_request_reviews = {
      dismiss_stale_reviews  = true
      dismissal_restrictions = ["team1","team2"]
    }
  }
}

Add issue labels

module "example_repo" {
  source  = "github.com/flaconi/terraform-github-repository.git?ref=master"

  name        = "example"
  description = "My example codebase"

  visibility = "private"

  default_branch_protection_enabled = false

  issue_labels = [
    {
      name        = "bug"
      color       = "d73a4a"
      description = "This is a bug."
    },
    {
      name        = "wontfix"
      color       = "ffffff"
      description = null
    },
  ]
}

Requirements

Name	Version
terraform	>= 1.3
github	~> 6.2

Providers

Name	Version
github	~> 6.2

Modules

Name	Source	Version
label	github.com/cloudposse/terraform-null-label.git	0.25.0

Resources

Name	Type
github_actions_environment_secret.this	resource
github_actions_repository_access_level.this	resource
github_actions_secret.this	resource
github_branch_default.this	resource
github_branch_protection.this	resource
github_dependabot_secret.this	resource
github_issue_label.this	resource
github_repository.this	resource
github_repository_collaborator.this	resource
github_repository_deploy_key.this	resource
github_repository_environment.this	resource
github_repository_ruleset.this	resource
github_repository_webhook.this	resource
github_team_repository.this	resource
github_team.this	data source

Inputs

Name	Description	Type	Default	Required
name	The name of the repository.	string	n/a	yes
actions_repository_access_level	This resource allows you to set the access level of a non-public repositories actions and reusable workflows for use in other repositories.	string	null	no
allow_auto_merge	Set to true to allow auto-merging pull requests on the repository.	bool	false	no
allow_merge_commit	Set to false to disable merge commits on the repository.	bool	false	no
allow_rebase_merge	Set to false to disable rebase merges on the repository.	bool	false	no
allow_squash_merge	Set to false to disable squash merges on the repository.	bool	true	no
allow_update_branch	Set to true to always suggest updating pull request branches.	bool	false	no
archive_on_destroy	Set to true to archive the repository instead of deleting on destroy.	bool	false	no
archived	Specifies if the repository should be archived.	bool	false	no
attributes	Additional attributes (e.g. policy or role)	list(string)	[]	no
auto_init	Meaningful only during create; set to true to produce an initial commit in the repository.	bool	true	no
bot_secrets	Repository dependabot secrets.	map(object({ encrypted_value = optional(string) plaintext_value = optional(string) }))	{}	no
branch_protection	Branch protection settings. Use to set protection rules for branches different to default branch.	map(object({ enforce_admins = optional(bool, true) allows_deletions = optional(bool, false) allows_force_pushes = optional(bool, false) require_signed_commits = optional(bool, true) required_linear_history = optional(bool, false) require_conversation_resolution = optional(bool, false) restrict_pushes = optional(object({ blocks_creations = optional(bool, false) push_allowances = optional(list(string), []) }), {}) required_status_enabled = optional(bool, true) required_status_checks = optional(object({ strict = optional(bool, true) contexts = optional(list(string), []) }), {}) required_pull_request_enabled = optional(bool, true) required_pull_request_reviews = optional(object({ dismiss_stale_reviews = optional(bool, true) restrict_dismissals = optional(bool, false) dismissal_restrictions = optional(list(string), []) pull_request_bypassers = optional(list(string), []) require_code_owner_reviews = optional(bool, true) required_approving_review_count = optional(number, 1) }), {}) }))	{}	no
collaborators	Map of users with permissions.	map(string)	{}	no
default_branch	The repository's default branch. The branch should exist prio to apply.	string	"main"	no
default_branch_protection	Default branch protection settings.	object({ enforce_admins = optional(bool, true) allows_deletions = optional(bool, false) allows_force_pushes = optional(bool, false) require_signed_commits = optional(bool, true) required_linear_history = optional(bool, false) require_conversation_resolution = optional(bool, false) restrict_pushes = optional(object({ blocks_creations = optional(bool, false) push_allowances = optional(list(string), []) }), {}) required_status_enabled = optional(bool, true) required_status_checks = optional(object({ strict = optional(bool, true) contexts = optional(list(string), []) }), {}) required_pull_request_enabled = optional(bool, true) required_pull_request_reviews = optional(object({ dismiss_stale_reviews = optional(bool, true) restrict_dismissals = optional(bool, false) dismissal_restrictions = optional(list(string), []) pull_request_bypassers = optional(list(string), []) require_code_owner_reviews = optional(bool, true) required_approving_review_count = optional(number, 1) }), {}) })	{}	no
default_branch_protection_enabled	Set to false if you want to disable branch protection for default branch	bool	true	no
delete_branch_on_merge	Automatically delete head branch after a pull request is merged.	bool	true	no
delimiter	Delimiter to be used between name, namespace, tenant, etc.	string	"-"	no
deploy_keys	List of deploy keys configurations.	list(object({ title = string key = string read_only = bool }))	[]	no
description	A description of the repository.	string	""	no
environments	Repository environments.	map(object({ reviewers = optional(object({ teams = optional(list(string), []) users = optional(list(string), []) })) branch_policy = optional(object({ protected_branches = optional(bool, false) custom_branch_policies = optional(bool, false) })) secrets = optional(map(object({ encrypted_value = optional(string) plaintext_value = optional(string) }))) }))	{}	no
gitignore_template	Meaningful only during create, will be ignored after repository creation. Use the name of the template without the extension. For example, "Terraform".	string	""	no
has_downloads	Set to true to enable the (deprecated) downloads features on the repository.	bool	null	no
has_issues	Set to false to disable the GitHub Issues features on the repository.	bool	true	no
has_projects	Set to true to enable the GitHub Projects features on the repository.	bool	false	no
has_wiki	Set to true to enable the GitHub Wiki features on the repository.	bool	false	no
homepage_url	URL of a page describing the project.	string	""	no
is_template	Set to true to tell GitHub that this is a template repository.	bool	false	no
issue_labels	List of issue labels on the repository.	list(object({ name = string color = string description = string }))	[]	no
license_template	Meaningful only during create, will be ignored after repository creation. Use the name of the template without the extension. For example, "Terraform".	string	""	no
merge_commit_message	Can be PR_BODY, PR_TITLE, or BLANK for a default merge commit message.	string	"PR_TITLE"	no
merge_commit_title	Can be PR_TITLE or MERGE_MESSAGE for a default merge commit title.	string	"MERGE_MESSAGE"	no
namespace	Namespace, e.g. terraform, product, mobile etc.	string	null	no
pages	The repository's GitHub Pages configuration.	object({ build_type = optional(string, "legacy") source = optional(object({ branch = string path = string })) })	null	no
rulesets	n/a	map(object({ required_linear_history = optional(bool, true) deletion = optional(bool, true) creation = optional(bool, true) update = optional(bool, false) target = optional(string, "branch") enforcement = optional(string, "active") includes = optional(list(string), ["~DEFAULT_BRANCH"]) excludes = optional(list(string), []) non_fast_forward = optional(bool, true) required_signatures = optional(bool, true) bypass_actors = optional(map(object({ actor_id = number actor_type = string bypass_mode = optional(string, "always") })), {}) pull_request = optional(object({ enabled = optional(bool, true) dismiss_stale_reviews_on_push = optional(bool, true) require_code_owner_review = optional(bool, true) required_approving_review_count = optional(number, 1) required_review_thread_resolution = optional(bool, true) require_last_push_approval = optional(bool, true) }), {}) required_status_checks = optional(object({ enabled = optional(bool, true) strict_required_status_checks_policy = optional(bool, false) contexts = optional(list(object({ integration_id = optional(number, 0) context = string })), []) })) }))	{}	no
secrets	Repository secrets.	map(object({ encrypted_value = optional(string) plaintext_value = optional(string) }))	{}	no
squash_merge_commit_message	Can be PR_BODY, COMMIT_MESSAGES, or BLANK for a default squash merge commit message.	string	"COMMIT_MESSAGES"	no
squash_merge_commit_title	Can be PR_TITLE or COMMIT_OR_PR_TITLE for a default squash merge commit title.	string	"COMMIT_OR_PR_TITLE"	no
tags	Additional tags (e.g. map('BusinessUnit','XYZ'))	map(string)	{}	no
teams	List of teams with permissions. Specify Team ID to avoid additional requests to GitHub API.	list(object({ id = optional(string) name = string permission = string }))	[]	no
template	Use a template repository to create this repository.	object({ owner = string repository = string })	null	no
tenant	A customer identifier, indicating who this instance of a resource is for. Could be used for application grouping.	string	null	no
topics	A list of topics to add to the repository.	list(string)	[]	no
use_fullname	Set 'true' to use namespace-tenant-name for github repository name, else name	bool	true	no
visibility	Set to public to create a public (e.g. open source) repository.	string	"private"	no
vulnerability_alerts	Set to true to enable security alerts for vulnerable dependencies. Enabling requires alerts to be enabled on the owner level.	bool	false	no
webhooks	List of webhook configurations.	list(object({ ident = string # some unique string to identify this webhook active = optional(bool, true) events = list(string) configuration = object({ url = string content_type = string secret = optional(string) insecure_ssl = optional(bool, false) }) }))	[]	no

Outputs

Name	Description
dependabot_secrets	A map of dependabot secret names
environments	A list of created environments
environments_secrets	A map of environment secret names
repository	Created repository
repository_branch_protection	Default branch protection settings
repository_secrets	A map of create secret names
repository_webhook_urls	Webhook URLs

License

MIT

Copyright (c) 2019-2022 Flaconi GmbH