Where does ECR storage cost come from in CI-heavy repositories?

In a CI-heavy repository, cost comes from the pipeline pushing images faster than anyone deletes them. ECR bills for stored bytes, so every image a pipeline leaves behind adds to registry storage cost until something removes it. That removal process is what an ECR lifecycle policy automates.

Most CI images fall into four classes:

  • Untagged manifests. Pushing a moving tag such as latest or main repoints the tag and leaves the previous manifest with no tag at all.
  • Per-commit tags (for example, a short Git SHA). One is created per build, and none are ever reused.
  • Per-branch and PR tags. These outlive the branch, often by months.
  • Release tags. There are few of them, and they often have to be kept for rollback or audit.
push 1:  main ──► sha256:a1
push 2:  main ──► sha256:b2    sha256:a1 (untagged)
push 3:  main ──► sha256:c3    sha256:b2 (untagged)
                               sha256:a1 (untagged)

Only the release class has a natural upper bound. The other three grow with commit volume, so untagged images and stale tags build up quietly.

Image count does not translate directly into stored bytes. Within a repository, layers shared by several images are stored once. Fifty builds that differ only in a thin application layer on a common base cost far less than fifty full images. Deleting an image frees only the layers that no remaining image references.

This matters most to the backend and platform engineers who own CI pipelines and registries. Their tagging conventions determine which images a lifecycle rule can target safely.

 CI pipeline            ECR repository (state after each push)
┌──────────┐           ┌──────────────────────────────────────────────┐
│ push 1   │─────────► │ main ──► sha256:a1                           │
├──────────┤           ├──────────────────────────────────────────────┤
│ push 2   │─────────► │ main ──► sha256:b2    sha256:a1  (untagged)  │
├──────────┤           ├──────────────────────────────────────────────┤
│ push 3   │─────────► │ main ──► sha256:c3    sha256:b2  (untagged)  │
│          │           │                       sha256:a1  (untagged)  │
└──────────┘           └──────────────────────────────────────────────┘

 Image classes                     Growth
┌──────────────────────────────┐
│ untagged manifests           │──► every push of a moving tag
│ per-commit tags (Git SHA)    │──► every build, never reused
│ per-branch / PR tags         │──► outlive the branch
│ release tags                 │──► few; keep for rollback/audit
└──────────────────────────────┘

 Stored bytes: each layer is stored once per repository
 sha256:a1 ──┐
 sha256:b2 ──┼──► ┌────────────────────┐
 sha256:c3 ──┘    │ shared base layers │  stored once
                  └────────────────────┘
 sha256:a1 ─────► ┌────────────────────┐
 sha256:b2 ─────► │ thin app layers    │  one per image; freed only
 sha256:c3 ─────► │ (a1, b2, c3)       │  when no image references it
                  └────────────────────┘

Each push of the moving main tag leaves the previous manifest untagged. Three of the four image classes grow with commit volume. Shared base layers are stored once, so image count does not map linearly to stored bytes.

How does an ECR lifecycle policy work?

A lifecycle policy is a JSON document attached to a single repository. It contains a list of rules, and each rule has three parts:

  • rulePriority: a unique integer that sets evaluation order.
  • selection: which images the rule targets and the threshold that triggers expiry.
  • action: expire is the only type.

The selection block does most of the work:

Field Values What it controls
tagStatus tagged, untagged, any Which images the rule considers at all
tagPrefixList / tagPatternList e.g. ci-, pr-* Narrows tagged rules to specific tags (one is required for tagged)
countType imageCountMoreThan Keep the newest N matching images and expire the rest
countType sinceImagePushed Expire images older than N units (countUnit: days)
countNumber integer The N in either count type

Rules are evaluated in ascending rulePriority order, so 1 runs before 10. Once a rule's selection matches an image, rules with higher numbers no longer consider that image. This is why ordering matters. A rule that retains the last 20 release- images must run before a broad age-based rule. If it runs after, the broad rule can expire release images first. For the same reason, a rule using tagStatus: any must have the highest priority number. It acts as a catch-all.

The minimal useful rule for CI repositories looks like this: priority 1, tagStatus: untagged, sinceImagePushed with countNumber: 7 and countUnit: days, and action expire. Each force-pushed latest or branch tag leaves an orphan behind, and this rule removes those orphans.

