Add support for manifest list signature removal and sparse manifest list stripping by aguidirh · Pull Request #2892 · podman-container-tools/skopeo

aguidirh · 2026-06-08T10:26:20Z

Summary

This PR introduces two new flags for the skopeo copy command to provide more granular control over multi-architecture image copying:

--remove-list-signatures: Removes only the manifest list signature while preserving per-instance signatures
--strip-sparse-manifest-list: Strips missing instances from manifest lists when copying specific platforms

Relates to #2882

Motivation

When copying multi-architecture images with platform-specific selections, users currently face two challenges:

The --remove-signatures flag removes ALL signatures (both manifest list and per-instance), but sometimes users only want to remove the manifest list signature
Some registries don't support sparse manifest lists (manifest lists with missing instances), requiring users to strip the non-copied instances

Changes

New Flags

--remove-list-signatures

Removes only the manifest list signature while preserving per-instance signatures
Provides finer control than --remove-signatures
If both flags are specified, --remove-signatures takes precedence

--strip-sparse-manifest-list

Strips missing instances from manifest lists when copying only a subset of platforms
Useful for registries that don't support sparse manifest lists
Requires explicit signature removal using either --remove-signatures or --remove-list-signatures
The operation will fail if signatures are present and not explicitly removed

Documentation

Updated docs/skopeo-copy.1.md with flag descriptions and usage examples
Added example showing how to copy specific platforms with sparse list stripping

Tests

Added TestCopyPlatformListWithStripSparse integration test
Updated TestSharedCopyOptionsCopyOptions unit tests to cover new flags

Test Plan

Unit tests pass: make test-unit-local
Integration tests pass: make test-integration-local
Validation passes: make validate-local
Documentation validation passes: make validate-docs

Example Usage

Copy specific platforms and strip the sparse manifest list:

skopeo copy --multi-arch=linux/amd64,linux/arm64 \
  --strip-sparse-manifest-list \
  --remove-list-signatures \
  docker://quay.io/skopeo/stable:latest \
  docker://registry.example.com/skopeo:latest

Remove only manifest list signatures:

skopeo copy --multi-arch=linux/amd64,linux/arm64 \
  --remove-list-signatures \
  docker://quay.io/skopeo/stable:latest \
  docker://registry.example.com/skopeo:latest

aguidirh · 2026-06-08T14:12:06Z

Hi @mtrmac,

I added the --remove-list-signatures to the sync command because I see a scenario where people would like to sync the repos where the signature of the manifest list is not present in source.

I did not add the --strip-sparse-manifest-list to the sync because I saw the sync command always pull and push everything, so I did not see a reason to add this flag.

Please let me know what you think about it.

mtrmac · 2026-06-08T14:17:06Z

I added the --remove-list-signatures to the sync command because I see a scenario where people would like to sync the repos where the signature of the manifest list is not present in source.

*shrug* I don’t see a strong reason to think users want that feature individually, but it’s easier / more consistent to implement that way, so, why not.

I did not add the --strip-sparse-manifest-list to the sync because I saw the sync command always pull and push everything, so I did not see a reason to add this flag.

Yeah, we’d have to move all of the --multi-arch option to be shared between copy and sync. That would also be fine, but more work, and really if users are motivated to use oc-mirror instead of skopeo sync, I think that’s the better outcome for everyone.

(ACK to the general structure from a very brief skim, I’ll try to do a more careful review soonish.)

TomSweeneyRedHat · 2026-06-10T20:50:00Z

+	require.NoError(t, err)
+	assert.Equal(t, 3, len(manifestFiles), "Expected manifest list + 2 platform manifests after stripping")
+}
+


It would be good to have a test that calls both --remove-list-signatures and --remove-signatures to make sure all get wiped.

It might also be good to have a test to make sure --strip-sparse-manifest-list fails without a --remove*signatures option

It would be good to have a test that calls both --remove-list-signatures and --remove-signatures to make sure all get wiped.

Do you mean testing each flag isolated? Or testing both of them together?

According to @mtrmac comment both flags shouldn't be used together.

It would be good to have a test that calls both --remove-list-signatures and --remove-signatures to make sure all get wiped.

Skipped — went with mtrmac's suggestion to reject both flags together instead. Implemented on d5d3ab84.

It might also be good to have a test to make sure --strip-sparse-manifest-list fails without a --remove*signatures option

Implemented on 4646b190.

TomSweeneyRedHat · 2026-06-10T20:51:50Z

@aguidirh looks like you need to update the branch.

TomSweeneyRedHat · 2026-06-10T20:52:02Z

Changes LGTM overall.

mtrmac

Thanks!

As usual, naming things tends to be the hardest part :)

…stripping This commit introduces two new flags for the skopeo copy command to provide more granular control over multi-architecture image copying: --remove-list-signatures: Removes only the manifest list signature while preserving per-instance signatures. This provides finer control than the existing --remove-signatures flag which removes all signatures. --strip-sparse-manifest-list: Strips missing instances from manifest lists when copying only a subset of platforms (using --multi-arch with a platform list). This is useful for registries that don't support sparse manifest lists. The --strip-sparse-manifest-list flag requires explicit signature removal using either --remove-signatures or --remove-list-signatures, as stripping instances invalidates the manifest list signature. These flags address scenarios where users need to copy multi-architecture images to registries with different signature requirements or those that don't support sparse manifest lists, while still maintaining control over which signatures are preserved. Documentation has been updated with usage examples, and integration tests have been added to verify the new functionality. Signed-off-by: Alex Guidi <aguidi@redhat.com>

