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:
Or you can see the status of any specific branch:
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’.
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 circleci.com!)