Automating ECR Cleanup and Policy Management

Managing container images in AWS Elastic Container Registry (ECR) can quickly become a challenge as your infrastructure grows. Multi-arch builds, frequent deployments, and evolving policies often leave behind orphaned images and inconsistent lifecycle rules. Manual cleanup is tedious and error-prone, so how do we automate this process and keep our registries lean and compliant?

In this post, I’ll introduce two open-source tools I built to solve this problem: ECR Lifecycle Cleaner and its companion GitHub Action. These tools help you enforce lifecycle policies and clean up orphaned images across all your ECR repositories, with minimal effort.

Why ECR Cleanup Matters

If you’re using docker buildx or pushing multi-arch images, you’ve probably noticed that ECR’s built-in lifecycle policies don’t always remove all the underlying image artifacts. You end up with untagged, orphaned images that consume storage and clutter your registry. Over time, this can lead to increased costs and operational headaches.

Meet ECR Lifecycle Cleaner

ECR Lifecycle Cleaner is a CLI utility designed to:

Clean up orphaned images left behind by multi-platform builds.
Apply lifecycle policies to multiple repositories at once.
Automate routine ECR maintenance at scale.

It’s built in Go, tested on Linux and MacOS, and supports dry-run operations to ensure you know exactly what will be deleted before you hit the go button.

Key Features

Clean Command: Scans your ECR repos and deletes orphaned images that have not been removed by lifecycle policies.
setPolicy Command: Applies a JSON lifecycle policy to one or many repositories in bulk.
Bulk Operations: Use --allRepos or regex patterns to target multiple repositories.
Dry Run: Always start with --dryRun to see what would be deleted or changed.

Example Usage

Clean up all orphaned images across every ECR repository:

ecr-lifecycle-cleaner clean --allRepos --dryRun

Apply a lifecycle policy to all production repositories:

ecr-lifecycle-cleaner setPolicy --policyFile policy.json --repoPattern '^app-.*-prod$' --dryRun

Warning: There is no undo! Always use --dryRun first.

GitHub Action: Automate Everything

To make this process even easier, I built the ECR Lifecycle Cleaner GitHub Action. This lets you schedule cleanups and policy enforcement directly from your CI/CD pipelines.

Example Workflow

name: Clean ECR Orphaned Images
on:
  schedule:
    - cron: '0 0 * * *'

jobs:
  clean-ecr:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Clean ECR Repositories
        uses: gjorgji-ts/ecr-lifecycle-cleaner-gh-action@v1.1.0
        with:
          ecr-lifecycle-cleaner-version: '1.2.1'
          command: 'clean'
          dry-run: 'false'
          all-repos: 'true'

You can also use the action to apply policies, target specific repositories, or run in dry-run mode on PRs to validate changes before merging.

Security & Best Practices

Principle of Least Privilege: Grant only the necessary ECR permissions to your CI/CD role.
Dry Run First: Always validate changes before running destructive operations.
Automate Regularly: Schedule cleanups to keep your ECR usage efficient and predictable.

Conclusion

By combining the ECR Lifecycle Cleaner CLI with the GitHub Action, you can automate ECR maintenance and focus on building, not cleaning. No more manual image deletions, bloated registries, just clean policy-driven automation.

If you find these tools useful, feel free to ⭐ the repos or open an issue with feedback!

Happy automating! 🚀

Automating ECR Cleanup and Policy Management.