Runtime configuration

The runtime configuration is an optional setup applied to individual runs instead of being global to the stack. It's defined in .spacelift/config.yml file at the root of your repository.

Configuration schema

A single file is used to define settings for all stacks associated with its host Git repository, so the file structure looks like this:

version: "2"

stack_defaults:
    runner_image: your/first:runner
    # Note that tflint is not installed by
    # default - this example assumes that your
    # runner image has this available.
    before_init:
        - echo "checking formatting"
        - terraform fmt -diff
        - tflint

# Every field in the configuration is
# optional, and has a reasonable default. This file
# allows you to override those defaults, and you can
# merely override individual fields.
stacks:
    # The key of is the immutable slug of your stack
    # which you will find in the URL.
    first-stack: &shared
        before_apply:
            - hostname
        project_root: infra
        terraform_version: 0.12.4
    second-stack:
        <<: *shared
        terraform_version: 0.13.0
        environment:
            AWS_REGION: eu-west-1
            TF_VAR_access_roles: '[productionsecurity, admin]'

The top level of the file contains three keys:

• version (defaults to 1 if not specified).
• stacks containing a mapping of immutable stack id to the stack configuration block.
• stack_defaults containing the defaults common to all stacks using this source code repository. Corresponding stack-specific settings will override any stack defaults.

Configuring individual stacks with spacectl

When configuring an individual stack with spacectl (such as through stack deploy --id example --runtime-config ./config.yml), omit the top-level config, so the file begins at runner_image.

runner_image: your/first:runner
# And so on, following the full
# configuration schema example.

However, when specifying a config.yml file within a repo, do not omit anything. Include everything in the schema, including version: "2" and stack_defaults:.

Runtime configuration precedence

Setting precedence will follow this order, starting from the most important to the least important:

1. The configuration for a specified stack defined in config.yml.
2. The stack defaults defined config.yml.
3. The stack configuration set in the Spacelift UI.

Info

The precedence of the runtime configuration file changed between versions 1 and 2. Previously the stack configuration set in the Spacelift UI had a higher precedence than the stack defaults defined in the config.yml file.

Starting with version 2, the values in the config.yml file always take precedence over stack settings defined outside the config.yml file.

If no stack slug is defined in the configuration file, only the first two sources are considered:

1. The stack configuration set in the Spacelift UI.
2. The stack defaults defined in config.yml.

Purpose of runtime configuration

Runtime configuration allows flexibility that would otherwise be hard to achieve. In general, its purpose is to preview effects of changes not related to the source code (e.g. OpenTofu/Terraform or Pulumi version upgrades, variable changes, etc.), before they become an established part of your infrastructure.

While stack environment applies both to tracked and non-tracked branches, a runtime configuration change can be pushed to a feature branch, which triggers proposed runs, allowing you to preview the changes before they have a chance to affect your state.

Info

If the runtime configuration file is not present or does not contain your stack, default values are used. Refer to each setting for its respective default.

Stacks configuration block

before_ and after_ hooks

Info

Each collection defaults to an empty array.

These scripts allow you to customize the Spacelift workflow. The following are available:

• before_init
• after_init
• before_plan
• after_plan
• before_apply
• after_apply
• before_perform
• after_perform
• before_destroy
• after_destroy
• after_run

environment map

Info

Defaults to an empty map.

The environment allows you to declaratively pass some environment variables to the runtime configuration of the stack. In case of a conflict, these variables will override both the ones passed via attached contexts and those directly set in stack's environment.

project_root setting

Info

Defaults to an empty string, pointing to the working directory for the run.

Project root is the path of your project directory inside the Hub repository. You can use this setting to point Spacelift to the right place if the repo contains source code for multiple stacks in various folders or serves multiple purposes like monorepos combining infrastructure definitions with source code (potentially even for multiple applications).

runner_image setting

Info

The default runner image can be defined multiple ways.

• No image set in runtime configuration file: Spacelift will look at the stack configuration.
• No image set in the stack configuration: Spacelift will use the default runner image specified on the account level.
• No image set as account-level default: Spacelift will use a vendor-specific image, like public.ecr.aws/spacelift/runner-terraform:latest for Terraform, or public.ecr.aws/spacelift/runner-opentofu:latest for OpenTofu stacks. See our Docker integration documentation for more details.

The runner image is the Docker image used to run your workloads. By making it a runtime setting, Spacelift allows testing the image before it modifies your infrastructure.

terraform_version setting

Info

Defaults to the latest known supported Terraform version.

