engine

engine sets the tool that Stategraph Orchestration runs for plan and apply. Set it for the whole repository, or per workflow under the workflows key.

`name`	Runs
`terraform`	The Terraform CLI. This is the default.
`tofu`	OpenTofu.
`stategraph`	The `stategraph` CLI, with your state in Infrastructure as a Database.
`terragrunt`	Terragrunt, on Terraform or OpenTofu.
`cdktf`	CDKTF, for infrastructure in TypeScript, Python, Go, or Java, on Terraform or OpenTofu.
`pulumi`	Pulumi.
`custom`	Your own command for each step.

Default Configuration

engine:
  name: terraform

Keys

name is required when engine is set. The other keys depend on the engine.

default_tf_version is an older, top-level form of engine. Without engine, default_tf_version: "1.5.0" is the same as engine: { name: terraform, version: "1.5.0" }. With engine, it sets the Terraform version of the terragrunt, cdktf, and stategraph engines that do not set tf_version. Use engine.

terraform and tofu

Key	Type	Description
`name`	string	`terraform` or `tofu`
`override_tf_cmd`	string	The program to call in place of `terraform` or `tofu`
`version`	string	The version of `terraform` or `tofu`
`outputs`	object	See outputs

terragrunt

Key	Type	Description
`name`	string	`terragrunt`
`override_tf_cmd`	string	The program to call in place of Terragrunt
`tf_cmd`	string	The Terraform-compatible program under Terragrunt. Default is `terraform`.
`tf_version`	string	The version of that program (Terraform or OpenTofu)
`version`	string	The version of Terragrunt
`outputs`	object	See outputs

cdktf

Key	Type	Description
`name`	string	`cdktf`
`override_tf_cmd`	string	The Terraform or OpenTofu program that plans and applies the synthesized code, in place of `terraform` or `tofu`
`tf_cmd`	string	The Terraform-compatible program under CDKTF. Default is `terraform`.
`tf_version`	string	The version of that program (Terraform or OpenTofu)
`outputs`	object	See outputs

stategraph

Runs the stategraph CLI, with your state in Infrastructure as a Database. It needs a Stategraph server, and a stategraph.json in each directory, committed to the repository. For setup, secrets, and limits, see Use with Orchestration.

Key	Type	Description
`name`	string	`stategraph`
`version`	string	Optional. The version of the `stategraph` CLI to install.
`override_tf_cmd`	string	The Terraform or OpenTofu program that the CLI calls, in place of `terraform` or `tofu`
`tf_cmd`	string	The Terraform-compatible program that the CLI runs. Default is `terraform`.
`tf_version`	string	The version of that program (Terraform or OpenTofu)

The runner reads STATEGRAPH_API_BASE, STATEGRAPH_API_KEY, and STATEGRAPH_TENANT_ID from the environment. All three are required. The stategraph engine does not collect outputs.

pulumi

Key	Type	Description
`name`	string	`pulumi`

The pulumi engine takes no other keys.

custom

Each step is optional. Orchestration skips a step that you do not set.

Key	Type	Description
`init`	array	The command for the init step
`plan`	array	The command for the plan step. To pass a plan file to the apply step, write it to the path in `TERRATEAM_PLAN_FILE`. The file format is up to your engine.
`diff`	array	The command that prints a readable diff of the plan
`resource_summary`	array	The command that prints the resource counts of the plan as a JSON object with the integer keys `created`, `updated`, `replaced`, and `deleted`. It runs after a plan with changes, and the counts show in the status check description and the summary comment. Orchestration skips the counts when the command fails or prints no JSON object.
`apply`	array	The command for the apply step
`unsafe_apply`	array	The command for `stategraph apply-autoapprove`, which applies with no stored plan file
`outputs`	array	The command that returns the output values as a JSON string

outputs

By default, Orchestration collects and stores the outputs of each apply. outputs controls this.

Key	Type	Description
`collect`	boolean	`true` collects the outputs, `false` turns it off. Default is `true`.

Examples

Using Terraform

engine:
  name: terraform
  version: '1.0.0'

Using OpenTofu

engine:
  name: tofu
  version: '1.9.0'

Using Terragrunt with a Specific Terraform Version

engine:
  name: terragrunt
  tf_version: '1.5.7'

Using Terragrunt with OpenTofu

engine:
  name: terragrunt
  tf_cmd: tofu

Using CDKTF with the Latest Terraform Version

engine:
  name: cdktf

Using Pulumi

engine:
  name: pulumi

Using Stategraph

engine:
  name: stategraph

Using Stategraph with OpenTofu

engine:
  name: stategraph
  tf_cmd: tofu
  tf_version: '1.7.0'

The runner needs the secrets and the stategraph.json files in stategraph.

Using a Custom Engine

engine:
  name: custom
  init: ['echo', 'init']
  plan: ['my-custom-plan']
  diff: ['printf', '+ added foo\n- removed bar\n~ updated baz\n']
  apply: ['my-custom-apply']
  outputs: ['echo', '{"foo": "bar"}']

Each step runs a command. Set only the steps that you need.