GitHub Actions Runner stack for Kubernetes

All notable changes to this project are documented here.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

v5.2.0 - 2026-09-02

Changed

• default GitHub Actions Runner Controller and runner scale set Helm charts and application version from 0.13.0 to 0.14.2

v5.1.0 - 2026-03-04

Added

• an option to restrict the controller to only watch resources in a single namespace by means of watch_single_namespace parameter for the controller variable (disabled by default)

v5.0.0 - 2026-02-23

NOTE Make sure that other modules in the project support the new (major) hashicorp/kubernetes and hashicorp/helm Terraform providers versions, see the Upgrade Notes section

BREAKING CHANGE: GitHub Actions Runner Controller and runner are replaced with scale sets in place of legacy mode utilized in previous versions. Upgrade requires full setup re-creation, see the Upgrade Notes section

Added

• an option to toggle cluster role binding by means of assign_cluster_role parameter for the controller variable (enabled by default)
• validation blocks to check name_prefix and runner names

Changed

• minimal Helm Terraform provider version to v3.1
• minimal Kubernetes Terraform provider version to v3.0
• minimal Terraform version to v1.9
• controller and runner deployment mode from legacy to scale sets
• legacy controller Helm chart and runner CRs to scale set controller and scale set runner charts

• controller and github_runners variables in accordance with the new Helm charts

• tf-k8s-crd module dependency, RunnerDeployment, and HorizontalRunnerAutoscaler CRs management

• github_token variable

v4.0.0 - 2024-07-03

(Last version compatible with Helm and Kubernetes Terraform providers v2.0)

BREAKING CHANGE: now GitHub Runner and runner autoscaler Kubernetes manifests management is covered by tf-k8s-crd module, which is incompatible with previous versions. Upgrade from an older version is possible with manual changes, see Upgrade Notes section

Added

• tf-k8s-crd module dependency

Changed

• IAM resource management - moved from "plain" resources to IAM module

v3.0.0 - 2023-02-22

BREAKING CHANGE: now all kubernetes provider resources use versioned resources which aren't compatible with previous version

NOTE: After module upgrade to v2.0 all kubernetes provider resources and other resources that depend on them will be recreated, or they can be reimported to TF state manually, see Upgrade Notes section

Changed

• use versioned Kubernetes provider resources instead of standard ones in order to satisfy requirements of future updates of providers
• code refactoring

v2.0.0 - 2022-11-18

BREAKING CHANGE: now all Kubernetes manifest resources are managed by kubectl provider instead of kubernetes which are't compatible with previous version

NOTE: After module upgrade to v2.0 all Kubernetes manifest resources will be recreated, or they can be reimported to TF state manually, see Upgrade Notes section

Added

• dependency function to make the setup more reliable
• kubectl provider dependency

Changed

• swapped kubernetes_manifest resource with kubectl_manifest
• tuned scaling conditions

Fixed

• bug when module fails while Kubernetes cluster is not created

v1.0.1 - 2022-11-16

Changed

• autoscaling metric conditions
• validation for github_runners[*].organization and github_runners[*].repo variables

v1.0.0 - 2022-11-08

First stable version

Added

• ability to deploy GitHub Actions Runner Controller and GitHub Runners with an opportunity of autoscaling
• options for setting a custom and/or flexible conditions for both resources

From v1.x to v2.x

Now all Kubernetes manifest resources are managed by kubectl provider instead of kubernetes. This approach is used to avoid cases when while deploying the module and the Kubernetes cluster at the same time, Kubernetes manifests are failing. The simplest, non-destructive way to upgrade is to remove the old kubernetes provider resource from state and import this resource as a kubectl provider resource, like so:

 bash# Re-import runner manifest
