Quickstart

Early access. Stacks is rolling out behind an organization flag. If the surfaces below aren’t visible, ask us to enable Stacks for your organization.

You’ll need: a GitHub repository with an OpenTofu configuration, and Console access to your organization.

1. Create a Stack

A Stack is a repository + path + branch bound to one OpenTofu version and one state:

• Repository — where the configuration lives (private is fine; clones use short-lived installation tokens, never deploy keys).
• Path — the directory to run in; in a monorepo, only pushes touching the Stack’s watched paths trigger Runs.
• Branch — the tracked branch. Pushes here create apply-capable Runs.

Leave the execution mode at its default (merge_then_apply) to start: every change parks at an approval. You can change how a Stack applies — including applying from the pull request before merge — later; see Execution modes.

2. Connect GitHub

The Stack’s overview shows whether the Longbridge Stacks App covers the repository. If it doesn’t yet, Connect GitHub takes you to the App’s install page; installing it on the repository brings you straight back, connected. The App requests read on your repository’s contents (to clone) and pull requests (for path filtering), and write on checks and issues (the plan/apply checks, the Apply button, and the apply comment on a merged pull request) — the full set is in Reference.

If the App was already installed on the repository, the Stack connects by itself at creation — the badge confirms it.

3. Open a pull request

Any PR against the tracked branch gets a plan-only Run and a Longbridge Stacks / <stack> check with the plan’s counts. The plan itself stays in the Console — plans can contain secrets, so the PR page only ever sees numbers.

4. Merge, review the plan, approve

Merging pushes to the tracked branch, which creates a Run pinned to the exact merge commit. It plans, then parks at awaiting approval. In the Run view, read the plan and Approve — the apply executes exactly the plan you approved, byte for byte. If more commits landed meanwhile, the approval is still bound to its plan, never the branch tip.

Destroy Runs always require approval, whatever the execution mode.

5. Use the hosted state from your laptop (optional)

Every Stack’s state is served over OpenTofu’s standard http backend. Mint a state key in the Stack’s settings, then:

terraform {
  backend "http" {}
}

export TF_HTTP_ADDRESS="https://api.stacks.lngbrdg.com/state/v1/<org>/<stack>"
export TF_HTTP_LOCK_ADDRESS="$TF_HTTP_ADDRESS"
export TF_HTTP_UNLOCK_ADDRESS="$TF_HTTP_ADDRESS"
export TF_HTTP_LOCK_METHOD=LOCK TF_HTTP_UNLOCK_METHOD=UNLOCK
export TF_HTTP_USERNAME="<key id>" TF_HTTP_PASSWORD="<key secret>"
tofu init

Local applies and hosted Runs share the same lock, so they can never write over each other.