Uptime badge for GitHub README: a live status badge in Markdown

A badge is an image your README loads from a URL, so it can show live status without you editing the file. Here is the Markdown to use, and why GitHub may show a slightly old value.

Updated

Short answer

Turn on the status badge in your UptimeIO status page settings, then paste the Markdown snippet into your README. The image is an SVG served from a URL, wrapped in a link to your status page. GitHub fetches README images through its own proxy, so a change may not appear right away.

Add a status badge free

The Markdown snippet

A README badge is an image inside a link. The image is the live badge, and the link sends people to your status page. Replace your-subdomain with your status page subdomain.

README.md: status badgeMarkdown
[![Status](https://api.uptimeio.com/api/public/status/your-subdomain/badge.svg?type=status)](https://your-subdomain.status.uptimeio.com)
README.md: 7-day uptime badgeMarkdown
[![Uptime](https://api.uptimeio.com/api/public/status/your-subdomain/badge.svg?type=uptime&period=7d)](https://your-subdomain.status.uptimeio.com)

If you have a verified custom domain, the snippet the dashboard gives you uses it as the link target instead.

Where to put it in the README

Most projects put badges on one line under the title, next to the build and license badges. One status badge is usually enough. Add the uptime badge as well if you want visitors to see a number, and pick a period that matches how you talk about reliability, such as 30 days.

Always keep the link around the image. A badge that says "partial outage" is only useful if the reader can click through to see which service is affected and what you are doing about it.

Choose a badge type

BadgeQueryShows
Statustype=statusThe overall status of the page: operational, partial outage, major outage, maintenance or unknown. It matches the banner on your public page
Uptimetype=uptimeThe average uptime across the monitors on the page, such as 99.95%

The uptime badge takes an optional period of 24h, 7d, 30d or 90d. The default is 30d. The color follows the uptime thresholds in your page settings: green at or above the operational threshold, amber at or above the degraded threshold, red below.

When the badge reads "not found"

The badge only renders for published, public status pages with the badge turned on. In every other case the image reads not found.

CauseFix
Badge is offEnable it in the Settings tab (badges are off by default)
Page is a draftPublish the page
Page is password protectedRemove password protection
Wrong subdomain in the URLCopy the snippet from the dashboard instead of typing it

Why GitHub shows an old value

GitHub does not load README images straight from the source. It routes them through an anonymizing proxy called Camo, which hides the viewer's browser details. GitHub's documentation says the proxy follows the cache headers the image's origin server sends, and does not state a fixed lifetime. So the badge on GitHub can lag behind the status page.

That is how GitHub serves images, and it applies to every badge in a README. Opening your status page shows the current state. For GitHub's own guidance on refreshing an image, see its page on anonymized URLs (docs.github.com, "About anonymized URLs").

Set it up in UptimeIO

  1. Create and publish a status page, if you have not already.
  2. Open Status Pages, select the page, then open the Settings tab.
  3. In the Status badge section, select Enable status badge and click Save Changes.
  4. Two badges appear with a live preview. Click Copy next to the Markdown snippet of the one you want.
  5. Paste it into your README and commit.
  • Plans: badges are available on all plans, including Free.
  • HTML: the dashboard also copies an HTML snippet, for websites and docs sites.
  • Uptime periods: 24 hours, 7 days, 30 days (default) or 90 days.

Questions

How do I add an uptime badge to my GitHub README?
Enable the status badge in your status page settings, copy the Markdown snippet, and paste it into your README. It is an image wrapped in a link to your status page.
Why does my badge not update right away on GitHub?
GitHub serves README images through its Camo proxy and follows the cache headers from the image source, so a change may not appear right away. This is GitHub's behaviour and applies to all README badges.
Does the badge have a dark mode version?
No. There is one badge design, with a status badge and an uptime badge. The color changes with the status or uptime value.
Is the badge free?
Yes. Badges are available on all plans, including Free, and are off until you enable them.
Can I use the badge outside GitHub?
Yes. The dashboard gives you an HTML snippet as well as Markdown, so you can use it on a website or docs site.

Related

Start monitoring in a few minutes

Start monitoring free

Free plan · 50 monitors · No credit card required