In GitHub Packages, your Container registry holds three years of untagged image versions; where do they come from, and how do you prune them safely?
answer
- every push is a version
- tags move, digests stay
- nothing cleans up for you
- the role a workflow needs to delete
basics
~20 sEach pushed image digest becomes a version; when a tag moves to a newer push, the old version is left untagged. GitHub Packages documents no automatic cleanup, so a job lists versions and deletes untagged ones it has checked are unused.
solid answer
~40 sIn the Container registry every pushed manifest is a **package version** identified by its digest, and tags are labels on versions. Moving a tag such as `main` to a new build leaves the previous version with **no tag**, so a busy pipeline produces untagged versions on every push. The Packages documentation describes **no built-in retention or cleanup policy**, so pruning is a job you run: list versions through the REST API, select those whose `metadata.container.tags` is empty and old enough, and delete them by version ID. In a workflow, `GITHUB_TOKEN` can delete only if the workflow's repository has **Admin** on the package, which it gets by default when its workflow published the package. Prune carefully: untagged does not mean unreferenced, and mistakes are restorable for 30 days.
code
bash · 13 lines# List versions of an organization-scoped container package
curl -sS \
-H "Authorization: Bearer $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2026-03-10" \
"https://api.github.com/orgs/example-org/packages/container/web-app/versions?per_page=100"
# Delete one version by its id (restorable for 30 days)
curl -sS -X DELETE \
-H "Authorization: Bearer $GITHUB_TOKEN" \
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2026-03-10" \
"https://api.github.com/orgs/example-org/packages/container/web-app/versions/123456"go deeper
Know that each push creates a version and that moving a tag leaves the old version untagged.
Explain how to find untagged versions through the REST API and why the workflow's repository needs Admin on the package to delete them.
Design a pruning job with a dry run, a minimum kept set, exclusions for referenced digests, a deletion log and the 30-day restore as safety net.
Decide retention per package class — release images kept long, branch builds pruned fast — and keep the policy ready for a future change in container billing.
## Where untagged versions come from The Container registry in GitHub Packages (`ghcr.io`) records every pushed image manifest as a **package version**. A version is identified by its **digest**, and **tags** are names attached to versions. The REST API shows this directly: each version has an `id`, a `name` (for a container, its digest) and `metadata.container.tags`, a list that may be empty. Untagged versions accumulate in a few ordinary ways: - **Moving tags.** A pipeline that pushes `main` or `latest` on every merge moves the tag to the new version; the previous version keeps its digest and loses its only tag. - **Rebuilds of the same version tag.** Re-pushing `1.4.0` with a different build produces a new digest and strands the old one. - **Multi-platform images.** A multi-arch image is a list that references one image per architecture; the per-platform manifests that list points at can appear as versions without tags of their own. Over three years of CI that is thousands of versions nobody will ever pull by name. How tags and digests behave in general is the subject of the material on container registry tags and digests; what matters here is how GitHub Packages stores and removes them. ## What the clutter costs As of October 2026, GitHub's billing documentation states that **Container registry storage and bandwidth are currently free**, and that GitHub will give at least one month's notice before changing that. The untagged pile is therefore not on today's bill, but it still matters: - the version list becomes unusable for humans investigating what was deployed; - a pricing change would make years of clutter billable with only a month to clean it up; - packages in other registries — npm, NuGet, RubyGems, Maven — that are private **do** count against the owner's storage allowance, and the same version sprawl happens there. ## There is no automatic retention policy The GitHub Packages documentation describes deleting and restoring versions by hand, through the REST API and from workflows; it describes no setting that expires versions automatically. A retention policy is something the team writes and schedules. ## Pruning from a workflow A safe pruning job follows these steps: 1. **List versions** with `GET /orgs/{org}/packages/container/{package_name}/versions` (or the `/user/...` equivalent), paging with `per_page` up to 100. 2. **Select candidates**: versions whose `metadata.container.tags` is empty and whose `created_at` is older than your threshold. 3. **Exclude anything still referenced**: per-platform manifests of tagged multi-arch images, and digests that deployments pin. 4. **Delete** each candidate with `DELETE .../versions/{package_version_id}`. 5. **Log** the IDs deleted, so you can restore within 30 days if something breaks. The credential: | Caller | What it needs | |---|---| | Workflow using `GITHUB_TOKEN` | The workflow's repository holds **Admin** on the package | | Personal access token (classic) | `read:packages` and `delete:packages`; the organization endpoint also requires admin permissions in the organization and Admin on the package | When a workflow publishes a package with `GITHUB_TOKEN`, its repository gets the Admin role by default. For an image published some other way, a package admin grants the pruning repository Admin under the package's *Manage Actions access* section. The documentation marks workflow deletion and restoration through the REST API as **public preview** as of October 2026. ## Guard rails - **Untagged is not unreferenced.** Deleting a platform manifest behind a tagged multi-arch image breaks pulls for that architecture. - **Public packages have a ceiling.** A public version with more than 5,000 downloads cannot be deleted by its owner. - **Deletion is reversible for 30 days**, provided the namespace and version are not reused — keep the log. - **Run it on a schedule** with a dry-run mode first, and keep a minimum number of recent versions even when untagged, so a rollback by digest still works. - **Treat release images differently** from branch builds: versions carrying release tags are usually kept for as long as anything may run them, while untagged branch-build versions get a short window. - **Audit what a run removed** by calling the list endpoint with `state=deleted`, which returns deleted versions that can still be restored.
- In GitHub Packages, why can deleting untagged versions break a tagged multi-architecture image?A multi-arch image is a list that references one image per architecture, and those per-platform manifests can appear as versions without their own tags. Deleting one leaves the tagged list pointing at something missing, so pulls for that architecture fail. A pruning job must exclude digests that tagged images still reference.
- In GitHub Packages, a pruning workflow gets 403 when deleting versions of an image another pipeline published. What is missing?The workflow's repository lacks the Admin role on that package. Only the repository whose workflow published the package gets Admin by default; for any other repository a package admin must grant Admin under Manage Actions access before `GITHUB_TOKEN` can delete versions.
- GitHub Packages expires untagged container versions automatically after a while.
- Every untagged version is safe to delete because nothing can reference it.
- Write access on the package is enough for a workflow to delete versions.
- Untagged Container registry storage is today's biggest line on the bill.
- Deleted container versions are gone the moment the job finishes.