GitLab "contains unknown keys" in .gitlab-ci.yml

By Kaveh Alemi·Latchkey

GitLab found a key it does not recognize at that position. Usually a typo, a global keyword placed inside a job, or a job keyword placed at the top level.

What this error means

Validation fails naming the unexpected key - "config contains unknown keys: scripts" or "jobs:build config contains unknown keys: imag". The rest of the file is fine; one key name or its placement is wrong.

This GitLab CI configuration is invalid: jobs:build config contains unknown keys: imag

Common causes

Misspelled keyword

imag for image, scripts for script, artifact for artifacts, tag for tags. GitLab’s keyword list is fixed, so any deviation is "unknown".

Keyword in the wrong scope

Global-only keywords (stages, workflow, default) inside a job, or job-only keywords at the top level, are unknown for that context.

How to fix it

Correct the keyword spelling

Match the exact reserved keyword. The error names the bad key verbatim.

build:
  image: node:20      # not "imag"
  script:             # not "scripts"
    - npm ci
  tags:               # not "tag"
    - docker

Move keywords to the right scope

1. Put stages, workflow, include, and default at the top level only.
2. Put script, stage, rules, artifacts, tags inside jobs.
3. Re-validate in the Pipeline Editor after moving.

How to prevent it

• Enable a GitLab CI JSON schema in your editor for keyword autocompletion.
• Reference the keyword list in the GitLab CI/CD YAML docs when unsure.
• Lint in CI before merge so typos never reach the default branch.

Frequently asked questions

Related guides

References

• GitHub Actions documentation