You know the colourful little badges on the top of every README — coverage, build status, version, all of that? Most of them come from shields.io, which works beautifully when your repo is public. The moment your project is private and lives on a self-hosted GitLab, those services can’t reach in. gobadger is the tool I wrote to solve that.

The problem

You want a “coverage: 87%” badge on your private GitLab project, but:

  • shields.io can’t see your private API.
  • Most badge generators assume a public web service.
  • You don’t want to stand up a whole side application just to render an SVG.

gobadger is a single binary that takes a title, a value and an optional colour, and writes an SVG. You then publish that SVG as a CI artifact, and GitLab’s badge feature consumes it from a stable artifact URL. No external service in the loop.

Usage

The flags are deliberately tiny:

$ gobadger -h
Usage of gobadger:
  -c string   color of badge (default "#5272B4")
  -o string   output file name (default "badge.svg")
  -t string   title
  -v string   Value for the title

That’s the whole interface. Title, value, colour, output path. No config file, no template engine.

A real GitLab CI job

Here’s what it looks like in .gitlab-ci.yml. Add a stage that calls gobadger and exposes the resulting SVGs as artifacts:

build_badges:
  stage: build
  image: sgaunet/gobadger:latest
  script:
    - gobadger -o ref.svg   -t godoc -v reference
    - gobadger -o badge.svg -t title -v value -c "#00FF00"
  artifacts:
    name: badge.svg
    paths:
      - badge.svg
      - ref.svg
    expire_in: 2 days

Two things to notice:

  1. The Docker image sgaunet/gobadger:latest already contains the binary, so the job is two lines.
  2. Both files are listed in artifacts.paths — that’s what makes them retrievable through GitLab’s stable artifact URL.

Wiring the badge into GitLab

Once the job runs, head to Settings -> General -> Badges and add a new badge with:

  • Name: whatever you want
  • Link: https://gitlab.com/%{project_path}/-/commits/%{default_branch}
  • Badge image URL: https://gitlab.com/%{project_path}/-/jobs/artifacts/main/raw/badge.svg?job=build_badges

GitLab interpolates %{project_path} and %{default_branch} per project, so the same badge config works across forks and renames. The ?job=build_badges query parameter tells GitLab which job to pull the artifact from.

The result: a real, live badge on your private project’s overview page, regenerated every time the pipeline runs.

Install

The most useful install path is the Docker image — that’s what you’ll use in CI:

FROM sgaunet/gobadger:latest AS build

FROM ...
COPY --from=build /usr/bin/gobadger /usr/bin/gobadger

Or pull the binary directly:

curl -L -o gobadger \
  https://github.com/sgaunet/gobadger/releases/download/v0.2.0/gobadger_0.2.0_linux_amd64
chmod +x gobadger

Status

I’ll be honest: gobadger is in maintenance mode. It does the one thing it set out to do, dependencies get updates, but I’m not actively adding features. If you need fancy badges with logos, gradients and dynamic data fetching, this isn’t it. If you need an “X: Y” SVG generated inside a CI job, it’s exactly the right size.

Where to find it

Open source, MIT-licensed, deliberately small. If you’ve been staring at a badge-shaped hole on a private GitLab project, give it a try.