Terraform GitHub Repository Module

A comprehensive Terraform module for managing GitHub repositories with advanced features like branch protection, file management, team access control, and deployment keys. You can use this module to create new repositories or manage existing ones.

Features

• Create new repositories or manage existing ones
• Complete GitHub repository management
• Branch protection rules
• File content management
• Team access configuration
• Action secrets management
• Repository collaborator management
• Deploy key management
• Automated README generation
• Issue management

Usage

Creating a New Repository

module "new_repository" {
  source = "HappyPathway/repo/github"
  
  name                     = "my-repository"
  repo_org                = "MyOrganization"
  create_repo             = true  # Default, can be omitted
  force_name              = true
  github_repo_description = "Repository description"
  github_repo_topics      = ["terraform", "automation"]
  github_is_private       = false
}

Managing an Existing Repository

module "existing_repository" {
  source = "HappyPathway/repo/github"
  
  name        = "existing-repository"
  repo_org    = "MyOrganization"
  create_repo = false  # Tell Terraform to manage existing repository
  
  # All other settings will be applied to the existing repository
  github_repo_topics = ["managed", "terraform"]
  github_has_issues = true
}

Basic Repository

module "basic_repo" {
  source = "HappyPathway/repo/github"
  
  name     = "my-project"
  repo_org = "MyOrganization"
}

Repository with Protected Branches

module "protected_repo" {
  source = "HappyPathway/repo/github"
  
  name     = "protected-project"
  repo_org = "MyOrganization"
  
  branch_protections = {
    main = {
      required_status_checks = true
      enforce_admins        = true
      required_reviews      = 2
    }
  }
}

Repository with Managed Files

module "managed_repo" {
  source = "HappyPathway/repo/github"
  
  name     = "managed-project"
  repo_org = "MyOrganization"
  
  managed_extra_files = {
    "README.md" = {
      content   = file("${path.module}/templates/readme.md")
      overwrite = true
    }
    "CONTRIBUTING.md" = {
      content   = file("${path.module}/templates/contributing.md")
      overwrite = false
    }
  }
}

Repository with Deploy Keys

module "repo_with_deploy_keys" {
  source = "HappyPathway/repo/github"
  
  name     = "my-project-with-deploy-keys"
  repo_org = "MyOrganization"
  
  deploy_keys = [
    {
      title     = "CI Server Key"
      key       = "ssh-rsa AAAAB3NzaC1yc2EAAA..."
      read_only = true  # Default is true, can be omitted
    },
    {
      title     = "Deploy Server Key"
      key       = "ssh-rsa AAAAB3NzaC1yc2EBBB..."
      read_only = false  # Write access for deployment
    }
  ]
}

Inputs

Name	Description	Type	Required	Default
name	Repository name	string	Yes	-
repo_org	GitHub organization name	string	No	null
create_repo	Whether to create a new repository or manage existing	bool	No	true
force_name	Keep exact repository name (no date suffix)	bool	No	false
github_repo_description	Repository description	string	No	null
github_repo_topics	Repository topics	list(string)	No	[]
github_is_private	Make repository private	bool	No	true
// ...other inputs...

Outputs

Name	Description
github_repo	All repository attributes (see details below)
ssh_clone_url	SSH clone URL
node_id	Repository node ID for GraphQL
full_name	Full repository name (org/repo)
repo_id	Repository ID
html_url	Repository web URL
http_clone_url	HTTPS clone URL
git_clone_url	Git protocol clone URL
visibility	Repository visibility (public/private)
default_branch	Default branch name
topics	Repository topics
template	Template repository info

Complete Repository Attributes

The github_repo output includes:

Basic Info:

• name - Repository name
• full_name - Full repository name (org/repo)
• description - Repository description
• html_url - GitHub web URL
• ssh_clone_url - SSH clone URL
• http_clone_url - HTTPS clone URL
• git_clone_url - Git protocol URL
• visibility - Public or private status

Settings:

• topics - Repository topics
• has_issues - Issue tracking enabled
• has_projects - Project boards enabled
• has_wiki - Wiki enabled
• is_template - Template repository status
• allow_merge_commit - Merge commit allowed
• allow_squash_merge - Squash merge allowed
• allow_rebase_merge - Rebase merge allowed
• allow_auto_merge - Auto-merge enabled
• delete_branch_on_merge - Branch deletion on merge

