Embeddable status badges

We provide project and branch status images, which you can embed anywhere you want: a GitHub README, a dashboard, or anywhere else you can imagine!

Here’s our current build status:

The status images are also available in “shield” style:

In the project settings for each of your repositories, there’s a “Status Badges” section that can generate code for Markdown, rst, etc. Or if you want to tweak them manually, how they work is straightforward:

You can use a simple image URL like this to see the status of your project’s default branch:

For example: circleci/mongofinil badge and shield

Or you can see the status of any specific branch:

For example: circleci/mongofinil master branch badge and shield

One small wrinkle: if your branch name includes characters that are “special” in URLs (most commonly ‘/’) they’ll need to be URL encoded when constructing status badge URLs. For example, the badge for a branch called ‘feature/nonexistent’ would be at ‘…/tree/feature%2Fnonexistent.png’.

Access Control

We recommend creating specific, narrowly scoped API tokens. In fact, we created a whole class of tokens just for this purpose: tokens which give read-only access to the build status of a single project, and nothing else. You can create and manage these tokens from the Project Settings > API Permissions page of any project.

If you prefer, it is also possible to use a user’s API token as the circle-token. These tokens are very powerful, so only do that in a trusted environment!

(You can also link to the image without providing a circle-token, in which case the image will only appear for people who are currently logged-in to!)