GHCR Cleanup Manager Visualizer

Local browser visualizer for GHCR Cleanup Manager SQLite scan databases.

Use it to inspect manifest graphs, compare two scans of the same package, and investigate cleanup edge cases.

Example compare view: red-bordered manifests are present in the older scan and removed in the newer one.

Quick Demo

Download the test scenario DB from the latest release and try the visualizer without first running your own workflow.

The DB contains dozens of scenario packages with different graphs and before/after views of cleanup operations on them.

curl -LO https://github.com/ghcr-manager/ghcr-cleanup-manager/releases/latest/download/ghcr-cleanup-manager-release-scenarios.sqlite
npx ghcr-cleanup-manager-visualizer --db ./ghcr-cleanup-manager-release-scenarios.sqlite

Or run the release image:

docker run --rm -p 8080:8080 \
  -v "$PWD:/data:ro" \
  ghcr.io/ghcr-manager/ghcr-cleanup-manager-visualizer:latest \
  --db /data/ghcr-cleanup-manager-release-scenarios.sqlite

Open the local URL printed by the command and select:

• owner: ghcr-cleanup-manager-test
• package: select one with 2images or 2multiarch in the name
• tag search: image or multiarch

Good search terms for tags in most scenarios are: image, multiarch, keep, or delete.

For an overview of the test scenario graphs and cleanup cases, see test-scenarios.

Install

npm install --global ghcr-cleanup-manager-visualizer

Requirement: Node.js 24 or newer.

Run

ghcr-cleanup-manager-visualizer --db ./artifacts/acme__demo.sqlite

The command prints a local URL such as http://127.0.0.1:43217. Open that URL in your browser.

Optional flags:

• --host <host>: override the bind host. Default: 127.0.0.1
• --port <port>: override the bind port. Default: 0

Example:

ghcr-cleanup-manager-visualizer --db ./artifacts/acme__demo.sqlite --host 0.0.0.0 --port 4000

Docker

Release images are published only from release tags and use these tags:

• vX.Y.Z
• vX
• latest

Example:

docker run --rm -p 8080:8080 \
  -v "$PWD:/data:ro" \
  ghcr.io/ghcr-manager/ghcr-cleanup-manager-visualizer:v1.1.6 \
  --db /data/acme__demo.sqlite

Container defaults:

• host: 0.0.0.0
• port: 8080

DB Input

The visualizer reads the SQLite DB produced by GHCR Cleanup Manager as GitHub Action artifacts uploaded by scan, cleanup.

Typical flow:

1. Run a scan or cleanup workflow and download the SQLite DB run artifact.
2. Start ghcr-cleanup-manager-visualizer with that DB.
3. Select owner and package, then enter a tag or digest to center the graph.
4. Optionally select a second scan to compare two recorded scans.

Compare Mode

When a package has at least two completed scans, the visualizer defaults to comparing the newest two scans:

• main scan: the older of the newest two scans
• compare scan: the newest scan

In compare mode, the visualizer shows delta information in two places.

Manifest nodes:

• gray border: present in both scans
• green border: added in the newer scan
• red border: removed in the newer scan

Tags in the details panel:

• plain tag text: present in both scans
• (+) tag-name: tag added in the newer scan
• (-) tag-name: tag removed in the newer scan

This is the fastest way to inspect what changed between two scans of one package graph.

Example compare view: red-bordered manifests are present in the older scan and removed in the newer one.

Example compare view: tags with '(-)' were removed. Here the manifest with the other tag remained.

Source Checkout

From this repository checkout, you can run the visualizer without publishing:

npm run build
npm run visualize -- --db ./artifacts/acme__demo.sqlite

Project

Main project and issue tracker:

• Repository: https://github.com/ghcr-manager/ghcr-cleanup-manager
• Issues: https://github.com/ghcr-manager/ghcr-cleanup-manager/issues