kamal-image-retention: Cleaning Up After Deploys

Kamal prunes old containers and images on your app servers. But each release can leave another copy on the machine that built it and in your Docker registry. Those copies keep taking up disk space after the app has moved on.

I made kamal-image-retention to clean up those two places, one application at a time. It reads the image name, registry, hosts and SSH settings from your existing Kamal configuration.

Add it to the Gemfile you use to run Kamal, then run bundle install:

gem "kamal-image-retention", "~> 0.1.1", require: false

From the application’s Kamal directory, preview what is eligible for removal, then apply it:

bundle exec kamal-retain-images
bundle exec kamal-retain-images --apply

Pass -d staging to both commands if you deploy to a named destination. Without --apply, nothing is removed.

By default, it keeps the five newest distinct builds tagged with a full Git SHA, ordered by image creation time. Kamal’s existing retain_containers setting changes that number. Named tags such as stable are protected, along with images referenced by running or stopped containers on the build machine or the configured app hosts. An older build still in use survives even if it falls outside the newest five.

For automatic cleanup, the README has a post-deploy hook for deploy and redeploy. It inherits the deployment destination from Kamal.

Registry cleanup currently supports Kamal’s kamal-docker-registry container running Distribution v3, with its default configuration and a single Docker volume at /var/lib/registry. With GHCR or another hosted registry, it cleans the build machine and leaves registry retention to the provider. Collection pauses pushes and pulls across the supported registry, including its other repositories.

It requires Ruby 3.2 or newer and Kamal ~> 2.12. MIT licensed, on RubyGems and GitHub.