Terraform module to create and manage a GitHub repository.

Take care when configuring either var.license_template or var.gitignore_template as the values are case sensitive. See here for a list of supported licenses or here for a list of supported gitignore templates - to use either, provide the file name without the extension, e.g. mit or Terraform respectively.

Setting one of these templates can only be done during creation of the repository. If you want to add a LICENSE or .gitignore file after repository creation, you'll need to do it like any other file.

Additional branches can be created and configured using var.branches. Any branches created here are in addition to the default branch (var.default_branch).

You can create branches by either adding them to var.branches:

module "mcaf-repository" {
  source = "schubergphilis/mcaf-repository/github"

  name = "my-repo"

  branches = {
    "develop" = {}
  }
}

Or by specifying the source branch or hash by setting source_branch or source_sha respectively:

module "mcaf-repository" {
  source = "schubergphilis/mcaf-repository/github"

  name = "my-repo"

  branches = {
    "develop" = {
      source_branch = "release"
    }
  }
}

See the github_branch resource for more details

This module allows creating and managing files in a GitHub repository by using var.repository_files.

To create files:

module "mcaf-repository" {
  source = "schubergphilis/mcaf-repository/github"

  name = "my-repo"

  repository_files = {
    ".github/dependabot.yml" = {
      content = file("${path.root}/files/dependabot.yml")
    }
    "README.md" = {
      content = "Welcome to my project!"
      managed = false
    }
  }
}

The map key refers to the file path in the repository, and the content field contains the file content. By default, files created using this method are managed by Terraform, but this can be changed by setting the managed field to false, meaning any changes done outside of Terraform will be ignored.

The default behaviour is for any branch created by this branch to inherit the default branch protection settings (var.default_branch_protection), but this can be overridden by either settings the branch_protection key or disabling branch protection by setting the use_branch_protection field to false.

To override the default branch protection settings, specify the branch_protection key:

module "mcaf-repository" {
  source = "schubergphilis/mcaf-repository/github"

  name = "my-repo"

  branches = {
    "develop" = {
      branch_protection = {
        enforce_admins         = true
        require_signed_commits = true
      }
    }
  }
}

In the event you want to create branches using Terraform but do not want any branch protection to be configured, you can set use_branch_protection to false:

module "mcaf-repository" {
  source = "schubergphilis/mcaf-repository/github"

  name = "my-repo"

  branches = {
    "develop" = {
      use_branch_protection = false
    }
  }
}

For more examples, see the branches examples.

References to URLs, issues, pull requests, and commits are automatically shortened and converted into links. You can configure custom autolink references for a repository using the autolink_references variable.

You define custom autolinks by specifying a reference prefix and a target URL using var.autolink_references:

module "mcaf-repository" {
  source = "schubergphilis/mcaf-repository/github"

  name = "my-repo"

  autolink_references = {
    "JIRA" = { url_template = "https://my-jira-instance.atlassian.net/browse/<num>" }
  }
}

In the above example, JIRA-123 is converted to https://jira.example.com/issue?query=123 when viewing comments or commit messages.

Enviroments can be configured using the var.environments variable. This allows you to create environments with secrets, variables, and deployment policies.

You can also call the module directory, see its [README] for more details, or see the environments examples.

This module manages repository access by granting access to pre-existing teams. To grant a team access, populate the access map, using the team name as the key and the desired level as the value, for example:

module "mcaf-repository" {
  source = "schubergphilis/mcaf-repository/github"

  name = "my-repo"

  access = {
    MyTeam   = "maintain"
    Everyone = "push"
  }
}

The module will use a data resource to look up the team ID and assign the team the desired permissions.

resource "github_team" "myteam" {
  name = "MyTeam"
}

module "mcaf-repository" {
  source = "schubergphilis/mcaf-repository/github"

  name = "my-repo"

  access = {
    MyTeam   = "maintain"
    Everyone = "push"
  }

  depends_on = [github_team.myteam]
}

By default, the module will enable squash merges and disable merge commits and rebase merges. You can change this by setting the allow_merge_commit, allow_rebase_merge and allow_squash_merge variables to true or false.

To more easily select a single strategy, you can set the merge_strategy variable to one of the following values:

