How it works

Agents live in separate networks and dial out. The orchestrator never needs a path in.

1. A PR comment like terraplane plan -s stg-apse2-foundation hits the orchestrator.
2. The orchestrator reads terraplane.yaml from the repo, resolves the stack to its environment and agent, and enqueues a job.
3. An agent in that stack’s network polls the orchestrator, claims the job, and runs Terraform.
4. The agent posts the result back; the orchestrator updates the PR.

Each agent only needs outbound HTTP to the orchestrator. Agents can sit in entirely different networks, accounts, or environments — routing is declared in terraplane.yaml, not by punching holes inward.

Repo config

terraplane.yaml is environment-scoped. Stacks live under an environment, which sets the default agent. Agent can be overridden per-stack, and stack names must be globally unique.

environments:
  - name: staging
    agent: agent-dev
    stacks:
      - name: stg-apse2-foundation
        dir: terraform/environments/staging/ap-southeast-2/foundation
      - name: stg-apse2-platform
        dir: terraform/environments/staging/ap-southeast-2/platform

Target by stack name (-s) or environment (-e/-env), or combine both.

What the orchestrator owns

• SCM webhook verification and event handling
• Job and lock state (Postgres)
• Enqueuing work for agents to claim
• Writing results back to the PR
• Reaping expired job claims on a timer

What agents own

• Polling the orchestrator (AGENT_ORCHESTRATOR_URL) for available jobs
• Claiming a job, sending heartbeats, submitting results via HTTP
• Cloning with the configured deploy key
• Running plan / apply in the stack directory

That boundary is intentional: keep secrets and network reachability with the agent, keep SCM-facing coordination with the orchestrator. No inbound connections into the agent networks, no long-lived sockets.