Terraform provider

The GantryCD provider lets OpenTofu manage GantryCD itself. It supports stacks, contexts, runner groups, cloud access, roles, service accounts, and related settings.

Add it like any other provider:

terraform {
  required_providers {
    gantrycd = {
      source = "providers-preview-yuq4ybx.gantrycd.io/gantrycd/gantrycd"
    }
  }
}

provider "gantrycd" {}

The provider reads these variables when they are not set in the provider block:

GANTRYCD_API_URL
GANTRYCD_ORG_ID
GANTRYCD_PAT

Set them when running OpenTofu outside GantryCD.

Inside a GantryCD deployment, no token setup is needed. The runner sets the variables with a short-lived token for the stack’s service account. Roles on that account decide which GantryCD resources the code may change.

Use a normal service account token for OpenTofu that runs in another CI system. Do not put the token in .tf files or state.

The provider source, examples, and current resource schemas are in terraform-provider-gantrycd.

For a common use of the provider inside GantryCD, see Stacks of stacks.

Manage authorization labels

Use authz_labels on a stack, context, runner group, or standalone service account, and authz_label in a custom role permission:

resource "gantrycd_context" "payments" {
  name         = "payments"
  authz_labels = ["team-payments"]
}

resource "gantrycd_role" "payments_reader" {
  name = "payments-reader"

  permission {
    resource_type = "context"
    action        = "read"
    authz_label    = "team-payments"
  }
}

The provider owns each resource’s complete authorization label set. Removing authz_labels from configuration or setting [] removes all labels. Include existing labels when importing a resource if you want to retain them. Ordinary labels metadata is a separate field.

The credential running the provider needs permission to create or update the resource and assign_label for every authorization label it adds or removes. A grant targets one exact label; omit the permission’s authz_label to grant the action across the resource type. See Access for the matching rules and Stacks of stacks for scoped creation.

Upgrade from name-based permissions

Upgrade the backend to the label-only release before applying with the updated provider. Replace removed permission.resource_pattern fields with exact authz_label grants and set matching labels on the resources. Old fields are rejected; names and glob patterns no longer select authorization targets.

The backend cutover clears old custom permissions. Reapply custom roles after upgrading; built-in roles are restored automatically. An administrator can use the built-in admin role to apply the initial labels and grants.