Status updates overview
CircleCI reports the status of your pipelines back to your version control system (VCS). This lets you see the progress and results of your CircleCI jobs and workflows without leaving your VCS. For example, you can spot a failing job on a pull request before you merge.
Introduction
CircleCI reports status updates to your VCS at the job level or the workflow level. What you see depends on your VCS.
| Type | Level | Available for | Setup |
|---|---|---|---|
Job |
GitHub, Bitbucket |
On by default. |
|
Workflow |
GitHub |
Install the CircleCI Checks GitHub App. |
|
Workflow |
Cursor Origin |
On by default. |
|
Workflow |
GitLab |
On by default. You cannot disable them. |
Commit status updates
Commit status updates are the default way CircleCI reports pipeline status to GitHub and Bitbucket. CircleCI reports one commit status for each job.
Where commit status updates appear
When a pipeline is triggered in CircleCI, status information is sent back to your VCS. Commit status updates appear in the following locations:
-
In pull requests when viewing an individual commit.
-
Next to individual commits in a pull/merge request conversation view.
-
At the end of a pull/merge request.
The following images show where to find commit status updates in GitHub. Bitbucket has similar locations.
-
Status updates in PR
-
Commit status
-
Commit status in PR
Commit status update naming
CircleCI displays commit status updates differently depending on the job type.
Regular jobs display using the following format:
-
Format:
ci/circleci: <job_name> -
Example:
ci/circleci: build -
Example:
ci/circleci: rspec
Approval jobs and no-op jobs display using the following format:
-
Format:
ci/circleci: <workflow_name>/<job_name> -
Example:
ci/circleci: build_and_deploy/approval-deploy -
Example:
ci/circleci: build_and_deploy/no-op-job
The workflow name prefix for approval and no-op jobs provides additional context. These jobs typically require manual intervention or represent conditional workflow states. Regular jobs that run automatically do not require this additional context.
| Need to find the workflow for a regular job? Click through to the CircleCI dashboard. The full workflow context is visible there. |
Disable commit status updates
If you use GitHub Checks, you can disable commit status updates to avoid duplication of statuses.
To disable commit status updates in the CircleCI web app:
-
In the CircleCI web app, select your org from the org cards on your user homepage.
-
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
-
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. -
Select Advanced Settings.
-
Set VCS Status Updates to
off.
You can re-enable commit status updates by setting VCS Status Updates to on.
| The VCS Status Updates setting affects GitHub and Bitbucket Cloud commit status updates. It does not affect GitLab status updates, which you cannot disable, or Cursor Origin checks. |
GitHub Checks
GitHub Checks reports workflow status in the Checks tab of a GitHub pull request. You can rerun workflows from the Checks tab, and select View more details on CircleCI Checks to open the workflow in the CircleCI web app.
GitHub Checks is a GitHub App. In GitHub, the app is called CircleCI Checks.
| GitHub does not provide a granular way to rerun workflows. Selecting Re-run checks reruns all checks, regardless of whether you choose "re-run failed checks" or "re-run all checks". |
Prerequisites
-
Your project must use Workflows.
-
You must be an admin on your GitHub repository to authorize installation of the CircleCI Checks app.
Enable GitHub Checks
-
In the CircleCI web app, select Org in the sidebar.
-
Select VCS Connections.
-
Select Manage GitHub Checks.
-
On the CircleCI Checks app settings page in GitHub, select the repositories you want to use Checks with, and select Save.
After installation completes, the Checks tab on a GitHub pull request shows workflow status.
GitHub Checks naming
Each workflow in a pipeline generates a GitHub Check.
-
GitHub OAuth integrations name each check after its workflow.
-
GitHub App integrations name each check using the workflow name and the first eight characters of the pipeline definition ID. This prevents naming collisions. You can find the pipeline definition ID in in the CircleCI web app.
If multiple pipelines trigger for the same commit SHA with workflows that share the same name, only one GitHub Check appears for that workflow name. Use unique workflow names across pipelines to get distinct checks.
If you use the Skip Jobs feature, CircleCI does not report the status of skipped builds. GitHub Checks are still created in GitHub.
GitHub Checks and commit status updates together
Your project continues to receive commit status updates after you turn on GitHub Checks. With both enabled, a GitHub pull request shows:
-
Workflow status in the Checks tab.
-
Job status in the Checks section of the pull request conversation view.
To show workflow status only, see Disable Commit Status Updates.
Disable GitHub Checks for a project
-
In the CircleCI web app, select Org in the sidebar.
-
Select VCS Connections.
-
Select Manage GitHub Checks. The Update CircleCI Checks repository access page appears.
-
Deselect the repository you want to remove, and select Save. If you are removing GitHub Checks from the only repository it is installed on, you must either suspend or uninstall CircleCI Checks.
-
Confirm that commit status updates are on for the project so you see job level status in GitHub pull requests. In the CircleCI web app, go to and confirm that GitHub Status Updates is set to
on.
Uninstall GitHub Checks for the organization
-
In the CircleCI web app, select Org in the sidebar.
-
Select VCS Connections.
-
Select Manage GitHub Checks.
-
Scroll down and select Uninstall to uninstall the CircleCI Checks app.
-
Confirm that commit status updates are on for your projects so you see job level status in GitHub pull requests. In the CircleCI web app, go to and confirm that GitHub Status Updates is set to
on.
| GitHub OAuth integrations automatically re-enable job level status when you uninstall GitHub Checks. GitHub App integrations do not disable or re-enable job level status automatically. |
Troubleshoot GitHub Checks waiting for status
If the following message appears and the check never completes in the Checks tab, a branch protection setting in GitHub may be the cause.
ci/circleci:build — Waiting for status to be reported
The ci/circleci:build status key refers to the job status from CircleCI, but with GitHub Checks CircleCI posts status at the workflow level. If you protect a branch and require this status key, GitHub waits for a job status that never completes.
To fix this, deselect the ci/circleci:build status key in your branch protection rules.
-
In GitHub, go to .
-
Select Edit on the protected branch.
-
Deselect the
ci/circleci:buildstatus key.
Cursor Origin checks
| The Cursor Origin integration is in beta. |
For Cursor Origin projects, CircleCI reports one check for each workflow rather than a status for each job. Cursor Origin checks are on by default and use Origin’s native checks, so you need no separate app.
Each check is named CircleCI / <workflow_name>, for example CircleCI / my-workflow. Checks appear in the following locations in Cursor Origin:
-
On a commit page, under the commit message.
-
On a pull request, in the merge box on the Activity tab and in the Checks tab.
Select Details on a commit, or select the check in the Checks tab of a pull request, to see the workflow’s jobs and their results. Each job links to the job in the CircleCI web app, and View on CircleCI opens the workflow.