Base Images
Choose the container image for your builds. Add a setup script to install dependencies.
Default behavior
By default, Zippy runs builds in an ubuntu:24.04
container. No configuration needed.
The container mounts your project at /app
and runs zippy.sh
from there.
Selecting an image
Choose a base image by adding a setup script to your repo root. The script name determines the image:
| Script name | Container image |
|---|---|
ubuntu.sh |
ubuntu:24.04 |
ubuntu-24.04.sh |
ubuntu:24.04 |
ubuntu-20.04.sh |
ubuntu:20.04 |
alpine.sh |
alpine:latest |
alpine-3.19.sh |
alpine:3.19 |
The version in the filename becomes the image tag. Use any valid tag for your chosen base.
Setup scripts
Setup scripts run once when the container is created, and again whenever the script changes. Use them to install system dependencies.
Ubuntu example
Alpine example
Tip: Setup scripts are cached. Zippy tracks the script's SHA256 hash and only re-runs it when the content changes.
How it works
On each push, Zippy:
-
Detects your setup script (e.g.,
ubuntu-22.04.sh) - Creates or reuses a container with that base image
- Runs the setup script if it changed since the last build
- Runs
zippy.shinside the container
Changing images
When you change your setup script's filename (e.g., from
ubuntu-22.04.sh
to ubuntu-24.04.sh), Zippy detects the image change and recreates your container:
Best practices
Pin your versions
Use versioned scripts like ubuntu-22.04.sh
instead of ubuntu.sh
for reproducible builds.
Keep setup scripts minimal
Only install system dependencies in setup scripts. Use
zippy.sh
for project-specific setup like npm install.
Use Alpine for speed
Alpine images are smaller and start faster. Great for simple builds that don't need glibc.