Dynamic text
Add a fixed label or place {status} inside it to display the current result.
Installable GitHub App · Open source
Workflow status.
Nothing else.
Status Lights turns GitHub Actions results into compact, customizable SVG indicators—built for Markdown dashboards that need signal instead of noise.
Free for public repositories. Actions and Metadata are read-only; Status Lights has no code, workflow, settings, or repository write access.
platform-overview.md
live view
SYSTEM HEALTH
At a glance
SERVICE
BUILD
TEST
DEPLOY
portal
data-api
documentation
01 / WHY
Badges explain.
Status lights scan.
A badge is useful when you need a label. A status light is better when the surrounding table already supplies the context. It is smaller, quieter, and much easier to scan across a large service matrix.
TRADITIONAL BADGE
buildpassing
STATUS LIGHT
02 / INSTALL THE APP
One read-only install.
Live status after that.
Install Status Lights from GitHub and select the public repositories you want to expose. GitHub sends signed workflow updates; Status Lights never needs your personal access token.
Install Status LightsStatus-light URLs are public. Install this public service only on public repositories.
03 / HOW IT WORKS
Events in.
Small SVG out.
The GitHub App receives workflow changes as they happen. Normal image requests read that stored state instead of polling GitHub's API every time a dashboard loads.
-
01
Run the workflow
Use an installed repository and run the workflow on its default branch.
workflow_run · workflow_job -
02
GitHub sends the state
A signed webhook updates the locally stored workflow and job result.
POST /webhooks/github -
03
Request the light
The same public URL returns the latest state as a cache-friendly SVG.
GET /github/acme/api/ci.yml.svg
04 / CUSTOMIZE
Make the signal yours.
Build a production-ready URL with readable path segments. The appearance preview runs in your browser, and the generated URL calls the live service.
APPEARANCE PREVIEW
LIVE GENERATOR URL
The preview lets you inspect every state. Use the generated URL to retrieve the latest real result for the workflow or job you entered.
05 / CAPABILITIES
Flexible dimensions
Control height, optional width, font size, and corner radius from the URL.
Complete colour control
Set the success, failure, running, and unknown states to your own hexadecimal colours.
Portable fonts
Select a dependable sans, serif, or monospace stack that survives image proxies.
Webhook-driven
GitHub sends each change once; normal SVG requests do not consume GitHub API quota.
Safe by design
Read-only permissions, signed webhooks, strict paths, and escaped SVG output limit access.
06 / PUBLIC SERVICE
Useful should be easy to use.
Free to use
No paid tier, separate Status Lights account, or client-side token for public workflows.
Open source
The implementation, decisions, and deployment configuration stay public.
URL first
A status light should be portable enough to work wherever an image URL works.
Honest unknowns
Gray clearly identifies a repository that is not installed or a workflow that has not emitted its first event.
07 / ROADMAP
The App architecture is shipped.
Status Lights now receives workflow and job state through an installable GitHub App. The next step is to remove the short unknown period after a new installation.
-
SHIPPED
SVG renderer
Validated colours, text, sizing, state mapping, and public URLs -
SHIPPED
Workflow and job lights
Default-branch workflow state plus exact job display-name selection -
SHIPPED
Installable GitHub App
Read-only permissions, signed webhooks, and locally stored current state -
NEXT
Installation bootstrap
Seed existing workflow states immediately instead of waiting for the next run
START HERE
Install once.
Keep dashboards current.
Select your public repositories, run a workflow, and build the light you want to embed.