Start Building for Free

Adding status badges

4 days ago1 min read
Server v4.x
Server v3.x
On This Page

This document describes how to create a badge that displays your project’s build status (passed or failed) in a README or other document.


Status badges are commonly embedded in project READMEs, although they can be placed in any web document. CircleCI provides a tool to generate embed code for status badges. By default, a badge displays the status of a project’s default branch, though you can also display the status of specific branches.

A badge status allows teams to quickly see build statuses in their repository. Badges change appearance depending on their status (success, failure).

You can generate code for the following formats:

  • Image URL

  • Markdown

  • Textile

  • RDoc

  • AsciiDoc

  • reStructuredText

  • pod

Generating a status badge

To generate your own status badge, you will need to know, and substitute, the following variables in the code snippets below:

  • <PROJECT_NAME> - Your project’s name. Example: circleci-docs

  • <ORG_NAME> - The organization or user name the project in question belongs to

  • <VCS> - your VCS provider (gh for "GitHub" and bb for Bitbucket)

  • <LINK> - The link you want the status badge to go to when clicked (example: the pipeline overview page)

  • Optional: an API token (to create badges for private projects)

The following examples demonstrate how to generate a status badge for various template languages. Each example also provides a status badge code for a specific branch.

Creating badges for private repositories


To create a status API token, go to the CircleCI web app, navigate to a specific project, go to Project Settings  API Permissions, and create a token scoped to status.

Badge styles

If you find the default status badge too minimal, you can use the shield style. To use the shield style, replace style=svg with style=shield in the link you generated above.

Passed `svg` version
Failed `svg` version
Passing shield version
Failing shield version

Known issues and limitations

  • In cases where there are multiple workflows running within a pipeline, the status badge will show the result (red or green) of the latest workflow that has finished running. This is a bug. The expected behavior is for the badge to update to show the result of the last workflow once the pipeline is complete.

Suggest an edit to this page

Make a contribution
Learn how to contribute