diff options
Diffstat (limited to 'doc/development/cicd/schema.md')
-rw-r--r-- | doc/development/cicd/schema.md | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/doc/development/cicd/schema.md b/doc/development/cicd/schema.md new file mode 100644 index 00000000000..b63d951b881 --- /dev/null +++ b/doc/development/cicd/schema.md @@ -0,0 +1,146 @@ +--- +stage: Verify +group: Pipeline Authoring +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 +type: index, howto +--- + +# Contribute to the CI Schema **(FREE)** + +The [pipeline editor](../../ci/pipeline_editor/index.md) uses a CI schema to enhance +the authoring experience of our CI configuration files. With the CI schema, the editor can: + +- Validate the content of the CI configuration file as it is being written in the editor. +- Provide autocomplete functionality and suggest available keywords. +- Provide definitions of keywords through annotations. + +As the rules and keywords for configuring our CI configuration files change, so too +should our CI schema. + +This feature is behind the [`schema_linting`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/feature_flags/development/schema_linting.yml) +feature flag for self-managed instances, and is enabled for GitLab.com. + +## JSON Schemas + +The CI schema follows the [JSON Schema Draft-07](https://json-schema.org/draft-07/json-schema-release-notes.html) +specification. Although the CI configuration file is written in YAML, it is converted +into JSON by using `monaco-yaml` before it is validated by the CI schema. + +If you're new to JSON schemas, consider checking out +[this guide](https://json-schema.org/learn/getting-started-step-by-step) for +a step-by-step introduction on how to work with JSON schemas. + +## Update Keywords + +The CI schema is at [`app/assets/javascripts/editor/schema/ci.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/assets/javascripts/editor/schema/ci.json). +It contains all the keywords available for authoring CI configuration files. +Check the [keyword reference](../../ci/yaml/index.md) for a comprehensive list of +all available keywords. + +All keywords are defined under `definitions`. We use these definitions as +[references](https://json-schema.org/learn/getting-started-step-by-step#references) +to share common data structures across the schema. + +For example, this defines the `retry` keyword: + +```json +{ + "definitions": { + "retry": { + "description": "Retry a job if it fails. Can be a simple integer or object definition.", + "oneOf": [ + { + "$ref": "#/definitions/retry_max" + }, + { + "type": "object", + "additionalProperties": false, + "properties": { + "max": { + "$ref": "#/definitions/retry_max" + }, + "when": { + "description": "Either a single or array of error types to trigger job retry.", + "oneOf": [ + { + "$ref": "#/definitions/retry_errors" + }, + { + "type": "array", + "items": { + "$ref": "#/definitions/retry_errors" + } + } + ] + } + } + } + ] + } + } +} +``` + +With this definition, the `retry` keyword is both a property of +the `job_template` definition and the `default` global keyword. Global keywords +that configure pipeline behavior (such as `workflow` and `stages`) are defined +under the topmost **properties** key. + +```json +{ + "properties": { + "default": { + "type": "object", + "properties": { + "retry": { + "$ref": "#/definitions/retry" + }, + } + } + }, + "definitions": { + "job_template": { + "properties": { + "retry": { + "$ref": "#/definitions/retry" + } + }, + } + } +} +``` + +## Guidelines for updating the schema + +- Keep definitions atomic when possible, to be flexible with + referencing keywords. For example, `workflow:rules` uses only a subset of + properties in the `rules` definition. The `rules` properties have their + own definitions, so we can reference them individually. +- When adding new keywords, consider adding a `description` with a link to the + keyword definition in the documentation. This information shows up in the annotations + when the user hovers over the keyword. +- For each property, consider if a `minimum`, `maximum`, or + `default` values are required. Some values might be required, and in others we can set + blank. In the blank case, we can add the following to the definition: + +```json +{ + "keyword": { + "oneOf": [ + { + "type": "null" + }, + ... + ] + } +} +``` + +## Test the schema + +For now, the CI schema can only be tested manually. To verify the behavior is correct: + +1. Enable the `schema_linting` feature flag. +1. Go to **CI/CD** > **Editor**. +1. Write your CI/CD configuration in the editor and verify that the schema validates + it correctly. |