Template Configuration

This document provides comprehensive reference for writing template YAML configurations. Templates use a YAML-based configuration format that defines infrastructure, inputs, and deployment behavior.

Template Body Structure

The template body uses YAML format with the templateSchema. Here's a minimal example:

inputs:
  - id: environment
    name: Environment
    type: select
    options:
      - dev
      - staging
      - prod
  - id: app_name
    name: Application Name
    type: short_text

stacks:
  - key: main
    name: ${{ inputs.app_name }}-${{ inputs.environment }}
    vcs:
      reference:
        value: main
        type: branch
      repository: my-infrastructure
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

Important

Templates use the templateSchema which requires the stacks array format (not a single stack object). Each stack must have a unique key field, and VCS configuration uses the reference structure with value and type fields.

Space

The optional top-level space field allows you to specify the space slug where the deployment will be created. Stacks created by the deployment are placed in the same space as the deployment.

space: my-space-01KK1N9DPV4TD456M5PTTFX7QZ
stacks:
  - key: main
    name: my-stack
    # ...

If space is set, it overrides any space selected by the user during deployment. If omitted, the deployment is created in the template's space.

Info

Unlike the original Blueprint schema where space was a per-stack field, in the Template schema space is a top-level field that applies to the entire deployment.

Templating Restrictions

The following fields cannot use template expressions (${{ }}):

