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 Settings 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 master branch you would add: ?branch=master 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 branch 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 Sample Sample Sample
?style=square Sample Sample Sample

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 Sample Sample Sample
?theme=slack Sample Sample Sample
?theme=github Sample Sample Sample
?theme=saturn Sample Sample Sample
?theme=flickr Sample Sample Sample
?theme=solarized Sample Sample Sample
?theme=mono Sample Sample Sample

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 Sample Sample Sample
?theme=9c0,f93,0ad,d6d6d6 Sample Sample Sample
?theme=9c0,f93,0ad,d6d6d6,000 Sample Sample Sample
?theme=9c0,f93,0ad,d6d6d6,000,fff Sample Sample Sample

Sample badge URLs

You can use the following URLs for testing your theme:

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=master
{"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.