GitLab CI "jobs:job:rules config should be an array" - rules Invalid

By Daniel Zoghalchali·Latchkey

Each entry under rules: must be a hash (a mapping with keys like if, changes, exists, when). When an entry is a bare string or the nesting is off by one level, GitLab rejects the whole job.

What this error means

The Pipeline Editor or CI lint reports that the job rules config is invalid, naming the offending job. The rest of the file parses, but the named job will not run.

This GitLab CI configuration is invalid:
jobs:test:rules config should be an array of hashes

Common causes

A rule is a scalar instead of a hash

Writing rules: - $CI_COMMIT_BRANCH makes the entry a string. Each list item must be a mapping, e.g. - if: '${CI_COMMIT_BRANCH}'.

Keys nested one level too deep or too shallow

Putting if/when directly under rules: (not under a list item), or indenting the list under another key, breaks the expected array-of-hashes shape.

Empty or null rule entry

A trailing - with nothing after it produces a null list item, which is not a valid rule hash.

How to fix it

Make every rule a hash with explicit keys

Each - under rules: introduces a mapping. Use if, changes, or exists, optionally with when and allow_failure.

test:
  script: make test
  rules:
    - if: '${CI_PIPELINE_SOURCE} == "merge_request_event"'
    - if: '${CI_COMMIT_BRANCH} == "main"'
      when: on_success

Validate the shape before pushing

1. Open CI/CD then Editor and use the Validate tab to lint the file.
2. Confirm each list item under rules is indented as a mapping, not a scalar.
3. Remove any dangling - that creates a null entry.

How to prevent it

• Treat each rule as a mapping; never put a bare variable as a list item.
• Lint .gitlab-ci.yml in the Pipeline Editor before merging.
• Keep if expressions quoted so YAML does not mis-parse them.

Frequently asked questions

Related guides

References

• GitHub Actions documentation