willluck/pkgbadge repository overview

⁠pkgbadge

Self-hosted badge server for GitHub Container Registry. Scrapes GHCR package pages and serves shields.io endpoint badges⁠ with pull counts, versions, image sizes, and platform info.

⁠Features

• Pull count, version, image size, and architecture badges for any public GHCR package
• Shields.io endpoint badge⁠ compatible JSON responses
• Background scraping on a configurable interval (default 6h)
• Supports packages where the repo name differs from the package name
• Zero external dependencies, Go stdlib only
• Distroless container image
• Graceful shutdown (SIGINT/SIGTERM)
• 1-hour client-side cache headers

⁠Quick Start

⁠Docker CLI

docker run -d \
  --name pkgbadge \
  --restart unless-stopped \
  -p 8080:8080 \
  -e PKGBADGE_PACKAGES="owner/repo,owner/repo/package" \
  ghcr.io/will-luck/pkgbadge:latest

⁠Docker Compose

services:
  pkgbadge:
    image: ghcr.io/will-luck/pkgbadge:latest
    ports:
      - "8080:8080"
    environment:
      PKGBADGE_PACKAGES: "owner/repo,owner/repo/package"
    restart: unless-stopped

Then add badges to your README:

![GHCR Pulls](https://img.shields.io/endpoint?url=https://your-host/owner/package/pulls.json)
![Version](https://img.shields.io/endpoint?url=https://your-host/owner/package/version.json)

⁠Badge Types

⁠Configuration

Package format is owner/package when the repo and package names match, or owner/repo/package when they differ (e.g. Will-Luck/Docker-Sentinel/docker-sentinel).

See the wiki⁠ for detailed configuration and usage guides.

⁠Documentation

See the Wiki⁠ for:

• Installation options⁠ (Docker, Compose, from source)
• Badge types and shields.io usage⁠
• API reference⁠
• Troubleshooting⁠

⁠Licence

MIT