• merge
• rebase
• squash

Using merge_strategy will override the above variables.

It is possible to create (and manage) files within a GitHub repository using this module. We have a repository_files variable that takes a map of files to create; the key represents the name (and path) for the file, and the value is an object with the following attributes:

• branch: optional value to specify the branch, defaults to the default branch
• content: content of the file, can be a string or string sourced from a file or template using file() or templatefile() respectively.
• managed: whether Terraform should manage this file, or if it is a one time commit and any changes done outside of Terraform, defaults to true
• overwrite_on_create: whether to overwrite the file if it already exists when creating it, defaults to false

Example:

module "mcaf-repository" {
  source = "schubergphilis/mcaf-repository/github"

  name = "my-repo"

  repository_files = {
    "README.md" = {
      content = "# My repo"
      managed = false
    }
    ".github/workflows/ci.yml" = {
      content = templatefile("${path.module}/ci.yml.tpl", { name = "My repo" })
    }
    "docs/index.md" = {
      content = file("${path.module}/index.md")
    }
  }
}

map(object({
    is_alphanumeric = optional(bool, false)
    url_template    = string
  }))

map(object({
    source_branch         = optional(string)
    source_sha            = optional(string)
    use_branch_protection = optional(bool, true)

    branch_protection = optional(object({
      allows_force_pushes    = optional(bool, false)
      enforce_admins         = optional(bool, false)
      require_signed_commits = optional(bool, true)

      required_checks = optional(object({
        strict   = optional(bool)
        contexts = optional(list(string))
      }))

      restrict_pushes = optional(object({
        blocks_creations = optional(bool)
        push_allowances  = optional(list(string))
      }))

      required_reviews = optional(object({
        dismiss_stale_reviews           = optional(bool, true)
        dismissal_restrictions          = optional(list(string))
        pull_request_bypassers          = optional(list(string))
        require_code_owner_reviews      = optional(bool, true)
        require_last_push_approval      = optional(bool, null)
        required_approving_review_count = optional(number, 2)
      }))
    }), null)
  }))

map(object({
    property_name  = string
    property_type  = string
    property_value = list(string)
  }))

object({
    allows_force_pushes    = optional(bool, false)
    enforce_admins         = optional(bool, false)
    require_signed_commits = optional(bool, true)

    required_checks = optional(object({
      strict   = optional(bool)
      contexts = optional(list(string))
    }))

    required_reviews = optional(object({
      dismiss_stale_reviews           = optional(bool, true)
      dismissal_restrictions          = optional(list(string))
      pull_request_bypassers          = optional(list(string))
      require_code_owner_reviews      = optional(bool, true)
      require_last_push_approval      = optional(bool, null)
      required_approving_review_count = optional(number, 2)
    }))

    restrict_pushes = optional(object({
      blocks_creations = optional(bool)
      push_allowances  = optional(list(string))
    }))
  })

{
  "enforce_admins": false,
  "require_signed_commits": true,
  "required_reviews": {
    "dismiss_stale_reviews": true,
    "require_code_owner_reviews": true,
    "required_approving_review_count": 2
  }
}

map(object({
    secrets    = optional(map(string), {})
    variables  = optional(map(string), {})
    wait_timer = optional(number, null)

    deployment_policy = optional(object({
      branch_patterns = optional(set(string), [])
      tag_patterns    = optional(set(string), [])
    }))

    reviewers = optional(object({
      teams = optional(list(string)) # Use team names here
      users = optional(list(string)) # Use user names here
    }))
  }))

object({
    build_type = string
    branch     = optional(string)
    cname      = optional(string)
    path       = optional(string, "/")
  })

map(object({
    branch              = optional(string)
    commit_message      = optional(string)
    commit_prefix       = optional(string)
    content             = string
    managed             = optional(bool, true)
    overwrite_on_create = optional(bool, false)
    skip_ci             = optional(bool, false)
  }))

object({
    owner      = string
    repository = string
  })

object({
    default_workflow_permissions     = optional(string, null)
    can_approve_pull_request_reviews = optional(bool, false)
  })

100% Open Source and licensed under the Apache License Version 2.0. See LICENSE for full details.