• Stack keys (/stacks/*/key) - Must be static strings
• Stack dependencies (/stacks/*/depends_on/*) - Must be static references
• All VCS fields (/stacks/*/vcs/**) - Including repository, provider, namespace, reference.value, reference.type, etc.
• Input definitions (/inputs/**) - Including id, name, type, options, default, etc.

Templating is allowed in fields like name, description, labels, autodeploy, environment variables, vendor configuration, and most other stack settings.

Input Types

Templates support various input types to collect information from users:

Type	Description	Use Case
short_text	Single-line text input	Names, identifiers, short values
long_text	Multi-line text area	Descriptions, configurations, scripts
secret	Masked sensitive input	Passwords, API keys, tokens
number	Integer input	Counts, port numbers, limits
float	Decimal number input	Percentages, ratios, measurements
boolean	Checkbox	Feature toggles, flags
select	Dropdown with options	Predefined choices like environments

Input Definition

Each input is defined with the following properties:

inputs:
  - id: app_name              # Unique identifier for this input
    name: Application Name     # Display name shown to users
    description: The name of your application  # Optional help text
    type: short_text          # Input type
    default: my-app           # Optional default value
    validations:              # Optional validation rules
      required: true
      min_length: 3
      max_length: 20
      pattern: "^[a-zA-Z0-9-]+$"

Input Properties

• id (required): Unique identifier used to reference the input in template expressions
• name (required): Human-readable display name shown in the deployment form
• description (optional): Help text explaining what the input is for
• type (required): Input type (see table above)
• default (optional): Default value if user doesn't provide one
• validations (optional): Validation rules to enforce
• options (required for select): Array of allowed values for select inputs

Input Validations

Templates support validation rules to ensure users provide valid data:

String Validation

validations:
  required: true              # Field must be filled
  min_length: 3              # Minimum character count
  max_length: 50             # Maximum character count
  length_equal: 10           # Exact character count required
  pattern: "^[a-z-]+$"       # Regular expression pattern

Number Validation

validations:
  required: true              # Field must be filled
  greater_than: 0            # Value must be greater than
  greater_than_or_equal: 1   # Value must be >=
  less_than: 100             # Value must be less than
  less_than_or_equal: 99     # Value must be <=
  not_equal: 50              # Value cannot equal
  step: 2                    # Increment step (for integers)

Boolean Validation

validations:
  required: true              # Field must be filled (cannot be null)

Select Validation

type: select
options:                      # List of allowed values
  - dev
  - staging
  - prod
validations:
  required: true              # User must select a value

Using Template Variables

Template variables can be referenced throughout your configuration using the ${{ }} syntax:

inputs:
  - id: environment
    name: Environment
    type: select
    options:
      - dev
      - prod

stacks:
  - key: main
    name: app-${{ inputs.environment }}
    description: '${{ inputs.environment == "prod" ? "Production" : "Development" }} environment'
    labels:
      - Environment/${{ inputs.environment }}
    vcs:
      reference:
        value: main
        type: branch
      repository: my-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"
    environment:
      variables:
        - name: ENV
          value: ${{ inputs.environment }}
        - name: DEBUG
          value: '${{ inputs.environment == "dev" }}'

Variable Syntax

• Reference inputs: ${{ inputs.input_id }}
• Use context variables: ${{ context.property }}
• Use maps: ${{ maps[inputs.env].property }}
• Apply CEL expressions: ${{ inputs.name.lowerAscii() }}

Templating Restrictions

Warning

Not all fields support templating. The following paths cannot use ${{ }} expressions:

Structural Fields (must be static): - stacks.*.key - Stack identifiers must be deterministic - stacks.*.depends_on.* - Dependencies must be known at parse time

VCS Configuration (must be static): - stacks.*.vcs.repository - Repository name - stacks.*.vcs.provider - Provider type (GITHUB, GITLAB, etc.) - stacks.*.vcs.namespace - Organization/namespace - stacks.*.vcs.reference.value - Branch/tag/SHA value - stacks.*.vcs.reference.type - Reference type (branch/tag/sha) - stacks.*.vcs.project_root - Project root path

Input Definitions (must be static): - inputs.*.id - Input identifiers - inputs.*.name - Input display names - inputs.*.type - Input types - inputs.*.options - Select options - inputs.*.default - Default values - inputs.*.validations - Validation rules

Why these restrictions? These fields define the template's structure and must be deterministic at parse time. VCS fields determine which repository to use, so they cannot depend on runtime inputs.

What CAN be templated? Most other fields including name, description, labels, autodeploy, autoretry, administrative, environment variables, vendor settings, hooks, schedules, and attachments.

Context Variables

Templates provide built-in context variables for dynamic values:

stacks:
  - key: main
    name: app-${{ context.random_string }}
    description: Created at ${{ string(context.time) }}
    labels:
      - owner/${{ context.user.login }}
    vcs:
      reference:
        value: main
        type: branch
      repository: my-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"
    environment:
      variables:
        - name: DEPLOYMENT_ID
          value: "${{ context.random_uuid }}"

Available Context Properties

Property	Type	Description
context.deployment.created_at	Timestamp	Creation date of deployment
context.deployment.name	String	Name of deployment
context.deployment.slug	String	Slug of deployment
context.time	Timestamp	UTC time of deployment
context.random_string	String	Random 6-character string
context.random_number	Number	Random number (0-1000000)
context.random_uuid	String	Random UUID
context.user.login	String	User's login name
context.user.name	String	User's full name
context.user.account	String	Account subdomain

Stack Configuration

Templates can configure all stack settings using the templateSchema:

stacks:
  - key: main
    name: ${{ inputs.stack_name }}
    description: My application stack
    labels:
      - app/${{ inputs.app_name }}
      - env/${{ inputs.environment }}

    # Behavioral settings
    administrative: false
    autodeploy: true
    autoretry: false

    # VCS configuration (template schema format)
    vcs:
      reference:
        value: main
        type: branch  # Options: branch, tag, sha
      repository: my-repo
      provider: GITHUB
      namespace: my-org
      project_root: terraform/
      project_globs:
        - "modules/**"

    # Vendor configuration (choose one vendor per stack)
    vendor:
      opentofu:
        manage_state: true
        version: "1.11.0"
        workspace: ${{ inputs.environment }}
        concise: true
        enable_cpu_profiling: true
        workflow_tool: OPENTOFU  # Options: OPENTOFU, CUSTOM

    # Environment configuration
    environment:
      variables:
        - name: ENVIRONMENT
          value: ${{ inputs.environment }}
        - name: APP_NAME
          value: ${{ inputs.app_name }}
        - name: API_KEY
          value: ${{ inputs.api_key }}
          secret: true
        - name: NON-STRING_VARIABLE
          value: "${{ inputs.my_boolean }}"

      mounted_files:
        - path: config.json
          content: |
            {
              "environment": "${{ inputs.environment }}",
              "features": {
                "feature_a": ${{ inputs.enable_feature_a }}
              }
            }
          secret: false

    # Attachments
    attachments:
      contexts:
        - id: my-context-id
          priority: 1
      policies:
        - my-policy-id
      clouds:
        aws:
          id: my-aws-integration-id
          read: true
          write: true

Non-string variable values

All value: fields must be strings.

Wrap boolean and number inputs in quotes to avoid parse errors, for example, "${{ inputs.my_boolean }}".

Templates use the templateSchema format. The key differences from the Blueprint schema are:

• Must use stacks array (not a single stack object).
• Each stack requires a unique key field.
• VCS configuration uses reference.value and reference.type instead of direct branch, tag, or sha fields.
• See the Template Schema Reference section for complete details.

For complete stack configuration options, refer to the Stack Configuration documentation.

Multiple Stacks

Templates can create multiple stacks in a single deployment:

inputs:
  - id: app_name
    name: Application Name

stacks:
  - key: frontend
    name: ${{ inputs.app_name }}-frontend
    vcs:
      reference:
        value: main
        type: branch
      repository: frontend-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

  - key: backend
    name: ${{ inputs.app_name }}-backend
    depends_on:
      - frontend
    vcs:
      reference:
        value: main
        type: branch
      repository: backend-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

Note

When using multiple stacks, each stack must have a unique key field for dependency management.

Stack Dependencies

You can create dependencies between stacks using the depends_on field or stack_dependency_references:

stacks:
  - key: database
    name: ${{ inputs.app_name }}-db
    vcs:
      reference:
        value: main
        type: branch
      repository: database-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

  - key: application
    name: ${{ inputs.app_name }}-app
    depends_on:
      - database
    environment:
      stack_dependency_references:
        - name: DB_CONNECTION_STRING
          from_stack: database
          output: connection_string
    vcs:
      reference:
        value: main
        type: branch
      repository: app-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

Dependency Features

• depends_on: Ensures stacks are created in order
• stack_dependency_references: Pass outputs from one stack to another as environment variables
• Multiple dependencies can be specified
• Prevents circular dependencies

External Stack Dependencies

In addition to dependencies between stacks within the same template, you can define dependencies on already existing stacks that are not part of the template. This is useful when your template needs to consume outputs from shared infrastructure stacks (e.g., a networking or database stack) that are managed separately.

External dependencies reference stacks by their slug rather than by a template key. The referenced stacks must already exist in the same Spacelift account, and the user deploying the template must have read access to the space containing each external stack.

There are two ways to define external dependencies:

• external_depends_on: A list of existing stack slugs that the stack depends on. This ensures ordering but does not pass any outputs.
• external_stack_dependency_references: Defined inside the environment block, these map outputs from an external stack to environment variables in the dependent stack. The from_stack field takes the external stack's slug.

You can use both approaches together. If the same external stack appears in both external_depends_on and external_stack_dependency_references, the dependency is created only once with the output references included.

stacks:
  - key: networking
    name: ${{ inputs.app_name }}-networking
    external_depends_on:
      - existing-monitoring-stack
    environment:
      external_stack_dependency_references:
        - name: VPC_ID
          from_stack: existing-vpc-stack
          output: vpc_id
        - name: SUBNET_IDS
          from_stack: existing-vpc-stack
          output: subnet_ids
    vcs:
      reference:
        value: main
        type: branch
      repository: networking-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

  - key: application
    name: ${{ inputs.app_name }}-app
    depends_on:
      - networking
    external_depends_on:
      - existing-monitoring-stack
    vcs:
      reference:
        value: main
        type: branch
      repository: app-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

In this example:

• The networking stack depends on an external stack existing-monitoring-stack (ordering only) and consumes outputs from existing-vpc-stack via external_stack_dependency_references.
• The application stack depends on the template-internal networking stack via depends_on, and also has an external ordering dependency on existing-monitoring-stack.

Note

Unlike depends_on which cannot use template expressions, external_depends_on values can be templated using ${{ }} expressions.

Template Engine

Templates use the same template engine as Blueprints, based on Google CEL. The implementation is available on GitHub.

Supported Functions

CEL supports various built-in functions:

• String operations: contains, startsWith, endsWith, matches, replace, lowerAscii, upperAscii, split, join
• Operators: *, /, -, +, ==, !=, <, <=, >, >=, &&, ||, !, ?:
• Type conversions: string(), int(), bool()

CEL Expression Examples

inputs:
  - id: app_name
    name: Application Name
  - id: environment
    name: Environment
    type: select
    options:
      - dev
      - prod

stacks:
  - key: main
    # String manipulation
    name: ${{ inputs.app_name.lowerAscii().replace(" ", "-") }}-${{ inputs.environment }}

    # Conditional logic
    description: '${{ inputs.environment == "prod" ? "Production environment" : "Development environment" }}'

    # Boolean conditions
    autodeploy: ${{ inputs.environment != 'prod' }}
    administrative: ${{ inputs.environment == 'prod' }}

    # String operations
    labels:
      - '${{ inputs.environment.upperAscii() }}'
      - app/${{ inputs.app_name.lowerAscii() }}

    vcs:
      reference:
        value: main
        type: branch
      repository: my-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

YAML Syntax Validity

Reserved YAML characters (:, ?, >, |) within CEL expressions require quotes:

# Invalid - YAML parsing error
name: ${{ condition ? "yes" : "no" }}

# Valid - quoted expression
name: '${{ condition ? "yes" : "no" }}'

Maps

Maps allow you to preconfigure specific values and enable deterministic value selection:

inputs:
  - id: env
    name: Environment
    type: select
    options:
      - prod
      - dev

maps:
  prod:
    stack_name: production-app
    description: Production environment
    instance_count: 5
    manage_state: true
  dev:
    stack_name: development-app
    description: Development environment
    instance_count: 1
    manage_state: false

stacks:
  - key: main
    name: ${{ maps[inputs.env].stack_name }}
    description: ${{ maps[inputs.env].description }}
    vcs:
      reference:
        value: main
        type: branch
      repository: my-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: ${{ maps[inputs.env].manage_state }}
        version: "1.5.0"
    environment:
      variables:
        - name: INSTANCE_COUNT
          value: "${{ maps[inputs.env].instance_count }}"

Note

Maps cannot reference inputs in their definitions, and inputs cannot reference maps.

Map Use Cases

• Environment-specific configurations
• Predefined resource sizes (small, medium, large)
• Regional settings
• Tier-based configurations (bronze, silver, gold)

Schedules

Templates support scheduling for drift detection and scheduled tasks:

inputs:
  - id: enable_drift_detection
    name: Enable Drift Detection
    type: boolean
  - id: enable_reconcile
    name: Enable Auto-Reconcile
    type: boolean
    default: false

stacks:
  - key: main
    name: scheduled-stack
    vcs:
      reference:
        value: main
        type: branch
      repository: my-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"
    schedules:
      # Drift detection
      drift:
        cron:
          - "0 2 * * *"  # Run daily at 2 AM
        reconcile: ${{ inputs.enable_reconcile }}
        ignore_state: false
        timezone: UTC

      # Scheduled tasks
      tasks:
        - command: "terraform plan"
          cron:
            - "0 0 * * 0"  # Weekly on Sunday at midnight
          timezone: UTC
        - command: "echo 'Health check'"
          cron:
            - "0 */6 * * *"  # Every 6 hours
          timezone: UTC

Schedule Types

Drift Detection:

• Automatically check for configuration drift
• Option to reconcile differences automatically
• Configurable cron schedule
• Can ignore state file changes

Scheduled Tasks:

• Run arbitrary commands on a schedule
• Support for multiple scheduled tasks
• Each task has its own cron schedule
• Timezone configuration per task

Scheduled Deletion

Templates support automatic deployment deletion at a specified time. The scheduled_delete field is defined at the top level of the template body (alongside inputs, maps, and stacks), and applies to the entire deployment rather than individual stacks.

This is useful for ephemeral or time-limited environments, such as demo deployments, temporary testing infrastructure, or trial environments that should be cleaned up automatically.

inputs:
  - id: delete_in_seconds
    name: Delete in seconds
    type: number

scheduled_delete:
  timestamp_unix: ${{ int(context.time) + inputs.delete_in_seconds }}
  delete_stacks: false

stacks:
  - key: main
    name: ${{ context.deployment.name }}-stack
    vcs:
      reference:
        value: main
        type: branch
      repository: spacelift-infra
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true

Scheduled Deletion Properties

Property	Type	Required	Default	Description
timestamp_unix	number	Yes	-	Unix timestamp (in seconds) specifying when the deployment should be deleted
delete_stacks	boolean	No	true	Whether to also delete the deployment's stacks when the scheduled deletion fires

The timestamp_unix field supports template expressions. A common pattern is to calculate it relative to the deployment time using context.time. For example, ${{ int(context.time) + 3600 }} schedules the deployment to be deleted one hour after creation.

Deletion Behavior

When the scheduled deletion timestamp is reached:

• If delete_stacks is true (the default), the deployment and all of its stacks are destroyed. If any stack is not in a terminal state (for example, a run is in progress), the deletion is postponed and a notification is sent. The system retries periodically until all stacks are ready to be deleted.
• If delete_stacks is false, the stacks are detached from the deployment and continue to exist as independent stacks. Only the deployment itself is removed.

Note

When a deployment is updated (for example, by changing the template version or inputs), the scheduled deletion is reconciled. If the new template version includes a scheduled_delete block, the existing schedule is replaced with the new one. If the new version does not include scheduled_delete, the existing schedule is removed.

Hooks

Templates support lifecycle hooks for custom actions:

stacks:
  - key: main
    name: hooked-stack
    vcs:
      reference:
        value: main
        type: branch
      repository: my-repo
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"
    hooks:
      init:
        before: ["echo", "Initializing..."]
        after: ["echo", "Initialization complete"]

      plan:
        before: ["echo", "Planning changes..."]
        after: ["./notify-team.sh", "${{ inputs.environment }}"]

      apply:
        before: ["echo", "Applying changes..."]
        after: ["echo", "Deployment complete"]

      destroy:
        before: ["echo", "Destroying resources..."]
        after: ["echo", "Resources destroyed"]

      run:
        after: ["./cleanup.sh"]

Hook Types

• init: Run before/after initialization
• plan: Run before/after planning
• apply: Run before/after applying changes
• destroy: Run before/after destroying resources
• run: Run after any run completes

Hook Best Practices

1. Keep hooks simple: Complex logic belongs in the repository
2. Use for notifications: Alert teams about deployments
3. Validate inputs: Check prerequisites before operations
4. Cleanup: Remove temporary files after runs

Best Practices

Input Design

Good input design:

inputs:
  - id: app_name
    name: Application Name
    description: A unique name for your application (lowercase, hyphens allowed)
    type: short_text
    validations:
      required: true
      min_length: 3
      max_length: 30
      pattern: "^[a-z0-9-]+$"

  - id: environment
    name: Environment
    description: Select the target environment for deployment
    type: select
    options:
      - dev
      - staging
      - prod
    default: dev

Bad input design:

inputs:
  - id: x
    name: X
    type: short_text

  - id: env
    name: Env
    type: short_text  # Should be select with options

Template Structure

1. Organize inputs logically: Group related inputs together
2. Use descriptive IDs: Make input IDs clear and meaningful
3. Provide defaults: Set sensible defaults for optional inputs
4. Add descriptions: Help users understand what each input does
5. Validate thoroughly: Use validation rules to prevent errors

Variable Usage

1. Use maps for complex logic: Instead of many conditional expressions
2. Keep expressions simple: Complex logic can be hard to debug
3. Quote when needed: Remember YAML special character rules
4. Use context variables: For unique identifiers and timestamps

Security

1. Mark secrets: Always use secret: true for sensitive values
2. Validate inputs: Prevent injection attacks with pattern validation
3. Least privilege: Configure minimal required permissions
4. Audit hooks: Review hook commands for security issues

Examples

Simple Web Application

inputs:
  - id: app_name
    name: Application Name
    type: short_text
    validations:
      required: true
      pattern: "^[a-z0-9-]+$"

  - id: environment
    name: Environment
    type: select
    options:
      - dev
      - prod
    default: dev

stacks:
  - key: main
    name: ${{ inputs.app_name }}-${{ inputs.environment }}
    autodeploy: ${{ inputs.environment == 'dev' }}

    vcs:
      reference:
        value: main
        type: branch
      repository: web-app-template
      provider: GITHUB

    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

    environment:
      variables:
        - name: ENVIRONMENT
          value: ${{ inputs.environment }}
        - name: APP_NAME
          value: ${{ inputs.app_name }}

Multi-Stack Application with Dependencies

inputs:
  - id: app_name
    name: Application Name
    type: short_text
    validations:
      required: true

stacks:
  - key: database
    name: ${{ inputs.app_name }}-db
    vcs:
      reference:
        value: main
        type: branch
      repository: postgres-template
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

  - key: backend
    name: ${{ inputs.app_name }}-api
    depends_on:
      - database
    environment:
      stack_dependency_references:
        - name: DATABASE_URL
          from_stack: database
          output: connection_string
    vcs:
      reference:
        value: main
        type: branch
      repository: api-template
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

  - key: frontend
    name: ${{ inputs.app_name }}-web
    depends_on:
      - backend
    environment:
      stack_dependency_references:
        - name: API_URL
          from_stack: backend
          output: api_endpoint
    vcs:
      reference:
        value: main
        type: branch
      repository: frontend-template
      provider: GITHUB
    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

Environment-Based Configuration with Maps

inputs:
  - id: app_name
    name: Application Name
    type: short_text

  - id: environment
    name: Environment
    type: select
    options:
      - dev
      - staging
      - prod

maps:
  dev:
    instance_type: t3.micro
    instance_count: 1
    autodeploy: true
    backup_enabled: false
  staging:
    instance_type: t3.small
    instance_count: 2
    autodeploy: true
    backup_enabled: true
  prod:
    instance_type: t3.medium
    instance_count: 3
    autodeploy: false
    backup_enabled: true

stacks:
  - key: main
    name: ${{ inputs.app_name }}-${{ inputs.environment }}
    autodeploy: ${{ maps[inputs.environment].autodeploy }}

    vcs:
      reference:
        value: main
        type: branch
      repository: app-template
      provider: GITHUB

    vendor:
      terraform:
        manage_state: true
        version: "1.5.0"

    environment:
      variables:
        - name: INSTANCE_TYPE
          value: ${{ maps[inputs.environment].instance_type }}
        - name: INSTANCE_COUNT
          value: "${{ maps[inputs.environment].instance_count }}"
        - name: BACKUP_ENABLED
          value: "${{ maps[inputs.environment].backup_enabled }}"

Schema

The up-to-date schema of a Blueprint is available through a GraphQL query for authenticated users:

{
  templateSchema
}

Tip

Remember that there are multiple ways to interact with Spacelift. You can use the GraphQL API, the CLI, the Terraform Provider, or the web UI.

For simplicity, here is the current schema, but it might change in the future:

Click to expand

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Blueprint",
    "type": "object",
    "properties": {
        "space": {
            "type": "string",
            "minLength": 1,
            "description": "The slug of the space where the deployment and its stacks will be created. If set, overrides user-supplied space."
        },
        "inputs": {
            "$ref": "#/definitions/inputs"
        },
        "maps": {
            "$ref": "#/definitions/maps"
        },
        "stacks": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/stack"
            }
        },
        "scheduled_delete": {
            "$ref": "#/definitions/delete_schedule"
        }
    },
    "additionalProperties": false,
    "required": ["stacks"],
    "definitions": {
        "maps": {
            "type": "object",
            "additionalProperties": {
                "type": "object",
                "additionalProperties": {
                    "oneOf": [
                        {
                            "type": "string"
                        },
                        {
                            "type": "number"
                        },
                        {
                            "type": "boolean"
                        }
                    ]
                }
            }
        },
        "inputs": {
            "type": "array",
            "items": {
                "$ref": "#/definitions/input"
            }
        },
        "input": {
            "type": "object",
            "oneOf": [
                {
                    "additionalProperties": false,
                    "required": [
                        "id",
                        "name"
                    ],
                    "properties": {
                        "id": {
                            "type": "string"
                        },
                        "name": {
                            "type": "string"
                        },
                        "description": {
                            "type": "string"
                        },
                        "default": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "number"
                                },
                                {
                                    "type": "boolean"
                                }
                            ]
                        },
                        "validations": {
                            "$ref": "#/definitions/string_validations"
                        },
                        "type": {
                            "type": "string",
                            "enum": [
                                "short_text",
                                "long_text",
                                "secret"
                            ]
                        }
                    }
                },
                {
                    "additionalProperties": false,
                    "required": [
                        "id",
                        "name",
                        "type"
                    ],
                    "properties": {
                        "id": {
                            "type": "string"
                        },
                        "name": {
                            "type": "string"
                        },
                        "description": {
                            "type": "string"
                        },
                        "default": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "number"
                                },
                                {
                                    "type": "boolean"
                                }
                            ]
                        },
                        "validations": {
                            "$ref": "#/definitions/number_validations"
                        },
                        "type": {
                            "type": "string",
                            "enum": [
                                "number",
                                "float"
                            ]
                        }
                    }
                },
                {
                    "additionalProperties": false,
                    "required": [
                        "id",
                        "name",
                        "type"
                    ],
                    "properties": {
                        "id": {
                            "type": "string"
                        },
                        "name": {
                            "type": "string"
                        },
                        "description": {
                            "type": "string"
                        },
                        "default": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "number"
                                },
                                {
                                    "type": "boolean"
                                }
                            ]
                        },
                        "type": {
                            "type": "string",
                            "enum": [
                                "boolean"
                            ]
                        }
                    }
                },
                {
                    "additionalProperties": false,
                    "required": [
                        "id",
                        "name",
                        "type",
                        "options"
                    ],
                    "properties": {
                        "id": {
                            "type": "string"
                        },
                        "name": {
                            "type": "string"
                        },
                        "description": {
                            "type": "string"
                        },
                        "default": {
                            "oneOf": [
                                {
                                    "type": "string"
                                },
                                {
                                    "type": "number"
                                },
                                {
                                    "type": "boolean"
                                }
                            ]
                        },
                        "type": {
                            "type": "string",
                            "enum": [
                                "select"
                            ]
                        },
                        "options": {
                            "type": "array",
                            "minItems": 1,
                            "items": {
                                "type": "string"
                            }
                        }
                    }
                }
            ]
        },
        "stack": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "name",
                "vcs",
                "vendor",
                "key"
            ],
            "properties": {
                "name": {
                    "type": "string",
                    "minLength": 1
                },
                "description": {
                    "type": "string"
                },
                "labels": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "administrative": {
                    "type": "boolean"
                },
                "autodeploy": {
                    "type": "boolean"
                },
                "autoretry": {
                    "type": "boolean"
                },
                "runner_image": {
                    "type": "string"
                },
                "secret_masking_enabled": {
                    "type": "boolean"
                },
                "worker_pool": {
                    "type": "string"
                },
                "attachments": {
                    "$ref": "#/definitions/attachment"
                },
                "environment": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                        "mounted_files": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/mounted_file"
                            }
                        },
                        "variables": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/variable"
                            }
                        },
                        "stack_dependency_references": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/dependency_reference"
                            }
                        },
                        "external_stack_dependency_references": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/dependency_reference"
                            }
                        }
                    }
                },
                "hooks": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                        "apply": {
                            "$ref": "#/definitions/before_after_hook"
                        },
                        "init": {
                            "$ref": "#/definitions/before_after_hook"
                        },
                        "plan": {
                            "$ref": "#/definitions/before_after_hook"
                        },
                        "perform": {
                            "$ref": "#/definitions/before_after_hook"
                        },
                        "destroy": {
                            "$ref": "#/definitions/before_after_hook"
                        },
                        "run": {
                            "$ref": "#/definitions/after_hook"
                        }
                    }
                },
                "schedules": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                        "drift": {
                            "$ref": "#/definitions/drift_detection_schedule"
                        },
                        "tasks": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/task_schedule"
                            }
                        }
                    }
                },
                "vcs": {
                    "type": "object",
                    "oneOf": [
                        {
                            "additionalProperties": false,
                            "required": [
                                "reference",
                                "provider",
                                "repository"
                            ],
                            "properties": {
                                "reference": {
                                    "$ref": "#/definitions/git_reference"
                                },
                                "project_root": {
                                    "type": "string"
                                },
                                "project_globs": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "provider": {
                                    "type": "string",
                                    "enum": [
                                        "GITHUB",
                                        "GITLAB",
                                        "BITBUCKET_DATACENTER",
                                        "BITBUCKET_CLOUD",
                                        "GITHUB_ENTERPRISE",
                                        "SHOWCASE",
                                        "AZURE_DEVOPS"
                                    ]
                                },
                                "id": {
                                    "type": "string",
                                    "description": "The id of the VCS provider."
                                },
                                "namespace": {
                                    "type": "string"
                                },
                                "repository": {
                                    "type": "string",
                                    "minLength": 1,
                                    "description": "The name of the repository."
                                }
                            }
                        },
                        {
                            "additionalProperties": false,
                            "required": [
                                "reference",
                                "provider",
                                "repository_url"
                            ],
                            "properties": {
                                "reference": {
                                    "$ref": "#/definitions/git_reference"
                                },
                                "project_root": {
                                    "type": "string"
                                },
                                "project_globs": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                },
                                "provider": {
                                    "type": "string",
                                    "enum": [
                                        "RAW_GIT"
                                    ]
                                },
                                "repository": {
                                    "type": "string",
                                    "description": "The name of the repository. If not provided, it'll be extracted from the repository_url."
                                },
                                "namespace": {
                                    "type": "string",
                                    "description": "The namespace of the repository. If not provided, it'll be extracted from the repository_url."
                                },
                                "repository_url": {
                                    "type": "string",
                                    "minLength": 1,
                                    "description": "The URL of the repository. This is only used for the 'RAW_GIT' provider."
                                }
                            }
                        }
                    ]
                },
                "vendor": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                        "ansible": {
                            "$ref": "#/definitions/ansible_vendor"
                        },
                        "cloudformation": {
                            "$ref": "#/definitions/cloudformation_vendor"
                        },
                        "kubernetes": {
                            "$ref": "#/definitions/kubernetes_vendor"
                        },
                        "pulumi": {
                            "$ref": "#/definitions/pulumi_vendor"
                        },
                        "opentofu": {
                            "$ref": "#/definitions/opentofu_vendor"
                        },
                        "terraform": {
                            "$ref": "#/definitions/terraform_vendor"
                        },
                        "terragrunt": {
                            "$ref": "#/definitions/terragrunt_vendor"
                        }
                    }
                },
                "depends_on": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "minLength": 1
                    }
                },
                "external_depends_on": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "minLength": 1
                    }
                },
                "key": {
                    "type": "string"
                }
            }
        },
        "attachment": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "contexts": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/context"
                    }
                },
                "clouds": {
                    "type": "object",
                    "additionalProperties": false,
                    "properties": {
                        "aws": {
                            "$ref": "#/definitions/aws_attachment"
                        },
                        "azure": {
                            "$ref": "#/definitions/azure_attachment"
                        }
                    }
                },
                "policies": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "roles": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/role_binding"
                    }
                }
            }
        },
        "aws_attachment": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "id",
                "read",
                "write"
            ],
            "properties": {
                "id": {
                    "type": "string"
                },
                "read": {
                    "type": "boolean"
                },
                "write": {
                    "type": "boolean"
                }
            }
        },
        "azure_attachment": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "id",
                "read",
                "write",
                "subscription_id"
            ],
            "properties": {
                "id": {
                    "type": "string"
                },
                "read": {
                    "type": "boolean"
                },
                "write": {
                    "type": "boolean"
                },
                "subscription_id": {
                    "type": "string"
                }
            }
        },
        "context": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "id"
            ],
            "properties": {
                "id": {
                    "type": "string"
                },
                "priority": {
                    "type": "integer",
                    "minimum": 0
                }
            }
        },
        "role_binding": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "role_id",
                "space_id"
            ],
            "properties": {
                "role_id": {
                    "type": "string"
                },
                "space_id": {
                    "type": "string"
                }
            }
        },
        "mounted_file": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "path",
                "content"
            ],
            "properties": {
                "path": {
                    "type": "string"
                },
                "content": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                },
                "secret": {
                    "type": "boolean"
                }
            }
        },
        "dependency_reference": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "name",
                "from_stack",
                "output"
            ],
            "properties": {
                "name": {
                    "type": "string"
                },
                "from_stack": {
                    "type": "string"
                },
                "output": {
                    "type": "string"
                },
                "trigger_always": {
                    "type": "boolean"
                }
            }
        },
        "variable": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "name",
                "value"
            ],
            "properties": {
                "name": {
                    "type": "string"
                },
                "value": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                },
                "secret": {
                    "type": "boolean"
                }
            }
        },
        "after_hook": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "after": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "minLength": 1
                }
            }
        },
        "before_after_hook": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "before": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "minLength": 1
                },
                "after": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "minLength": 1
                }
            }
        },
        "drift_detection_schedule": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "cron",
                "reconcile"
            ],
            "properties": {
                "cron": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/cron_schedule",
                        "maxLength": 1
                    }
                },
                "reconcile": {
                    "type": "boolean"
                },
                "ignore_state": {
                    "type": "boolean"
                },
                "timezone": {
                    "type": "string"
                }
            }
        },
        "task_schedule": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "command"
            ],
            "oneOf": [
                {
                    "required": [
                        "command",
                        "cron"
                    ]
                },
                {
                    "required": [
                        "command",
                        "timestamp_unix"
                    ]
                }
            ],
            "properties": {
                "command": {
                    "type": "string",
                    "minLength": 1
                },
                "cron": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/cron_schedule",
                        "minLength": 1
                    }
                },
                "timestamp_unix": {
                    "type": "number",
                    "minimum": 1600000000
                },
                "timezone": {
                    "type": "string"
                }
            }
        },
        "cron_schedule": {
            "type": "string",
            "pattern": "^(\\*|\\d+|\\d+-\\d+|\\d+\\/\\d+|\\*\\/\\d+|\\d+(,\\d+)+)(\\s+(\\*|\\d+|\\d+-\\d+|\\d+\\/\\d+|\\*\\/\\d+|\\d+(,\\d+)+)){4}$"
        },
        "delete_schedule": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "timestamp_unix"
            ],
            "properties": {
                "timestamp_unix": {
                    "type": "number"
                },
                "delete_stacks": {
                    "type": "boolean"
                }
            }
        },
        "ansible_vendor": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "playbook"
            ],
            "properties": {
                "playbook": {
                    "type": "string",
                    "minLength": 1
                }
            }
        },
        "cloudformation_vendor": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "entry_template_file",
                "template_bucket",
                "stack_name",
                "region"
            ],
            "properties": {
                "entry_template_file": {
                    "type": "string",
                    "minLength": 1
                },
                "template_bucket": {
                    "type": "string",
                    "minLength": 1
                },
                "stack_name": {
                    "type": "string",
                    "minLength": 1
                },
                "region": {
                    "type": "string",
                    "minLength": 1
                }
            }
        },
        "kubernetes_vendor": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "namespace"
            ],
            "properties": {
                "namespace": {
                    "type": "string",
                    "minLength": 1
                }
            }
        },
        "pulumi_vendor": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "stack_name",
                "login_url"
            ],
            "properties": {
                "stack_name": {
                    "type": "string",
                    "minLength": 1
                },
                "login_url": {
                    "type": "string",
                    "minLength": 1
                }
            }
        },
        "opentofu_vendor": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "manage_state"
            ],
            "properties": {
                "version": {
                    "type": "string"
                },
                "workspace": {
                    "type": "string"
                },
                "use_smart_sanitization": {
                    "type": "boolean"
                },
                "external_state_access_enabled": {
                    "type": "boolean"
                },
                "concise": {
                    "type": "boolean"
                },
                "enable_cpu_profiling": {
                    "type": "boolean"
                },
                "manage_state": {
                    "type": "boolean"
                },
                "workflow_tool": {
                    "type": "string",
                    "enum": [
                        "OPENTOFU",
                        "CUSTOM"
                    ]
                }
            }
        },
        "terraform_vendor": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "manage_state"
            ],
            "properties": {
                "version": {
                    "type": "string"
                },
                "workspace": {
                    "type": "string"
                },
                "use_smart_sanitization": {
                    "type": "boolean"
                },
                "manage_state": {
                    "type": "boolean"
                },
                "workflow_tool": {
                    "type": "string",
                    "enum": [
                        "TERRAFORM_FOSS",
                        "CUSTOM",
                        "OPEN_TOFU"
                    ]
                }
            }
        },
        "terragrunt_vendor": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "terraform_version": {
                    "type": "string"
                },
                "terragrunt_version": {
                    "type": "string"
                },
                "use_run_all": {
                    "type": "boolean"
                },
                "use_smart_sanitization": {
                    "type": "boolean"
                },
                "terragrunt_tool": {
                    "type": "string",
                    "enum": [
                        "TERRAFORM_FOSS",
                        "OPEN_TOFU",
                        "MANUALLY_PROVISIONED"
                    ]
                }
            }
        },
        "string_validations": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "required": {
                    "type": "boolean"
                },
                "min_length": {
                    "type": "integer",
                    "minimum": 0
                },
                "max_length": {
                    "type": "integer",
                    "minimum": 0
                },
                "length_equal": {
                    "type": "integer",
                    "minimum": 0
                },
                "pattern": {
                    "type": "string"
                }
            }
        },
        "number_validations": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "required": {
                    "type": "boolean"
                },
                "greater_than": {
                    "type": "number"
                },
                "greater_than_or_equal": {
                    "type": "number"
                },
                "less_than": {
                    "type": "number"
                },
                "less_than_or_equal": {
                    "type": "number"
                },
                "not_equal": {
                    "type": "number"
                },
                "step": {
                    "type": "integer"
                }
            }
        },
        "git_reference": {
            "type": "object",
            "additionalProperties": false,
            "required": [
                "value",
                "type"
            ],
            "properties": {
                "value": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The git reference value (branch name, tag name, or commit SHA)."
                },
                "type": {
                    "type": "string",
                    "enum": [
                        "branch",
                        "tag",
                        "sha"
                    ],
                    "description": "The type of git reference: 'branch', 'tag', or 'sha'."
                }
            }
        }
    }
}

