Skip to main content
Set APP_EXPERIMENTAL=iac on the control plane and in the CI job until v1.1.0. See Experimental features.
The loop is the same everywhere: a pull request runs a plan and shows the diff, merging runs the apply. Use two tokens: a read-only one for the plan job, a write one for the apply job on the protected branch.

GitHub Actions with the CLI

Works with plain files. The install step is yours: download the levelrail-cli release binary for the runner. The blocks on this page that are CI workflows, not Levelrail documents, are not checked by the examples guard.
Pass placeholder values with --var, --values or --allow-env. The plan job needs the same flags as the apply job. The first run with --source also plans a managed-by:<source> tag change that plain diff does not show, so it can exit 2 even when the files match live state; later runs are stable. The runner’s own credentials (GITHUB_TOKEN, ACTIONS_*, cloud keys) are never read unless you name them exactly.

GitHub Actions with the stack Action

For numbered revisions, rollback and approvals, use the stack Action in integrations/github-action/stack. It posts one sticky plan comment per stack on a pull request and applies on merge.
Rules that bite:
  • Pass the same secrets list to the plan step and the apply step. The plan hash covers secret names, so a plan without them has a different hash.
  • In apply mode, exit 2 means the revision awaits approval, not a change. The step reports the status pending_approval.
  • Pin the Action to a release tag or commit SHA instead of main, and set its version input to the release your server runs. Do not rely on latest.
  • Environments are the approval gate: give the production apply job environment: production with required reviewers, and keep one token secret per environment.
  • Approvals need a root token and a different person from the one who applied, so a CI token cannot approve. See Approvals.
Inputs, outputs and the full recipe are in integrations/github-action/stack/README.md and GitHub Action for IaC.

No stored secret

Instead of a long-lived token, a job can swap its GitHub identity for a short-lived token bound to one stack. Set oidc: "true" on the Action, give the job id-token: write, and register what each workflow may do once with levelrail-cli stack trust add. An apply trust needs an exact branch or tag and an environment. For tokens created by hand, give one token per job with stack_verbs set to plan or apply. See Tokens in CI.

Any other CI

GitLab CI, CircleCI, Jenkins and Buildkite run the same two commands from the table above. Ready templates for deploying an image are in Use any CI, and the GitHub deploy Action is described in GitHub Actions.
Next: How it works, IaC errors.
Last modified on November 17, 2026