Managing GitHub with Terraform (and GitHub!)

Here we define the inputs for the module, and sensible defaults:

variable "name" {
  description = "Name of the repository to be created."
  type        = string
}

variable "description" {
  description = "Description we should give to the repository"
  type        = string
}

variable "archived" {
  description = "If the repository is archived or not."
  type        = bool
  default     = false
}

variable "topics" {
  default     = null
  description = "An array of topic names to be added to the repository"
  type        = list(string)
}

variable "visibility" {
  default     = "private"
  description = "Determines repository visibility"
  type        = string
  validation {
    condition = anytrue([
      var.visibility == "private",
      var.visibility == "public"
    ])
    error_message = "Visibility must be either 'private' or 'public'"
  }
}

variable "open_source" {
  description = "If the repository should be licensed as open source or not."
  type        = bool
  default     = false
}

variable "codeowners" {
  description = "Additional codeowners for the repository"
  type        = list(string)
  default     = null
}

Here, we transform our variables - where needed - to the values we actually want to use within the module and define default codeowners across the organisation. For this module, we simply want to take the list of codeowners we get given and transform them into valid CODEOWNER file entries, whilst codeowners are hard-coded to GitHub usernames. In larger organisations, it’d probably be better to manage this via teams but it’s suitable enough for my needs.

locals {
  codeowners        = var.codeowners == null ? null : formatlist("# Codeowner managed by sudoblark.terraform.github\n* %s", var.codeowners)
  codeowners_string = var.codeowners == null ? null : join("\n", local.codeowners)

  default_codeowners = [
    "* @benjaminlukeclark"
  ]
  default_codeowners_string = join("\n", local.default_codeowners)
}

A bit of explanation may be needed here. The var.codeowners == null ? <true> : <false> syntax is how terraform implements ternary operators, although it calls it a conditional expression. So, put simply, if var.codeowners is null then local.codeowners and local.codeowners_string is also null but if not then we dynamically create valid codeowner entries. We’ll cover some examples in file.tf.

This simply defines our required providers, required as the GitHub provider has an unexpected feature.

terraform {
  required_providers {
    github = {
      source  = "integrations/github"
      version = "~> 4.0"
    }
  }
}

These define default licensing for Sudoblark Ltd GitHub repositories, based on if they’re open or closed source.

This defines data needed for the module. As branch_protection.tf relies on the main branch being created - which takes a while - we set references to the main branch here such that terraform waits until that branch has been auto-created. If we didn’t do this, then downstream dependencies with hard-coded references to main might fail as they would be referencing an object that has not yet been created via the GitHub RESTAPI. So instead, we set this reference via a data object and implicit dependency detection does the rest.

data "github_branch" "main" {
  # Get reference to main branch for repository, which should be created automatically.
  # So using this ensures we wait till repo is fully created before doing more things.
  repository = github_repository.repository.name
  branch     = "main"
}

Perhaps the most important file. This actually makes the repository, with some hardcoded defaults (which we want to hard-code across the entire organisation, but are very easy to amend if we need to in the future via simple Boolean variables)

resource "github_repository" "repository" {
  name                   = var.name
  description            = format("%s%s", var.description, " - repo managed by sudoblark.terraform.github")
  allow_squash_merge     = true
  allow_rebase_merge     = false
  archived               = var.archived
  auto_init              = true
  delete_branch_on_merge = true
  topics                 = var.topics == null ? null : var.topics
  visibility             = var.visibility
  has_downloads          = true
  has_projects           = true
  has_issues             = true
  has_wiki               = true
}

Notice the description. Here, we’re making it abundantly clear how this repository is managed in case anyone comes across it and wonders how to change merge request settings, license files, codeowners etc.

Here, we protect the main branch of our repository. You’ll be horribly surprised how many places don’t protect their main branch. For now it’s hard-coded, but it’d be simple enough to have this resource take in a map of maps (similar to Python’s ability to do nested dictionaries) of any number of branch protection rules on a per repo basis. For example, you could have default main branch protections but protect additional development branches for some repos, for others require more reviewers, etc. But perfection is the enemy of progress, and for my particular use case I can just hard-code the main protections and improve iteratively if needed:

resource "github_branch_protection" "main" {
  repository_id                   = github_repository.repository.node_id
  allows_deletions                = false
  enforce_admins                  = false
  pattern                         = data.github_branch.main.branch
  require_conversation_resolution = true
  required_linear_history         = false

  required_status_checks {
    strict = true
  }

  required_pull_request_reviews {
    dismiss_stale_reviews           = true
    require_code_owner_reviews      = true
    required_approving_review_count = 1
  }
}

Here, we create LICENSE.txt and CODEOWNER files for every repository based on var.open_source and the calculated codeowner_string items in local.tf from earlier:

resource "github_repository_file" "license" {
  repository          = github_repository.repository.name
  branch              = data.github_branch.main.branch
  file                = "LICENSE.txt"
  content             = var.open_source ? file("${path.module}/open_source.txt") : file("${path.module}/closed_source.txt")
  commit_message      = "license.txt - managed by sudoblark.terraform.github"
  overwrite_on_create = true
}

