Embedding Build Status Badges

Basics > Embedding Build Status Badges

This document describes how to embed a badge that shows the build status (passed or failed) for your project in your README or in another document. You can generate code for the following formats: Image URL, Markdown, Textile, Rdoc, AsciiDoc, reStructuredText, and pod.


CircleCI provides build status badges for projects and branches. Status badges are commonly embedded in GitHub READMEs, although they can be placed virtually anywhere.


CircleCI provides a tool to generate embed code for status badges.

  1. In the Notifications section of your project’s settings, click Status Badges.
  2. By default, the badge will display the status of your project’s default branch. If you want to show the status of a different branch, use the Branch dropdown menu to select it.
  3. (Optional) If you haven’t created an API token for viewing a project’s details, click on API Permissions in the Permissions section. Next, click Create Token, choose the Status scope, and create a label for the token.
  4. (Optional) In the API Token dropdown menu, select the token you want to use.
  5. Select the appropriate language from the Embed Code dropdown menu.
  6. Copy and paste the generated link to the web page or document where you want to display the status badge.


If you find the standard status badge ugly, you can use the highly-attractive shield style. Behold the difference:

  • Standard
  • Shield

To use the shield style, simply replace style=svg with style=shield in the link you generated above.