Skip to content
TerraplaneTerraplane

Configuration

Config is environment variables (optional .env via Viper). Defaults below are what the binary uses if unset.

Orchestrator

Section titled “Orchestrator”
Variable Default Role
ORCHESTRATOR_GITHUB_WEBHOOK_SECRET — GitHub webhook HMAC
ORCHESTRATOR_GITHUB_ACCESS_TOKEN — GitHub API (files, comments)
ORCHESTRATOR_LISTEN_ADDRESS 127.0.0.1 Bind address
ORCHESTRATOR_LISTEN_PORT 8080 Bind port
DATABASE_URL / DATABASE_DRIVER driver postgres Job/lock persistence
SHARED_AUTH_TOKEN — Orchestrator ↔ agent auth
SCM_PROVIDER github SCM backend (currently GitHub)
ORCHESTRATOR_DISPATCHER_JOB_POLL_INTERVAL 5s How often to poll for work / reap expired claims
ORCHESTRATOR_JOB_LEASE 2m How long a claimed job stays leased before it can be reclaimed
ORCHESTRATOR_JOB_CLEANUP_INTERVAL 720h Delete terminal jobs older than this
ORCHESTRATOR_JOB_CLEANUP_POLL_INTERVAL 1h How often to run that cleanup

Agent

Section titled “Agent”
Variable Default Role
AGENT_ID — Must match agent: in terraplane.yaml
AGENT_ORCHESTRATOR_URL http://127.0.0.1:8080 HTTP(S) base URL of the orchestrator
AGENT_SCM_SSH_KEY_PATH — Deploy key for clone
SHARED_AUTH_TOKEN — Must match the orchestrator
AGENT_POLL_INTERVAL 5s How often to ask for jobs
AGENT_HEARTBEAT_INTERVAL 30s Heartbeat while a job is in progress
AGENT_PERIODIC_COMMENT_INTERVAL 15s How often to snapshot plan/apply output for the live PR progress comment
AGENT_WORK_DIR — Working directory for clones and runs
AGENT_TERRAFORM_BIN_DIR — Where Terraform binaries are stored/downloaded
AGENT_DEFAULT_TERRAFORM_VERSION 1.15.6 Terraform version when a stack does not set tool_version

Shared / misc

Section titled “Shared / misc”
Variable Default Role
LOG_LEVEL info Log verbosity
SERVER_SHUTDOWN_TIMER 5s Orchestrator graceful shutdown window
AGENT_CLIENT_SHUTDOWN_TIMER 5s Agent graceful shutdown window

terraplane.yaml

Section titled “terraplane.yaml”

Environments set the default agent; stacks can override it. Stack names must be globally unique. Optional tool_version pins the Terraform binary for that stack (otherwise the agent uses AGENT_DEFAULT_TERRAFORM_VERSION).

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

See .env-example in the repository for a minimal local starting point.