Panfactum LogoPanfactum
Infrastructure ModulesDirect ModulesKuberneteskube_gha
kube_gha_runners
Beta
Direct
Source Code Link

GHA Runners

This module provides deployments of self-hosted GHA runners that can be targeted in GHA workflows.

For installation instructions, see our guide.

Usage

Connecting the Runner to GitHub

Follow GitHub's documentation to provision a Classic Personal Access Token (PAT) with the correct permissions. Provide this token as an input via github_token.

For each runner, set the github_config_url to the URL of your repository, organization, or enterprise. This is the entity that the runners will belong to. We generally recommend making the runner available at the organization level so that all of your organization's repositories can use the runner in their GHA workflows.

Referencing the Runner in a Workflow

The runner's name is the key that you use specify in the runners input:

inputs = {
  runners = {
    default = {
      ...
    }
  }
}

After you apply this module, you can specify which GHA workflow jobs will use the runner as follows:

jobs:
  test:
    runs-on: default

Reducing Startup Times

By default, this module does not provision any idle runners. As a result, when new workflow jobs are created, the jobs are delayed by 1-2 minutes as runners initialize.

For each runner, you can set min_replicas to a non-zero value to allow idle runners in your cluster. These will be ready to receive new workflow jobs immediately and reduce your overall workflow runtimes. However, these will also consume their full amount of allocated resources (CPU, memory, storage) in the cluster while sitting idle.

Providers

The following providers are needed by this module:

  • helm (2.12.1)

  • kubectl (2.1.3)

  • kubernetes (2.34.0)

  • pf (0.0.5)

  • vault (4.5.0)

Required Inputs

The following input variables are required:

github_token

Description: The GitHub token that the runners will use to register with GitHub

Type: string

runners

Description: A mapping of runner names to their configuration values

Type:

map(object({
    github_config_url              = string # The url for the organization or repository that the runners will belong to
    min_replicas                   = optional(number, 0)
    max_replicas                   = optional(number, 25)
    action_runner_image_registry   = optional(string, "ghcr.io")
    action_runner_image_repository = optional(string, "actions/actions-runner")
    action_runner_image_tag        = optional(string, "latest")
    tmp_space_gb                   = optional(number, 1)   # The number of GB of disk space to allocate to the runner
    memory_mb                      = optional(number, 250) # The number of MB of memory to allocate to the runner
    cpu_millicores                 = optional(number, 100) # The number of millicores of cpu to allocate to the runner
    arm_nodes_enabled              = optional(bool, true)  # Whether to allow this runner to run on arm64 nodes
    spot_nodes_enabled             = optional(bool, true)  # Whether to allow this runner to run on spot nodes
  }))

Optional Inputs

The following input variables are optional (have default values):

extra_env_secrets

Description: A key-value mapping of extra secret environment variables for the runner pods

Type: map(string)

Default: {}

extra_pod_annotations

Description: Annotations to add to every runner pod

Type: map(string)

Default: {}

extra_pod_labels

Description: Labels to add to every runner pod

Type: map(string)

Default: {}

gha_runner_scale_set_helm_version

Description: The version of the actions-runner-controller-charts/gha-runner-scale-set helm chart to deploy

Type: string

Default: "0.9.3"

node_image_cache_enabled

Description: Whether to cache images locally for better startup performance

Type: bool

Default: true

panfactum_scheduler_enabled

Description: Whether to use the Panfactum pod scheduler with enhanced bin-packing

Type: bool

Default: true

pull_through_cache_enabled

Description: Whether to use the ECR pull through cache for the deployed images

Type: bool

Default: true

Outputs

No outputs.

Maintainer Notes

No notes.