Custom Base Images for GitHub Actions
Accelerate your workflows by pre-installing dependencies directly into your runner's base image. Instead of installing packages at runtime during every job, custom base images let you create optimized runners with your tools already available, eliminating repetitive setup steps and reducing job execution time.
Preinstalled packages
Enable custom base image
Go to the desired Runner Profile and select a customizable base image.
Select APT packages
Type the Ubuntu packages to install.

You can find the list of available packages from the Ubuntu website.
Submit the profile
After updating your profile definition the custom base image will be built. Once the image is ready to use, you will see a confirmation in the profile editor.

You can modify the list of pre-installed packages at any time. Any update to the selection will automatically update the base image.
Custom Dockerfile base
Using a custom Dockerfile, you can add any dependencies on top of the Namespace base image. Dockerfile syntax is fully supported, allowing customization beyond pre-installing APT packages.
Important to know:
- The final layer must be based on NAMESPACE_BASE_IMAGE_REF. The base image contains the software required to integrate with GitHub, without it your workflows won't start.
- After an image is built, it needs to be distributed and optimized. Workflows using this profile may take longer to start than normal while this is still in progress.
To get started with a Dockerfile-based custom image:
Enable custom base image
Go to the desired Runner Profile and select a customizable base image.
Add customization steps
Add your custom Dockerfile steps to the input. Make sure to build on NAMESPACE_BASE_IMAGE_REF in your final layer:
ARG NAMESPACE_BASE_IMAGE_REF=""
FROM ${NAMESPACE_BASE_IMAGE_REF} AS base

Submit the profile
After updating your profile definition the custom base image will be built. Once the image is ready to use, you will see a confirmation in the profile editor.

You can modify the Dockerfile at any time. Any update will automatically rebuild the base image.
Note that a new image needs to be distributed and optimized. During this operation, workflows using this profile may take longer to start.
Caching Custom Base Images
For optimal performance, we recommend enabling container image caching when using custom base images. This minimizes the startup time of your runners, as the base image will already be pulled and unpacked.
Faster pulls with one click
To enable container image caching, simply check the corresponding option in your runner profile configuration.

That's it! Repeated pulls of the base image will now complete in seconds rather than minutes.
When combining custom base images with container image caching, all image contents, including working directory, will land in the cache. Namespace is working on an optimized image distribution mechanism that provisions custom base images in seconds, without occupying space in the cache.