Additional Info:

• default_branch - Default branch name
• archived - Archive status
• homepage_url - Homepage URL if set
• vulnerability_alerts - Vulnerability alerts status
• template - Template repository details if used
• gitignore_template - .gitignore template if used
• license_template - License template if used

Limitations and Important Notes

Managing Existing Repositories

When managing existing repositories (create_repo = false):

• The repository must already exist in the specified organization
• You must have admin access to the repository
• Some settings may be read-only if they were set during repository creation
• Initial repository settings (like auto_init) are ignored
• Branch protection rules can only be added, not removed

Error Cases

The module will fail if:

• When create_repo = false and the repository doesn't exist
• When create_repo = false and repo_org is not specified
• When trying to manage a repository you don't have admin access to
• When applying branch protection rules to a private repository without a GitHub Enterprise plan

Best Practices

1. When managing existing repositories:

   • Start with create_repo = false and minimal settings
   • Gradually add configuration to avoid conflicts
   • Use terraform plan to verify changes
   • Consider using lifecycle blocks to ignore specific attributes

2. For new repositories:

   • Use create_repo = true (default)
   • Set force_name = true to maintain consistent naming
   • Configure all settings during initial creation

Testing

This module includes automated tests that verify:

• Repository creation
• Data source lookups for existing repositories
• All output attributes

Run the tests using:

terraform test

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License - see LICENSE for details

Requirements

No requirements.

Providers

Name	Version
github	6.6.0
tls	4.0.6

Modules

No modules.

Resources

Name	Type
github_actions_environment_secret.environment_secrets	resource
github_actions_environment_variable.environment_variables	resource
github_actions_secret.secret	resource
github_actions_variable.variable	resource
github_branch.branch	resource
github_branch_default.default_main_branch	resource
github_branch_protection.protection	resource
github_repository.repo	resource
github_repository_collaborator.collaborators	resource
github_repository_deploy_key.deploy_key	resource
github_repository_environment.environments	resource
github_repository_file.codeowners	resource
github_repository_file.extra_files	resource
github_repository_file.managed_extra_files	resource
github_team_repository.admin	resource
tls_private_key.deploy_key	resource
github_organization_teams.root_teams	data source
github_ref.ref	data source
github_repository.existing	data source
github_repository.template_repo	data source
github_team.admin_teams	data source
github_team.environment_teams	data source
github_user.collaborators	data source
github_user.environment_users	data source
github_user.pull_request_bypassers	data source

Inputs

