debian-mirror-gitlab/doc/development/cicd/schema.md

stage	group	info	type
Verify	Pipeline Authoring	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	index, howto

Contribute to the CI Schema (FREE)

The pipeline editor 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 feature flag for self-managed instances, and is enabled for GitLab.com.

JSON Schemas

The CI schema follows the JSON Schema Draft-07 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 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. It contains all the keywords available for authoring CI configuration files. Check the keyword reference for a comprehensive list of all available keywords.

All keywords are defined under definitions. We use these definitions as references to share common data structures across the schema.

For example, this defines the retry keyword:

{
  "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.

{
  "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:

{
  "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.
2. Go to CI/CD > Editor.
3. Write your CI/CD configuration in the editor and verify that the schema validates it correctly.