Cloud Native Buildpacks Cache: Follow the Layer Lifecycle in CI

A Cloud Native Buildpacks build is not one opaque command that happens to reuse files. The platform runs buildpacks through a lifecycle, then assembles their output as an OCI image. When a CI build is unexpectedly cold, trace the lifecycle and the layer metadata before changing cache keys or increasing runner size. A cache image can carry reusable buildpack layers between ephemeral machines, but it does not make every build input reusable or prove that an output is fresh.

Trace the lifecycle, not just elapsed time

The lifecycle has five core phases: analyze, detect, restore, build, and export. Analyze checks image metadata and registry access; detect resolves a buildpack group and plan; restore brings eligible cached layers into the build container; build executes those buildpacks; export assembles the application image and updates cache output. For Platform API 0.7 and later, analyze runs before detect; older Platform API behavior differs, so phase order should be read against the builder’s API version rather than assumed from a log copied from another project. The Analyze phase guide, operator lifecycle guide, and phase guide for buildpack authors describe the responsibilities and API-version nuance.

The three layer flags describe different consumers, not three synonyms for “cached.” A build layer is available to later buildpacks in the build phase; a cache layer is eligible for local restoration on a later build; a launch layer is shipped in the final app image. A layer can have more than one role. A buildpack also decides whether stored metadata still makes a prior layer valid; for example, a changed runtime major version or dependency lockfile can require a rebuild. See the buildpack caching strategies guide before assuming that a cache hit means a launch artifact was reused.

Wire a remote cache into ephemeral CI

On a disposable CI worker, point each build at a registry cache image and publish the result. The cache-image option requires --publish; later builds can restore eligible layers from that image and may update it. Use registry locations your organization controls, and provide a trusted, pinned builder reference through your CI configuration:

APP_IMAGE='registry.example.invalid/team/service:commit-abc123'
CACHE_IMAGE='registry.example.invalid/team/service-cache:main'
# Set this in CI to an approved builder reference (prefer an immutable digest).
: "${BUILDER_REF:?Set BUILDER_REF to the approved builder image}"

pack build "$APP_IMAGE" \
  --path . \
  --builder "$BUILDER_REF" \
  --cache-image "$CACHE_IMAGE" \
  --publish

The .invalid registry is a deliberate placeholder, not a real endpoint. The command is illustrative and was not executed here. The pack build cache-image instructions show the same --cache-image plus --publish pairing and note that image retention is the owner’s responsibility.

Do not diagnose reuse from total elapsed time alone. Compare a cold build with a repeat build using the same application image lineage and cache image, then read the phase output:

===> RESTORING
Restoring ... from cache
Not restoring ... marked as launch=true

That excerpt is schematic, not a verbatim lifecycle log: the official phase guide shows the launch=true non-restoration case, while the positive Restoring ... from cache line is illustrative and exact wording varies by lifecycle version. First ask whether analyze found the expected previous app image and whether restore saw the intended cache image. Then inspect which layer was not restored and whether its buildpack metadata says it is cacheable and still valid. A launch=true layer may be present in the application image without being restored into the build container; that message alone is not a cache failure.

When no layer is restored, check these boundaries in order:

Confirm the job passed the same cache-image reference and actually publishes it; a differently scoped branch or repository tag is a different cache location.
Confirm the registry credentials can read and update that image. Analyze, restore, and export need image-repository or daemon access.
Compare the builder and buildpack group and their input metadata. A changed dependency manifest or runtime requirement can correctly invalidate a layer.
Inspect the particular layer’s build, cache, and launch intent instead of expecting every layer to participate in every phase.
Check registry retention and job ownership. Buildpacks do not clean old cache images up for you, and builds using a shared cache image can update it.

These checks separate a missing cache transport from a deliberate invalidation. If the layer was invalidated because an input changed, making the cache key broader may hide a real dependency change rather than fix performance.

Treat the builder trust setting as a credential boundary

The lifecycle phases that analyze, restore, and export need registry credentials or access to a container-image daemon. The buildpacks themselves do not need those credentials for their work. With an untrusted builder, pack runs the lifecycle phases in separate containers so the privileged image-access phases are separated from buildpack execution. With a trusted builder, pack may use the single creator lifecycle binary. That is a trust decision, not only a speed setting: trust only builders whose buildpacks you are willing to run within the credential boundary described by the trusted builders guide.

The operational model is straightforward: the app image is the build result, the cache image is mutable performance state, and layer metadata is the buildpack’s reuse contract. Keep those roles distinct, observe restore decisions at layer granularity, and preserve a cold build path so cache absence affects build time rather than whether the pipeline can produce an image.

Related:

Sources:

Trace the lifecycle, not just elapsed time

Wire a remote cache into ephemeral CI

Treat the builder trust setting as a credential boundary

Comments