Overview

CircleCI provides status badges that offer a visual representation of the build status, enabling easy tracking of the health and progress of your CI/CD pipeline. These badges come in three different types, each indicating a specific aspect of the build status. Here's a comprehensive guide to understanding the three different status badges in CircleCI builds:

Build Status Badge (build)

Badge URL Format: https://circleci.com/gh/<ORG>/<PROJECT>/tree/<BRANCH>.svg?style=svg&circle-token=<TOKEN>
Indication: Reflects the overall status of the latest build on the specified branch. Variants include:

Passing: Indicates that the build has completed successfully without any errors.
Failing: Signifies that the build has encountered errors or failures during the execution of tasks.
Running: Shows that the build is currently in progress and is actively being executed.
Canceled: Indicates that the workflow has been stopped or canceled due to outside intervention, such as an API call, manual user intervention, etc. This badge is denoted by a black color.
Not Run: While similar to the Canceled status badge in appearance, this status typically comes with an error or warning message in the UI stating that the build was not run for various reasons.

Workflow Status Badge (workflow)

Badge URL Format: https://circleci.com/gh/<ORG>/<PROJECT>/<WORKFLOW>?style=svg&circle-token=<TOKEN>
Indication: Represents the status of a particular workflow within the CI/CD pipeline. Features include:

Success: Indicates that the workflow has executed successfully, meeting all defined criteria and completing without errors. This badge is denoted by a green color.
Failure: Denotes that the workflow encountered issues or failures during execution, requiring attention and possible troubleshooting. This badge is denoted by a red color.
On Hold: Indicates that the workflow is paused at a manual approval or validation step, awaiting manual intervention before proceeding. This badge is denoted by a black color
Canceled: Indicates that the workflow has been stopped or canceled due to outside intervention, such as an API call, manual user intervention, etc. This badge is denoted by a black color

Approval Status Badge (approval)

Badge URL Format: https://circleci.com/gh/<ORG>/<PROJECT>/<WORKFLOW_ID>/status?circle-token=<TOKEN>
Indication: Displays the approval status of a manual approval step within a workflow. Key points include:

Approved: Confirms that the manual approval step has been successfully authorized and allowed to progress further.
Pending Approval: Indicates that a manual approval is required before the workflow can continue execution.

Utilizing Status Badges

Integration: Embed status badges in README files, documentation, or project dashboards for quick reference and visibility of build statuses.
Monitoring: Use status badges to monitor build health, detect failures, and track progress across different branches and workflows.
Customization: Customize badge styles or incorporate within external tools to enhance the visual representation of build statuses.

Understanding the distinctions between the three different types of status badges in CircleCI builds empowers users to effectively monitor build status, workflow progress, and approval steps within their CI/CD pipelines. By leveraging these badges strategically, teams can streamline collaboration, improve visibility, and ensure the smooth operation of their development.

Additional Resources:

Understanding the 3 Different Status Badges in CircleCI Builds