How to bulk upload variables from .tfvars files to Spacelift stacks

Currently, there's no single built-in command to take a .tfvars file and bulk-load it into a stack's environment variables with descriptions and sensitivity settings in one step. However, there are several approaches you can use to achieve this workflow.

Available Methods

1. Terraform Provider (Recommended for ongoing management)

You can manage variables as code using spacelift_stack_environment_variable or context-level resources. This approach allows you to:

• Set write_only for sensitive values

• Add descriptions to variables

• Keep variables version-controlled and reviewable

• Reuse variables across multiple stacks

Learn more about using contexts for this approach.

2. GraphQL API with Custom Script

You can create a custom script that parses your .tfvars file and uses the GraphQL API to create variables in bulk. Here's the mutation you'll need:

mutation AddEnvironmentConfig($stackId: ID!, $input: ConfigInput!) {
  stackConfigAdd(stack: $stackId, config: $input) {
    id
    type
    __typename
  }
}

Example variables for the mutation:

{
  "stackId": "your-stack-id",
  "input": {
    "id": "variable-name",
    "description": "Variable description",
    "writeOnly": false,
    "value": "variable-value",
    "type": "ENVIRONMENT_VARIABLE"
  }
}

For mounting files, you can use "type": "FILE_MOUNT" and provide the file content as a Base64-encoded string in the value field.

3. spacectl CLI

You can use the spacectl command-line tool to manage environment variables and mount files:

spacectl stack environment setvar    # Sets an environment variable
spacectl stack environment mount     # Mount a file from existing file or STDIN
spacectl stack environment list      # Lists all environment variables and mounted files
spacectl stack environment delete    # Deletes an environment variable or mounted file

4. Direct File Mounting

If you want Terraform to consume the .tfvars file directly without converting to individual variables, you can mount it as a file in the stack (secret or non-secret) and use -var-file or a hook to pass it to Terraform. This keeps your file intact but doesn't provide per-variable metadata in the UI.

Finding API Calls

To discover the exact API calls for your specific use case, you can perform the action in the UI first and then follow this guide to capture the corresponding GraphQL request from your browser's developer tools.

Example Scripts

For reference implementations, you can check out this bulk update stacks script which demonstrates how to interact with the Spacelift API programmatically.

Feature Request

If you'd like to see a native bulk-import feature that accepts .tfvars files with optional metadata for descriptions and sensitivity, consider submitting a feature request at feedback.spacelift.io. This allows the community to upvote the idea and helps the product team prioritize based on demand.