How to plan in review and apply on merge
By the end of this guide you will have one shell script, ci.sh, with two modes: ci.sh plan makes a saved plan and prints it for a reviewer, and ci.sh apply applies exactly that saved plan after the merge. You’ll also see what happens when something else applied first, how to apply only part of the graph, how approvals behave with no terminal, and which exit codes and JSON a script can rely on. There is no CI-vendor configuration here: any runner that can run a shell script and keep a file between two jobs will do.
You need to have finished First steps, a local Temporal dev server on localhost:7233, and jq. The example project is docs/site/examples/howto/ci/shop/ in the vect repository. It has three roots, network (a random_pet), app (which takes the network’s name), and docs (independent), using only the random provider and terraform_data. Run IDs and digests in the output will differ from yours.
The script runs vect CLI-direct, so there is no server to operate. A real pipeline would also need the workspace’s state to live somewhere both jobs can reach (see Storage); here both jobs run in one folder, so the local stores are shared.
The script
#!/usr/bin/env bash
# ci.sh plan|apply: plan on a pull request, apply that same plan on merge.
set -euo pipefail
PLAN=${PLAN_FILE:-plans/review.plan}
export VECT_CONFIG=${VECT_CONFIG:-server.vect}
VECT=${VECT:-vect}
case ${1:-} in
plan)
mkdir -p "$(dirname "$PLAN")"
# Progress goes to stderr; stdout is the JSON document and nothing else.
"$VECT" plan --out "$PLAN" --metadata "pr=${PR:-none}" --format json >plan.json
jq -r '.nodes[] | "\(.address)\t\(.action)\t\(.reason)"' plan.json
;;
apply)
[ -f "$PLAN" ] || { echo "ci.sh: no plan file at $PLAN" >&2; exit 1; }
set +e
"$VECT" apply "$PLAN" --metadata "pr=${PR:-none}" --metadata "commit=${COMMIT:-none}" --format json >apply.json
status=$?
set -e
case $status in
0) jq -r '"apply \(.state): run \(.run_id)"' apply.json ;;
1) echo "ci.sh: run did not succeed" >&2; jq -r '.nodes[] | select(.status != "applied") | "\(.address): \(.status) \(.reason)"' apply.json >&2 ;;
2) echo "ci.sh: bad invocation" >&2 ;;
esac
exit "$status"
;;
*)
echo "usage: ci.sh plan|apply" >&2
exit 2
;;
esacThree things about it matter for everything below:
VECT_CONFIGpoints at the server configuration. A CLI-direct command reads it only from--configorVECT_CONFIG; aserver.vectin the current directory is not picked up on its own.- The plan file is the hand-off between the two jobs.
--outwrites it, andvect apply <file>takes it as its only argument. - With
--format jsonthe machine-readable document is the only thing on standard output. Node events, executor logs, and Temporal client noise go to standard error, so the script can parse stdout and leave stderr in the job log.
.vectignore lists server.vect, plans/, plan.json, and apply.json, so none of them gets bundled.
Plan on the pull request
From the example folder, in a shell with vect on your PATH, point the CLI at the server configuration once. The bare vect commands later in this guide need it too (ci.sh sets it itself, to the same file):
export VECT_CONFIG=$PWD/server.vectPR=12 ./ci.sh plan 2>/dev/nullterraform.app defer unknown inputs: inputs.network
terraform.docs run will run
terraform.network run will run(PR=12 stands for your pull request number. 2>/dev/null hides the progress stream so the page stays short; your job log should keep it.) Nothing was changed. app is defer because its input is the network’s name, which doesn’t exist yet, so it will be planned during the apply once network has converged.
The saved plan is plans/review.plan, and plan.json has the whole result. Post the table above to the pull request, and keep the plan file as the job’s artifact:
jq '{run_id, kind, state, plan_file, metadata}' plan.json{
"run_id": "01a1e290-703e-72b7-9805-a1bdf2d3e378",
"kind": "plan",
"state": "succeeded",
"plan_file": "sha256:cd45ba668fd2ba2a71a37ed55ea64594933c3541bad9b899b46a6306956dd2a5",
"metadata": {
"pr": "12"
}
}--metadata tags the run and its plan file; vect never interprets it. Metadata belongs to each command: the apply below does not inherit the plan’s tags, which is why ci.sh apply passes pr and commit itself, so the apply run and its deployment pointer can be traced back to the pull request. The other plan.json fields are nodes (each with address, status, action, reason, and version), approvals, failed, skipped, and digests; it holds no values. plan_file is the digest of the plan file this run wrote, and is set only on plan runs, so don’t read it from an apply. See vect plan for the full list.
A plan file is written only when the plan succeeds, and it is stored with the server and expires after plan_ttl (7 days unless you set it on the workspace).
Apply on merge
The merge job needs the plan file and nothing else from the pull request:
COMMIT=9f3c2ab ./ci.sh apply 2>/dev/nullapply succeeded: run 01a1e290-79d4-7186-9277-4beae9020273The apply runs on the plan file’s own bundle and pinned facts, not on whatever the merge job checked out. That is what “apply exactly that plan” means in vect: the configuration and facts are exactly the reviewed ones. The plan is consumed by the first apply that uses it, so a retried job is refused rather than applied twice:
./ci.sh applyvect: failed_precondition: the plan file is not valid: sha256:cd45ba668fd2ba2a71a37ed55ea64594933c3541bad9b899b46a6306956dd2a5 was already used by an apply
ci.sh: run did not succeedThe exit status is 1. An expired plan, or a file that doesn’t match a registered plan, is refused the same way, so a merge job that can’t apply the reviewed plan fails instead of falling back to something else.
terraform apply plan.tfplan applies a frozen set of actions, and fails if the state moved. A vect plan file freezes the inputs to planning: the bundle, the facts, the scope, and the approvals attested for it. What it applies is decided again against the real state, as the next section shows.When the plan has gone stale
A pull request waits in review while other work lands. Suppose the pull request changes docs from v1 to v2 (in roots/docs/main.tf, input = "v1" becomes input = "v2"), and its plan is made:
sed -i.bak 's/"v1"/"v2"/' roots/docs/main.tf && rm roots/docs/main.tf.bak
PR=13 ./ci.sh plan 2>/dev/nullterraform.app no-op inputs unchanged
terraform.docs update will update
terraform.network no-op inputs unchangedWhile it waits, a different pipeline changes the file to "v3" and runs a plain vect apply:
sed -i.bak 's/"v2"/"v3"/' roots/docs/main.tf && rm roots/docs/main.tf.bak
vect apply >/dev/null 2>&1Then the merge job runs ./ci.sh apply and looks at the node lines of apply.json:
./ci.sh apply >/dev/null 2>&1
jq -c '.nodes[]' apply.json{"address":"terraform.app","status":"unchanged","action":"no-op","reason":"inputs unchanged (replanned: saved_plans is replan)","version":1,"reuse":"replanned","reuse_reason":"saved_plans is replan"}
{"address":"terraform.docs","status":"applied","action":"update","reason":"will update (replanned: saved_plans is replan)","version":3,"reuse":"replanned","reuse_reason":"saved_plans is replan"}
{"address":"terraform.network","status":"unchanged","action":"no-op","reason":"inputs unchanged (replanned: saved_plans is replan)","version":1,"reuse":"replanned","reuse_reason":"saved_plans is replan"}(These are the node lines of apply.json, compacted with jq -c.) By default each node is planned again immediately before it is applied, and the saved plan contributes only its bundle, facts, and approvals. docs was planned from its real current version, v3, and updated to the pull request’s v2. Nothing failed, and the reason field says which path each node took. The reviewer saw a plan against the old state; what ran is the pull request’s configuration against the current one. That is the same “plan again, then apply” rule as in How runs work.
If you want a stale plan to be visible instead of silently re-planned, set saved_plans = "reuse" on the workspace:
saved_plans is replan unless you set it. With reuse, apply skips the plan step for a node only when, checked under the node’s lease, all of these hold: the node need not re-plan, the run’s source and bundle digests equal the plan file’s, the node’s current Inventory version equals the one recorded in the plan, and its freshly evaluated inputs digest matches. A node must re-plan when it is named by an explicit --target, is in-flight, stale, or uncertain, has unknown inputs, or needs recovery. So a plan file made with --target is never reused, and its apply reports reuse_reason “the run is a forced full run, or the node is an explicit target”. Any node that fails a condition is planned again as usual, with the reason recorded. (RUN-SAVED-2, FLEET-AFF-7.)workspace "dev" {
…
saved_plans = "reuse"
}With reuse and no interference, the node that changes reuses the saved plan, and the ones that change nothing are planned again because “the saved plan changes nothing”. Change docs again, plan, and apply (here jq selects only the reuse keys):
sed -i.bak 's/"v3"/"v4"/' roots/docs/main.tf && rm roots/docs/main.tf.bak
PR=14 ./ci.sh plan >/dev/null 2>&1
./ci.sh apply >/dev/null 2>&1
jq -c '.nodes[] | {address, status, reuse, reuse_reason}' apply.json{"address":"terraform.app","status":"unchanged","reuse":"replanned","reuse_reason":"the saved plan changes nothing"}
{"address":"terraform.docs","status":"applied","reuse":"reused","reuse_reason":null}
{"address":"terraform.network","status":"unchanged","reuse":"replanned","reuse_reason":"the saved plan changes nothing"}And when another apply landed in between, the stale node says so:
sed -i.bak 's/"v4"/"v5"/' roots/docs/main.tf && rm roots/docs/main.tf.bak
PR=15 ./ci.sh plan >/dev/null 2>&1
sed -i.bak 's/"v5"/"v6"/' roots/docs/main.tf && rm roots/docs/main.tf.bak
vect apply >/dev/null 2>&1
./ci.sh apply >/dev/null 2>&1
jq -c '.nodes[] | {address, status, reuse, reuse_reason}' apply.json{"address":"terraform.app","status":"unchanged","reuse":"replanned","reuse_reason":"the saved plan changes nothing"}
{"address":"terraform.docs","status":"applied","reuse":"replanned","reuse_reason":"the node was applied since the plan (Inventory version 5, planned at 4)"}
{"address":"terraform.network","status":"unchanged","reuse":"replanned","reuse_reason":"the saved plan changes nothing"}A script that must not apply anything the reviewer didn’t see can fail the job when reuse is replanned for a node whose action isn’t no-op. vect doesn’t stop it for you: a reused plan isn’t checked for drift since it was made, and a node that fails the reuse conditions is simply planned again.
Apply only part of the graph
--target <address> limits a plan or apply to one executor (or stack). Out-of-scope upstream nodes are read from Inventory unless you pass --upstream=include; Running part of the graph explains the choice. With the docs root edited once more:
sed -i.bak 's/"v6"/"v7"/' roots/docs/main.tf && rm roots/docs/main.tf.bak
vect plan --target terraform.docs 2>/dev/nullplan of workspace "dev": succeeded (run 01a1e290-eb53-7eb5-a1be-5037dce3e674)
scope: --target terraform.docs (upstream: inventory)
terraform.docs update will updatevect apply --target terraform.docs --format json 2>/dev/null | jq -c '{state, targets, upstream, nodes: [.nodes[] | {address, status}]}'{"state":"succeeded","targets":["terraform.docs"],"upstream":"inventory","nodes":[{"address":"terraform.docs","status":"applied"}]}A plan file records its own scope, so --target combined with a plan file is a usage error (exit 2). To apply part of the graph on merge, put --target on the plan and apply the file as is (with docs edited once more, so there is something to apply):
sed -i.bak 's/"v7"/"v8"/' roots/docs/main.tf && rm roots/docs/main.tf.bak
vect plan --target terraform.docs --out plans/t.plan 2>/dev/null
PLAN_FILE=plans/t.plan ./ci.sh apply 2>/dev/null
jq -c '{targets, nodes: [.nodes[] | {address, status}]}' apply.jsonplan of workspace "dev": succeeded (run 01a1e291-0f95-7e82-b208-9e3d057d70cb)
scope: --target terraform.docs (upstream: inventory)
terraform.docs update will update
plan file sha256:66c872d76de6adfbcc0f9a86e81d67f07de16807f666639cfe56e6fd35a6a6d0 written to plans/t.plan
apply succeeded: run 01a1e291-10b9-7883-8691-2d7fa4679288
{"targets":["terraform.docs"],"nodes":[{"address":"terraform.docs","status":"applied"}]}Approvals with no terminal
The pull request above changed nothing destructive. A destroy raises an approval request, and a CI job has nobody to answer it. What happens depends on where the run executes. CLI-direct with no terminal applies the workspace’s unattended_approvals policy, which is reject:
vect destroy --target terraform.docs </dev/null 2>/dev/nulldestroy of workspace "dev": failed (run 01a1e291-1253-7645-a96e-8155254ba31b)
scope: --target terraform.docs (upstream: inventory)
terraform.docs skipped approval rejected by unattended: destroy terraform.docs::terraform_data.docs
approval requests:
apr_eaba1ffd04bfec934f9f8187 destroy terraform.docs::terraform_data.docs destroy terraform.docs::terraform_data.docs [rejected by unattended]
node terraform.docs skipped: approval rejected by unattended: destroy terraform.docs::terraform_data.docsThe command exits 1, and nothing was destroyed. You have three ways to let it through, from narrowest to widest:
--auto-approvefor this one run:vect destroy --target terraform.docs --auto-approve </dev/null 2>/dev/nulldestroy of workspace "dev": succeeded (run 01a1e291-1371-7109-ad0c-da6c6d59725a) scope: --target terraform.docs (upstream: inventory) terraform.docs applied (destroy) teardown approval requests: apr_eaba1ffd04bfec934f9f8187 destroy terraform.docs::terraform_data.docs destroy terraform.docs::terraform_data.docs [approved by auto-approve] deployment pointer 9 appendedunattended_approvals = "approve"on the workspace, for every unattended run there. The record showsapproved by unattendedinstead.Attest the approvals in the plan, ahead of time. A person runs
vect approve plans/review.plan, andvect applyhonors those requests when the change is the same one they approved. Which workspaces honor this is theplan_approvalssetting.
--auto-approve on the one job that is meant to destroy things, or an attested plan, over turning on unattended_approvals = "approve" for a whole workspace. Neither applies to a served runner (--api-url): there an unanswered request waits, up to approval_timeout, for someone to run vect approve --run. See Approvals.Exit codes and JSON
A script can branch on three codes, the same for every command:
| Code | Meaning |
|---|---|
0 | The command succeeded, and a plan or apply run succeeded. |
1 | A runtime or configuration failure, including a run that failed, was canceled, or had a node skipped or rejected. Also a refused plan file and a failed API call. |
2 | A usage error: an unknown flag, a bad value, a missing workspace. Retrying won’t help. |
vect apply --format yaml </dev/nullvect: invalid --format "yaml": want text or jsonThat exits 2. ci.sh follows the same convention, so running it with no argument exits 2 and a missing plan file exits 1.
--format json is accepted by plan, apply, destroy, affected, runs, output, inventory, and gc. The document carries a format_version (currently 1) and is a stable contract; the text output is not. For a failed run it names what failed and what was decided:
With docs applied again (the --auto-approve run above destroyed it), a rejected destroy as JSON:
vect apply --target terraform.docs >/dev/null 2>&1
vect destroy --target terraform.docs --format json 2>/dev/null </dev/null | jq -c '{state, failed, skipped, approvals}'{"state":"failed","failed":["terraform.docs"],"skipped":[],"approvals":[{"id":"apr_2578405c71c2f22a8392069c","kind":"destroy","target":"terraform.docs::terraform_data.docs","summary":"destroy terraform.docs::terraform_data.docs","raised_at":"apply","node":"terraform.docs","change_digest":"sha256:5db38a5b346dee1c72385f5317d33dd2a34b6c0fbdc88fa0bbe7f6d5fb9a560d","state":"rejected","decided_by":"unattended","decided_by_issuer":"","decided_at":"2026-11-16T04:15:26Z"}]}The node’s own nodes[].status is skipped, as in the text summary, while the run-level failed list collects failed, blocked, and rejected nodes. Branch on the exit code and state, and use the lists for reporting.
Things to know
- Keep stderr. Executor logs and engine errors appear only there, and
--format jsonleaves them in place. - A canceled job (Ctrl-C or SIGTERM) cancels a CLI-direct run and waits up to 30 seconds for it to end; the run exits
1. The next plan finds the node’sin-flightmarker and says so. - Two jobs for the same workspace with different local stores can take each other’s tasks. In a real pipeline, give both the same shared stores.
- vect doesn’t serialize your pipeline. If two applies of one workspace can overlap, make your CI runner queue them.
See also
- How runs work: runs, approvals, targeting, and the plan-then-apply rule.
- CLI reference:
vect plan,vect apply, exit codes, and output formats. - Server configuration:
saved_plans,plan_ttl,unattended_approvals,plan_approvals. - Runtime spec: RUN-PLAN-4 to RUN-PLAN-6, RUN-APPLY-3, RUN-SAVED-1 to RUN-SAVED-4, RUN-APPROVAL-3.