• Validate the CI YAML configuration
  • YAML expansion
• Validate a CI YAML configuration with a namespace
• Validate a project’s CI configuration
• Use jq to create and process YAML & JSON payloads
  • Escape YAML for JSON encoding
  • Parse a CI Lint response

CI Lint API

Validate the CI YAML configuration

Checks if CI/CD YAML configuration is valid. This endpoint validates basic CI/CD configuration syntax. It doesn’t have any namespace-specific context.

Access to this endpoint does not require authentication when the instance allows new sign ups and:

• Does not have an allowlist or denylist.
• Does not require administrator approval for new sign ups.
• Does not have additional sign up restrictions.

Otherwise, authentication is required.

POST /ci/lint

curl --header "Content-Type: application/json" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/ci/lint" --data '{"content": "{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}'

Be sure to paste the exact contents of your GitLab CI/CD YAML configuration because YAML is very sensitive about indentation and spacing.

Example responses:

• Valid content:

  {
    "status": "valid",
    "errors": [],
    "warnings": []
  }
  

• Valid content with warnings:

  {
    "status": "valid",
    "errors": [],
    "warnings": ["jobs:job may allow multiple pipelines to run for a single action due to
    `rules:when` clause with no `workflow:rules` - read more:
    https://docs.gitlab.com/ee/ci/troubleshooting.html#pipeline-warnings"]
  }
  

• Invalid content:

  {
    "status": "invalid",
    "errors": [
      "variables config should be a hash of key value pairs"
    ],
    "warnings": []
  }
  

• Without the content attribute:

  {
    "error": "content is missing"
  }
  

YAML expansion

include:
  remote: 'https://example.com/remote.yaml'

test:
  stage: test
  script:
    - echo 1

another_test:
  stage: test
  script:
    - echo 2

{
  "status": "valid",
  "errors": [],
  "merged_yaml": "---\n:another_test:\n  :stage: test\n  :script: echo 2\n:test:\n  :stage: test\n  :script: echo 1\n",
  "jobs": [
    {
      "name":"test",
      "stage":"test",
      "before_script":[],
      "script":["echo 1"],
      "after_script":[], 
      "tag_list":[],
      "environment":null,
      "when":"on_success",
      "allow_failure":false,
      "only":{
        "refs":["branches","tags"]
      },
      "except":null
    },
    {
      "name":"another_test",
      "stage":"test",
      "before_script":[],
      "script":["echo 2"],
      "after_script":[],
      "tag_list":[],
      "environment":null,
      "when":"on_success",
      "allow_failure":false,
      "only":{
        "refs":["branches","tags"]
      },
      "except":null
    }
  ]
}

POST /projects/:id/ci/lint

curl --header "Content-Type: application/json" "https://gitlab.example.com/api/v4/projects/:id/ci/lint" --data '{"content": "{ \"image\": \"ruby:2.6\", \"services\": [\"postgres\"], \"before_script\": [\"bundle install\", \"bundle exec rake db:create\"], \"variables\": {\"DB_NAME\": \"postgres\"}, \"types\": [\"test\", \"deploy\", \"notify\"], \"rspec\": { \"script\": \"rake spec\", \"tags\": [\"ruby\", \"postgres\"], \"only\": [\"branches\"]}}"}'

GET /projects/:id/ci/lint

curl "https://gitlab.example.com/api/v4/projects/:id/ci/lint"

{
  "valid": true,
  "merged_yaml": "---\n:test_job:\n  :script: echo 1\n",
  "errors": [],
  "warnings": []
}

{
  "valid": false,
  "merged_yaml": "---\n:test_job:\n  :script: echo 1\n",
  "errors": [
    "jobs config should contain at least one visible job"
  ],
  "warnings": []
}

.api_test:
  rules:
    - if: '$CI_PIPELINE_SOURCE=="merge_request_event"'
      changes:
        - src/api/*
deploy:
  extends:
    - .api_test
  rules:
    - when: manual
      allow_failure: true
  script:
    - echo "hello world"

jq --raw-input --slurp < example-gitlab-ci.yml

jq --null-input --arg yaml "$(<example-gitlab-ci.yml)" '.content=$yaml' \
| curl "https://gitlab.com/api/v4/ci/lint?include_merged_yaml=true" \
--header 'Content-Type: application/json' \
--data @-

jq --raw-output '.merged_yaml | fromjson' <your_input_here>

{"status":"valid","errors":[],"merged_yaml":"---\n:.api_test:\n  :rules:\n  - :if: $CI_PIPELINE_SOURCE==\"merge_request_event\"\n    :changes:\n    - src/api/*\n:deploy:\n  :rules:\n  - :when: manual\n    :allow_failure: true\n  :extends:\n  - \".api_test\"\n  :script:\n  - echo \"hello world\"\n"}

:.api_test:
  :rules:
  - :if: $CI_PIPELINE_SOURCE=="merge_request_event"
    :changes:
    - src/api/*
:deploy:
  :rules:
  - :when: manual
    :allow_failure: true
  :extends:
  - ".api_test"
  :script:
  - echo "hello world"

jq --null-input --arg yaml "$(<example-gitlab-ci.yml)" '.content=$yaml' \
| curl "https://gitlab.com/api/v4/ci/lint?include_merged_yaml=true" \
--header 'Content-Type: application/json' --data @- \
| jq --raw-output '.merged_yaml | fromjson'