Adding Additional Tools to the Docker Runner Image

Last updated: August 15, 2025

Some Spacelift runner images do not include every tool you might need for your workflows. If your automation requires extra utilities, you can create a custom Docker image that builds on top of an existing Spacelift runner image.

Creating a Custom Runner Image

The recommended approach is to build on top of our existing runner image rather than starting from scratch. This ensures you maintain access to all Spacelift tooling while adding the packages you need.

Here's how to add Git to your custom runner image:

  1. Create a Dockerfile that extends our base runner image

  2. Add the Git package installation command

  3. Ensure proper user permissions are maintained

Example Dockerfile:

FROM public.ecr.aws/spacelift/runner-<type>:latest

RUN apk add --no-cache <your-package-here>

Important Considerations

When customizing the runner image, keep these key points in mind:

  • User Requirements: Spacelift workflows run as the spacelift user with UID 1983. Make sure this user exists in your image and has the correct UID.

  • File Permissions: Any files or tools you add should have the right ownership and permissions set for the spacelift user.

  • Base Image Compatibility: The exact commands may vary depending on the base image you're starting from.

Additional Resources

For detailed instructions on customizing runner images, see our documentation: Customizing the Runner Image

You can also inspect our public runner images on GitHub to understand the base configuration: Spacelift