logo
Sign in

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.

Select APT packages

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.

APT packages ready

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
Custom Dockerfile

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.

Custom Dockerfile ready

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.

profile container image caching

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.