This setting is only valid on Terraform stacks and specifies the Terraform version that the run will use. The main use case is testing a newer version of Terraform before you use it to change the state. This version can only be equal to or higher than the one already used to apply state changes. For more details on Terraform version management, please refer to its dedicated help section.

opentofu_version setting

Info

Defaults to the latest known supported OpenTofu version.

This setting specifies the OpenTofu version to be used during the run. It is only read on legacy Terraform stacks with terraform_workflow_tool set to OPEN_TOFU. Specify a version that aligns with those officially supported and tested by Spacelift.

Example: opentofu_version: "1.8.0"

Warning

Native OpenTofu vendor stacks do not read this key. If it (or terraform_version) applies to a native OpenTofu stack without an opentofu block, every run fails during preparation with an error saying the configuration still sets terraform_version. Use the opentofu block instead.

opentofu setting

This setting overrides the OpenTofu version and workflow tool for a native OpenTofu vendor stack, either per stack or through stack_defaults. It is the only way to override these settings from the repository for native OpenTofu stacks; the legacy opentofu_version key does not apply to them.

• version: The OpenTofu version or constraint. Always set it with the OPENTOFU workflow tool. If the block does not set version, the run ignores the stack's version and uses the newest OpenTofu version that Spacelift supports. With CUSTOM, Spacelift ignores version.
• workflow_tool: The workflow tool to use, OPENTOFU (default) or CUSTOM.

Other OpenTofu vendor settings (smart sanitization, concise output, CPU profiling, external state access, workspace) always come from the stack and cannot be overridden here.

Example:

version: "2"

stack_defaults:
    opentofu:
        version: "1.10.1"

stacks:
    my-opentofu-stack:
        opentofu:
            version: "1.12.0"
    my-custom-opentofu-stack:
        opentofu:
            workflow_tool: CUSTOM

Mixed Terraform and OpenTofu monorepos

Spacelift checks the stack-specific entry first and then stack_defaults. The check stops at the first level that has an opentofu block. A level that sets terraform_version or opentofu_version without an opentofu block fails the run for native OpenTofu stacks, even when that level is stack_defaults shared with Terraform stacks. Either give every OpenTofu stack its own opentofu block, or keep terraform_version under the individual Terraform stacks instead of stack_defaults.

Info

The opentofu block does not change the stack's vendor. For legacy Terraform stacks using the OpenTofu workflow tool, use opentofu_version instead, or migrate to native OpenTofu stacks.

terraform_workflow_tool setting

This setting determines the Terraform implementation used in the workflow:

• TERRAFORM_FOSS (default): Utilizes the official Terraform by HashiCorp. Best for standard Terraform operations and official provider support.
• CUSTOM: Enables the use of Custom Workflows for highly customized or unique deployment processes.

Pulumi version management is based on Docker images.

git_sparse_checkout_paths setting

Info

Defaults to an empty list. If empty, the value from the stack option will be applied.

Git sparse checkout paths allow you to specify a list of directories and files that will be used in sparse checkout, meaning that only the specified paths from the list will be cloned. This can help reduce the size of the workspace by only downloading the parts of the repository that are needed for the stack.

Only path values are allowed; glob patterns are not supported.

Example valid paths:

• ./infrastructure/
• infrastructure/
• infrastructure
• ./infrastructure/main.tf

Example invalid path (glob pattern):

• ./infrastructure/*

terragrunt setting

This setting determines the Terragrunt parametrization.

• terragrunt_tool: Choose the tool that should be used by Terragrunt between TERRAFORM_FOSS (default), OPEN_TOFU and MANUALLY_PROVISIONED.
• terragrunt_version: Terragrunt version. Defaults to the latest version.
• terraform_version: The Terraform version. Must not be provided when tool is set to MANUALLY_PROVISIONED. Defaults to the latest available OpenTofu/Terraform version.
• use_run_all: Whether to use terragrunt run-all instead of terragrunt. Defaults to false.
• use_smart_sanitization: Indicates whether runs on this will use Terraform's sensitive value system to sanitize the outputs of Terraform state and plans in Spacelift instead of sanitizing all fields. Defaults to false.
• use_state_management: Indicates whether Spacelift handles the OpenTofu/Terraform state.

You must set all necessary fields because if the terragrunt section is present in the config, it replaces all Terragrunt values rather than merging them. For example, if you set terraform_version only, all other fields will be reset to their defaults.

Info

Terragrunt specific parameters only work when the stack is a Terragrunt stack. Adding this does not override the stack type. For example, Ansible stacks don't become Terragrunt stacks.