How to Add a Status Badge to a GitHub README
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
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
- 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
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
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.
Option A: Modern SVG Badge (Recommended)
This is the recommended badge for most use cases.
Base URL
https://[slug].openstatus.dev/badge/v2
Markdown Snippet
Example:
Customization
You can customize the badge by adding query parameters to the URL.
- Theme:
?theme=dark(default islight) - Size:
?size=md(options:sm,md,lg,xl; default issm) - Variant:
?variant=outline(adds a border; default has no border)
Example with all options:
Option B: Legacy PNG Badge
Use this badge if you prefer the older style.
Base URL
https://[slug].openstatus.dev/badge
Markdown Snippet
Example:
Customization
- Theme:
?theme=dark(default islight) - Size:
?size=lg(options:sm,md,lg,xl; default issm)
Example with all options:
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.