How to Run a Self-Hosted shields.io Server

The shields.io server ships as a Docker image you can run yourself to badge private repos or avoid the public instance rate limits.

Run ghcr.io/badges/shields (or shieldsio/shields) in your own environment, set upstream tokens as env vars, and change your badge URLs to your host. Routes stay identical to the public instance.

Steps

Run the shields server image and expose port 8080.
Provide upstream tokens (for example GH_TOKEN) as environment variables.
Replace img.shields.io in your badge URLs with your host.

Run the server

Terminal

docker run -d --name shields \
  -p 8080:80 \
  -e GH_TOKEN=ghp_yourtoken \
  ghcr.io/badges/shields:server

README markdown

README.md

![Build](https://badges.internal.acme.com/github/actions/workflow/status/acme/widget/ci.yml?branch=main)

Gotchas

A private badge server behind auth cannot be reached by GitHub camo, so private-repo READMEs may still not render it externally.
Set upstream tokens so registry and GitHub routes are not rate-limited.

Related guides

How to Create a Dynamic shields.io Endpoint BadgeBuild a dynamic shields.io badge by hosting a JSON document in the shields schema and pointing the endpoint r… How to Build a Badge for a Custom MetricBuild a badge that reflects a custom metric such as bundle size by computing the value in CI, writing shields… How to Handle Badge Caching and the Camo ProxyUnderstand how GitHub proxies README badges through its camo image cache, why badges look stale, and how cach…