GitLab Runner for Kubernetes

Module deploys GitLab Runner into a Kubernetes cluster via Helm.

Module optionally deploys GitLab agent into a Kubernetes cluster via Helm.

Once you have a Corewide Solutions Portal account, this one-time action will use your browser session to retrieve credentials:

 shellterraform login solutions.corewide.com

Provision instructions

Initialize mandatory providers:

Copy and paste into your Terraform configuration and insert the variables:

 hclmodule "tf_k8s_gitlab_ci_runner" {
  source  = "solutions.corewide.com/kubernetes/tf-k8s-gitlab-ci-runner/helm"
  version = "~> 2.4.0"

  # specify module inputs here or try one of the examples below
  ...
}

Initialize the setup:

 shellterraform init

Define update strategy

Corewide DevOps team strictly follows Semantic Versioning Specification to provide our clients with products that have predictable upgrades between versions. We recommend pinning patch versions of our modules using pessimistic constraint operator (~>) to prevent breaking changes during upgrades.

To get new features during the upgrades (without breaking compatibility), use ~> 2.4 and run terraform init -upgrade

For the safest setup, use strict pinning with version = "2.4.0"

Module 20% off	~~$1,200~~ $960
TOTAL	$960

BUY

1,329

Corewide Proprietary License

v2.4.0 released 1 month, 1 week ago

New version approx. every 24 weeks

Upgrade Notes

Changelog

Module deploys GitLab Runner into a Kubernetes cluster via Helm.

Module optionally deploys GitLab agent into a Kubernetes cluster via Helm.

All notable changes to this project are documented here.

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

v2.4.0 - 2026-09-17

Added

option to toggle the mounting of Docker socket in CI job pods by means of the job_pod_mount_docker_socket variable (enabled by default)

v2.3.0 - 2026-09-16

NOTE: GitLab Runner and agent might be upgraded, see the Upgrade Notes section

Changed

runner Helm chart (from 0.85.0 to 0.92.1) and application (from alpine-v18.8.0 to alpine-v19.3.2) default versions
agent Helm chart (from 2.23.0 to 2.31.0) and application (from v18.8.0 to v19.3.2) default versions
pipeline image default version from the latest common docker:dind to a specific docker:29.8-dind

v2.2.0 - 2026-09-02

Added

optional job_additional_labels variable for adding custom labels to pods created by GitLab Runner

v2.1.0 - 2026-03-04

Added

optional installation of the GitLab agent by means of the agent variable

v2.0.0 - 2026-02-19

BREAKING CHANGE: module inputs and resources management have a fundamentally new concept; module utilizes the new (major) Kubernetes and Helm providers' versions (make sure that other modules in the project support new Terraform providers' versions). Upgrade from an older version is possible with manual changes, see the Upgrade Notes section

Added

authentication_token variable for providing an authentication token in accordance with the updated runner registration workflow

Changed

Helm chart (from 0.56.0 to 0.85.0) and application (from alpine-v16.1.0 to alpine-v18.8.0) versions
minimal Kubernetes Terraform provider version to v3.0
minimal Helm Terraform provider version to v3.1

Removed

deprecated default_image variable
obsolete registration_token variable

v1.2.0 - 2024-03-22

(Last version compatible with Helm and Kubernetes Terraform providers version 2.0)

Added

optional node_selector and job_node_selector variables for GitLab Runner placement management
optional job_service_account_name_prefix variable for providing name prefix of Service Accounts allowed to be used in CI job pods
optional pipeline_image variable that will replace default_image in v1.5

Changed

code refactoring
updated chart and application versions
GitLab Runner base OS image to Alpine instead of Ubuntu

Deprecated

default_image variable in favour of pipeline_image and will be deleted in v1.5

Fixed

an issue with applying jobs concurrency

v1.1.0 - 2023-02-24

Added

app_version and chart_version variables for GitLab Runner management

Changed

code refactoring

v1.0.0 - 2022-12-23

First stable version

Added

ability to deploy GitLab Runner with customizable values
ability to create additional namespace for GitLab Runner components or use already existing one

From `v1.x` to `v2.x`

The module from v2.0 has several management changes that require attention:

registration_token input was replaced by the authentication_token in accordance with the updated runner registration workflow. A runner can be created, and its token can be fetched directly in the GitLab UI or programmatically
processing of the custom_values inputs

Update the declaration of the module according to the requirements and examples to match the designed configuration. Make sure that the mentioned inputs are updated with the new format:

replace registration_token with authentication_token and corresponding value
replace default_image with pipeline_image with the same value (this point is optional, and must be addressed only to continue using the custom container image to run pipeline steps in)
custom_values must be supplied as a single map with all subparameters instead of a map of Helm set array entities

```hcl
module "gitlab_runner" {
...
# from v1.x format
custom_values = {
"podLabels.managed-by" = "terraform"
"podLabels.environment" = "development"
}

 scdoc# to v2.0 format
...
custom_values = {
  podLabels = {
    managed-by  = "terraform"
    environment = "development"
  }
}

}
```

Changed Kubernetes and Helm Terraform providers versions, which aren't compatible with older versions. After the module version is upgraded, re-init the module to upgrade the providers versions. Upgrade the provider versions on the project level:

```hcl
terraform {
required_providers {
helm = {
source = "hashicorp/helm"
version = "~> 3.1"
}

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

}
```

Upgrade project dependencies:

bash terraform init --upgrade

Update the declaration of the module according to the requirements and examples to match the designed configuration, then the configuration can be applied.

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

 bashterraform apply

From `v2.2.x` to `v2.3.x`

