GitHub Badges: Add Shields.io Badges to Your README
November 11, 2026 · 10 min read
GitHub Badges: How to Add Shields.io Badges to a README
GitHub badges are the small two-part images at the top of a README, such as build: passing or license: MIT. You add one with Markdown image syntax that points at a badge URL, usually from Shields.io. This tutorial covers static, dynamic and GitHub Actions badges, styling, placement and fixing badges that stop updating.
What Are GitHub Badges? Achievements vs README Badges
The phrase covers two different things, and search results mix them up. Achievements are badges GitHub awards for activity on the platform. Per GitHub's profile reference, they appear as small badges in the sidebar of your profile. You earn them, and you can hide them from your profile settings, but you can't add one with Markdown.
README badges, the GitHub badges most people search for, are ordinary images. Each one is an SVG served from a URL, and the URL itself describes what the badge says. Because they're just images, they work in any Markdown file that renders images. The rest of this post is about README badges. Stats cards for a profile README are a separate project, covered in our GitHub Readme Stats guide.
How Do You Add Badges to a GitHub README?
You add GitHub badges with the same syntax as any image: an exclamation mark, alt text in square brackets, then the badge URL in parentheses. The Markdown image guide covers that syntax in full.

That renders a badge with a gray left half reading license and a blue right half reading MIT. Many projects also make the badge clickable, so a visitor who clicks it lands on the thing it describes. Wrap the image in a link:
[](LICENSE)
On GitHub, the relative target LICENSE resolves to the license file in the same repository. Write real alt text, such as License: MIT, because a screen reader announces it in place of the image. If you want a badge to act as a call-to-action button, the Markdown button post shows that pattern and the HTML alternatives.
Shields.io Badge URL Anatomy: Label, Message and Color
Every static Shields.io badge follows one pattern: https://img.shields.io/badge/ followed by label, message and color, separated by single dashes. Drop the label and you get a one-part badge: badge/beta-orange shows just beta on an orange background. The static badge docs list every option.
Because dashes separate the parts, and URLs can't contain raw spaces, the path uses a few escapes:
| You type in the URL | The badge shows |
|---|---|
_ or %20 | a space |
__ | one underscore |
-- | one dash |
%25 | a percent sign |
Here's how those rules play out in real Shields.io badges:




These render as made with | Python, version | 2.0-beta, coverage | 95% and a single beta badge. Colors accept Shields.io names such as brightgreen and yellowgreen, any CSS color name, and hex, rgb or hsl values. Write hex codes without the #, because a # would end the URL path.
One rendering difference to know about: on GitHub, those four lines sit in one paragraph and render side by side. Our editor's preview shows each badge on its own line, even when they share a line in the source. Use it to check that every URL renders, then check the row layout on GitHub.
If you'd rather fill in a form than type URLs, our badge URL builder assembles Shields.io URLs and gives you the snippet as Markdown, HTML, RST or AsciiDoc. It doesn't host badges or check your repository's status.
Styling Shields.io Badges With style, logo and Colors
Query parameters change how a badge looks without touching its text. The style parameter takes flat (the default), flat-square, plastic, for-the-badge or social. Note that for-the-badge prints the text in capitals.




The first two show the same docs | latest badge in square and tall uppercase styles. The third adds a white Python logo to the left half. The last one overrides both halves: labelColor paints the left side dark gray, and color turns the right side green.
| Parameter | What it controls |
|---|---|
logo | An icon slug from Simple Icons, such as github or python |
logoColor | The icon's color (Simple Icons logos only) |
logoSize=auto | Lets wide logos resize to fit |
label | Replaces the left-hand text |
labelColor and color | Left and right background colors |
cacheSeconds | Cache lifetime; values below the badge's default are ignored |
Copy a slug by clicking an icon's title on the Simple Icons site. Chain parameters with &, as in the Python example above.
Dynamic Badges: GitHub, npm and Actions Status
A static badge says whatever you typed. Dynamic GitHub badges read live data, so the version number or build result updates without editing the README. Shields.io has service badges for a long list of sources:



