Skip to content
GantryCD Provider

gantrycd_runner_group (Resource)

A GantryCD runner group: a pool of worker processes addressable by label set. self-hosted groups return a one-time private_key; github-actions groups have GantryCD dispatch a GitHub workflow as the runner instead.

Example Usage

# Self-hosted (the default): runners register with the one-time private_key
# returned at creation. Capture it from state or an output right away.
resource "gantrycd_runner_group" "standard" {
  name         = "standard"
  labels       = { tier = "standard" }
  authz_labels = ["platform"]
}

output "standard_runner_private_key" {
  value     = gantrycd_runner_group.standard.private_key
  sensitive = true
}

# github-actions: GantryCD dispatches the workflow and that run plays the
# runner role, so no self-hosted process is needed.
resource "gantrycd_runner_group" "ci" {
  name   = "ci"
  type   = "github-actions"
  labels = { tier = "ci" }

  github_config {
    repository_owner    = "example"
    repository_name     = "infrastructure"
    workflow_file       = "gantrycd.yml"
    workflow_ref        = "main"
    max_concurrent_runs = 5
    app_id              = 123456
    private_key         = var.github_app_private_key
  }
}

Schema

Required

  • name (String) Group name. Requires replacement because the Update API only accepts label and github_config edits.

Optional

  • authz_labels (Set of String) Protected authorization labels, matched exactly by role grants. Owns the full set; omit or set [] to clear. Adding or removing a label requires runner_group:assign_label for that label, in addition to permission to create or update the resource. Separate from ordinary metadata labels.
  • github_config (Block, Optional) GitHub Actions provider config. Required when type is github-actions; must be omitted otherwise. (see below for nested schema)
  • labels (Map of String) Labels every runner in the group inherits, as key=value pairs.
  • type (String) How the group sources runners: self-hosted (default) or github-actions. Requires replacement.

Read-Only

  • connection_status (String) Aggregate connection status (e.g. connected / disconnected).
  • id (String) Server-assigned group UUID. Used as the Terraform import id.
  • identity_realm (String) Identity realm inherited from the configured provider.
  • last_dispatch_error (String) Why the group most recently failed to bring a runner online; null once a runner successfully comes online. Most relevant for github-actions groups, where a workflow_dispatch can fail synchronously.
  • last_dispatch_error_at (String) RFC3339 timestamp of the most recent dispatch failure; null if there is none.
  • private_key (String, Sensitive) PEM-encoded private signing key returned by the Create API for self-hosted groups. Null for github-actions groups. Re-derivation is impossible — terraform import will leave this null; rotate via the CLI to obtain a fresh value.
  • runner_count (Number) Number of runners currently registered in the group.

Nested Schema for github_config

Optional:

  • app_id (Number) GitHub App ID used to mint an installation token at dispatch time.
  • max_concurrent_runs (Number) Maximum number of workflow runs dispatched concurrently. Defaults to 5.
  • private_key (String, Sensitive) RSA PEM private key of the GitHub App. Write-only: the API never returns it, so it is preserved from state on Read and is null after import.
  • repository_name (String) Repository containing the dispatch workflow.
  • repository_owner (String) GitHub org or user that owns the workflow repository.
  • workflow_file (String) Workflow file to dispatch, e.g. gantrycd.yml. Must end in .yml or .yaml.
  • workflow_ref (String) Branch, tag, or SHA to dispatch the workflow against. Defaults to main.

Import

Import is supported using the following syntax:

The terraform import command can be used, for example:

# Import by runner group id. Key material (private_key, github_config.private_key)
# is never returned by the API and stays null after import.
terraform import gantrycd_runner_group.standard rg_01HXXXXXXXXXXXXXXXXXXXXXXX