Module from v2.3 has several adjustments that require attention:

runner Helm chart and application default versions are updated to 0.92.1 and alpine-v19.3.2, respectively. Review the Helm chart and application release notes if any custom runner configurations are applied
agent Helm chart and application default versions are updated to 2.31.0 and v19.3.2, respectively. Review the release notes if any custom agent configurations are applied
pipeline image default version changed from the latest common docker:dind to a specific docker:29.8-dind

You can skip this chapter if you have already used these versions or newer.
Now the configuration can be applied:

 bashterraform apply

Deploy GitLab Runner with mandatory values only:

 hclmodule "gitlab_runner" {
  source  = "solutions.corewide.com/kubernetes/tf-k8s-gitlab-ci-runner/helm"
  version = "~> 2.4"

  authentication_token = "glrt-aBCdef_123456-GhJkLMnOpQrSTU.78.90xyz"
}

Programmatically create a group runner and use the generated token for the authentication to the GitLab server:

NOTE: runner registration setup may differ based on the required runner type (group, project, or instance(shared)).

 hclresource "gitlab_user_runner" "main" {
  runner_type     = "group_type"
  group_id        = "1234567890"
  description     = "Main self-hosted runner"
  tag_list        = ["backend", "frontend"]
  untagged        = true
  maximum_timeout = 1800
  access_level    = "not_protected"
}

module "gitlab_runner" {
  source  = "solutions.corewide.com/kubernetes/tf-k8s-gitlab-ci-runner/helm"
  version = "~> 2.4"

  authentication_token = gitlab_user_runner.main.token
}

NOTE: GitLab provider must be authenticated with permissions to manage the CI runners.

Deploy GitLab Runner and GitLab agent with custom configuration:

 hclmodule "gitlab_runner" {
  source  = "solutions.corewide.com/kubernetes/tf-k8s-gitlab-ci-runner/helm"
  version = "~> 2.4"

  authentication_token = "glrt-aBCdef_123456-GhJkLMnOpQrSTU.78.90xyz"
  name_prefix          = "staging"
  gitlab_url           = "https://my-gitlab.com"
  namespace            = "ci"
  pipeline_image       = "alpine/git"
  chart_version        = "0.80.0-beta"
  app_version          = "ubi-fips"

  node_selector = {
    "eks.amazonaws.com/nodegroup" = "maintenance"
  }

  job_node_selector = {
    "eks.amazonaws.com/nodegroup" = "gitlab"
  }

  job_additional_labels = {
    "job_stage" = "$${CI_JOB_STAGE}"
  }

  custom_values = {
    podAnnotations = {
      "iam.amazonaws.com/role" = "arn:aws:iam::123456789012:role/application_abc/component_xyz/Access"
    }

    podLabels = {
      managed-by  = "terraform"
      environment = "development"
    }
  }

  agent = {
    enabled      = true
    access_token = "glagent-aBCdef_123456-GhJkLMnOpQrSTU.78.90xyz"

    custom_values = {
      replicas = 1

      podLabels = {
        managed-by  = "terraform"
        environment = "development"
      }
    }
  }
}

Variable	Description	Type	Default	Required	Sensitive
`authentication_token`	Authentication token for GitLab Runner	`string`		yes	yes
`name_prefix`	Name prefix for all the resources created by the module	`string`		yes	no
`agent`	GitLab agent parameters	`object`	`{}`	no	no
`agent.access_token`	GitLab agent access token	`string`		no	no
`agent.app_version`	GitLab agent application version	`string`	`v19.3.2`	no	no
`agent.chart_version`	GitLab agent chart version	`string`	`2.31.0`	no	no
`agent.custom_values`	Custom values for GitLab agent chart	`any`	`{}`	no	no
`agent.enabled`	Whether GitLab agent should be enabled	`bool`	`false`	no	no
`agent.kas_address`	GitLab Kubernetes agent server address	`string`	`wss://kas.gitlab.com`	no	no
`agent.node_selector`	Node selector to place GitLab agent pods in. If it is not provided, the runner node selector is used	`map(string)`	`{}`	no	no
`app_version`	GitLab Runner application version	`string`	`alpine-v19.3.2`	no	no
`chart_version`	GitLab Runner chart version	`string`	`0.92.1`	no	no
`concurrent_jobs`	Number of pipelines running at the same time	`number`	`4`	no	no
`create_namespace`	Indicates creation of dedicated namespace for GitLab Runner	`bool`	`true`	no	no
`custom_values`	Custom values for GitLab Runner	`any`	`{}`	no	no
`gitlab_url`	GitLab server URL to connect GitLab Runner to	`string`	`https://gitlab.com`	no	no
`job_additional_labels`	Additional labels to add to pipeline jobs spawned by GitLab Runner	`map(string)`	`{}`	no	no
`job_node_selector`	Node selector to place pipeline jobs spawned by GitLab Runner	`map(string)`	`{}`	no	no
`job_pod_mount_docker_socket`	Toggle the mounting of Docker socket in CI job pods	`bool`	`true`	no	no
`job_service_account_name_prefix`	Name prefix of Service Accounts allowed to be used in CI job pods	`string`	`gitlab-runner`	no	no
`namespace`	The namespace to install GitLab Runner into	`string`	`gitlab`	no	no
`node_selector`	Node selector to place GitLab Runner itself in	`map(string)`	`{}`	no	no
`pipeline_image`	Default container image to run pipeline steps in	`string`	`docker:29.8-dind`	no	no
`termination_period`	The duration in seconds that the pod has to terminate gracefully, after the job completed	`number`	`1800`	no	no