Using a custom OpenTofu binary source instead of GitHub downloads

By default, Spacelift downloads OpenTofu binaries from GitHub. If you need to use your own CDN or custom source for OpenTofu binaries, you can achieve this by using a custom runner image with the binary pre-installed.

How it works

Before downloading from GitHub, Spacelift checks for an existing binary at the path {SPACELIFT_WORKER_BINARIES_DIRECTORY}/tofu/tofu-{version}. For example, it would look for tofu-1.10.2 for version 1.10.2.

If the binary is found and the version matches what's configured on your stack, Spacelift will use the cached binary instead of downloading from GitHub. You'll see a log message like:

Using OpenTofu X.X.X from cache

Implementation approach

Since SPACELIFT_WORKER_BINARIES_DIRECTORY is a volume that gets mounted at runtime (not during image build), you need to copy the binary into the correct location after the container starts but before Spacelift begins its checks.

The recommended approach is to:

1. Install your custom OpenTofu binary in your custom runner image

2. Create an entrypoint script that copies the binary to the expected location at runtime

3. Wrap the Spacelift launcher with this entrypoint script

This ensures the binary is available in the correct location after the volume is mounted but before Spacelift starts looking for it.

Alternative approaches

You can also explore using:

• Custom workflow tools for more advanced customization

• Custom runner images with hooks for additional setup steps

These methods are particularly useful for vendor versions that aren't natively supported by Spacelift.