`yamlschema`

Офлайн-проверка .gitlab-ci.yml и docker-compose.yml по официальным JSON-схемам — утилита песочницы IzzyLab

yamlschema — небольшая утилита, встроенная в песочницу IzzyLab (это не стандартный пакет Linux). Она читает YAML-файл и проверяет его по официальной JSON-схеме: GitLab CI (gitlab-ci) или Compose Specification (compose). Так конфиг оценивается почти как настоящим инструментом — опечатка в ключе или задача без script будут ошибкой, а не «валидным YAML». Работает без интернета: схемы лежат в /opt/schemas.

На реальных проектах ту же роль играют встроенный CI Lint в GitLab и docker compose config.

Синтаксис

yamlschema gitlab-ci ФАЙЛ
yamlschema compose   ФАЙЛ

Ровно два аргумента. Других опций нет. Чтобы проверить данные из конвейера, передай /dev/stdin как файл.

Режимы

Режим	Схема	Что проверяет дополнительно
`gitlab-ci`	`/opt/schemas/gitlab-ci.json` (GitLab 17.8)	у каждой задачи есть `script`, `run`, `trigger` или `extends`; её `stage` объявлен в `stages` (если `stages` нет — допустимы `build`, `test`, `deploy`, `.pre`, `.post`; по умолчанию стадия — `test`)
`compose`	`/opt/schemas/compose-spec.json`	только схема: неизвестные ключи, типы, допустимые значения

В gitlab-ci задачами не считаются служебные ключи (default, include, stages, variables, workflow, image, services, cache, before_script, after_script, spec) и скрытые задачи, начинающиеся с точки (.template).

Вывод и коды выхода

При успехе ничего не печатает. Ошибки идут в stderr, по одной на строку, не больше пяти:

bad-ci.yml: build: Additional properties are not allowed ('scrpt' was unexpected)
bad-ci.yml: deploy/when: 'sometimes' is not one of ['on_success', 'on_failure', 'always', 'never', 'manual', 'delayed']
bad-ci.yml: build: job has no script
bad-ci.yml: build: stage 'biuld' is not declared in stages

Формат: файл: путь/к/полю: сообщение. Путь (root) — ошибка на верхнем уровне. Сообщение обрезается до 200 символов.

Код	Значение
`0`	файл соответствует схеме
`1`	есть ошибки схемы, файл не читается или это не YAML
`2`	неверный вызов: не тот режим или число аргументов (печатает `usage`)

Примеры

cat > .gitlab-ci.yml <<'EOF'
stages: [build, test]
build:
  stage: build
  image: alpine:3.20
  script:
    - echo build
test:
  script: echo test
EOF
yamlschema gitlab-ci .gitlab-ci.yml && echo OK

cat > docker-compose.yml <<'EOF'
services:
  web:
    image: nginx:1.27
    ports: ["8080:80"]
    depends_on: [db]
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: example
EOF
yamlschema compose docker-compose.yml && echo OK

# проверить YAML, который выдала другая команда
yq '.' docker-compose.yml | yamlschema compose /dev/stdin

# в скрипте — только код выхода
if yamlschema gitlab-ci .gitlab-ci.yml 2>/dev/null; then echo valid; else echo invalid; fi

Частые ошибки и что они значат

Сообщение	Причина
`Additional properties are not allowed ('scrpt' was unexpected)`	опечатка или неизвестный ключ в задаче GitLab
`Unevaluated properties are not allowed ('port' was unexpected)`	то же для compose (там правильно `ports`)
`job has no script`	у задачи нет `script` (или ключ написан с ошибкой)
`stage 'x' is not declared in stages`	стадия не перечислена в `stages`
`'sometimes' is not one of [...]`	недопустимое значение — в скобках список разрешённых
`10 is not of type 'string'`	не тот тип: например, `interval: 10` вместо `"10s"`
`[{'echo a': 'b'}] is not valid under any of the given schemas`	строка с `:` в `script` стала словарём — нужны кавычки
`(root): None is not of type 'object'`	файл пустой

Подводные камни

Видно максимум пять ошибок. После исправления запусти снова: могут появиться следующие.
Двоеточие с пробелом в команде. - echo a: b в script YAML читает как словарь {'echo a': 'b'}. Бери такие строки в кавычки: - 'echo a: b'.
В compose одна ошибка тянет за собой вторую. Неверное значение внутри healthcheck даёт и 'healthcheck' was unexpected на уровне сервиса, и настоящую причину глубже (services/w/healthcheck/interval: 10 is not of type 'string'). Ищи самую длинную строку пути.
Задача без stage попадает в test. Если в stages перечислены свои стадии без test, получишь stage 'test' is not declared in stages — укажи stage явно.
Проверяется структура, а не смысл. Пройдут проверку: needs на несуществующую задачу, extends на несуществующий шаблон, depends_on на несуществующий сервис, include на отсутствующий файл (включаемые файлы не читаются).
Файл должен быть передан явно. Без аргументов или с третьим аргументом — usage и код 2, а не проверка текущего каталога.
Утилита есть только в песочнице. Вне IzzyLab аналоги — CI Lint в интерфейсе GitLab и docker compose config -q.

См. также

gitlab-ci · docker-compose · yq · kubeconform · actionlint