Question: GHCR image cleanup strategy for ephemeral tags and orphan architecture-specific layers

[thpham]

Hi 👋

First, thanks for this excellent workflow example! The native multi-arch build approach (avoiding QEMU) is exactly what we're looking for in our CI/CD pipelines.

Context

We're adopting this workflow pattern for building ephemeral images (e.g., per-PR preview images, feature branch builds, or short-lived testing images). In these scenarios, we frequently create and delete image tags.

Question / Feature Request

I'm wondering if you've thought about or have recommendations for GHCR image cleanup strategies, particularly around:

1. Cleanup of ephemeral tags

When building images for PRs or feature branches, we end up with many tags like:

• ghcr.io/org/repo:pr-123
• ghcr.io/org/repo:feature-xyz
• ghcr.io/org/repo:sha-abc1234

These accumulate quickly and contribute to GitHub storage quota consumption.

2. Orphan architecture-specific layers

This is the trickier part. With the push-by-digest approach used in the build job, each architecture (amd64, arm64) pushes its layers independently before the manifest merge. When an ephemeral tag is deleted:

• Does deleting the manifest list automatically dereference the underlying arch-specific image digests?
• Are the architecture-specific layers (blobs) eventually garbage collected by GHCR?
• Or do we need to explicitly clean up the individual @sha256:... references?

Our Concern

Without proper cleanup, our storage quota could explode with unused/orphan layers, especially since:

• Each build produces 2x the layers (one per arch)
• The per-arch images are pushed by digest before being referenced by the manifest
• If only the tag/manifest is deleted, the underlying blobs might remain indefinitely

Would Love to Know

• Have you considered adding a cleanup job to the workflow (perhaps triggered on PR close or on a schedule)?
• Any experience or insights into how GHCR handles garbage collection of unreferenced blobs?
• Would you consider adding documentation or an example for this use case?

Some options I've seen include:

• actions/delete-package-versions
• GitHub's container registry cleanup policies
• Custom scripts using the GitHub API

Any guidance or best practices you could share would be greatly appreciated!

Thanks again for the great work on this repo 🙏

[ngeorger]

Hi 👋

First, thanks for this excellent workflow example! The native multi-arch build approach (avoiding QEMU) is exactly what we're looking for in our CI/CD pipelines.

Thank you for your kind words and I'm happy to help.

Context

We're adopting this workflow pattern for building ephemeral images (e.g., per-PR preview images, feature branch builds, or short-lived testing images). In these scenarios, we frequently create and delete image tags.

Ok, I guess you are using a private repo? Also, please indicate (if possible) how many triggering events you have per day, example: about 5 PR, 3 features, or just an average per day, example: 10 events per day. This is just for get an idea for an optimal solution for your use-case.

Question / Feature Request

I'm wondering if you've thought about or have recommendations for GHCR image cleanup strategies, particularly around:

1. Cleanup of ephemeral tags

When building images for PRs or feature branches, we end up with many tags like:

• ghcr.io/org/repo:pr-123
• ghcr.io/org/repo:feature-xyz
• ghcr.io/org/repo:sha-abc1234

These accumulate quickly and contribute to GitHub storage quota consumption.

In the past I've been using this solution for those purposes, but I've stopped using it due to security concerns over Python dependencies which could leaks credentials/tokens.

https://github.com/sredevopsorg/container-retention-policy

2. Orphan architecture-specific layers

This is the trickier part. With the push-by-digest approach used in the build job, each architecture (amd64, arm64) pushes its layers independently before the manifest merge. When an ephemeral tag is deleted:

• Does deleting the manifest list automatically dereference the underlying arch-specific image digests?

By deleting the manifest, only deletes the specified manifest, not the referenced layers/blobs/digests

• Are the architecture-specific layers (blobs) eventually garbage collected by GHCR?

By default, no "garbage collection" is automatically performed either in Actions Cache or Container Registry.

• Or do we need to explicitly clean up the individual @sha256:... references?

Yes, you need to manually (or custom-automated) perform a cleaning process both for Actions Cache and/or Container Registry

Our Concern

Without proper cleanup, our storage quota could explode with unused/orphan layers, especially since:

• Each build produces 2x the layers (one per arch)

That's correct but there is no other "simple and easy" way to build images for multiple archs with more efficient layering logic.

• The per-arch images are pushed by digest before being referenced by the manifest

Yes, that's correct. This method allows parallel building with different runners for each architecture.

• If only the tag/manifest is deleted, the underlying blobs might remain indefinitely

That's correct.

Would Love to Know

• Have you considered adding a cleanup job to the workflow (perhaps triggered on PR close or on a schedule)?

It's not a bad idea at all, but I think it should be a separated/optional feature

• Any experience or insights into how GHCR handles garbage collection of unreferenced blobs?

If your repo/package/container is not private, this is not a concern -at least in costs or billing-, but it's really important with private repos and enterprise accounts.

As mentioned, Github don't perform any actions on them by default.

• Would you consider adding documentation or an example for this use case?

Sure! Please give some feedback after reading this reply and find the best solution together.

Some options I've seen include:

• actions/delete-package-versions
• GitHub's container registry cleanup policies
• Custom scripts using the GitHub API

Any guidance or best practices you could share would be greatly appreciated!

The action you mentions seems like the best solution, because it's an official action, but it seems to not receiving active updates anymore.

I suggest to evaluate this action to cleanup your container registry and some automated script based on gh-cli to perform cleaning on the actions cache too.

Thanks again for the great work on this repo 🙏

You are welcome! Thanks for your excellent suggestions and questions.

[ngeorger]

Answered in #32 (comment)