Use this API to validate a GitLab CI/CD configuration.

These endpoints take JSON-encoded YAML content. To preserve the formatting of your CI/CD configuration, it can help to escape and encode the YAML with a third-party tool such as jq before you make the request.

Validate existing CI/CD configuration

GET /api/v4/projects/{id}/ci/lint

Validates the .gitlab-ci.yml configuration for a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
sha
Query		StringCommit SHA, branch, or tag that the CI/CD configuration content is taken from. Defaults to the head of the project’s default branch. Deprecated. Use content_ref instead. Mutually exclusive with content_ref
content_ref
Query		StringCommit SHA, branch, or tag that the CI/CD configuration content is taken from. Defaults to the head of the project’s default branch. Mutually exclusive with sha
dry_run
Query		BooleanIf true, runs a pipeline creation simulation. If false, runs only a static check
Default: false
include_jobs
Query		BooleanIf true, includes the list of jobs that would exist in a static check or pipeline simulation
ref
Query		StringIf dry_run is true, sets the branch or tag to use to validate the CI/CD YAML configuration. Defaults to the project’s default branch. Deprecated. Use dry_run_ref instead. Mutually exclusive with dry_run_ref
dry_run_ref
Query		StringIf dry_run is true, sets the branch or tag to use to validate the CI/CD YAML configuration. Defaults to the project’s default branch. Mutually exclusive with ref

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiLintResult
400Bad Request—
404Not found—

Validate a CI/CD configuration

POST /api/v4/projects/{id}/ci/lint

Validates a provided CI/CD configuration in the context of a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
content
Required		StringCI/CD configuration content
dry_runBooleanIf true, runs a pipeline creation simulation. If false, runs only a static check
Default: false
include_jobsBooleanIf true, includes the list of jobs that would exist in a static check or pipeline simulation
refStringIf dry_run is true, sets the branch or tag to use to validate the CI/CD YAML configuration. Defaults to the project’s default branch

Responses

CodeDescriptionSchema
200OKAPIEntitiesCiLintResult
400Bad Request—
404Not Found—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCiLintResult

PropertyTypeDescription
errorsArray of stringsExample: ["variables config should be a hash of key value pairs"]
includesArray of APIEntitiesCiLintResultIncludeExample: [{"blob":"https://gitlab.com/root/example-project/-/blob/..."}]
jobsArray of objectsExample: [{"name":"test","script":["ls"]}]
merged_yamlStringExample: ---\n:another_test:\n :stage: test\n :script: echo 2\n:test:\n :stage: test\n :script: echo 1\n
validBoolean—
warningsArray of stringsExample: ["jobs:job may allow multiple pipelines ..."]

APIEntitiesCiLintResultInclude

PropertyTypeDescription
blobStringExample: https://gitlab.com/gitlab-org/gitlab/-/blob/e52d6d0246d7375291850e61f0abc101fbda9dc2/.gitlab/ci/build-images.gitlab-ci.yml
context_projectStringExample: gitlab-org/gitlab
context_shaStringExample: e52d6d0246d7375291850e61f0abc101fbda9dc2
extraObjectExample: {"job_name":"test","project":"gitlab-org/gitlab","ref":"master"}
locationStringExample: .gitlab/ci/build-images.gitlab-ci.yml
rawStringExample: https://gitlab.com/gitlab-org/gitlab/-/raw/e52d6d0246d7375291850e61f0abc101fbda9dc2/.gitlab/ci/build-images.gitlab-ci.yml
typeStringExample: local
←
REST API / CI jobs
REST API / CI resource groups
→