How do I set a worker Docker image for multiple stacks?

Last updated: September 8, 2025

Context

When managing multiple stacks in Spacelift, you might want to configure a common worker Docker image across all stacks instead of setting it individually for each stack. This configuration can be managed through either contexts or blueprints.

Answer

There are two recommended approaches to set a worker Docker image for multiple stacks:

1. Using Contexts (Recommended)

You can create a context with the autoattach:* label and mount a config.yaml file containing the runner_image setting to /mnt/workspace/source/.spacelift/config.yaml.

2. Using Blueprints

Alternatively, you can utilize blueprints to define common configurations across multiple stacks.

Important Note on File Precedence: When a context mounts a file to the same path that already exists in the repository, the context's version takes precedence. The context file will be laid over the workspace after the Git checkout, overwriting any existing file at the same path.

This behavior allows you to safely test different configurations in feature branches while maintaining the global settings through contexts for your production environment.