GitHub Actions Tutorial — Workflow Badges

Workflow Badges

A workflow badge is a small image that shows the current status of your workflow (passing/failing). Adding it to your README signals to users and contributors that your project has automated testing.

---

Badge URL Format

GitHub provides a badge URL for every workflow:

https://github.com/{owner}/{repo}/actions/workflows/{workflow-file}/badge.svg

Example:

https://github.com/octocat/my-app/actions/workflows/ci.yml/badge.svg

---

Adding a Badge to Your README

Markdown Format

Add this to your README.md:

![CI](https://github.com/octocat/my-app/actions/workflows/ci.yml/badge.svg)

This renders as a badge: CI: passing (green) or CI: failing (red).

With a Link to the Actions Tab

Wrap the badge in a link so clicking it opens the Actions tab:

[![CI](https://github.com/octocat/my-app/actions/workflows/ci.yml/badge.svg)](https://github.com/octocat/my-app/actions/workflows/ci.yml)

---

Branch-Specific Badges

By default, the badge shows the status of the default branch (usually main). You can show the status of a specific branch:

![CI](https://github.com/octocat/my-app/actions/workflows/ci.yml/badge.svg?branch=develop)

---

Event-Specific Badges

Show the badge for a specific trigger event:

![CI](https://github.com/octocat/my-app/actions/workflows/ci.yml/badge.svg?event=push)

---

Getting the Badge URL from GitHub

If you don’t want to construct the URL manually:

1. Go to Actions tab
2. Click on the workflow name in the left sidebar
3. Click the “…“ menu (three dots) at the top right
4. Select “Create status badge”
5. Choose the branch and copy the Markdown

---

Multiple Badges

Many projects show multiple badges for different workflows:

![CI](https://github.com/octocat/my-app/actions/workflows/ci.yml/badge.svg)
![Deploy](https://github.com/octocat/my-app/actions/workflows/deploy.yml/badge.svg)
![Security](https://github.com/octocat/my-app/actions/workflows/security.yml/badge.svg)

This gives readers a quick health overview of your project.

---

Badge Caching

GitHub caches badge images for a few minutes. If your workflow just completed but the badge still shows the old status, wait 2-3 minutes and refresh.

Tip: Add ?cache-bust=1 or a timestamp query parameter to force a fresh badge during testing (remove before committing).

---

Quick Reference

Badge Type	URL Parameter
Default branch	No parameter needed
Specific branch	?branch=develop
Specific event	?event=push
Both	?branch=main&event=push

---

← Previous: Viewing Results

Next: Practice Exercises →