Name	Description	Type	Default	Required
additional_codeowners	Additional entries for CODEOWNERS file	list(string)	[]	no
admin_teams	Teams to grant admin access	list(string)	[]	no
allow_unsigned_files	Whether to allow file management even when signed commits are required	bool	false	no
archive_on_destroy	Archive repository instead of deleting on destroy	bool	true	no
archived	Archive this repository	bool	false	no
collaborators	Map of collaborators and their permission levels	map(string)	{}	no
commit_author	The author name to use for file commits	string	"Terraform"	no
commit_email	The email to use for file commits	string	"terraform@roknsound.com"	no
create_codeowners	Create CODEOWNERS file	bool	true	no
create_repo	Whether to create a new repository or manage an existing one	bool	true	no
deploy_keys	List of SSH deploy keys to add to the repository	list(object({ title = string key = optional(string, "") # The key is optional because it can be generated # by the module itself if create is set to true # and the key is not provided read_only = optional(bool, true) create = optional(bool, false) }))	[]	no
enforce_prs	Enforce pull request reviews	bool	true	no
environments	List of GitHub environments to create for the repository	list(object({ name = string reviewers = optional(object({ teams = optional(list(string), []) users = optional(list(string), []) }), {}) deployment_branch_policy = optional(object({ protected_branches = optional(bool, true) custom_branch_policies = optional(bool, false) }), {}) secrets = optional(list(object({ name = string value = string })), []) vars = optional(list(object({ name = string value = string })), []) }))	[]	no
extra_files	Additional files to create in the repository	list(object({ path = string content = string }))	[]	no
force_name	Keep exact repository name (no date suffix)	bool	false	no
github_allow_auto_merge	Allow pull requests to be automatically merged	bool	false	no
github_allow_merge_commit	Allow merge commits	bool	false	no
github_allow_rebase_merge	Allow rebase merging	bool	false	no
github_allow_squash_merge	Allow squash merging	bool	true	no
github_allow_update_branch	Allow updating pull request branches	bool	true	no
github_auto_init	Initialize repository with README	bool	true	no
github_codeowners_team	n/a	string	"terraform-reviewers"	no
github_default_branch	Default branch name	string	"main"	no
github_delete_branch_on_merge	Delete head branch after merge	bool	true	no
github_dismiss_stale_reviews	Dismiss stale pull request approvals	bool	true	no
github_enforce_admins_branch_protection	Enforce branch protection rules on administrators	bool	true	no
github_has_discussions	Enable discussions feature	bool	false	no
github_has_downloads	Enable downloads feature	bool	false	no
github_has_issues	Enable issues feature	bool	false	no
github_has_projects	Enable projects feature	bool	true	no
github_has_wiki	Enable wiki feature	bool	true	no
github_is_private	Make repository private	bool	true	no
github_merge_commit_message	Message for merge commits	string	"PR_TITLE"	no
github_merge_commit_title	Title for merge commits	string	"MERGE_MESSAGE"	no
github_org_teams	Organization teams configuration	list(any)	null	no
github_pro_enabled	Is this a Github Pro Account? If not, then it's limited in feature set	bool	false	no
github_push_restrictions	List of team/user IDs with push access	list(string)	[]	no
github_repo_description	Repository description	string	null	no
github_repo_topics	Repository topics	list(string)	[]	no
github_require_code_owner_reviews	Require code owner review	bool	true	no
github_required_approving_review_count	Number of approvals needed for pull requests	number	1	no
github_squash_merge_commit_message	Message for squash merge commits	string	"COMMIT_MESSAGES"	no
github_squash_merge_commit_title	Title for squash merge commits	string	"COMMIT_OR_PR_TITLE"	no
gitignore_template	Gitignore template to use	string	null	no
homepage_url	Repository homepage URL	string	null	no
is_template	Make this repository a template	bool	false	no
license_template	License template to use for the repository	string	null	no
managed_extra_files	Additional files to manage in the repository	list(object({ path = string content = string }))	[]	no
name	Name of the repository	string	n/a	yes
pages_config	Configuration for GitHub Pages	object({ branch = optional(string, "gh-pages") path = optional(string, "/") cname = optional(string) })	null	no
prefix	Prefix to add to repository name	string	null	no
pull_request_bypassers	Users/teams that can bypass pull request requirements	list(string)	[]	no
repo_org	GitHub organization name	string	null	no
require_last_push_approval	Require approval from the last pusher	bool	false	no
require_signed_commits	Whether to require signed commits for the default branch	bool	false	no
required_status_checks	Required status checks for protected branches	object({ contexts = list(string) strict = optional(bool, false) })	null	no
secrets	GitHub Actions secrets	list(object({ name = string value = string }))	[]	no
security_and_analysis	Security and analysis settings for the repository	object({ advanced_security = optional(object({ status = string }), { status = "disabled" }) secret_scanning = optional(object({ status = string }), { status = "disabled" }) secret_scanning_push_protection = optional(object({ status = string }), { status = "disabled" }) })	null	no
template_repo	Template repository name	string	null	no
template_repo_org	Template repository organization	string	null	no
vars	GitHub Actions variables	list(object({ name = string value = string }))	[]	no
vulnerability_alerts	Enable Dependabot alerts	bool	false	no

Outputs

Name	Description
default_branch	Default branch of the repository
full_name	Full name of the repository in org/repo format
git_clone_url	URL that can be provided to git clone to clone the repository anonymously via the git protocol
github_repo	All attributes of the GitHub repository
html_url	URL to the repository on GitHub
http_clone_url	URL that can be provided to git clone to clone the repository via HTTPS
node_id	Node ID of the repository, used for GraphQL API access
repo_id	Repository ID
ssh_clone_url	URL that can be provided to git clone to clone the repository via SSH
template	Template repository this repository was created from
topics	List of topics applied to the repository
visibility	Whether the repository is private or public