Working with Workflow Status Badges
1. Creating Status Badges
Status badges provide a visual indicator of your workflow's current status, making it easy to see at a glance whether your CI/CD pipeline is passing or failing. You can add these badges to your repository's README or documentation.
| Badge Type | URL Format | Description |
|---|---|---|
| Build Status | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg |
Shows the status of a specific workflow (e.g., build, test) |
| Branch Status | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg?branch=<branch_name> |
Shows the status of a workflow for a specific branch |
Example: Adding a Build Status Badge to README.md
[](https://github.com/octocat/Hello-World/actions/workflows/main.yml)
Note: The badge URL uses the workflow file name (e.g.,
main.yml) and must be updated if the workflow file is renamed.
2. Using Branch Specific Badges
GitHub Actions workflow status badges can be customized to reflect the status of workflows on specific branches. This is useful for displaying the build status of feature branches or release branches.
| Badge Type | URL Format | Description |
|---|---|---|
| Branch-specific badge | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg?branch=<branch_name> |
Displays the status of a workflow on a specific branch. |
Example: Branch-specific Badge URL
https://github.com/octocat/Hello-World/actions/workflows/main.yml/badge.svg?branch=feature-branch
Note: The
workflow_id in the URL can be either the workflow file name (e.g., main.yml) or the numeric ID of the workflow as shown in the GitHub UI.
3. Using Event Specific Badges
GitHub Actions allows you to display workflow status badges that are specific to different events. These badges help visualize the current state of workflows triggered by various events like pushes, pull requests, or scheduled runs.
| Event | Badge URL Format | Description |
|---|---|---|
| push | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg?event=push |
Displays status for workflows triggered by a push event. |
| pull_request | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg?event=pull_request |
Shows status for workflows triggered by pull request events. |
| schedule | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg?event=schedule |
Indicates the status of workflows triggered by scheduled events. |
| workflow_dispatch | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg?event=workflow_dispatch |
Reflects the status of workflows manually triggered via the GitHub UI or API. |
Example: Embedding a Push-Specific Badge
<img src="https://github.com/octocat/Hello-World/actions/workflows/main.yml/badge.svg?event=push" alt="Push Workflow Status">
Note: The
workflow_id in the badge URL corresponds to the id field of the workflow file or its name if no ID is specified.
4. Embedding in README
To embed a GitHub Actions workflow status badge in your README, use the following Markdown syntax:
Example: Embedding Workflow Badge
[](https://github.com/OWNER/REPO/actions/workflows/WORKFLOW_FILE.yml)Replace OWNER, REPO, and WORKFLOW_FILE.yml with your repository details.
| Parameter | Description | Example |
|---|---|---|
| OWNER | Repository owner or organization name | octocat |
| REPO | Repository name | Hello-World |
| WORKFLOW_FILE.yml | Name of the workflow file (including extension) | ci.yml |
Note: The badge will display
passing, failing, or pending based on the last run of the workflow.
Warning: Ensure that your repository is public or that the badge URL is accessible to viewers if the repo is private.
5. Customizing Badge Style
| Property | Values | Description |
|---|---|---|
| style | flat, flat-square, for-the-badge, plastic, popout, popout-square |
Defines the visual style of the badge |
| logo | github, actions, circleci, travis, jenkins |
Specifies the logo to display on the badge |
| logoColor | Hex color code or named color | Sets the color of the logo (e.g., #000000) |
| label | String | Custom label text for the left side of the badge |
| color | Hex color code or named color | Background color of the right side of the badge |
Example: Custom Badge Style
Note: The
style parameter affects the overall shape and padding of the badge. For example, flat-square gives a square appearance with flat edges.
6. Using Multiple Badges
Example: Displaying Multiple Workflow Status Badges
<!-- Badge for "Build" workflow -->
<img src="https://github.com/example/repo/actions/workflows/build.yml/badge.svg" alt="Build Status">
<!-- Badge for "Test" workflow -->
<img src="https://github.com/example/repo/actions/workflows/test.yml/badge.svg" alt="Test Status">
<!-- Badge for "Deploy" workflow -->
<img src="https://github.com/example/repo/actions/workflows/deploy.yml/badge.svg" alt="Deploy Status">
| Badge Type | URL Pattern | Description |
|---|---|---|
| Workflow Badge | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>.yml/badge.svg |
Displays the status of a specific workflow |
| Branch Badge | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>.yml/badge.svg?branch=<branch_name> |
Displays the status of a workflow for a specific branch |
| Event Badge | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>.yml/badge.svg?event=<event_type> |
Displays the status of a workflow triggered by a specific event |
Note: The
badge.svg endpoint returns a dynamically generated SVG badge that reflects the current status of the workflow.
Warning: Badge URLs may change if the workflow file name or path is modified. Ensure that badge URLs in documentation or README files are updated accordingly.
7. Creating Dynamic Badges
Dynamic badges in GitHub Actions provide real-time status information about workflows. These badges can be embedded in README files or documentation to show the current state of a workflow.
| Badge Type | URL Pattern | Description | Example |
|---|---|---|---|
| Workflow Status | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg |
Shows the status of a specific workflow | <img src="https://github.com/octocat/Hello-World/actions/workflows/main.yml/badge.svg" alt="Workflow Status"> |
| Branch Status | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg?branch=<branch_name> |
Shows status for a specific branch | <img src="https://github.com/octocat/Hello-World/actions/workflows/main.yml/badge.svg?branch=develop" alt="Branch Status"> |
| Event Type | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg?event=<event_type> |
Shows status for a specific event type | <img src="https://github.com/octocat/Hello-World/actions/workflows/main.yml/badge.svg?event=pull_request" alt="Event Status"> |
Example: Using a Dynamic Badge in README
# My Project
[](https://github.com/octocat/Hello-World/actions/workflows/main.yml)
This project uses GitHub Actions for CI/CD.
Note: The badge URL uses the workflow file name or ID. For workflows with special characters, ensure proper encoding.
8. Showing Build Status
Example: Adding a workflow status badge to README
# My Project
[](https://github.com/example/my-project/actions)
This project uses GitHub Actions for CI/CD.
| Badge Type | URL Pattern | Description | Notes |
|---|---|---|---|
| Build Status | https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg |
Shows the status of the last run of a workflow | Replace <owner>, <repo>, and <workflow_id> with actual values |
| Build Status (by name) | https://github.com/<owner>/<repo>/actions/workflows/<workflow_name>/badge.svg |
Shows the status of the last run of a workflow by name | Use workflow name in URL path, not ID |
Note: The badge URL includes the workflow name or ID in the path. For workflows with spaces, use URL encoding (e.g.,
main%20workflow).Warning: If the workflow name contains special characters, ensure proper URL encoding to avoid badge display issues.
Badge Configuration Options
- Branch: Append
?branch=mainto the badge URL to show status for a specific branch - Event: Append
?event=pushto show status for a specific event type - Workflow ID: Use the numeric workflow ID from the GitHub UI or API
9. Using Coverage Badges
Example: Setting up a coverage badge
name: Code Coverage
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm install
- name: Run tests with coverage
run: npm run test:coverage
- name: Upload coverage to Codecov
uses: codecov/codecov-action@v3
with:
file: ./coverage/lcov.info
| Badge Type | URL Format | Description | Notes |
|---|---|---|---|
| Codecov | https://codecov.io/gh/<owner>/<repo>/branch/<branch>/badge.svg |
Code coverage from Codecov service | Requires upload of coverage data via codecov-action |
| Coveralls | https://coveralls.io/repos/<repo>/badge.svg?branch=<branch> |
Code coverage from Coveralls service | Upload coverage data using coveralls.io integration |
| Cobertura | https://img.shields.io/badge/coverage-<percentage>-green.svg |
Generic coverage badge using shields.io | Can be customized with any coverage percentage |
Note: Coverage badges are typically generated by CI services like Codecov or Coveralls after test runs. The badge URL usually includes the repository owner, name, and branch.
Warning: Ensure that your coverage report is uploaded to the service before generating the badge, otherwise it will show as 0% or fail to load.
10. Creating Custom Badges
Example: Basic Badge Configuration
name: CI
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Build
run: echo "Building..."
| Property | Description | Values | Notes |
|---|---|---|---|
| name | Workflow name | string |
Used in badge URL and UI |
| on | Triggers for workflow | array |
Supports push, pull_request, etc. |
| jobs | Job definitions | object |
Each job runs on a runner |
Note: Badge URLs follow the pattern
https://github.com/<owner>/<repo>/actions/workflows/<workflow_id>/badge.svg.Warning: Badge visibility depends on repository visibility (public/private).
Badge Configuration Summary
- Use
nameto identify workflows in badges - Define triggers with
on - Jobs run on runners (e.g.,
ubuntu-latest) - Badge SVG updates automatically when workflow runs
11. Adding Badge Tooltips
| Property | Values | Description |
|---|---|---|
| alt | string |
Alternative text for accessibility and tooltip display |
| title | string |
Tooltip text shown on hover (HTML title attribute) |
Example: Adding Tooltip to Badge
<img src="https://github.com/octocat/Hello-World/actions/workflows/main.yml/badge.svg" alt="Build Status" title="Workflow: main.yml - Last run: Success">Note: The
title attribute provides a native browser tooltip that appears when hovering over the badge image.12. Linking Badges to Workflows
GitHub Actions workflow status badges can be linked directly to the workflow run page for easy access and monitoring.
| Badge URL Format | Parameters | Description |
|---|---|---|
https://github.com/OWNER/REPO/actions/workflows/WORKFLOW_ID/badge.svg |
branch, event |
Displays the status of a specific workflow run on a given branch or event |
Example: Linking Badge to Workflow
<img src="https://github.com/octocat/Hello-World/actions/workflows/main.yml/badge.svg" alt="Workflow Status">Note: The
WORKFLOW_ID is the filename or ID of the workflow file (e.g., main.yml) in the .github/workflows directory.Warning: If the workflow name includes special characters, ensure it's properly URL-encoded in the badge link.