fix: support container extraction with OCI layout export

[leodido]

Problem

When exportToCache is enabled, Docker images are exported in OCI layout format (not loaded into Docker daemon). The container filesystem extraction code uses checkImageExists() which calls docker image inspect, failing for OCI layout images with:

image not found - build may have failed silently

This blocks packages that use container extraction (e.g., extracting files from a Docker image to use in subsequent builds) when SLSA L3 caching is enabled.

Root Cause

The PostProcess function in Docker package builds always validates the image exists using checkImageExists(), which assumes the image is in the Docker daemon. With OCI layout export, the image is written to image.tar in the build directory and never loaded into the daemon.

Solution

Add checkOCILayoutExists() function to validate OCI layout images by checking for image.tar in the build directory. Update PostProcess to use the appropriate validation based on the exportToCache flag:

• exportToCache=false → use checkImageExists() (Docker daemon)
• exportToCache=true → use checkOCILayoutExists() (OCI layout)

Changes

• pkg/leeway/build.go:

  • Add checkOCILayoutExists() function (lines 2040-2065)
  • Update PostProcess to use appropriate check based on exportToCache flag (lines 2793-2825)

• pkg/leeway/build_oci_test.go:

  • Add TestCheckOCILayoutExists with 4 test cases covering:
    • Valid OCI layout
    • Missing image.tar
    • Empty image.tar
    • Invalid file type

• pkg/leeway/build_integration_test.go:

  • Add TestDockerPackage_ContainerExtraction_Integration with 2 subtests:
    • with_docker_daemon: Docker daemon path
    • with_oci_layout: OCI layout path
  • Fix TestDockerPackage_ExportToCache_Integration to create docker-container builder
  • Fix TestDockerPackage_CacheRoundTrip_Integration to create docker-container builder
  • Fix test expectations for OCI export behavior
  • Add comprehensive comments explaining what each test validates and SLSA L3 relevance

• .github/workflows/integration-tests.yaml:

  • Add workflow_dispatch trigger for manual test runs

• README.md:

  • Document docker-container builder requirement for OCI export
  • Clarify that docker/setup-buildx-action uses docker-container by default

Test Results

✅ All integration tests passing:

• TestDockerPackage_ExportToCache_Integration (3 subtests) - OCI layout export functionality
• TestDockerPackage_CacheRoundTrip_Integration - Complete cache workflow
• TestDockerPackage_OCILayout_Determinism_Integration - Deterministic builds (critical for SLSA L3)
• TestDockerPackage_OCILayout_SLSA_Integration ⭐ - PRIMARY SLSA L3 TEST - End-to-end provenance generation
• TestDockerPackage_ContainerExtraction_Integration (2 subtests) - Container extraction with both paths

Both Docker daemon and OCI layout paths verified working correctly with no "image not found" errors.

Related Issues

Part of the OCI layout + SLSA L3 work:

• Depends on: fix: extract digest from OCI layout for SLSA provenance #289 (SLSA provenance digest extraction)
• Blocks: gitpod-io/gitpod-next#11868 (SLSA L3 testing)
• Fixes https://linear.app/ona-team/issue/CLC-2009/docker-export-mode-for-slsa-l3-compliance-leeway

How to Test

Run the integration tests:

go test -tags=integration -v ./pkg/leeway/ -run ".*Integration" -timeout 10m

All tests should pass, demonstrating container extraction works with both Docker daemon and OCI layout.

Documentation

Updated README.md with OCI export requirements and docker-container builder setup instructions.

/hold

[geropl]

LGTM ✔️

[leodido]

Rebased on main

✅ Successfully rebased on latest main branch after PR #289 was merged.

Rebase details:

• Base branch changed from ldd/extract-digest-from-oci-layout to main
• No conflicts encountered (automatic rebase)
• All commits preserved with new commit hashes
• Branch force-pushed to update PR

Commit history:

6add4dd docs: add comprehensive comments to integration tests
e530a03 docs: add OCI export requirements to README
e03499a fix: support container extraction with OCI layout export

Status:

• ✅ Mergeable: true
• ✅ All test cases and comments preserved
• ✅ Ready for review and merge