/terraform-github-repository

Terraform module for maintaining Github repo's

Primary LanguageHCLMIT LicenseMIT

GitHub Repository Module

lint test Tag Terraform license

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({
    source = 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