Expiration runs asynchronously. When you apply a policy, nothing is deleted right away. Images are removed some time after they qualify, and storage charges fall only once that happens. A lifecycle policy reduces cost. It does not guarantee deletion on a schedule, so do not use its timing as a compliance or data-retention control.

{
  "rules": [
    {
      "rulePriority": 1,
      "description": "Expire untagged images (orphans from re-pushed tags) 7 days after push",
      "selection": {
        "tagStatus": "untagged",
        "countType": "sinceImagePushed",
        "countUnit": "days",
        "countNumber": 7
      },
      "action": { "type": "expire" }
    },
    {
      "rulePriority": 10,
      "description": "Keep the newest 20 release- images; evaluated before the catch-all so they are protected",
      "selection": {
        "tagStatus": "tagged",
        "tagPrefixList": ["release-"],
        "countType": "imageCountMoreThan",
        "countNumber": 20
      },
      "action": { "type": "expire" }
    },
    {
      "rulePriority": 100,
      "description": "Catch-all: expire any remaining image older than 30 days; must have the highest priority number",
      "selection": {
        "tagStatus": "any",
        "countType": "sinceImagePushed",
        "countUnit": "days",
        "countNumber": 30
      },
      "action": { "type": "expire" }
    }
  ]
}

A lifecycle policy that expires untagged orphans after 7 days, keeps the newest 20 release- images, and ends with a tagStatus any catch-all at the highest priority number. JSON has no comments, so each rule is annotated with its description field.

How should you align your tagging convention with lifecycle rules?

A lifecycle policy can only target images by tag prefix (or pattern), tag status, push age and image count. It cannot see who built an image, which branch produced it, or whether anything is running it. Your tags are the only signal it has, so give each image class its own prefix and one rule.

Generic "keep the last N" rules fail when classes share a prefix. Suppose a CI pipeline pushes dozens of main-* images a day, and a rarely deployed service's only production build also carries a main-* tag. A rule keeping 50 images rotates that build out within days, while nothing about it changed. A separate prefix per class keeps fast-moving builds from pushing out slow-moving ones.

The policy also has no knowledge of what is deployed. Mark in-use images through tags: when a build is promoted, add a tag such as release-2024.06.1 or prod-current to the same digest. Then give the protective rule a higher priority (lower number) than the cleanup rules. Once a higher-priority rule selects an image, lower-priority rules cannot expire it, even if it still carries its original pr- or main- tag.

Image class Tag prefix Retention rule type Rationale
Release / promoted release-, prod- Count, set high Rollback targets. Infrequent pushes keep the count low.
Main branch main- Count (last N) Recent builds are useful for bisecting and redeploys.
PR / per-commit pr-, sha- Age since push Short-lived and high volume. Worthless after merge.
Untagged none Age since push Superseded pushes and leftover layers.

How do you write and apply an ECR lifecycle policy for a CI repository?

The worked policy has four rules. Lower rulePriority numbers are evaluated first. Once a rule's selection matches an image, rules with a higher number can no longer act on it.

  1. Priority 1, release tags. tagStatus: tagged, tagPrefixList: ["v"], countType: imageCountMoreThan, count 50.
  2. Priority 2, pr- prefix. Keep the newest 20.
  3. Priority 3, sha- prefix. Keep the newest 30.
  4. Priority 4, untagged. tagStatus: untagged, countType: sinceImagePushed, countUnit: days, count 3.

Release comes first for a specific reason. CI pipelines often promote a build by adding v1.4.2 to an image that already carries sha-9f3c1e. If the sha- rule ran at priority 1, it would claim that image and count it among the last 30 commits. Your release would then expire after a busy week. The same failure happens with any broad rule placed above a protective one. A tagStatus: any rule is the worst case, and ECR requires it to have the highest priority number.

Preview, apply, verify

  1. Record the starting state. Run aws ecr describe-images with a --query that returns length(imageDetails), and save the full tag list.
  2. Start a preview. Run aws ecr start-lifecycle-policy-preview with --lifecycle-policy-text file://policy.json.
  3. Read the preview results. Poll aws ecr get-lifecycle-policy-preview until the status is COMPLETE. Then read each result's imageTags and appliedRulePriority. Any release tag marked for expiry means your ordering is wrong.
  4. Apply the policy. Run aws ecr put-lifecycle-policy with the same file.
  5. Verify. Expiration is not immediate, so wait before checking. Then rerun describe-images and diff the counts and tags against your baseline.
