About

Aegis is a SVG badge generation service, icons powered by Font Awesome. See the changelog for notable changes.

Usage

Query Parameters

NOTE: You can use these query parameters to modify any badges generated from badge services below.

Query parameters for configuring your badge appearance.

Query Parameter	Description	Input Format	Example
color	Sets the badge primary color	RGB Hex Values, CSS Color Keywords	"fff", "1BACBF", "mediumturquoise"
icon	Sets the badge icon	Any one of the available Font Awesome Icons: <STYLE>/<NAME>	"brands/github", "regular/star", "solid/star"
status	Sets the badge status text	Any URL-encoded string	"Build%20Status", "ビルド状態"
style	Sets the badge style	Any one of the 4 available badge styles (classic, flat, plastic, semaphoreci)	"classic", "flat", "plastic", "semaphoreci"
subject	Sets the badge subject text	Any URL-encoded string	"Failed", "失敗"

Static Badge Service

Path	Description	Example
/static?subject=release&status=v2.0.0	Static badge
/static?subject=style&status=classic&style=classic /static?subject=style&status=flat&style=flat /static?subject=style&status=plastic&style=plastic /static?subject=style&status=semaphoreci&style=semaphoreci	With various badge styles
/static?subject=license&status=AGPL%20v3&icon=solid/balance-scale	With icon
/static?subject=ビルド状態&status=成功&color=26A876	With non-english characters

Bitbucket Badge Service

Path	Description	Example
/bitbucket/forks/<USERNAME>/<REPO_SLUG>	Fork count
/bitbucket/issues/<USERNAME>/<REPO_SLUG> /bitbucket/issues/<USERNAME>/<REPO_SLUG>?state=new /bitbucket/issues/<USERNAME>/<REPO_SLUG>?state=open /bitbucket/issues/<USERNAME>/<REPO_SLUG>?state=resolved /bitbucket/issues/<USERNAME>/<REPO_SLUG>?state=on-hold /bitbucket/issues/<USERNAME>/<REPO_SLUG>?state=invalid /bitbucket/issues/<USERNAME>/<REPO_SLUG>?state=duplicate /bitbucket/issues/<USERNAME>/<REPO_SLUG>?state=wontfix /bitbucket/issues/<USERNAME>/<REPO_SLUG>?state=closed	Issue count
/bitbucket/pull-requests/<USERNAME>/<REPO_SLUG> /bitbucket/pull-requests/<USERNAME>/<REPO_SLUG>?state=open /bitbucket/pull-requests/<USERNAME>/<REPO_SLUG>?state=declined /bitbucket/pull-requests/<USERNAME>/<REPO_SLUG>?state=merged /bitbucket/pull-requests/<USERNAME>/<REPO_SLUG>?state=superseded	Pull Request count

GitHub Badge Service

Path	Description	Example
/github/forks/<OWNER>/<REPOSITORY>	Fork count
/github/issues/<OWNER>/<REPOSITORY> /github/issues/<OWNER>/<REPOSITORY>?state=open /github/issues/<OWNER>/<REPOSITORY>?state=closed	Issue count
/github/pull-requests/<OWNER>/<REPOSITORY> /github/pull-requests/<OWNER>/<REPOSITORY>?state=open /github/pull-requests/<OWNER>/<REPOSITORY>?state=closed /github/pull-requests/<OWNER>/<REPOSITORY>?state=merged	Pull Request count
/github/stars/<OWNER>/<REPOSITORY>	Star count

GitLab Badge Service

