Skip to content
TerraplaneTerraplane

Quickstart

Goal: orchestrator + agent up locally, a repo with terraplane.yaml, and a PR comment that plans.

1. Prerequisites

Section titled “1. Prerequisites”
  • Docker
  • A GitHub personal access token (orchestrator API access)
  • A webhook secret you’ll configure on the GitHub webhook
  • An SSH deploy key the agent can use to clone the Terraform repo

2. Run Terraplane

Section titled “2. Run Terraplane”
Terminal window
git clone https://github.com/terraplane-org/terraplane.git
cd terraplane
cp .env-example .env

Edit .env and set at least:

Terminal window
ORCHESTRATOR_GITHUB_ACCESS_TOKEN=...
ORCHESTRATOR_GITHUB_WEBHOOK_SECRET=...
AGENT_SCM_SSH_KEY_PATH=/absolute/path/to/deploy_key
SHARED_AUTH_TOKEN=some-shared-secret

Then:

Terminal window
docker compose up --build

Compose starts Postgres, migrates, and brings up the orchestrator on :8080. Agents (agent-dev, agent-prod) start polling the orchestrator over HTTP.

Confirm the orchestrator is healthy:

Terminal window
curl -f http://localhost:8080/health

3. Point GitHub at you

Section titled “3. Point GitHub at you”

Expose :8080 somehow (ngrok, Cloudflare Tunnel, Tailscale Funnel — your call) and add a repository webhook:

  • Payload URL: https://<your-tunnel>/scm/webhook
  • Content type: application/json
  • Secret: same as ORCHESTRATOR_GITHUB_WEBHOOK_SECRET
  • Events: Issue comments (PR review comments travel as issue comments)

4. Configure a Terraform repo

Section titled “4. Configure a Terraform repo”

In the repo you want Terraplane to manage, add terraplane.yaml. Stacks are grouped under named environments, which set the agent. 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

agent must match the AGENT_ID of a running agent (agent-dev in the default Compose file).

5. Plan from a pull request

Section titled “5. Plan from a pull request”

Open a PR, then comment:

terraplane plan -s stg-apse2-foundation

Plan all stacks in an environment:

terraplane plan -e staging

Terraplane will acknowledge the comment, run the plan, and post results back on the PR. When you’re ready:

terraplane apply -s stg-apse2-foundation

Stuck? Unlock and try again:

terraplane unlock -s stg-apse2-foundation

Next

Section titled “Next”