diff options
Diffstat (limited to 'doc/development/cicd/schema.md')
| -rw-r--r-- | doc/development/cicd/schema.md | 87 |
1 files changed, 75 insertions, 12 deletions
diff --git a/doc/development/cicd/schema.md b/doc/development/cicd/schema.md index b63d951b881..0e456a25a7a 100644 --- a/doc/development/cicd/schema.md +++ b/doc/development/cicd/schema.md @@ -5,26 +5,26 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, howto --- -# Contribute to the CI Schema **(FREE)** +# Contribute to the CI/CD 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: +The [pipeline editor](../../ci/pipeline_editor/index.md) uses a CI/CD schema to enhance +the authoring experience of our CI/CD configuration files. With the CI/CD schema, the editor can: -- Validate the content of the CI configuration file as it is being written in the editor. +- Validate the content of the CI/CD 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. +As the rules and keywords for configuring our CI/CD configuration files change, so too +should our CI/CD 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. +The CI/CD schema follows the [JSON Schema Draft-07](https://json-schema.org/draft-07/json-schema-release-notes.html) +specification. Although the CI/CD configuration file is written in YAML, it is converted +into JSON by using `monaco-yaml` before it is validated by the CI/CD schema. If you're new to JSON schemas, consider checking out [this guide](https://json-schema.org/learn/getting-started-step-by-step) for @@ -32,8 +32,8 @@ 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. +The CI/CD 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/CD configuration files. Check the [keyword reference](../../ci/yaml/index.md) for a comprehensive list of all available keywords. @@ -138,9 +138,72 @@ under the topmost **properties** key. ## Test the schema -For now, the CI schema can only be tested manually. To verify the behavior is correct: +### Verify changes 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. + +### Write specs + +All of the CI/CD schema specs are in [`spec/frontend/editor/schema/ci`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/spec/frontend/editor/schema/ci). +Legacy tests are in JSON, but we recommend writing all new tests in YAML. +You can write them as if you're adding a new `.gitlab-ci.yml` configuration file. + +Tests are separated into **positive** tests and **negative** tests. Positive tests +are snippets of CI/CD configuration code that use the schema keywords as intended. +Conversely, negative tests give examples of the schema keywords being used incorrectly. +These tests ensure that the schema validates different examples of input as expected. + +`ci_schema_spec.js` is responsible for running all of the tests against the schema. + +A detailed explanation of how the tests are set up can be found in this +[merge request](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/83047). + +#### Update schema specs + +If a YAML test does not exist for the specified keyword, create new files in +`yaml_tests/positive_tests` and `yaml_tests/negative_tests`. Otherwise, you can update +the existing tests: + +1. Write both positive and negative tests to validate different kinds of input. +1. If you created new files, import them in `ci_schema_spec.js` and add each file to their + corresponding object entries. For example: + + ```javascript + import CacheYaml from './yaml_tests/positive_tests/cache.yml'; + import CacheNegativeYaml from './yaml_tests/negative_tests/cache.yml'; + + // import your new test files + import NewKeywordTestYaml from './yaml_tests/positive_tests/cache.yml'; + import NewKeywordTestNegativeYaml from './yaml_tests/negative_tests/cache.yml'; + + describe('positive tests', () => { + it.each( + Object.entries({ + CacheYaml, + NewKeywordTestYaml, // add positive test here + }), + )('schema validates %s', (_, input) => { + expect(input).toValidateJsonSchema(schema); + }); + }); + + describe('negative tests', () => { + it.each( + Object.entries({ + CacheNegativeYaml, + NewKeywordTestYaml, // add negative test here + }), + )('schema validates %s', (_, input) => { + expect(input).not.toValidateJsonSchema(schema); + }); + }); + ``` + +1. Run the command `yarn jest spec/frontend/editor/schema/ci/ci_schema_spec.js` + and verify that all the tests successfully pass. + +If the spec covers a change to an existing keyword and it affects the legacy JSON +tests, update them as well. |