Skip to main content
Version: Next 🚧

Customization point: Staging Scripts



This customization interacts with the customization of buildpacks.

Epinio uses staging scripts to interact with Paketo Cloud Native Buildpacks.

Epinio automatically selects the set of staging scripts based on the name of the chosen builder image, and the images supported by a specific definition.

By default Epinio installs three definitions.

  1. One to support Bionic-based builder images (paketo-buildpacks/builder:*).
  2. One to support Jammy-based builder images (paketo-buildpacks/builder-jammy-*:*).
  3. One to serve as fallback for any images not captured by the other two.

It is this last definition which is configured when customizing buildpacks with a different image.

By default this fallback is configured for Jammy-based images in general, and the jammy full stack paketo builder image in particular


A set of staging scripts is represented by a kubernetes ConfigMap resource labeled with epinio-staging.

This ConfigMap is expected to have the following keys:

builderGlob-pattern to match the image references supported by this spec.
userIDUser ID to run the build script with.
groupIDGroup ID to run the build script with.
envStandard environment for the scripts, YAML-formatted string, key/value map.
baseOptional redirect to the actual ConfigMap with the scripts.
buildShell script to compile the unpacked sources into an image.
Executed using the chosen builder image
downloadImageContainer image to run the download script with.
downloadShell script to retrieve the app sources from the Epinio's S3 storage.
Executed using the downloadImage
unpackImageContainer image to run the unpack script with.
unpackShell script to unpack the app sources into a directory tree.
Executed using the unpackImage

When base is specified it refers to a ConfigMap which contains all the keys listed after base.

If base and any of the keys listed after it are specified in the same resource then base has priority.

This mechanism allows the sharing of script and image data between specifications differing only in the user/group/environment required to run the build script.


User and group IDs, and general support for multiple staging scripts, was added because the Bionic and Jammy-based builders use different numeric ids for their cnb user.

Env was added as the different builders may require different values for the CNB_PLATFORM_API environment variable.

Staging script API, Download

The download script is executed using the downloadImage and further configured with four environment variables:

PROTOCOLS3 storage, protocol
ENDPOINTS3 storage, primary endpoint
BUCKETS3 storage, name of bucket to read
BLOBIDS3 storage, blod id/name of app sources, in the bucket

Staging script API, Unpack

The unpack script is executed using the unpackImage and further configured with a single environment variable:

BLOBIDblob id / file name of the app source archive to unpack
USERIDNumeric id of the cnb user used to run the build script
GROUPIDNumeric id of the user group used to run the build script

Staging script API, Build

The build script is executed using the using the chosen builder image and further configured with a two environment variables:

PREIMAGEurl to the result image from a previous push
APPIMAGEurl to save the new application image under
USERIDNumeric id of the cnb user used to run the build script
GROUPIDNumeric id of the user group used to run the build script

When present the PREIMAGE is used by /cnb/lifecycle/creator as a cache for layers, speeding up compilation.

Epinio determines the set of staging scripts to use by glob-matching the chosen builder image (name and tag) against the builder key of all found specifications and selecting the first matching.

To ensure a deterministic search order the specifications are sorted lexicographically by name.

The exception to the above are specifications with builder == "*" or builder == "". These specifications match everything and the last found is used as the fallback if and only if no other specification matched.

If no specification matched, and no fallback was found, staging fails.