…t list stripping Signed-off-by: Alex Guidi <aguidi@redhat.com>

aguidirh · 2026-06-12T15:28:24Z

@mtrmac are these tests flakies?

Because make test-integration-local is passing on my localhost.

mtrmac · 2026-06-16T13:06:42Z

@mtrmac are these tests flakies?

The same, newly added, test is failing in all three runs, I think this very likely to be legitimate.

I guess, but did not verify, that the image is not signed, so that error path does not engage. I’m not very sure what TestCopyPlatformListStripRemovedPlatformsFailsWithoutSignatureRemoval is supposed to verify — but maybe using --preserve-digests instead of relying on a signature would trigger the same “we can’t modify the manifest list” error path.

Because make test-integration-local is passing on my localhost.

I think most tests there are skipped without SKOPEO_CONTAINER_TESTS (and enabling that outside of a non-confined VM might be a bad idea).

mtrmac

Thanks! LGTM apart from the failing TestCopyPlatformListStripRemovedPlatformsFailsWithoutSignatureRemoval

mtrmac · 2026-06-16T13:11:28Z

 	}

+	if opts.removeSignatures && opts.removeListSignatures {
+		return nil, nil, fmt.Errorf("Only one of --remove-signatures and --remove-list-signatures can be specified")


Non-blocking: covering this in unit tests wouldn’t hurt.

aguidirh changed the title ~~Add support for selective signature removal and sparse manifest list stripping~~ Add support for manifest list signature removal and sparse manifest list stripping Jun 8, 2026

aguidirh force-pushed the RUN-4764 branch from 7927978 to 7bc9c42 Compare June 8, 2026 10:40

aguidirh mentioned this pull request Jun 8, 2026

skopeo copy --multi-arch with specific platforms fails with "blob unknown to registry" when manifest list contains other platforms #2882

Open

aguidirh force-pushed the RUN-4764 branch from 7bc9c42 to b95e405 Compare June 8, 2026 12:22

mtrmac linked an issue Jun 8, 2026 that may be closed by this pull request

skopeo copy --multi-arch with specific platforms fails with "blob unknown to registry" when manifest list contains other platforms #2882

Open

TomSweeneyRedHat reviewed Jun 10, 2026

View reviewed changes

mtrmac reviewed Jun 11, 2026

View reviewed changes

aguidirh added 10 commits June 12, 2026 15:47

fixup! Add support for selective signature removal and sparse manifes…

77a8fef

…t list stripping Signed-off-by: Alex Guidi <aguidi@redhat.com>

fixup! Add support for selective signature removal and sparse manifes…

da893d5

…t list stripping Signed-off-by: Alex Guidi <aguidi@redhat.com>

fixup! Add support for selective signature removal and sparse manifes…

4937c9a

…t list stripping Signed-off-by: Alex Guidi <aguidi@redhat.com>

fixup! Add support for selective signature removal and sparse manifes…

d5d3ab8

…t list stripping Signed-off-by: Alex Guidi <aguidi@redhat.com>

fixup! Add support for selective signature removal and sparse manifes…

df57833

…t list stripping Signed-off-by: Alex Guidi <aguidi@redhat.com>

fixup! Add support for selective signature removal and sparse manifes…

22beab5

…t list stripping Signed-off-by: Alex Guidi <aguidi@redhat.com>

fixup! Add support for selective signature removal and sparse manifes…

3c52c38

…t list stripping Signed-off-by: Alex Guidi <aguidi@redhat.com>

fixup! Add support for selective signature removal and sparse manifes…

fbcc823

…t list stripping Signed-off-by: Alex Guidi <aguidi@redhat.com>

fixup! Add support for selective signature removal and sparse manifes…

4646b19

…t list stripping Signed-off-by: Alex Guidi <aguidi@redhat.com>

aguidirh force-pushed the RUN-4764 branch from b95e405 to 4646b19 Compare June 12, 2026 13:50

fixup! Add support for selective signature removal and sparse manifes…

4c11758

…t list stripping Signed-off-by: Alex Guidi <aguidi@redhat.com>

mtrmac reviewed Jun 16, 2026

View reviewed changes

Conversation

aguidirh commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

Changes

New Flags

Documentation

Tests

Test Plan

Example Usage

Uh oh!

aguidirh commented Jun 8, 2026

Uh oh!

mtrmac commented Jun 8, 2026

Uh oh!

TomSweeneyRedHat Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

TomSweeneyRedHat Jun 10, 2026

Choose a reason for hiding this comment

Uh oh!

aguidirh Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

aguidirh Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

aguidirh Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

TomSweeneyRedHat commented Jun 10, 2026

Uh oh!

TomSweeneyRedHat commented Jun 10, 2026

Uh oh!

mtrmac left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aguidirh commented Jun 12, 2026

Uh oh!

mtrmac commented Jun 16, 2026

Uh oh!

mtrmac left a comment

Choose a reason for hiding this comment

Uh oh!

mtrmac Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aguidirh commented Jun 8, 2026 •

edited

Loading