Runner group selectors

A runner group defines labels. A stack uses a selector with the same names and values.

Match a runner group

For example, a runner group may define:

region = eu-west
network = private
arch = amd64

A stack can select it with:

region = eu-west
network = private

Every item in the stack selector must match. The runner group may have extra labels, such as arch in this example.

Set group labels under Runner group → Settings → Routing labels. Set the stack selector under Stack → Options → Runner selector. Use only the short names there; GantryCD adds the gantrycd:runner-group: prefix to the stack labels.

If more than one available group matches, any of them can take the run. Add another selector when the choice matters.

Set the default

Use Runner groups → Default group to choose where stacks without a selector run. Without a default, any available group can take those runs.

With the Terraform provider, define the full stack labels and the default group:

resource "gantrycd_stack" "app" {
  # ...
  labels = {
    "gantrycd:runner-group:region"  = "eu-west"
    "gantrycd:runner-group:network" = "private"
  }
}

resource "gantrycd_default_runner_group" "default" {
  runner_group_id = gantrycd_runner_group.primary.id
}

Runner spec overrides

Runner spec overrides ask the selected runner group to change the runner it starts. The supported fields depend on that runner group’s implementation.

Today:

• Self-hosted Kubernetes groups receive the overrides documented below.
• GitHub Actions groups can be selected, but receive no runner spec overrides.

Add them under Stack → Options → Labels, or to the stack labels in the Terraform provider.

Kubernetes

Self-hosted Kubernetes groups installed with the Helm chart support these fields:

For example:

gantrycd:runner-spec:kubernetes_request_cpu = 500m
gantrycd:runner-spec:kubernetes_limit_cpu = 2
gantrycd:runner-spec:kubernetes_request_memory = 1Gi
gantrycd:runner-spec:kubernetes_limit_memory = 4Gi
gantrycd:runner-spec:kubernetes_image = ghcr.io/acme/gantrycd-runner:v1

CPU and memory use Kubernetes quantities. Any option you leave out keeps the runner group’s value.

The image label works only when the runner group Helm values include:

ephemeralRunner:
  allowStackImageOverride: true

Enable it only for stacks you trust. The selected image runs with the runner Pod’s service account and cloud access. Changes apply to new deployments.

GitHub Actions

GitHub Actions groups support runner group selectors, but no runner spec overrides. Set runs-on, the container image, and other compute options in the GitHub workflow instead.