Resolve pre_start hook images alongside service images

[ndeloof]

What I did

Fixes #13924.

pre_start hooks run as ephemeral init containers with their own image (ServiceHook.Image), but that image was ignored by Compose image resolution:

• docker compose config --images didn't list it
• docker compose pull didn't fetch it
• docker compose up failed at runtime with No such image when the hook image wasn't already present locally (the hook has no on-the-fly pull — createPreStartContainer just calls ContainerCreate with hook.Image)

This PR treats pre_start hook images like service images. A new api.GetDependentImages(service) helper returns a service's pre_start hook images, and it is used wherever service images are collected/pulled:

Location	Change
pkg/api/api.go	new GetDependentImages helper
pkg/compose/build.go — getLocalImagesDigests	collect hook images
pkg/compose/pull.go — pullRequiredImages (up/create path)	pull missing hook images (same pattern as VolumeTypeImage)
pkg/compose/pull.go — pull (the pull command)	pull missing hook images, inheriting the parent service pull policy
cmd/compose/config.go — runConfigImages	list hook images

Scope

Only pre_start is in scope. post_start / pre_stop hooks run via ExecCreate inside the service container (pkg/compose/hook.go) and never use hook.Image, so there is nothing to pull for them. An empty hook image falls back to the service image, which is already resolved.

Known limitations / follow-ups

Digest resolution and locking are not covered by this PR, deliberately:

• config --resolve-image-digests: compose-go's Project.WithImagesResolved only resolves service.Image, never hook images. Covering hooks cleanly requires extending WithImagesResolved upstream — done in Resolve dependent images (pre_start hooks, type: image volumes) in WithImagesResolved compose-spec/compose-go#894, to be wired here once it is released and vendored.
• config --lock-image-digests: this produces an override file that is re-merged, but pre_start has no special merge rule and its list is merged by concatenation (override/merge.go), so a hook override would duplicate the hook instead of pinning it. To be addressed together with / after the compose-go change.

Tests

Unit tests only:

• TestGetDependentImages (pkg/api) — with/without hook image, and confirms post_start/pre_stop are not collected.
• TestGetLocalImagesDigests_PreStartHook (pkg/compose) — the hook image (alpine:3.19) is inspected alongside the service image (alpine:3.20).

How to test manually

services:
  sample:
    image: alpine:3.20
    command: sh -c 'sleep 5'
    pre_start:
      - image: alpine:3.19
        command: sh -c 'echo init'

$ docker rmi alpine:3.19
$ docker compose config --images   # now lists alpine:3.19 AND alpine:3.20
$ docker compose pull              # now pulls alpine:3.19

[docker-agent]

Assessment: 🟢 APPROVE

The PR correctly surfaces pre_start hook images for resolution, pulling, and listing. The core logic in GetDependentImages, the goroutine closures in pull(), and error propagation are all sound. No high or medium severity bugs were confirmed.

Summary of analysis:

• GetDependentImages correctly filters empty images and only includes pre_start hooks (not post_start/pre_stop, which have no image to pull).
• pull() correctly inherits the parent service's pull policy for hook images, including skipping on PullPolicyNever/PullPolicyBuild, checking local presence for PullPolicyMissing/PullPolicyIfNotPresent, and always pulling for PullPolicyAlways.
• pullRequiredImages() follows the same "pull if missing" pattern as the existing volume-image block — consistent with the function's existing design.
• Goroutine closures are safe: hookService is a local copy per iteration.
• Error propagation from hook-image pulls goes through eg.Wait() and is correctly returned to callers.

[Copilot]

Pull request overview

This PR fixes image resolution/pulling for pre_start lifecycle hooks by treating hook images as dependent images of a service, ensuring they are listed by docker compose config --images and pulled by both docker compose pull and the up/create pull path.

Changes:

• Add api.GetDependentImages(service) to expose pre_start hook images as additional service-dependent images.
• Include hook images in local image digest inspection and image pulling logic.
• Extend config --images output to include pre_start hook images.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pkg/api/api.go	Adds GetDependentImages helper for pre_start hook images.
pkg/api/api_test.go	Adds unit tests for GetDependentImages.
pkg/compose/build.go	Includes hook images when collecting local image digests.
pkg/compose/build_test.go	Adds unit test validating hook image digest inspection.
pkg/compose/pull.go	Pulls missing pre_start hook images in both pull and up/create pull paths.
cmd/compose/config.go	Updates config --images to print hook images.

[ndeloof]

Note to myself: we should extract an ImageRef struct so pullServiceImage doesn't relies on ServiceConfig and we don't need such a hack

[codecov]

Codecov Report

❌ Patch coverage is 28.84615% with 37 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pkg/compose/pull.go	14.63%	31 Missing and 4 partials ⚠️
cmd/compose/config.go	0.00%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

This PR correctly wires pre_start hook images into docker compose config --images, docker compose pull, and the up/create pull path. The overall approach is sound. One inconsistency was found in the up/create path: hook images are not force-pulled when the parent service has pull_policy: always, while service images are. See the inline comment for details.

[docker-agent]

[medium] addPreStartHookPulls silently skips hook images when service has pull_policy: always

addPreStartHookPulls guards against pulling already-present images with a plain existence check:

if _, ok := images[img]; ok {
    continue  // skips regardless of pull policy
}

This means that when a service has pull_policy: always, its own image is force-pulled every time (because mustPull returns true for PullPolicyAlways), but its pre_start hook images are silently skipped if they are already present locally — they never get the same "always re-pull" treatment.

A user who sets pull_policy: always to ensure freshness on every docker compose up will see the service image updated while stale hook images are left behind, which can lead to subtle divergence between the service container and its init hooks.

The fix is to also respect PullPolicyAlways in addPreStartHookPulls, analogous to how mustPull handles it for service images:

Suggested change

	if _, ok := images[img]; ok {
	for name, service := range project.Services {
	if service.PullPolicy == types.PullPolicyNever {
	continue
	}
	for i, img := range api.GetDependentImages(service, project.Name) {
	if service.PullPolicy != types.PullPolicyAlways {
	if _, ok := images[img]; ok {
	continue
	}
	}
	if scheduled[img] {
	continue
	}

Confidence	Score
🟡 moderate	67/100