Skip to content

Latest commit



108 lines (72 loc) · 6.1 KB

File metadata and controls

108 lines (72 loc) · 6.1 KB
layout title short-title description categories contentTags
Enabling GitHub Checks
Enabling GitHub Checks
How to enable GitHub Checks for CircleCI


{: #introduction }

The GitHub Checks feature is not currently supported for projects that have integrated with the CircleCI GitHub App. To find out if you authorized through the GitHub OAuth app or the CircleCI GitHub App, see the GitHub App integration page. {: class="alert alert-info" }

This document describes how to enable the GitHub Checks feature and authorize CircleCI to report workflow status to GitHub user interface. The GitHub checks integration feature is not currently available on CircleCI server.

GitHub Checks provides you with workflow status messages and gives the option to rerun workflows from the GitHub Checks page.

After GitHub Checks is enabled, CircleCI workflow status is reported under the checks tab on GitHub.

CircleCI checks on GitHub

GitHub does not currently provide a granular way for you to rerun workflows. When you select the Re-run checks button, you will automatically re-run all checks, regardless of whether you selected "re-run failed checks" or "rerun all checks" from the Re-run checks button. {: class="alert alert-info" }

GitHub Check and GitHub status updates

{: #github-check-and-github-status-updates }

GitHub Checks should not be confused with GitHub status updates:

  • GitHub Checks are administered from the GitHub UI, and are reported in the GitHub UI per workflow.
  • GitHub status updates are the default way status updates from your builds are reported in the GitHub UI, and they are reported per job.

If both these features are enabled, in a GitHub PR view the Checks tab will show workflow status and the Checks section in the PR conversation view will show job status.

If you are using GitHuck Checks or GitHub Status updates with the skip jobs feature, the status of the skipped builds will not be reported even though the checks will be created in GitHub.


{: #prerequisites }

  • You must be using the cloud-hosted version of CircleCI.
  • Your project must be using Workflows.
  • You must be an admin on your GitHub repository to authorize installation of the CircleCI Checks integration.

Enable GitHub Checks

{: #enable-github-checks }

  1. In the CircleCI app sidebar, select Organization Settings.
  2. Select VCS.
  3. Click the Manage GitHub Checks button. CircleCI VCS Settings Page
  4. Select the repositories that should use checks and click the Install button.

After installation completes, the Checks tab on the GitHub PR view will be populated with workflow status information, and from here you can rerun workflows or navigate to the CircleCI app to view further information.

Checks status reporting

{: #checks-status-reporting }

CircleCI reports the status of workflows and all corresponding jobs under the Checks tab on GitHub. Additionally, Checks provides a button to rerun all workflows configured for your project.

After a rerun is initiated, CircleCI reruns the workflows from the start and reports the status in the Checks tab. To navigate to the CircleCI app from GitHub, click the View more details on CircleCI Checks link.

Your project will stop receiving job level status after GitHub Checks is turned on. You can re-enable this in the GitHub Status updates section of the Project Settings > Advanced Settings page in the CircleCI app. {: class="alert alert-info" }

Disable GitHub Checks for a project

{: #disable-github-checks-for-a-project }

To disable the GitHub Checks integration, navigate to the Organization Settings page in the CircleCI app, then remove the repositories using GitHub Checks, as follows:

  1. Click the Organization Settings option in the CircleCI sidebar.
  2. Select VCS.
  3. Click the Manage GitHub Checks button. The Update CircleCI Checks repository access page appears.
  4. Deselect the repository to uninstall the Checks integration. Click Save. If you are removing GitHub checks from the only repo you have it installed on, you will need to either suspend or uninstall CircleCI Checks.
  5. Confirm that GitHub status updates have been enabled on your project so you will see job level status within PRs in GitHub. Go to the CircleCI app and navigate to Project Settings > Advanced Settings and confirm that the setting GitHub Status Updates is set to on.

CircleCI VCS Settings Page

Uninstall Checks for the organization

{: #uninstall-checks-for-the-organization }

  1. Click the Organization Settings option in the CircleCI sidebar.
  2. Select VCS.
  3. Click the Manage GitHub Checks button.
  4. Scroll down and click the Uninstall button to uninstall the GitHub Checks app.

Troubleshoot GitHub Checks waiting for status in GitHub

{: #troubleshoot-github-checks-waiting-for-status-in-github }

ci/circleci:build — Waiting for status to be reported

If you have enabled GitHub Checks in your GitHub repository, but the status check never completes on GitHub Checks tab, there may be status settings in GitHub that you need to deselect. For example, if you choose to protect your branches, you may need to deselect the ci/circleci:build status key as this check refers to the job status from CircleCI, as follows:

Uncheck GitHub Job Status Keys

Having the ci/circleci:build checkbox enabled will prevent the status from showing as completed in GitHub when using a GitHub Check because CircleCI posts statuses to GitHub at a workflow level rather than a job level.

Go to Settings > Branches in GitHub and click the Edit button on the protected branch to deselect the settings, for example

Next steps

{: #next-steps }