#!/usr/bin/env bash
# Preview, apply and verify an ECR lifecycle policy (policy.json holds the four rules).
set -euo pipefail
REPO=ci-app

# 1. Baseline: total image count plus a sorted tag list to diff later.
aws ecr describe-images --repository-name "$REPO" --query 'length(imageDetails)'
aws ecr describe-images --repository-name "$REPO" \
  --query 'imageDetails[].imageTags[]' --output text | tr '\t' '\n' | sort > tags-before.txt

# 2. Dry run: nothing is deleted by a preview.
aws ecr start-lifecycle-policy-preview --repository-name "$REPO" \
  --lifecycle-policy-text file://policy.json

# 3. Poll until the preview finishes (status can also be FAILED or EXPIRED).
until [ "$(aws ecr get-lifecycle-policy-preview --repository-name "$REPO" \
  --query 'status' --output text)" != "IN_PROGRESS" ]; do sleep 5; done

# Which rule would expire each image?
aws ecr get-lifecycle-policy-preview --repository-name "$REPO" \
  --query 'previewResults[].[appliedRulePriority, join(`,`, imageTags || `[]`)]' --output text

# Ordering check: review any release (v*) tag that shows up here before applying.
# Expiring the oldest releases beyond the 50 kept is expected. A release tag that
# shows a priority other than 1 means a broader rule claimed it first.
aws ecr get-lifecycle-policy-preview --repository-name "$REPO" \
  --query "previewResults[?imageTags && length(imageTags[?starts_with(@, 'v')]) > \`0\`]"

# 4. Apply the same file that was previewed.
aws ecr put-lifecycle-policy --repository-name "$REPO" \
  --lifecycle-policy-text file://policy.json

# 5. Later, after expiration has had time to run, re-snapshot and diff against the baseline.
aws ecr describe-images --repository-name "$REPO" \
  --query 'imageDetails[].imageTags[]' --output text | tr '\t' '\n' | sort > tags-after.txt
diff tags-before.txt tags-after.txt || true

The AWS CLI workflow for an ECR CI repository: record a baseline, run a lifecycle policy preview, inspect which rule priority would expire each image and flag release tags for review, apply the policy, and diff tags afterward.

When should you avoid aggressive lifecycle rules?

Lifecycle rules only see what is in the registry: tags, push times, and image counts. They do not know what your clusters are running, and that gap causes most incidents.

Count-based rules and rarely deployed services. A rule like "keep the last 30 images" works for a service that ships daily. A service released twice a year may have its production image pushed out by thirty CI builds from feature branches in the same repository. If a node then scales up or a pod reschedules, the image pull fails. Keep release tags in their own rule, or keep CI and release images in separate repositories, so that branch churn cannot push out what production depends on.

Short windows shrink your rollback range. Expiring images after a few days also limits how far back you can roll back and removes the exact artifact you need to reproduce a bug reported against an old build. ECR has no undelete. A rebuild from the same commit is often not equivalent, because base images, unpinned packages, and resolved dependency versions change between builds. The rebuilt image can behave differently from the one you shipped.

Image indexes and digest references. A multi-architecture image is a tagged index that points to per-platform manifests, which are usually untagged. A blunt untagged-expiry rule can look dangerous here. Confirm in a preview how the rule treats these child manifests before you rely on it. Also check for deployment tooling, admission policies, or GitOps manifests that pin images by digest rather than by tag. Those references are invisible to a rule that only looks at tags.

Preview every policy change, compare the result against what is deployed, and start with long windows and generous counts. Tighten them once you have watched a few cycles of real expirations.

How do you roll out lifecycle policies across many repositories?

A lifecycle policy only helps if every repository has one, including repositories created long after the first policy was written. Clicking through the console, or running a cleanup script when the storage bill spikes, does not scale past a handful of repositories. New repositories start without rules, and each cleanup turns into an investigation of which images are still safe to delete.

Make the policy part of repository creation

