Help us learn about your current experience with the documentation. Take the survey.

贡献 CI/CD Schema

pipeline editor 使用 CI/CD schema 来增强我们 CI/CD 配置文件的编写体验。借助 CI/CD schema，编辑器可以：

在编辑器中编写 CI/CD 配置文件时验证其内容。
提供自动完成功能并建议可用的关键字。
通过注释提供关键字的定义。

随着配置我们 CI/CD 配置文件的规则和关键字的变化，我们的 CI/CD schema 也应该相应更新。

JSON Schemas

CI/CD schema 遵循 JSON Schema Draft-07 规范。尽管 CI/CD 配置文件是用 YAML 编写的，但在通过 CI/CD schema 验证之前，它会通过 monaco-yaml 转换为 JSON。

如果您是 JSON schema 的新手，可以考虑查看本指南，了解如何使用 JSON schema 的逐步介绍。

更新关键字

CI/CD schema 位于 app/assets/javascripts/editor/schema/ci.json。它包含用于编写 CI/CD 配置文件的所有关键字。有关所有可用关键字的完整列表，请查看 CI/CD YAML 语法参考。

所有关键字都在 definitions 下定义。我们使用这些定义作为引用来在整个 schema 中共享通用的数据结构。

例如，这定义了 retry 关键字：

{
  "definitions": {
    "retry": {
      "description": "如果作业失败则重试。可以是简单的整数或对象定义。",
      "oneOf": [
        {
          "$ref": "#/definitions/retry_max"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "max": {
              "$ref": "#/definitions/retry_max"
            },
            "when": {
              "description": "触发作业重试的单个或错误类型数组。",
              "oneOf": [
                {
                  "$ref": "#/definitions/retry_errors"
                },
                {
                  "type": "array",
                  "items": {
                    "$ref": "#/definitions/retry_errors"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

通过这个定义，retry 关键字既是 job_template 定义的一个属性，也是 default 全局关键字。配置流水线行为的全局关键字（如 workflow 和 stages）在顶层的 properties 键下定义。

{
  "properties": {
    "default": {
      "type": "object",
      "properties": {
        "retry": {
          "$ref": "#/definitions/retry"
        },
      }
    }
  },
  "definitions": {
    "job_template": {
      "properties": {
        "retry": {
          "$ref": "#/definitions/retry"
        }
      },
    }
  }
}

更新 schema 的指南

尽可能保持定义的原子性，以便灵活地引用关键字。例如，workflow:rules 只使用了 rules 定义中的部分属性。rules 属性有自己的定义，因此我们可以单独引用它们。
添加新关键字时，考虑添加一个带有文档中关键字定义链接的 description。当用户将鼠标悬停在关键字上时，此信息会显示在注释中。
对于每个属性，考虑是否需要 minimum、maximum 或 default 值。某些值可能是必需的，而在其他情况下我们可以设置为空。在空的情况下，我们可以向定义中添加以下内容：

{
  "keyword": {
    "oneOf": [
      {
        "type": "null"
      },
      ...
    ]
  }
}

测试 schema

验证更改

转到 CI/CD > Editor。
在编辑器中编写您的 CI/CD 配置，并验证 schema 是否正确验证了它。

编写规范

所有的 CI/CD schema 规范都在 spec/frontend/editor/schema/ci。传统测试使用 JSON，但我们建议用 YAML 编写所有新测试。您可以像添加新的 .gitlab-ci.yml 配置文件一样编写它们。

测试分为 positive 测试和 negative 测试。positive 测试是按预期使用 schema 关键字的 CI/CD 配置代码片段。相反， negative 测试展示了 schema 关键字错误使用的示例。这些测试确保 schema 按预期验证不同的输入示例。

ci_schema_spec.js 负责针对 schema 运行所有测试。

有关如何设置测试的详细说明，可以在这个 merge request 中找到。

更新 schema 规范

如果指定的关键字没有 YAML 测试，请在 yaml_tests/positive_tests 和 yaml_tests/negative_tests 中创建新文件。否则，您可以更新现有测试：

编写 positive 和 negative 测试来验证不同类型的输入。

如果您创建了新文件，请在 ci_schema_spec.js 中导入它们，并将每个文件添加到其对应的对象条目中。例如：

import CacheYaml from './yaml_tests/positive_tests/cache.yml';
import CacheNegativeYaml from './yaml_tests/negative_tests/cache.yml';

// 导入您的新测试文件
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, // 在此处添加 positive 测试
    }),
  )('schema validates %s', (_, input) => {
    expect(input).toValidateJsonSchema(schema);
  });
});

describe('negative tests', () => {
  it.each(
    Object.entries({
      CacheNegativeYaml,
      NewKeywordTestYaml, // 在此处添加 negative 测试
    }),
  )('schema validates %s', (_, input) => {
    expect(input).not.toValidateJsonSchema(schema);
  });
});

运行命令 yarn jest spec/frontend/editor/schema/ci/ci_schema_spec.js 并验证所有测试都成功通过。

如果规范涵盖了对现有关键字的更改并且影响了传统的 JSON 测试，也请更新它们。