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

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
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

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
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

CSVD/terraform-github-repo

About

Topics

Resources

Stars

Watchers

Forks

Releases

Contributors 2

Languages