Wrap the repository and its policy in one infrastructure-as-code module. In Terraform, that means an aws_ecr_repository resource paired with an aws_ecr_lifecycle_policy resource that references it. The policy document is built with jsonencode from module variables. In CloudFormation, the AWS::ECR::Repository resource accepts the policy through its LifecyclePolicy property. Teams that create repositories through the module get the baseline rules by default, so no one has to remember to add them.

Expose a small set of variables for the values that legitimately differ between services. Typical examples are the number of release-tagged images to keep and the age threshold for untagged images. A service with a long rollback window, or one that must keep audit-relevant builds, can override those values. It does not need a hand-written policy. Overrides then show up as deliberate, named exceptions instead of drift.

Review policies like code

A lifecycle rule deletes data, so it belongs in a pull request. The plan output shows exactly which repositories a change touches. Reviewers can check that the tag prefixes in the rules still match the tagging convention the CI pipeline uses.

For existing repositories, import them into state before you apply the module. That way the baseline replaces any ad hoc policies without recreating the repository.

# modules/ecr-repo/main.tf (Terraform HCL): one module creates the repo and its baseline policy together
variable "name" { type = string }

# Per-service overrides: defaults are the baseline
variable "release_images_to_keep" {
  type    = number
  default = 30
}
variable "untagged_expiry_days" {
  type    = number
  default = 7
}

resource "aws_ecr_repository" "this" {
  name = var.name
}

resource "aws_ecr_lifecycle_policy" "this" {
  repository = aws_ecr_repository.this.name
  policy = jsonencode({
    rules = [
      {
        rulePriority = 1
        description  = "Expire untagged layers left behind by CI pushes"
        selection    = { tagStatus = "untagged", countType = "sinceImagePushed", countUnit = "days", countNumber = var.untagged_expiry_days }
        action       = { type = "expire" }
      },
      {
        rulePriority = 2
        description  = "Keep only the newest release-tagged images"
        # Prefix must match the CI tagging convention; check this in review
        selection    = { tagStatus = "tagged", tagPrefixList = ["release-"], countType = "imageCountMoreThan", countNumber = var.release_images_to_keep }
        action       = { type = "expire" }
      }
    ]
  })
}

# Caller: a service with a long rollback window overrides one value by name
# module "payments_repo" {
#   source                 = "./modules/ecr-repo"
#   name                   = "payments-api"
#   release_images_to_keep = 90
# }

This Terraform module creates an ECR repository with a baseline lifecycle policy built by jsonencode from variables, so a service that needs longer retention overrides a named variable instead of hand-writing a policy.

How much can lifecycle policies save, and what are the alternatives?

Before the policy is live, estimate what it will remove. Do not multiply image count by image size. Images in a repository share layers, and a shared layer is stored once. A count-based estimate therefore overstates savings, often by a wide margin, because most CI pushes change only the top application layers.

Illustrative estimate (assumed numbers, not a benchmark)

Assumed inputs: compressed image size S = 0.8 GB, pushes per day N = 40, unique layer fraction u = 0.2, current accumulation D = 90 days, retention window R = 7 days, storage price P per GB-month (take this from current ECR pricing).

Stored GB ≈ S × (1 − u) + N × days × S × u

  • Before: 0.64 + 40 × 90 × 0.16 ≈ 577 GB
  • After: 0.64 + 40 × 7 × 0.16 ≈ 45 GB
  • Monthly saving ≈ (577 − 45) × P

A naive count of 3,600 images × 0.8 GB gives 2,880 GB. That figure is five times too high. To find your real u, compare layer digests between consecutive builds.

Alternatives

Approach Deployment awareness Maintenance effort Risk
Lifecycle policy None. It matches only on tags and age. Low after rollout Can expire a tag that is still deployed if the tag conventions drift
Scheduled script using deployment state High. It queries what is actually running. High. You own the code, credentials and failure handling. Bugs in the script can delete broadly
Reduce push volume Not applicable Changes to the pipeline and Dockerfile Fewer images available for debugging
Manual cleanup Whatever the operator checks Recurring toil Inconsistent results and human error

These approaches combine well. Reducing push volume lowers N and u, lifecycle rules enforce R, and a deployment-aware script handles the few repositories where age alone is not a safe signal.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to ecr lifecycle policy, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.