How to Add a Workflow Status Badge to the README in GitHub Actions

Each workflow exposes a badge at /actions/workflows/<file>/badge.svg that reflects its latest run status.

Embed the workflow badge image in your README, linking it to the workflow runs page. Append ?branch= or ?event= to scope the status it reports.

Steps

• Find the workflow file name (e.g. ci.yml).
• Embed .../actions/workflows/ci.yml/badge.svg as an image.
• Add ?branch=main to report only the default branch status.

README Markdown

[![CI](https://github.com/my-org/my-repo/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/my-org/my-repo/actions/workflows/ci.yml)

Gotchas

• The badge reflects the most recent run for the given filter, not a specific commit.
• Use ?event=push or ?event=schedule to avoid PR runs skewing the badge.

Related guides