resource "github_repository_file" "repository_codeowners_file" {
  repository          = github_repository.repository.name
  branch              = data.github_branch.main.branch
  file                = ".github/CODEOWNERS"
  content             = <<EOT
# Default owners for all the things in the repo - managed by sudoblark.terraform.github
${local.default_codeowners_string}
%{if local.codeowners_string != null}
${local.codeowners_string}
%{endif~}
  EOT
  commit_message      = "CODEOWNERS - managed by sudoblark.terraform.github"
  overwrite_on_create = true
}

For the license file, we use another ternary operator to use the content of open_source.txt if var.open_source is true else we use the content of closed_source.txt, whilst $(path.module) allows us to ensure these files are local to the repository module and not accidentally inject unknown text into our license files. If we wanted to open this up to allow custom licensing on a per repository basis this would be easy enough with similar logic to how we calculate codeowners in locals.tf.

EOT is Terraform’s version of a Here document. It lets us define a multi-line string in a readable manner, within which we’re using string templates to simply inject the multi-line strings generated in locals.tf. That’s a bit of a mouthful, so here’s a concrete example:

• With no var.codeowners defined a license file looks similar to below:

  # module.repositories["terraform.aws"].github_repository_file.repository_codeowners_file will be created
  + resource "github_repository_file" "repository_codeowners_file" {
      + branch              = "main"
      + commit_author       = (known after apply)
      + commit_email        = (known after apply)
      + commit_message      = "CODEOWNERS - managed by sudoblark.terraform.github"
      + commit_sha          = (known after apply)
      + content             = <<-EOT
            # Default owners for all the things in the repo - managed by sudoblark.terraform.github
            * @benjaminlukeclark
        EOT
      + file                = ".github/CODEOWNERS"
      + id                  = (known after apply)
      + overwrite_on_create = true
      + repository          = "terraform.aws"
      + sha                 = (known after apply)
    }

• Whilst if var.codeowners has items in its list, our locals.tf will dynamically generate a multi-line string with each codeowner on a new line. Which may result in a file similar to the below:

  # module.repositories["monsternames.open-api"].github_repository_file.repository_codeowners_file will be created
  + resource "github_repository_file" "repository_codeowners_file" {
      + branch              = "main"
      + commit_author       = (known after apply)
      + commit_email        = (known after apply)
      + commit_message      = "CODEOWNERS - managed by sudoblark.terraform.github"
      + commit_sha          = (known after apply)
      + content             = <<-EOT
            # Default owners for all the things in the repo - managed by sudoblark.terraform.github
            * @benjaminlukeclark
            
            # Codeowner managed by sudoblark.terraform.github
            * hello
            # Codeowner managed by sudoblark.terraform.github
            * world
        EOT
      + file                = ".github/CODEOWNERS"
      + id                  = (known after apply)
      + overwrite_on_create = true
      + repository          = "monsternames.open-api"
      + sha                 = (known after apply)
    }

name: Terraform checks on pull request

env:
  AWS_ACCESS_KEY_ID: ${{ secrets.SUDOBLARK_AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.SUDOBLARK_AWS_ACCESS_KEY_VALUE }}
  AWS_DEFAULT_REGION: eu-west-2
  # Automatically generated token unique to this repo per workflow execution
  REPO_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  # Explicitly provided token in ORG to access entire organisation
  ORG_GITHUB_TOKEN: ${{ secrets.SUDOBLARK_GITHUB_TOKEN }}

on: [pull_request]

permissions:
  contents: read
  pull-requests: write

jobs:
  validation:
    name: Terraform validate
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v3
        env:
          GITHUB_TOKEN: ${{ env.REPO_GITHUB_TOKEN }}

      - name: terraform validate
        uses: dflook/terraform-validate@v1

  linting:
    name: Terraform lint
    runs-on: ubuntu-20.04
    steps:
      - uses: actions/checkout@v3
        env:
          GITHUB_TOKEN: ${{ env.REPO_GITHUB_TOKEN }}

      - name: Install tflint
        uses: terraform-linters/setup-tflint@v3

      - name: Run tflint
        run: tflint

  plan:
    name: Terraform plan
    runs-on: ubuntu-20.04
    needs: [validation, linting]
    steps:
      - uses: actions/checkout@v3
        env:
          GITHUB_TOKEN: ${{ env.REPO_GITHUB_TOKEN }}

      - id: install-aws-cli
        uses: unfor19/install-aws-cli-action@v1

      - name: terraform plan
        uses: dflook/terraform-plan@v1
        env:
          GITHUB_TOKEN: ${{ env.ORG_GITHUB_TOKEN }}

name: Terraform apply

env:
  AWS_ACCESS_KEY_ID: ${{ secrets.SUDOBLARK_AWS_ACCESS_KEY_ID }}
  AWS_SECRET_ACCESS_KEY: ${{ secrets.SUDOBLARK_AWS_ACCESS_KEY_VALUE }}
  AWS_DEFAULT_REGION: eu-west-2
  # Explicitly provided token in ORG to access entire organisation
  GITHUB_TOKEN: ${{ secrets.SUDOBLARK_GITHUB_TOKEN }}

on:
  workflow_dispatch:
  schedule:
    - cron: 0 0 * * *
  push:
    branches:
      - main
    paths-ignore:
      - '.github/**'
      - 'LICENSE.txt'

permissions:
  contents: read
  pull-requests: write

jobs:
  apply:
    name: Terraform apply
    runs-on: ubuntu-20.04
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: terraform apply
        uses: dflook/terraform-apply@v1
        with:
          auto_approve: true