Replace cli/cli with your owner and repository, and marked with your package. The first reads the license GitHub detects for the repository and shows license | MIT. The second shows the newest release tag (v2.103.3 when we checked in November 2026). Shields.io can only see public data, so a private repository returns an error such as repo not found.
GitHub Actions workflow status badges
For build status, you don't need Shields.io at all. GitHub serves its own badge for each workflow file, documented in Adding a workflow status badge:
[](https://github.com/OWNER/REPO/actions/workflows/ci.yml)


The path uses the workflow's file name, not the name: inside it. By default the badge shows your default branch, and it falls back to the most recent run on any branch if the default branch has none. Add ?branch= or ?event= to narrow it. You can also open the workflow in the Actions tab, click the menu next to the run filter, and choose Create status badge to copy ready-made Markdown.
How Do You Make a Custom Dynamic Badge With the Endpoint Badge?
When no service badge covers your metric, use the endpoint badge. You host a small JSON file at a public URL, and Shields.io fetches it and draws the badge. The file needs schemaVersion, label and message:
{
"schemaVersion": 1,
"label": "docs coverage",
"message": "87%",
"color": "yellowgreen"
}
Then point the badge at it, URL-encoding the address:

Once that file is live, the badge reads docs coverage | 87% in yellow-green. An empty label hides the left half, and optional fields include labelColor, namedLogo, logoColor, style and isError. The catch is upkeep: something, usually a CI job, has to rewrite that JSON file whenever the number changes.
Where Should GitHub Badges Go in a README?
The usual spot is directly under the project title and one-line description, all on one line. That way a visitor sees status, version and license before scrolling. The README Markdown guide covers the rest of a README's structure.
# my-project
A command-line tool that tidies Markdown files.
[](https://github.com/OWNER/REPO/actions/workflows/ci.yml) [](LICENSE)
To center the row on GitHub, switch to HTML: wrap each badge as an img inside an a, and put the row in a paragraph with align="center". GitHub's sanitizer keeps align on a paragraph, so the row centers on the repository page.
We prefer three or four badges that each answer a question a visitor would ask: does it build, what's the latest version, what's the license. A wall of fifteen badges pushes the actual description off the screen. Try the demo below and change any label or color. The preview stacks the badges, but each one loads from the same URL GitHub would use.
Why Isn't My GitHub Badge Updating?
GitHub passes README images through Camo, its image proxy, which caches them. Shields.io also sets a cache lifetime per badge. In our test, the GitHub license badge came back with max-age=14400, which is four hours. A badge that looks stale is often just cached, and it catches up on its own within that window.
GitHub's anonymized URL docs suggest checking the image's headers first:
curl -I https://img.shields.io/github/v/release/cli/cli
Look at the Cache-Control line. As a last resort, copy the badge's image address on GitHub (it starts with https://camo.githubusercontent.com/) and run curl -X PURGE on it. GitHub asks you to purge sparingly, because it forces every visitor to re-request the image.
If waiting doesn't help, check these causes:
- Wrong workflow file name. The Actions badge path needs
ci.yml, not the workflow's display name. - Wrong branch. Without
?branch=, the badge tracks the default branch, not the one you just pushed. - Private repository. Workflow badges in private repos can't be viewed from outside GitHub, and Shields.io can't read private data.
- An unescaped dash.
version-2.0-beta-bluehas too many parts, so Shields.io returns a 404 badge not found image. Write2.0--beta.
The honest limitation: most GitHub badges depend on a third-party service. If Shields.io or the API behind it is slow, your README shows a broken image or an old value. Nothing in your Markdown can fix that.
Questions About Shields.io, Logos and Private Repos
GitHub badges come down to one idea: a badge is an image whose URL describes it. Start with a static license badge, add a workflow status badge from the Actions tab, and reach for the endpoint badge only when no service badge fits. Paste your badge row into the editor to check every URL renders before you commit the README.