Path	Description	Example
/gitlab/forks/<NAMESPACE>/<PROJECT_NAME>	Fork count
/gitlab/issues/<NAMESPACE>/<PROJECT_NAME> /gitlab/issues/<NAMESPACE>/<PROJECT_NAME>?state=opened /gitlab/issues/<NAMESPACE>/<PROJECT_NAME>?state=closed	Issue count
/gitlab/merge-requests/<NAMESPACE>/<PROJECT_NAME> /gitlab/merge-requests/<NAMESPACE>/<PROJECT_NAME>?state=opened /gitlab/merge-requests/<NAMESPACE>/<PROJECT_NAME>?state=closed /gitlab/merge-requests/<NAMESPACE>/<PROJECT_NAME>?state=locked /gitlab/merge-requests/<NAMESPACE>/<PROJECT_NAME>?state=merged	Merge Request count
/gitlab/stars/<NAMESPACE>/<PROJECT_NAME>	Star count

Getting Started

A GitHub access token is required at process start (GITHUB_ACCESS_TOKEN or -github-access-token).

make build
./bin/aegis -github-access-token "$GITHUB_ACCESS_TOKEN"

Or with Docker:

make docker-run GITHUB_ACCESS_TOKEN="$GITHUB_ACCESS_TOKEN"

Make targets

Target	Description
check-deps	Verify go and golangci-lint are on PATH
build	Build bin/aegis (CGO_ENABLED=0, trimmed, version ldflags)
build-all	Cross-compile linux/darwin amd64/arm64
run	Build and run
vet	go vet ./...
lint	golangci-lint run
tidy	go mod tidy
test	Unit tests
test-e2e	Blackbox tests against a real binary
test-all	Unit + e2e
docker-build	Distroless static non-root image
docker-run	Build and run, publishing 8080 and 9090

Endpoints

Listener	Path	Description
app :8080	GET /static	Static badge
app :8080	GET /github/{method}/{owner}/{repo}	GitHub badge
app :8080	GET /gitlab/{method}/{owner}/{repo}	GitLab badge
app :8080	GET /bitbucket/{method}/{owner}/{repo}	Bitbucket badge
admin :9090	GET /livez	Liveness
admin :9090	GET /readyz	Readiness
admin :9090	GET /metrics	Prometheus metrics
admin :9090	GET /version	Build metadata

Configuration

Precedence: built-in defaults → environment variables → CLI flags.

Flag	Env	Default	Description
-app-addr	APP_ADDR	:8080	Application listen address
-admin-addr	ADMIN_ADDR	:9090	Admin listen address
-log-level	LOG_LEVEL	info	debug, info, warn, error
-log-format	LOG_FORMAT	json	json or text
-read-timeout	READ_TIMEOUT	15s	Request read timeout
-read-header-timeout	READ_HEADER_TIMEOUT	5s	Header read timeout
-write-timeout	WRITE_TIMEOUT	15s	Response write timeout
-idle-timeout	IDLE_TIMEOUT	60s	Keep-alive idle timeout
-shutdown-timeout	SHUTDOWN_TIMEOUT	15s	Graceful shutdown timeout
-histogram-buckets	HISTOGRAM_BUCKETS	Prometheus defaults	HTTP duration buckets
-exclude-cache-control-headers	EXCLUDE_CACHE_CONTROL_HEADERS	false	Omit Cache-Control on badges
-root-redirect-url	ROOT_REDIRECT_URL	empty	Redirect target for GET /
-github-access-token	GITHUB_ACCESS_TOKEN	required	GitHub API token
-v / --version			Print version and exit

Layout

cmd/aegis/                 # process wiring and lifecycle
internal/config/           # defaults → env → flags
internal/observability/    # slog + Prometheus
internal/server/           # app + admin HTTP
internal/gitprovider/      # GitHub / GitLab / Bitbucket clients
internal/version/          # ldflags-injected build info
pkg/badge/                 # public SVG badge library
test/e2e/                  # blackbox tests (//go:build e2e)
deploy/kubernetes/         # Deployment, PDB, NetworkPolicy, ServiceMonitor

Kubernetes manifests live in deploy/kubernetes. The container image is gcr.io/distroless/static-debian12:nonroot (no shell, no Docker HEALTHCHECK; probes belong on :9090).

License

Aegis is MIT licensed.