Skip to content
openstatus openstatus
Get started

How to Add a Status Badge to a GitHub README

Problem

Section titled “Problem”

You want to display the real-time status of your service directly in your GitHub repository’s README file. This provides immediate visibility to your users and team members about the health of your application.

Solution

Section titled “Solution”

openstatus provides embeddable status badges that you can add to any Markdown file, including your README.md. You can choose between a modern SVG badge or a legacy PNG badge.

Prerequisites

Section titled “Prerequisites”
  • An openstatus account with a configured status page.
  • The “slug” of your status page (the unique name in its URL, e.g., https://[slug].openstatus.dev).

Step-by-step guide

Section titled “Step-by-step guide”

Step 1: Choose your badge type

Section titled “Step 1: Choose your badge type”

We recommend using the modern SVG badge (v2) as it offers more customization options.

  • SVG Badge (v2): More flexible, better styling, and uses a monospaced font.
  • PNG Badge (Legacy): Simpler, but with fewer customization options.

Step 2: Add the badge to your README

Section titled “Step 2: Add the badge to your README”

Copy the Markdown snippet for your chosen badge type and paste it into your README.md file. Remember to replace [slug] with your status page slug.

Section titled “Option A: Modern SVG Badge (Recommended)”

This is the recommended badge for most use cases.

Base URL
Section titled “Base URL”
https://[slug].openstatus.dev/badge/v2
Markdown Snippet
Section titled “Markdown Snippet”
![Status](https://[slug].openstatus.dev/badge/v2)

Example:

Status

Customization
Section titled “Customization”

You can customize the badge by adding query parameters to the URL.

  • Theme: ?theme=dark (default is light)
  • Size: ?size=md (options: sm, md, lg, xl; default is sm)
  • Variant: ?variant=outline (adds a border; default has no border)

Example with all options:

![Status](https://[slug].openstatus.dev/badge/v2?theme=dark&size=lg&variant=outline)

Option B: Legacy PNG Badge

Section titled “Option B: Legacy PNG Badge”

Use this badge if you prefer the older style.

Base URL
Section titled “Base URL”
https://[slug].openstatus.dev/badge
Markdown Snippet
Section titled “Markdown Snippet”
![Status](https://[slug].openstatus.dev/badge)

Example:

Status

Customization
Section titled “Customization”
  • Theme: ?theme=dark (default is light)
  • Size: ?size=lg (options: sm, md, lg, xl; default is sm)

Example with all options:

![Status](https://[slug].openstatus.dev/badge?theme=dark&size=lg)

Step 3: Commit your changes

Section titled “Step 3: Commit your changes”

Save your README.md file and commit it to your repository. The status badge will now be visible to anyone visiting your repository. It will automatically update to reflect the current status of your services.