2020-05-29 18:08:26 +00:00
---
stage: Verify
2021-05-26 15:10:57 +00:00
group: Pipeline Execution
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-05-29 18:08:26 +00:00
type: reference, howto
---
2021-06-22 00:07:53 +00:00
# External pipeline validation **(FREE SELF)**
2019-12-14 09:07:51 +00:00
2021-04-05 18:09:15 +00:00
You can use an external service to validate a pipeline before it's created.
2019-12-14 09:07:51 +00:00
2020-12-04 21:09:29 +00:00
WARNING:
2019-12-14 09:07:51 +00:00
This is an experimental feature and subject to change without notice.
2020-11-18 18:09:08 +00:00
GitLab sends a POST request to the external service URL with the pipeline
2021-05-11 18:10:36 +00:00
data as payload. The response code from the external service determines if GitLab
should accept or reject the pipeline. If the response is:
2019-12-14 09:07:51 +00:00
2021-05-11 18:10:36 +00:00
- `200` , the pipeline is accepted.
2021-05-21 09:10:16 +00:00
- `406` , the pipeline is rejected.
2021-05-11 18:10:36 +00:00
- Other codes, the pipeline is accepted and logged.
2019-12-14 09:07:51 +00:00
2021-05-11 18:10:36 +00:00
If there's an error or the request times out, the pipeline is accepted.
2021-05-05 21:09:59 +00:00
2021-05-11 18:10:36 +00:00
Pipelines rejected by the external validation service aren't created, and don't
appear in pipeline lists in the GitLab UI or API. If you create a pipeline in the
UI that is rejected, `Pipeline cannot be run. External validation failed` is displayed.
2021-05-05 21:09:59 +00:00
2021-05-11 18:10:36 +00:00
## Configure external pipeline validation
2019-12-14 09:07:51 +00:00
2021-04-05 18:09:15 +00:00
To configure external pipeline validation, add the
[`EXTERNAL_VALIDATION_SERVICE_URL` environment variable ](environment_variables.md )
and set it to the external service URL.
2021-03-30 09:10:51 +00:00
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
required number of seconds.
2019-12-14 09:07:51 +00:00
2021-05-11 18:10:36 +00:00
## Payload schema
2019-12-14 09:07:51 +00:00
```json
{
"type": "object",
"required" : [
"project",
"user",
"pipeline",
2021-03-23 18:09:05 +00:00
"builds",
"namespace"
2019-12-14 09:07:51 +00:00
],
"properties" : {
"project": {
"type": "object",
"required": [
"id",
2021-03-23 18:09:05 +00:00
"path",
"created_at"
2019-12-14 09:07:51 +00:00
],
"properties": {
"id": { "type": "integer" },
2021-03-23 18:09:05 +00:00
"path": { "type": "string" },
"created_at": { "type": ["string", "null"], "format": "date-time" }
2019-12-14 09:07:51 +00:00
}
},
"user": {
"type": "object",
"required": [
"id",
"username",
2021-03-23 18:09:05 +00:00
"email",
"created_at"
2019-12-14 09:07:51 +00:00
],
"properties": {
"id": { "type": "integer" },
"username": { "type": "string" },
2021-03-23 18:09:05 +00:00
"email": { "type": "string" },
2021-05-26 12:10:41 +00:00
"created_at": { "type": ["string", "null"], "format": "date-time" },
"current_sign_in_ip": { "type": ["string", "null"] },
"last_sign_in_ip": { "type": ["string", "null"] }
2019-12-14 09:07:51 +00:00
}
},
"pipeline": {
"type": "object",
"required": [
"sha",
"ref",
"type"
],
"properties": {
"sha": { "type": "string" },
"ref": { "type": "string" },
"type": { "type": "string" }
}
},
"builds": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"stage",
"image",
"services",
"script"
],
"properties": {
"name": { "type": "string" },
"stage": { "type": "string" },
"image": { "type": ["string", "null"] },
"services": {
"type": ["array", "null"],
"items": { "type": "string" }
},
"script": {
"type": "array",
"items": { "type": "string" }
}
}
}
2021-03-23 18:09:05 +00:00
},
"namespace": {
"type": "object",
"required": [
"plan",
"trial"
],
"properties": {
"plan": { "type": "string" },
"trial": { "type": "boolean" }
}
2021-06-09 18:11:25 +00:00
},
"provisioning_group": {
"type": "object",
"required": [
"plan",
"trial"
],
"properties": {
"plan": { "type": "string" },
"trial": { "type": "boolean" }
}
2019-12-14 09:07:51 +00:00
}
2021-03-23 18:09:05 +00:00
}
2019-12-14 09:07:51 +00:00
}
```
2021-04-05 18:09:15 +00:00
The `namespace` field is only available in [GitLab Premium ](https://about.gitlab.com/pricing/ )
and higher.