Automating GitHub configuration using Terraform

Securing your GitHub Organisation is crucial as it can contain sensitive code and data. It is therefore important to monitor contributors and contributions to ensure compliance and maintain code integrity. Manually managing GitHub configurations can be time-consuming and error-prone. Terraform provides a solution by allowing you to automate the setup and maintenance of GitHub Organisations, repositories, teams and permissions. By using Terraform for GitHub configuration, you can streamline workflows, improve security and ensure compliance with best practices. In this guide, we will take a look at the GitHub Terraform provider and build a secure and compliant environment for your GitHub infrastructure that meets Mondoo's security standards.

In our blog post about GitHub and Mondoo, we discussed how Mondoo can help you keep your GitHub repositories secure and compliant. If you want to automate the integration of your resources into Mondoo, check out our blog post about how to use Mondoo with Terraform. Mondoo can help you improve your infrastructure’s security and compliance by scanning for vulnerabilities and recommending best practice settings for your assets.

Prerequisites

• GitHub account
• GitHub organization
• Personal access token (PAT) with necessary permissions
• Terraform installed locally

Configuring the GitHub Provider

1. Install the GitHub Provider: Install the GitHub provider using the Terraform Registry. This provider is used to interact with GitHub's API and manage GitHub resources programmatically.

2. Configure the GitHub Provider: Configure the GitHub provider by setting the token and owner attributes. The token attribute should be set to your GitHub PAT, and the owner attribute should be set to the name of your GitHub organization.

    1terraform {
    2    required_providers {
    3        github = {
    4        source  = "integrations/github"
    5        version = "~> 6.0"
    6        }
    7    }
    8}
    9provider "github" {
   10    token = var.token
   11    owner = var.owner
   12}
   

Managing GitHub Resources

The GitHub Terraform provider allows you to manage various GitHub resources, including:

• Organisations
• Repositories
• Teams
• User Permissions
• Branch protection rules
• Projects
• Actions
• ...

We will now take a look at the creation of secure repositories and branch protection rules that align with Mondoo’s safety standards.

1. Create a GitHub Repository: Use the github_repository resource to create a new GitHub repository. This resource allows you to specify the repository name, description, visibility, and other security-related settings important for a high Mondoo asset score.

    1resource "github_repository" "secure_repo" {
    2    name        = "secure_repo"
    3    description = "Getting started: A secure repository with advanced security features. Authors: coolauthor"
    4    visibility = "public"
    5    default_branch = "main"
    6    has_issues   = true
    7    has_projects = true
    8    has_wiki     = true
    9    allow_merge_commit = true
   10    allow_squash_merge = false
   11    allow_rebase_merge = false
   12    allow_auto_merge   = true
   13    delete_branch_on_merge      = true
   14    web_commit_signoff_required = true
   15    has_downloads = false
   16    auto_init     = true
   17    archived           = false
   18    archive_on_destroy = false
   19}
   

2. Manage Repository Files: Use the github_repository_file resource to manage important files such as README, LICENSE, CODEOWNERS, support.md, security.md and code_of_conduct.md. This is an example implementation for a file:

    1resource "github_repository_file" "security_policy" {
    2    repository          = github_repository.secure_repo.name
    3    branch              = "main"
    4    file                = "security.md"
    5    content             = "This is a secure file."
    6    commit_message      = "Add security policy file"
    7    commit_author       = "Trusted User"
    8    commit_email        = "user@example.com"
    9    overwrite_on_create = true
   10}
   

   Note that the Mondoo checks expect filenames as stated above.

   A README file will be created automatically if you provide a repository description. Make sure to include a “Getting started:” and “Authors:” section in the README file.

   Ensure that the content of the CODEOWNERS file at least specifies code owners for the .github/workflows/ directory.

3. Manage Branch Protection Rules: Use the github_branch_protection resource to manage branch protection rules for your GitHub repository. This resource allows you to specify the branch name, enforce compliance, and set required pull request reviews.

    1resource "github_branch_protection" "branch_protection" {
    2    repository_id = github_repository.secure_repo.id
    3    pattern       = "main"
    4    enforce_admins                  = true
    5    require_signed_commits          = true
    6    require_conversation_resolution = true
    7    required_status_checks {
    8        strict   = true
    9        contexts = ["ci/mondoo"]
   10    }
   11    required_pull_request_reviews {
   12        dismiss_stale_reviews           = true
   13        restrict_dismissals             = true
   14        required_approving_review_count = 2
   15        require_code_owner_reviews      = true
   16        dismissal_restrictions = [
   17            "/user1",
   18        ]
   19    }
   20    restrict_pushes {
   21        push_allowances = [
   22            "/user1",
   23        ]
   24    }
   25    allows_force_pushes = false
   26}
   

These configurations will drastically enhance your repositories' security and provide you with a C rating for your assets in Mondoo. Unfortunately, the GitHub Terraform provider is unable to create new GitHub Actions workflows and therefore cannot pass all Mondoo checks. However, you can create new repositories using repository templates.

Repository Template

Repository templates are used to standardize and streamline the creation of new repositories with predefined configurations and settings. Although we cannot create workflows in Terraform, we can use predefined repositories that contain the missing security-related files. In this example, we use the template provided by a demo organisation we created, which already contains all the relevant settings and files. This is how we use the template within a new repository resource:

 1resource "github_repository" "template_example" {
 2    name        = "another_example"
 3    description = "My awesome codebase from a template."
 4    visibility  = "public"
 5
 6    template {
 7        owner                = "whatacoolorg"
 8        repository           = "demorepo"
 9        include_all_branches = true
10    }
11}

We can successfully pass all the Mondoo policy checks for GitHub after creating the new repository from a template and the branch protection rule.

Conclusion

In conclusion, securing your GitHub organization and repositories is critical to safeguarding sensitive code and data. Through the automation capabilities provided by Terraform, you can efficiently manage your GitHub infrastructure, enforce security standards, and ensure compliance with best practices. While some Mondoo checks may remain unaddressed due to limitations in creating GitHub Actions workflows via Terraform, leveraging repository templates can help bridge the gap and facilitate the creation of secure repositories from the beginning. By following the steps outlined in this guide and integrating Mondoo for vulnerability scanning and policy enforcement, you can elevate your GitHub security posture and mitigate potential risks effectively.