README.md

GitHub Action: Docker - Clean images

---

Overview

Action to clean up container images from GitHub Container Registry (ghcr.io). This is a wrapper around the ghcr-cleanup-action that provides a consistent interface for image cleanup operations including deleting untagged images, pruning old tags, and managing image lifecycle.

Permissions

Set permissions to write packages. This is required to delete images.

permissions:
  packages: write

Usage

- uses: hoverkraft-tech/ci-github-container/actions/docker/clean-images@e4bf7a12228a2a4b5993d2d36b99b4dd0ec80bf5 # 0.32.1
  with:
    # Comma-separated list of packages to cleanup.
    # Example: "application-1,application-2"
    #
    # This input is required.
    package: ""

    # Comma-separated list of tags to delete (supports wildcard syntax).
    # Example: `pr-*,dev`
    #
    # This input is required.
    tags: ""

    # GitHub token with the packages:write and packages:delete scopes.
    # See https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages#about-scopes-and-permissions-for-package-registries.
    #
    # Default: `${{ github.token }}`
    github-token: ${{ github.token }}

Inputs

Input	Description	Required	Default
package	Comma-separated list of packages to cleanup.	true	-
	Example: "application-1,application-2"
tags	Comma-separated list of tags to delete (supports wildcard syntax).	true	-
	Example: pr-*,dev
github-token	GitHub token with the packages:write and packages:delete scopes.	false	${{ github.token }}
	See https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages#about-scopes-and-permissions-for-package-registries.

Examples

Clean up pull request images

Delete images tagged with a pull request pattern after the PR is closed:

name: Clean PR Images
on:
  pull_request:
    types: [closed]

jobs:
  cleanup:
    runs-on: ubuntu-latest
    permissions:
      packages: write
    steps:
      - uses: hoverkraft-tech/ci-github-container/actions/docker/clean-images@e4bf7a12228a2a4b5993d2d36b99b4dd0ec80bf5 # 0.32.1
        with:
          package: my-app
          delete-tags: pr-${{ github.event.pull_request.number }}-*

Clean up untagged images

Remove all untagged images to save storage:

name: Clean Untagged Images
on:
  schedule:
    - cron: "0 3 * * *" # Daily at 3 AM

jobs:
  cleanup:
    runs-on: ubuntu-latest
    permissions:
      packages: write
    steps:
      - uses: hoverkraft-tech/ci-github-container/actions/docker/clean-images@e4bf7a12228a2a4b5993d2d36b99b4dd0ec80bf5 # 0.32.1
        with:
          package: my-app
          delete-untagged: true

Contributing

Contributions are welcome! Please see the contributing guidelines for more details.

License

This project is licensed under the MIT License.

SPDX-License-Identifier: MIT

Copyright © 2026 hoverkraft

For more details, see the license.

---

This documentation was automatically generated by CI Dokumentor.