pulumi preview: Usage, Options & Common CI Errors

See what pulumi up would change - without changing anything.

pulumi preview computes and prints the operations a pulumi up would perform, without executing them. It is the safe PR gate: review the diff, and optionally fail if there are unexpected changes.

What it does

pulumi preview runs your program and diffs it against current state, listing the creates, updates, replaces, and deletes that an update would make. It contacts providers to read current resources but performs no mutations, so it is safe to run on every pull request.

Common usage

# Preview changes for the selected stack
pulumi preview --stack acme/prod

# Fail the job if there is any drift/diff (good PR gate)
pulumi preview --stack acme/prod --expect-no-changes

# Machine-readable diff for a PR comment
pulumi preview --stack acme/prod --json

Common error in CI: passphrase/login required for preview

preview fails with "error: constructing secrets manager: passphrase must be set with PULUMI_CONFIG_PASSPHRASE" or "PULUMI_ACCESS_TOKEN must be set" even though it changes nothing - it still must read state and decrypt secrets. Fix: provide PULUMI_ACCESS_TOKEN (Pulumi Cloud) or PULUMI_CONFIG_PASSPHRASE (passphrase secrets provider) to the runner and select the stack. Use --expect-no-changes only when you genuinely want drift to fail the build, since any provider-side change will trip it.

Key options

Related guides