Core concepts

GantryCD has a small vocabulary. Learn these six words and the rest of the docs read easily.

The vocabulary

Organization — the top-level boundary. Everything — stacks, runner groups, members, integrations — belongs to exactly one organization. Switching orgs in the UI switches which resources you see.

Stack — a single unit of OpenTofu state. It points at a repository, a branch, a working directory, an OpenTofu version, and a set of labels. A stack is the thing you deploy.

Deployment — one user-visible workflow against a stack: plan this, destroy that, refresh state. A deployment moves through stages (for example plan → confirmation → apply) and is what you watch in the UI.

Run — the executable unit inside a deployment that a runner actually performs. A plan deployment has a plan run; after you confirm, it gets an apply run. Runs carry the status you see ticking over: queued, running, success.

Runner group — a long-lived coordinator that brings ephemeral runners online to perform runs. You operate runner groups; they are where your OpenTofu actually executes.

Ephemeral runner — a short-lived worker that performs exactly one run, then disappears. It clones the repo, runs OpenTofu, uploads logs and the plan, and deregisters.

How a change flows

The end-to-end path from a commit to applied infrastructure:

  git push / open PR
        │
        ▼
  ┌───────────────┐   plan succeeds, has changes   ┌──────────────┐
  │  Plan run     │ ─────────────────────────────▶ │ Confirmation │
  │  (a runner    │                                │ (you review  │
  │  executes)    │   no changes → finished        │  the plan)   │
  └───────────────┘                                └──────┬───────┘
                                                          │ confirm
                                                          ▼
                                                   ┌──────────────┐
                                                   │  Apply run   │
                                                   │  (a runner   │
                                                   │  executes)   │
                                                   └──────────────┘

1. A push to the stack’s tracked branch (or a manual trigger) creates a deployment in plan mode.
2. The backend queues a run. A runner group whose labels match the stack picks it up and launches an ephemeral runner.
3. The runner clones the repo, runs tofu plan, and uploads the result. If the plan has no changes, the deployment finishes right there.
4. If it has changes, the deployment waits at a confirmation step.
5. You review the plan and confirm. GantryCD creates an apply run, a runner executes tofu apply, and the deployment finishes.

Destroy and refresh follow the same shape with their own OpenTofu command.

Two ideas worth internalizing early

Labels select where a run executes

A stack carries labels. Keys under the reserved gantrycd:runner-group: prefix form its runner selector — the set of capabilities a runner group must advertise to be eligible. It works like Kubernetes node selectors: a run goes to a group only if every pair in its selector is present on that group’s labels. This is how you pin a stack to, say, a specific region or network. A stack with no such labels falls back to the organization’s default runner group.

See Runner groups.

One active deployment per stack

A stack can have only one state-changing deployment running at a time. If a second one is triggered while the first holds the lock, it waits in queued and is promoted automatically when the lock frees. Pull-request preview plans are the exception — they never take the lock, so they run alongside everything else.

See Deployments.