Skip to content
GantryCD Provider

gantrycd_stack (Resource)

A GantryCD stack: a versioned reference to an OpenTofu working directory plus the runtime settings deployments inherit.

Example Usage

resource "gantrycd_runner_group" "standard" {
  name   = "standard"
  labels = { tier = "standard" }
}

resource "gantrycd_stack" "payments" {
  name              = "payments-production"
  repository_url    = "https://github.com/example/infrastructure"
  working_directory = "/payments"
  branch            = "main"
  opentofu_version  = "1.11.0"
  managed_backend   = true
  allow_local_plans = false

  # Plan/apply confirmation and the deployment queue. Omitted settings reset to
  # their defaults (manual modes, no timeouts, queued push replacement enabled)
  # on every apply.
  auto_approve_mode = "non_destructive"
  pr_plan_mode      = "manual"
  queue_policy = {
    supersede_after_seconds  = 1800
    disable_queued_supersede = false
  }

  # Protected authorization labels: IAM grants target these, not the name.
  authz_labels = ["team-payments", "env-production"]

  # `gantrycd:runner-group:*` labels select the runner group by label subset.
  labels = {
    "gantrycd:runner-group:tier" = gantrycd_runner_group.standard.labels["tier"]
    "cost-center"                = "payments"
  }

  # Gates evaluated against the pull request's SCM status. Omit it, or a gate,
  # to leave that gate open.
  promotion_requirements = {
    plan = {
      required_checks = ["ci/lint"]
    }
    promote = {
      approvals_min   = 2
      required_checks = ["ci/lint", "ci/test"]
    }
  }

  # Lifecycle hooks run around init/plan/apply in phase, then priority order.
  hook {
    name     = "notify-plan-start"
    phase    = "pre_plan"
    priority = 10
    script   = "echo \"planning $${STACK_NAME:-payments}\""
  }
}

Schema

Required

  • branch (String) Default branch the stack tracks.
  • name (String) Stack name. The server derives the stack id from the name, so changing it replaces the stack — see the resource docs.
  • opentofu_version (String) OpenTofu version the runner installs for every deployment.
  • repository_url (String) Git repository URL that hosts the OpenTofu code. SSH (git@host:owner/repo) and HTTPS forms that point at the same repo are treated as equal, matching the backend’s canonicalization.
  • working_directory (String) Subdirectory inside the repo to run OpenTofu against (“” for the root).

Optional

  • allow_local_plans (Boolean) When true, the stack accepts local plans uploaded via gantrycli local-plan. Opt-in per stack; defaults to false. Manage it here or the backend resets it to false on every stack update.
  • 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 stack:assign_label for that label, in addition to permission to create or update the resource. Separate from ordinary metadata labels.
  • auto_approve_mode (String) Whether a successful plan skips the manual confirmation: one of manual, auto, non_destructive. Defaults to manual. Manage it here or the backend resets it to manual on every stack update.
  • hook (Block List) A lifecycle hook: a bash script run at a phase of the stack’s tofu init/plan/apply. Repeatable; omit entirely to leave the stack with no hooks. Block order is preserved: it breaks ties between hooks sharing a phase and priority, and it means editing a hook shows as an in-place change rather than as one hook removed and another added. (see below for nested schema)
  • labels (Map of String) Stack labels as key=value pairs. gantrycd:runner-group:* keys drive runner-group selection for the stack’s deployments; other keys are free-form metadata.
  • managed_backend (Boolean) When true, GantryCD provisions and owns the state backend. When false, the stack must configure its own backend block. Defaults to true. Manage it here or the backend resets it to true on every stack update.
  • pr_plan_mode (String) Whether a pull request’s preview plan waits for a human to confirm it (manual) or runs as soon as the PR syncs (auto). Defaults to manual. Manage it here or the backend resets it to manual on every stack update.
  • promotion_requirements (Attributes) Plan/promote gates evaluated against a pull request’s SCM status. Omit it, or a gate, to leave that gate open. (see below for nested schema)
  • queue_policy (Attributes) Deployment aging and queued push replacement. Defaults to no timeouts and queued push replacement enabled. Omitting the attribute resets these defaults. (see below for nested schema)

Read-Only

  • id (String) Server-assigned stack UUID. Used as the Terraform import id.
  • identity_realm (String) Identity realm inherited from the configured provider.
  • revision (Number) Config version, bumped by every update. Sent back on update so a concurrent edit is refused rather than overwritten.

Nested Schema for hook

Required:

  • phase (String) Lifecycle phase the hook runs at: one of pre_init, post_init, pre_plan, post_plan, pre_apply, post_apply.
  • priority (Number) Ordering priority within the phase, 1-99. Lower runs first.
  • script (String) Bash script executed via bash -e -o pipefail -x -c.

Optional:

  • name (String) Optional label for the hook, surfaced in run logs.

Nested Schema for promotion_requirements

Optional:

  • plan (Attributes) Conditions a PR must satisfy before GantryCD will plan it. (see below for nested schema)
  • promote (Attributes) Conditions a PR must satisfy before its plan can be promoted (applied). (see below for nested schema)

Nested Schema for promotion_requirements.plan

Optional:

  • approvals_min (Number) Minimum number of approving reviews the PR must have. Must be at least 1 when set.
  • required_checks (List of String) CI check/context names that must all report success on the PR head. Must be non-empty when set.

Nested Schema for promotion_requirements.promote

Optional:

  • approvals_min (Number) Minimum number of approving reviews the PR must have. Must be at least 1 when set.
  • required_checks (List of String) CI check/context names that must all report success on the PR head. Must be non-empty when set.

Nested Schema for queue_policy

Optional:

  • confirmation_timeout_seconds (Number) Skip a deployment left waiting for confirmation longer than this many seconds. Omit to disable.
  • disable_queued_supersede (Boolean) When true, new pushes keep older queued push-origin deployments instead of replacing them. Defaults to false. The separate supersede-after aging policy still applies.
  • queued_timeout_seconds (Number) Skip a deployment left queued behind the stack lane longer than this many seconds. Omit to disable.
  • supersede_after_seconds (Number) When a new deployment is enqueued, skip older queued or waiting deployments older than this many seconds, so only the freshest work runs. Omit to disable.

Import

Import is supported using the following syntax:

The terraform import command can be used, for example:

# Import by stack id.
terraform import gantrycd_stack.payments stk_01HXXXXXXXXXXXXXXXXXXXXXXX