shields README

The project's README from github.com/badges/shields. As one markdown file: README.md.

Daily Tests Status Code Coverage Chat on Discord

This is home to Shields.io, a service for concise, consistent, and legible badges in SVG and raster format, which can easily be included in GitHub readmes or any other web page. The service supports dozens of continuous integration services, package registries, distributions, app stores, social networks, code coverage services, and code analysis services. Every month it serves over 1.6 billion images and is used by some of the world's most popular open-source projects, VS Code, Vue.js and Bootstrap to name a few.

This repo hosts:

Examples

Make your own badges! (Quick example: https://img.shields.io/badge/left-right-f39f37)

Quickstart

Browse a complete list of badges and locate a particular badge by using the search bar or by browsing the categories. Click on the badge to fill in required data elements for that badge type (like your username or repo) and optionally customize (label, colors etc.). And it's ready for use!

Use the button at the bottom to copy your badge url or snippet, which can then be added to places like your GitHub readme files or other web pages.

Contributing

Shields is a community project. We invite your participation through issues and pull requests! You can peruse the contributing guidelines.

When adding or changing a service please add tests.

This project has quite a backlog of suggestions! If you're new to the project, maybe you'd like to open a pull request to address one of them.

You can read a tutorial on how to add a badge.

GitHub issues by-label

If you intend on reporting or contributing a fix related to security vulnerabilities, please first refer to our security policy.

Development

Open in GitHub Codespaces

  1. Install Node 24. You can use the package manager of your choice.
  2. Clone this repository.
  3. Run npm ci to install the dependencies.
  4. Run npm start to start the badge server and the frontend dev server.
  5. Open http://localhost:3000/ to view the frontend.

When server source files change, the badge server should automatically restart itself (using nodemon). When the frontend files change, the frontend dev server (docusaurus start) should also automatically reload. However the badge definitions are built only before the server first starts. To regenerate those, either run npm run prestart or manually restart the server.

To debug a badge from the command line, run npm run badge -- /npm/v/nock. It also works with full URLs like npm run badge -- https://img.shields.io/npm/v/nock.

Use npm run debug:server to start server in debug mode. This recipe shows how to debug Node.js application in VS Code.

Snapshot tests ensure we don't inadvertently make changes that affect the SVG or JSON output. When deliberately changing the output, run SNAPSHOT_DRY=1 npm run test:package to preview changes to the saved snapshots, and SNAPSHOT_UPDATE=1 npm run test:package to update them.

The server can be configured to use Sentry (configuration) and Prometheus (configuration).

Our full test suite as well as code coverage are run on a daily basis.

Hosting your own server

There is documentation about hosting your own server.

Awesome

Status badges are used widely across open-source and private software projects. Academics have studied the "signal" badges provide about software project quality. There are many existing libraries for rendering these badges, and alternatives to the hosted Shields badge service. awesome-badges is a curated collection of such resources. Contributions may be considered there. (The presence of a project in that collection should not be interpreted as an endorsement nor promotion from the Shields project)

History

b.adge.me was the original website for this service. Heroku back then had a thing which made it hard to use a toplevel domain with it, hence the odd domain. It used code developed in 2013 from a library called gh-badges, both developed by Thaddée Tyl. The project merged with shields.io by making it use the b.adge.me code and closed b.adge.me.

The original badge specification was developed in 2013 by Olivier Lacan. It was inspired by the Travis CI and similar badges (there were a lot fewer, back then). In 2014 Thaddée Tyl redesigned it with help from a Travis CI employee and convinced everyone to switch to it. The old design is what today is called the plastic style; the new one is the flat style.

You can read more about the project's inception, the motivation of the SVG badge specification, and the specification itself.

Project leaders

Maintainers:

Alumni:

License

Shields.io is dual licensed and distributed under the terms of both the MIT license and the Apache license (Version 2.0).

Community

Thanks to the people and companies who donate money, services or time to keep the project running. https://shields.io/community

shields (badges/shields)

Searching Database…

27.3K ·GitHub
Shields
What is this?Shields.io — a service for concise, consistent, and legible badges in SVG and raster format, designed to be embedded in GitHub readmes or any other web page.
Is it a hosted website, an npm library, or something I run myself?All three: a hosted service at shields.io, the server and frontend code in this repo, and an npm library called badge-maker for generating badges in code. You can also self-host the server.
How do I actually put a badge on my project?Browse or search the badge list on shields.io, click the one you need, fill in data like your username or repo, tweak label and colors if you like, then copy the URL or snippet into your README.
What do I need if I want to work on the code?Node 24 (engines also allow 26): clone the repo, run npm ci, then npm start to launch the badge server and the frontend dev server; nodemon hot-restarts the server on changes.
Anything quirky about running the dev server?Badge definitions are built only before the server first starts, so after changing them you must run npm run prestart or restart the server. Server and frontend hot-reload, but definitions do not.
Can I run my own badge server instead of relying on shields.io?Yes — the repo has documentation for hosting your own server, and a Docker image build is configured in CI. The self-hosted server can optionally report to Sentry and Prometheus.
What kinds of things can a badge actually show?Dozens of sources: continuous integration services, package registries, app stores, social networks, code coverage and code analysis tools. Examples include coverage percentage, release version, dependency status, weekly Liberapay donations, Python package downloads, Chrome extension ratings, and uptime.
How widely is it used?It serves over 1.6 billion badge images per month and is used by some of the world's most popular open-source projects, including VS Code, Vue.js, and Bootstrap.
What is the badge-maker npm package for?It is an npm library hosted in this repo for generating the same style of badges programmatically from your own code, and it comes with its own documentation and changelog.
Where did Shields come from?It started in 2013 as a library called gh-badges and the oddly-named site b.adge.me, both by Thaddee Tyl. The original badge spec by Olivier Lacan was inspired by Travis CI badges; the two later merged into shields.io, and the old design survives as the plastic style.
What are similar projects?skill-icons, github-readme-stats, Badges4-README.md-Profile, gatus, anthropies, metrics, markdown-badges, redoc
Which topics is it in?badges, status, badge, metadata, svg, github, hacktoberfest, free, npm, api, tool, apache-2.0
Creator
badges
Size
517.6 MB
Stars
27.3K
Updated
CommitOct 12
Age
13y
Commits · 90 Days