Build status badges in Jenkins - Commands & Configuration

Introduction

Build status badges show the current state of a Jenkins job's build. They help teams quickly see if the latest build passed or failed without opening Jenkins.

When you want to display the health of your project on a README file in GitHub.

When you want your team to quickly check if the latest build is stable from a dashboard.

When you want to include build status in documentation or project websites.

When you want to monitor multiple Jenkins jobs at a glance.

When you want to share build results with stakeholders who do not access Jenkins directly.

Commands

This command fetches the HTTP headers of the build status badge URL for the Jenkins job named 'my-app'. It verifies the badge URL is accessible.

Terminal

curl -I http://jenkins.example.com/job/my-app/badge/icon

Expected Output

HTTP/1.1 200 OK

Content-Type: image/svg+xml

Content-Length: 1234

Connection: keep-alive

This command downloads the build status badge image for the 'my-app' job and saves it as 'build-status.svg'. You can then embed this SVG in your README or website.

Terminal

curl http://jenkins.example.com/job/my-app/badge/icon > build-status.svg

Expected Output

No output (command runs silently)

This command appends Markdown syntax to the README.md file to display the build status badge image from Jenkins.

Terminal

echo "![Build Status](http://jenkins.example.com/job/my-app/badge/icon)" >> README.md

Expected Output

No output (command runs silently)

This command fetches the build status color in JSON format for the 'my-app' job. Useful for custom scripts to check build status programmatically.

Terminal

curl http://jenkins.example.com/job/my-app/api/json?tree=color

Expected Output

{"color":"blue"}

Key Concept

If you remember nothing else from this pattern, remember: Jenkins provides a simple URL to get a live build status badge image that you can embed anywhere.

Common Mistakes

Using the wrong job name or URL in the badge link.

The badge URL will return 404 or an error image, so the badge won't display correctly.

Double-check the Jenkins job name and URL path exactly as it appears in Jenkins.

Trying to use the badge URL without Jenkins being publicly accessible or without proper permissions.

The badge image won't load because Jenkins blocks unauthorized access.

Make sure Jenkins is accessible or configure anonymous read access for the badge URL.

Embedding the badge URL in places that do not support images or Markdown syntax.

The badge will not render and users won't see the build status.

Use the badge in Markdown files, HTML pages, or dashboards that support image rendering.

Summary

Use the Jenkins job badge URL to get a live build status image.

Download or embed the badge URL in README files or websites using Markdown syntax.

Verify the badge URL is accessible and uses the correct job name.