TemplateSchema Key Differences

Templates use the templateSchema format, which has important differences from the original Blueprint schema:

Required Changes

Aspect	Original Blueprint Schema	Template Schema
Stack Definition	Single stack object OR stacks array	Only stacks array (required)
Stack Key	Not required	Each stack must have unique key field
VCS Reference	Direct fields: branch, tag, sha	Structured: reference.value and reference.type
Space Field	Required space field per stack	Optional top-level space field (defaults to template's space)
Stack Limit	Max 5 stacks	Max 10 stacks

VCS Configuration

Spacelift supports GitHub, GitHub Enterprise, GitLab, Azure DevOps, Bitbucket Cloud, Bitbucket Data Center, and raw git as VCS integrations. You will need to configure a VCS integration in your templates.

For templates, you need to provide (at minimum) the VCS provider's reference.value (branch name, tag, or SHA), reference.type and provider. Other fields may be required if you're using a non-GitHub VCS provider.

• If your VCS is anything other than GITHUB or RAW_GIT, provide the namespace as well.
  • GitLab: The group name.
  • Bitbucket & Azure: The project name.
• If the VCS is RAW_GIT, provide the repository_url instead of the namespace and repository, and do not include an id.

The id is optional and only needed if you want to use a non-default (and non-raw git) integration. You can find the ID by clicking Copy ID in the VCS integration settings.

VCS Schema

The schema for VCS providers in templates is slightly different than the schema in blueprints:

Template SchemaBlueprint Schema

vcs:
    id: "github-for-my-org"   # Only needed if using a non-default & non-RAW_GIT integration. Copy from VCS integration settings in Spacelift.
    reference:
        value: main           # Can be branch name, tag, or SHA
        type: branch          # Must specify: "branch", "tag", or "sha"
    project_root: modules/networking
    project_globs:            # Globs do not mount the files or directories in your project root. They are used to trigger your stack when there are changes to a module outside of the project_root.
        - "terraform/**"
        - "k8s/**"
    namespace: "my-namespace" # The VCS organization name or project namespace, if using anything other than GITHUB or RAW_GIT
    repository: my-repo
    repository_url: "https://github.com/my-namespace/my-repository" # This is only needed for RAW_GIT
    provider: GITHUB          # Possible values: AZURE_DEVOPS, BITBUCKET_CLOUD, BITBUCKET_DATACENTER, GITHUB, GITHUB_ENTERPRISE, GITLAB, RAW_GIT

vcs:
    branch: main           # Direct field
    repository: my-repo
    provider: GITHUB

Reference Types

The reference.type field accepts three values:

• branch: Use a branch name (e.g., main, develop)
• tag: Use a git tag (e.g., v1.0.0)
• sha: Use a specific commit SHA (e.g., abc123def456)

Tip

When a template version is published, it's automatically pinned to the current commit SHA of the specified branch/tag, ensuring deterministic deployments.

Available Stack Properties

The templateSchema supports the following stack-level properties:

Property	Type	Description
key	string	Required. Unique identifier for the stack (used in dependencies)
name	string	Required. Stack display name (can be templated)
description	string	Optional description (can be templated)
labels	array	Optional labels for categorization (can be templated)
administrative	boolean	Mark stack as administrative (can be templated)
autodeploy	boolean	Enable automatic deployment on VCS changes (can be templated)
autoretry	boolean	Enable automatic retry on failure (can be templated)
vcs	object	Required. VCS configuration (cannot be templated)
vendor	object	Required. Infrastructure tool configuration (Terraform, Pulumi, etc.)
environment	object	Environment variables and mounted files (can be templated)
attachments	object	Contexts, policies, and cloud integrations
hooks	object	Lifecycle hooks (init, plan, apply, destroy)
schedules	object	Drift detection and scheduled tasks (supports drift and tasks only)
depends_on	array	Stack dependencies within the template (cannot be templated)
external_depends_on	array	Dependencies on existing stacks by slug (can be templated)
runner_image	string	Custom runner image
worker_pool	string	Worker pool ID
secret_masking_enabled	boolean	Enable secret masking in logs

Note

Property names in Template schema are case-sensitive and use lowercase without underscores for boolean flags (e.g., autodeploy, not auto_deploy). Some properties from the original Blueprint schema are not available in Template schema.

Related Resources

• Template Overview - General information about templates
• Templates Workbench - Creating and managing templates
• Template Deployments - Deploying from templates
• Blueprint Configuration - Similar configuration reference
• Stack Configuration - Stack settings reference