Build status badges

Build status badges help to visually show the current build state for a pipeline in places such as readmes and dashboards.

You can find your pipeline's status badge on the pipeline's Settings > Build Badges page.

Scoping to a branch

By default the build status badge will show the last build's status. You can scope it to a specific branch by adding a ?branch parameter to the URL. For example, to scope your badge to the main branch you would add: ?branch=main to the URL.

Scoping to a step

If you want to create a badge that represents a single step in the last build, you can scope it that step by adding a ?step parameter to the URL. For example, to scope your badge to the iOS Build step you would add: ?step=iOS%20Build to the URL. If you have multiple steps that match the given name it will show as passing only if all of the matching steps passed.

Styles

You can set the style of the badge by passing in a style parameter:

Default
?style=square

The square style can also be referred to as flat-square to match any shields.io badges you may use.

Themes

You can change the colors of the badges by passing in a theme parameter:

Default
?theme=slack
?theme=github
?theme=saturn
?theme=flickr
?theme=solarized
?theme=mono

Custom themes

You can also create your own theme by passing a comma-separated list of color values instead of the theme name.

The format is passing-bg-color,failing-bg-color,unknown-bg-color[,label-bg-color[,text-color,status-text-color]]

For example:

?theme=9c0,f93,0ad
?theme=9c0,f93,0ad,d6d6d6
?theme=9c0,f93,0ad,d6d6d6,000
?theme=9c0,f93,0ad,d6d6d6,000,fff

Sample badge URLs

You can use the following URLs for testing your theme:

  • /sample.svg?status=passing
  • /sample.svg?status=failing
  • /sample.svg?status=unknown

JSON output

You can get the JSON value of the status badge by specifying .json in the badge URL instead of .svg, including branch scoping and step scoping. For example:

$ curl https://badge.buildkite.com/3826789cf8890b426057e6fe1c4e683bdf04fa24d498885489.json?branch=main
{"status": "passing"}

Possible values for the "status" key are:

  • "passing"
  • "failing"
  • "unknown"

Contributing

Want to contribute a theme? Send a pull request to buildkite/build-status-badge-themes.