Concise, consistent, and legible badges in SVG and raster format

License: CC0-1.0

Language: JavaScript

Keywords: badge, github, metadata, status, svg

build status service-test status coverage Total alerts commits to be deployed chat on Discord follow on Twitter

This is home to, 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 470 million images.

This repo hosts:


  • code coverage percentage: coverage
  • stable release version: version
  • package manager release: gem
  • status of third-party dependencies: dependencies
  • static code analysis grade: codacy
  • SemVer version observance: semver
  • amount of Liberapay donations per week: receives
  • Python package downloads: downloads
  • Chrome Web Store extension rating: rating
  • Uptime Robot percentage: uptime

Make your own badges! (Quick example:

Browse a complete list of badges.


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:

GitHub issues by-label

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


  1. Install Node 8 or later. You can use the package manager of your choice. Tests need to pass in Node 8 and 10.
  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 (gatsby dev) should also automatically reload. However the badge definitions are built only before the server first starts. To regenerate those, either run npm run defs 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 --

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

Shields has experimental support for Gitpod, a pre-configured development environment that runs in your browser. To use Gitpod, click the button below and sign in with GitHub. Gitpod also offers a browser add-on, though it is not required. Please report any Gitpod bugs, questions, or suggestions in issue #2772.

Edit with Gitpod

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:js:server to preview changes to the saved snapshots, and SNAPSHOT_UPDATE=1 npm run test:js:server to update them.

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

Daily tests, including a full run of the service tests and overall code coverage, are run via badges/daily-tests.

Hosting your own server

There is documentation about hosting your own server.

History 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 by making it use the code and closed

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




Related projects


All assets and code are under the CC0 LICENSE and in the public domain unless specified otherwise.

The assets in logo/ are trademarks of their respective companies and are under their terms and license.


This project exists thanks to all the people who contribute. [Contribute].


Thank you to all our backers! 🙏 [Become a backer]


Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

Project Statistics

Sourcerank 14
Repository Size 40.3 MB
Stars 11,586
Forks 3,107
Watchers 121
Open issues 279
Dependencies 1,694
Contributors 344
Tags 9
Last updated
Last pushed

Top Contributors See all

Thaddée Tyl dependabot-preview[bot] Paul Melnikow dependabot[bot] chris48s Caleb Cartwright Pierre-Yves B. Danial Marcin Mielnicki Raphaël Pinson greenkeeper[bot] Peter Dave Hello Greg Bowler James Cahill tooomm anatoly techtonik Sagie Gur-Ari Daniel Lo Nigro Mathias Bynens Nicco Kunzmann

Packages Referencing this Repo

badge-maker badge library
Latest release 3.2.0 - Updated - 11.6K stars
gh-badges badge library
Latest release 2.2.2 - Updated - 11.6K stars

Recent Tags See all

3.1.0 June 03, 2020
3.0.1 June 02, 2020
3.0.0 May 06, 2020
2.2.1 May 30, 2019
2.2.0 May 29, 2019
2.1.0 November 18, 2018
2.0.0 November 09, 2018
2.0.0-beta1 October 30, 2018
1.3.0 September 07, 2016

Interesting Forks See all

Shields badge specification, website and default API server
JavaScript - Other - Last pushed - 5 stars - 3 forks
A legible & concise status badge solution for third-party codebase services.
Python - Other - Updated - 2 stars - 1 forks
Shields badge specification, website and default API server
JavaScript - Updated - 2 stars
A legible & concise status badge solution for third-party codebase services.
CC0-1.0 - Updated - 2 stars
Shields badge specification, website and default API server
JavaScript - CC0-1.0 - Last pushed - 1 stars

Something wrong with this page? Make a suggestion

Last synced: 2019-05-30 17:43:45 UTC

Login to resync this repository