Merge branch 'ci-external-pipeline-validation-docs' into 'master'

Update documentation for external pipeline validation service

See merge request gitlab-org/gitlab!57485

doc/administration/environment_variables.md

@@ -21,6 +21,9 @@ You can use the following environment variables to override certain values:
 |--------------------------------------------|---------|---------------------------------------------------------------------------------------------------------|
 | `DATABASE_URL`                             | string  | The database URL; is of the form: `postgresql://localhost/blog_development`.                            |
 | `ENABLE_BOOTSNAP`                          | string  | Enables Bootsnap for speeding up initial Rails boot (`1` to enable).                                    |
+| `EXTERNAL_VALIDATION_SERVICE_TIMEOUT`      | integer | Timeout, in seconds, for an [external CI/CD pipeline validation service](external_pipeline_validation.md). Default is `5`. |
+| `EXTERNAL_VALIDATION_SERVICE_URL`          | string  | URL to an [external CI/CD pipeline validation service](external_pipeline_validation.md).                |
+| `EXTERNAL_VALIDATION_SERVICE_TOKEN`        | string  | The `X-Gitlab-Token` for authentication with an [external CI/CD pipeline validation service](external_pipeline_validation.md). |
 | `GITLAB_CDN_HOST`                          | string  | Sets the base URL for a CDN to serve static assets (for example, `//mycdnsubdomain.fictional-cdn.com`). |
 | `GITLAB_EMAIL_DISPLAY_NAME`                | string  | The name used in the **From** field in emails sent by GitLab.                                           |
 | `GITLAB_EMAIL_FROM`                        | string  | The email address used in the **From** field in emails sent by GitLab.                                  |

doc/administration/external_pipeline_validation.md

@@ -7,7 +7,7 @@ type: reference, howto
 
 # External Pipeline Validation
 
-You can use an external service for validating a pipeline before it's created.
+You can use an external service to validate a pipeline before it's created.
 
 WARNING:
 This is an experimental feature and subject to change without notice.
@@ -19,19 +19,17 @@ data as payload. GitLab then invalidates the pipeline based on the response
 code. If there's an error or the request times out, the pipeline is not
 invalidated.
 
-Response Code Legend:
+Response codes:
 
-- `200` - Accepted
-- `406` - Not Accepted
-- Other Codes - Accepted and Logged
+- `200`: Accepted
+- `4XX`: Not accepted
+- All other codes: accepted and logged
 
 ## Configuration
 
-To configure external pipeline validation:
-
-1. Set the `EXTERNAL_VALIDATION_SERVICE_URL` environment variable to the external
-   service URL.
-1. Enable the `ci_external_validation_service` feature flag.
+To configure external pipeline validation, add the
+[`EXTERNAL_VALIDATION_SERVICE_URL` environment variable](environment_variables.md)
+and set it to the external service URL.
 
 By default, requests to the external service time out after five seconds. To override
 the default, set the `EXTERNAL_VALIDATION_SERVICE_TIMEOUT` environment variable to the
@@ -131,3 +129,6 @@ required number of seconds.
   }
 }
 ```
+
+The `namespace` field is only available in [GitLab Premium](https://about.gitlab.com/pricing/)
+and higher.

doc/development/cicd/index.md

@@ -182,3 +182,17 @@ Watch a walkthrough of this feature in details in the video below.
 <figure class="video-container">
   <iframe src="https://www.youtube.com/embed/NmdWRGT8kZg" frameborder="0" allowfullscreen="true"> </iframe>
 </figure>
+
+## External pipeline validation service
+
+The [external CI/CD pipeline validation service](../../administration/external_pipeline_validation.md)
+is available for use on self-managed GitLab instances, but is not in use on GitLab.com.
+It is configured with [environment variables](../../administration/environment_variables.md)
+on the instance.
+
+To enable the feature on GitLab.com, enable the `ci_external_validation_service`
+[feature flag](../feature_flags/index.md). The valid "Not accepted" response code
+for GitLab.com is `406` only.
+
+For more details, see the linked issues and MRs in the
+[feature flag rollout issue](https://gitlab.com/gitlab-org/gitlab/-/issues/325982).