Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions docs/guides/modules/integration/pages/enable-checks.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -16,22 +16,26 @@ After GitHub Checks is enabled, CircleCI workflow status is reported under the c

image::guides:ROOT:checks_tab.png[CircleCI checks on GitHub]

NOTE: 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.
NOTE: GitHub does not currently provide a granular way for you to rerun workflows. When you select the Re-run checks button, all checks are rerun, regardless of whether you selected "re-run failed checks" or "rerun all checks" from the Re-run checks button.

[#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 Checks from OAuth integrations have the same name as the associated workflow.
** GitHub Checks from GitHub App integrations are named using a combination of the workflow name and the first eight characters of the pipeline definition ID. The identifier is used to prevent naming collisions. The pipeline definition ID is available in the *Project Settings* > *Pipelines* page in the CircleCI web app.
** GitHub Checks from OAuth integrations have the same name as the associated workflow.
** GitHub Checks from GitHub App integrations are named using a combination of the workflow name and the first eight characters of the pipeline definition ID. The identifier is used to prevent naming collisions. The pipeline definition ID is available in the *Project Settings* > *Pipelines* page in the CircleCI web app.
** Each workflow in a pipeline generates a GitHub Check. 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 GitHub Checks.
* 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 both these features are enabled you will see the following in a GitHub PR view:

If you are using GitHuck Checks or GitHub Status updates with the xref:orchestrate:skip-build.adoc#skip-jobs[skip jobs feature],
the status of the skipped builds will not be reported even though the checks will be created in GitHub.
* The Checks tab will show *workflow status*.
* The Checks section in the PR conversation view will show *job status*.

If you are using GitHuck Checks or GitHub status updates with the xref:orchestrate:skip-build.adoc#skip-jobs[skip jobs feature],
the status of the skipped builds will not be reported. The checks are still created in GitHub.

[#prerequisites]
== Prerequisites
Expand All @@ -50,12 +54,12 @@ the status of the skipped builds will not be reported even though the checks wil
image::guides:ROOT:github-checks.png[CircleCI VCS Settings Page]
. You are now in the GitHub CircleCI Checks App settings page. Select the repositories that should use checks and select *Save*.

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.
After installation completes, the Checks tab on the GitHub PR view is populated with workflow status information. From the Checks tab 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.
CircleCI reports the status of workflows and all corresponding jobs under the Checks tab on GitHub. 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, select the *View more details on CircleCI Checks* link.

Expand Down Expand Up @@ -96,11 +100,11 @@ NOTE: GitHub OAuth integrations will automatically re-enable job level status wh

`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:
If you have enabled GitHub Checks and 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:

image::guides:ROOT:github_job_status.png[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.
Having the `ci/circleci:build` checkbox enabled prevents the status from showing as completed in GitHub when using a GitHub Check. CircleCI posts statuses to GitHub at a workflow level rather than a job level.

Go to menu:Settings[Branches] in GitHub and select the *Edit* button on the protected branch to deselect the settings, for example `+https://github.com/your-org/project/settings/branches+`.

Expand Down