terraform state rm module.github_runner.kubernetes_manifest.runner[0]
terraform import module.github_runner.kubectl_manifest.runner[0] actions.summerwind.dev/v1alpha1//RunnerDeployment//k8s-runners-0//github-runner-controller
# Re-import autoscaler manifest
terraform state rm module.github_runner.kubernetes_manifest.autoscaler[0]
terraform import module.github_runner.kubectl_manifest.autoscaler[0] actions.summerwind.dev/v1alpha1//HorizontalRunnerAutoscaler//runner-deployment-autoscaler-0//github-runner-controller

From v2.x to v3.x

Now all kubernetes provider resources use versioned resources. According to kubernetes provider's suggestions the simplest, non-destructive way to do this is to remove the old resource from state and import this resource as a version one, like so:

 bash# If Kubernetes namespace was managed by the module, it must be re-imported
terraform state rm module.github_runner.kubernetes_namespace.github_runner[0]
terraform import module.github_runner.kubernetes_namespace_v1.github_runner[0] github-runner-controller

From v3.x to v4.x

The module from v4.0 has switched from "plain" kubectl_manifest resources for GitHub Runner and runner autoscaler management to the module for CRD (Custom Resource Definitions) management. This results in a resource reference mismatch.
The CRD module uses alekc/kubectl provider instead of gavinbunney/kubectl. It means that the provider for all existing resources within your state must be updated and the following steps must be performed:

1. Change the required_providers sections in your main code to reflect the usage of alekc/kubectl
2. Do the following command to make the replace on all existing resources in your state:

 bashterraform state replace-provider gavinbunney/kubectl alekc/kubectl

3. Make terraform use new provider:

 bashterraform init

Then, TF state references of GitHub Runner and runner autostaler can be updated like so:

 bashterraform state mv module.runner_controller.kubectl_manifest.runner[0] module.runner_controller.module.runner[0].kubectl_manifest.crd
terraform state mv module.runner_controller.kubectl_manifest.autoscaler[0] module.runner_controller.module.runner[0].data.kubernetes_resource.crd

From v4.x to v5.x

Module from v5.0 has changed the runners declaration from a list of objects to a map of objects and now requires a token for each repository.

 hclmodule "runner_controller" {
  ...
  # from v4.x format
  github_token = "ghp_token"

  github_runners = [
    {
      repo = "repo-owner/repo-name"
    },
  ]
  # to v5.0 format
  ...
  github_runners = {
    repo-runner = {
      github_config_url = "https://github.com/repo-owner/repo-name"
      github_token      = "ghp_token"
    }
  }
}

Module from v5.0 has changed Helm and Kubernetes Terraform providers versions, which aren't compatible with an old version. After the module version is upgraded, re-init the module to upgrade the provider versions.

Upgrade the following Terraform provider versions on the project level:
* hashicorp/kubernetes to ~> 3.0
* hashicorp/helm to ~> 3.1

 hclterraform {
  required_providers {
    helm = {
      source  = "hashicorp/helm"
      version = "~> 3.1"
    }

    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "~> 3.0"
    }
  }
}

Upgrade project dependencies:

 bashterraform init --upgrade

If set, rewrite custom values passed to the cert-manager Helm Chart as nested maps following the below example.

Before:

 hclmodule "runner_controller" {
  ...
  controller = {
    custom_values = [
      {
        name  = "fullnameOverride"
        value = "bar"
      },
      {
        name  = "image.pullPolicy"
        value = "Always"
      },
    ]
  }
  ...
}

After:

 hclmodule "runner_controller" {
  ...
  controller = {
    custom_values = {
      fullnameOverride = "bar"

      image = {
        pullPolicy = "Always"
      }
    }
  }
  ...
}

• node_selector input doesn't require anymore escaping of the dot (.) symbol:

 hclmodule "runner_controller" {
  ...
  # from v1.x format
  controller = {
    node_selector = {
      "node\\.kubernetes\\.io/instance-type" = "m5.large"
    }
  }

  # to v2.0 format
  controller = {
    node_selector = {
      "node.kubernetes.io/instance-type" = "m5.large"
    }
  }
  ...
}

Apply the changes to make sure the state of the resources is up-to-date with the new provider version:

 bashterraform apply