Merge branch '327634-status-checks-widget-docs' into 'master'

Document merge request status checks widget

See merge request gitlab-org/gitlab!63038

doc/user/project/merge_requests/status_checks.md

@@ -113,6 +113,32 @@ To complete the deletion of the status check you must select the
 **Remove status check** button. This **permanently** deletes
 the status check and it **will not** be recoverable.
 
+## Status checks widget
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327634) in GitLab 14.1.
+> - The [external status checks](#external-status-checks) feature must be [enabled](#enable-or-disable-status-checks) to see the status checks widget.
+
+The status checks widget displays in merge requests and shows the status of external
+status checks:
+
+![Status checks widget](img/status_checks_widget_passed_v14_0.png)
+
+An organization might have a policy that does not allow merging merge requests if
+external status checks do not pass. However, the details in the widget are for informational
+purposes only. GitLab does not prevent merging of merge requests that fail status checks.
+
+While GitLab waits for a response from the external status check, the widget shows
+the status checks as `pending`:
+
+![Status checks widget pending](img/status_checks_widget_pending_v14_0.png)
+
+After GitLab [receives a response](../../../api/status_checks.md#set-approval-status-of-an-external-status-check)
+from the external status check, the widget updates accordingly.
+
+NOTE:
+GitLab cannot guarantee that the external status checks are properly processed by
+the related external service.
+
 ## Troubleshooting
 
 ### Duplicate value errors
@@ -149,6 +175,19 @@ An unexpected response was received from the branches retrieval API.
 As suggested, you should close the form and reopen again or refresh the page. This error should be temporary, although
 if it persists please check the [GitLab status page](https://status.gitlab.com/) to see if there is a wider outage.
 
+### Failed to load status checks
+
+```plaintext
+Failed to load status checks
+```
+
+An unexpected response was received from the external status checks API.
+You should:
+
+- Refresh the page in case this error is temporary.
+- Check the [GitLab status page](https://status.gitlab.com/) if the problem persists,
+  to see if there is a wider outage.
+
 ## Enable or disable status checks **(ULTIMATE SELF)**
 
 Status checks are under development and not ready for production use. It is

doc/user/project/merge_requests/widgets.md

@@ -62,3 +62,9 @@ merge request widget takes you directly to the pages changed, making it easier a
 faster to preview proposed modifications.
 
 [Read more about Review Apps](../../../ci/review_apps/index.md).
+
+## External status checks **(ULTIMATE)**
+
+If you have configured [external status checks](status_checks.md) you can
+see the status of these checks in merge requests
+[in a specific widget](status_checks.md#status-checks-widget).

ee/app/assets/javascripts/reports/status_checks_report/status_checks_reports_app.vue

@@ -72,8 +72,8 @@ export default {
     ),
     errorText: s__('StatusCheck|Failed to load status checks.'),
   },
-  docsLink: helpPagePath('user/project/merge_requests/approvals/index.md', {
-    anchor: 'notify-external-services',
+  docsLink: helpPagePath('user/project/merge_requests/status_checks.md', {
+    anchor: 'status-checks-widget',
   }),
 };
 </script>

ee/spec/frontend/reports/status_checks_report/__snapshots__/status_checks_reports_app_spec.js.snap

@@ -9,7 +9,7 @@ exports[`Grouped test reports app when mounted matches the default state compone
         <div class=\\"gl-display-flex gl-align-items-center\\">
           <p class=\\"gl-line-height-normal gl-m-0\\">Status checks</p>
           <!---->
-        </div> <span class=\\"gl-text-gray-500 gl-font-sm\\">When this merge request is updated, a call is sent to the following APIs to confirm their status. <gl-link-stub href=\\"/help/user/project/merge_requests/approvals/index.md#notify-external-services\\" class=\\"gl-font-sm\\">Learn more</gl-link-stub>.</span>
+        </div> <span class=\\"gl-text-gray-500 gl-font-sm\\">When this merge request is updated, a call is sent to the following APIs to confirm their status. <gl-link-stub href=\\"/help/user/project/merge_requests/status_checks.md#status-checks-widget\\" class=\\"gl-font-sm\\">Learn more</gl-link-stub>.</span>
       </div>
       <!---->
     </div>