---
title: "Adding status badges"
description: "Create and embed a CircleCI status badge that shows your project's build status in a README or any other web page or document."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-07"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Adding status badges

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

## Overview

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
    

## Generate status badge code

To get the code you need to embed a status badge for your project, follow these steps:

1.  In the CircleCI web app, select your org from the org cards on your user homepage.
    
2.  Select **Projects** from the sidebar and locate your project from the list. You can use the search to help.
    
3.  Select the ellipsis next to your project and select **Project Settings**.
    
    You can also access project settings from each project overview page using the **Settings** button.
    

4.  Select **Status Badges** from the sidebar.
    
5.  Select a branch to show the most recent status for.
    
6.  \[Optional\] If your project is private, select **Add API token**. In the modal, select **Add API token** again to add an API token with the `status` scope to your project.
    
7.  Select a format for your status badge code from the dropdown.
    
8.  Select **Copy** to copy the code. You can now add the badge to your README or other document.
    

## Manually generate status badge code

### Generate 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).
    
*   `<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.

Replace `circleci.com` in the following examples with your CircleCI Server hostname.

<Tabs>
<Tab title="Markdown">

```md
# Template:
[![<ORG_NAME>](https://circleci.com/<VCS>/<ORG_NAME>/<PROJECT_NAME>.svg?style=svg)](<LINK>)

# Example:
[![CircleCI](https://circleci.com/gh/circleci/circleci-docs.svg?style=svg)](https://circleci.com/gh/circleci/circleci-docs)

# Example for specific branch:
[![CircleCI](https://circleci.com/gh/circleci/circleci-docs/tree/teesloane-patch-5.svg?style=svg)](https://circleci.com/gh/circleci/circleci-docs/?branch=teesloane-patch-5)
```

</Tab>
<Tab title="Textile">

```md
# Template:
!https://circleci.com/<VCS>/<ORG_NAME>/<PROJECT_NAME>.svg?style=svg!:<LINK>

# Example:
!https://circleci.com/gh/circleci/circleci-docs.svg?style=svg!:https://circleci.com/gh/circleci/circleci-docs

# Example for specific branch:
!https://circleci.com/gh/circleci/circleci-docs/tree/teesloane-patch-5.svg?style=svg!:https://circleci.com/gh/circleci/circleci-docs/?branch=teesloane-patch-5
```

</Tab>
<Tab title="RDoc">

```md
# Template:
{<img src="https://circleci.com/<VCS>/<ORG_NAME>/<PROJECT_NAME>.svg?style=svg" alt="<ORG_NAME>" />}[https://circleci.com/gh/<ORG_NAME>/<PROJECT_NAME>]

# Example:
{<img src="https://circleci.com/gh/circleci/circleci-docs.svg?style=svg" alt="CircleCI" />}[https://circleci.com/gh/circleci/circleci-docs]

# Example for specific branch:
{<img src="https://circleci.com/gh/circleci/circleci-docs/tree/teesloane-patch-5.svg?style=svg" alt="CircleCI" />}[https://circleci.com/gh/circleci/circleci-docs/?branch=teesloane-patch-5]
```

</Tab>
<Tab title="AsciiDoc">

```adoc
# Template:
image:https://circleci.com/<VCS>/<ORG_NAME>/<PROJECT_NAME>.svg?style=svg["<ORG_NAME>", link="https://circleci.com/<VCS>/<ORG_NAME>/<PROJECT_NAME>"]

# Example:
image:https://circleci.com/gh/circleci/circleci-docs.svg?style=svg["CircleCI", link="https://circleci.com/gh/circleci/circleci-docs"]

# Example for specific branch:
image:https://circleci.com/gh/circleci/circleci-docs/tree/teesloane-patch-5.svg?style=svg["CircleCI", link="https://circleci.com/gh/circleci/circleci-docs/?branch=teesloane-patch-5"]
```

</Tab>
<Tab title="reStructuredText">

```rst
# Template:
.. image::guides:ROOT:https://circleci.com/<VCS>/<ORG_NAME>/<PROJECT_NAME>.svg?style=svg
    :target: https://circleci.com/<VCS>/<ORG_NAME>/<PROJECT_NAME>

# Example:
.. image:: https://circleci.com/gh/circleci/circleci-docs.svg?style=svg
    :target: https://circleci.com/gh/circleci/circleci-docs

# Example for specific branch:
.. image:: https://circleci.com/gh/circleci/circleci-docs/tree/teesloane-patch-5.svg?style=svg
    :target: https://circleci.com/gh/circleci/circleci-docs/?branch=teesloane-patch-5
```

</Tab>
<Tab title="pod">

```
# Template:
=for HTML <a href="https://circleci.com/<VCS>/<ORG_NAME>/<PROJECT_NAME>"><img src="https://circleci.com/<VCS>/<ORG_NAME>/<PROJECT_NAME>.svg?style=svg"></a>

# Example:
=for HTML <a href="https://circleci.com/gh/circleci/circleci-docs"><img src="https://circleci.com/gh/circleci/circleci-docs.svg?style=svg"></a>

# Example for specific branch:
=for HTML <a href="https://circleci.com/gh/circleci/circleci-docs/?branch=teesloane-patch-5"><img src="https://circleci.com/gh/circleci/circleci-docs/tree/teesloane-patch-5.svg?style=svg"></a>
```

</Tab>
</Tabs>

### Creating badges for private repositories

To create a status badge for a private project, create an API token scoped to `status`. Include that token in the URL string of your badge. Consider the following markdown image badge snippet against the original markdown example above; it has a URL parameter for a token added.

```markdown
[![CircleCI](https://circleci.com/<VCS>/<ORG_NAME>/<PROJECT_NAME>.svg?style=svg&circle-token=<YOUR_STATUS_API_TOKEN>)](<LINK>)
```

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](https://shields.io/). To use the shield style, replace `style=svg` with `style=shield` in the link you generated above.

> **Image:** Passed `svg` version

Figure 1. Passed svg-style status badge

> **Image:** Failed `svg` version

Figure 2. Failed svg-style status badge

> **Image:** Passing shield version

Figure 3. Passing shield-style status badge

> **Image:** Failing shield version

Figure 4. Failing shield-style status badge

## 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. That behavior 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.