/terraform-github-repo

Manage Github repos with Terraform with good defaults

Primary LanguageHCLBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

Set up a github repository with standard config.

Limited options are provided as this module is for configuring a repository using opinionated settings. If more control is needed, use the terraform github_repository directly.

Usage

module "github_terraform_aws_ecs_service" {
  source       = "trussworks/repo/github"

  repo_name    = "terraform-aws-ecs-service"
  description  = "Creates an ECS Service."
  homepage_url = "https://registry.terraform.io/modules/trussworks/ecs-service/aws"

  topics = [
    "terraform",
    "terraform-modules",
    "aws-ecs",
    "ecs",
    "ecs-service",
  ]

  private             = false
  status_check_strict = true
}

Requirements

Name Version
terraform >= 0.13.0
github >= 4.10.0

Providers

Name Version
github >= 4.10.0

Modules

No modules.

Resources

Name Type
github_branch.main resource
github_branch_default.main resource
github_branch_protection.main resource
github_repository.main resource

Inputs

Name Description Type Default Required
additional_push_users The list of Github usernames allowed to push to the protected main branch list(string) [] no
archived Specifies if the repository should be archived bool false no
default_branch_name The default branch for the repo. Branch protection settings will be applied to the branch with this name. Currently defaults to main. string "main" no
delete_branch_on_merge Delete branches upon merge bool true no
description A description of the repository string n/a yes
homepage_url URL of a page describing the project string "" no
is_template Tell GitHub that this is a template repository bool false no
private Set to true to create a private repository. Repositories are created as private by default bool true no
repo_name The name of the repository string n/a yes
status_checks_strict Require branches to be up to date before merging bool true no
template Optional template to use for creating the repo 
object({
    owner      = string
    repository = string
  })
 null no
topics The list of topics for the repository list(string) [] no

Outputs

No outputs.

Note on auto-init

We tried using the auto-init variable on the repo resource from the GitHub Terraform Provider and found that it is

  1. Not a fun workflow
  2. Still has outstanding issues/bugs related to it

The behavior around what happens when you update or continually run Terraform with a resource with auto-init = true so we're not willing to deal with that.

Developer Setup

Install dependencies (macOS)

brew install pre-commit go terraform terraform-docs
pre-commit install --install-hooks

Accessing the GitHub API

Set GITHUB_TOKEN environment variable. See the terraform github provider token docs. You will need to create a github personal access token with "Full control of private repositories" access scope.