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 integerThe ID or URL-encoded path of the project
sha
Query		StringDeprecated: Use content_ref instead. Mutually exclusive with content_ref
content_ref
Query		StringThe CI/CD configuration content is taken from this commit SHA, branch or tag. Defaults to the HEAD of the project’s default branch. Mutually exclusive with sha
dry_run
Query		BooleanRun pipeline creation simulation, or only do static check. This is false by default
Default: false
include_jobs
Query		BooleanIf the list of jobs that would exist in a static check or pipeline simulation should be included in the response. This is false by default
ref
Query		StringDeprecated: Use dry_run_ref instead. Mutually exclusive with dry_run_ref
dry_run_ref
Query		StringBranch or tag used as context when executing a dry run. Defaults to the default branch of the project. Only used when dry_run is true. 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 integerThe ID or URL-encoded path of the project

Request body (application/json)

PropertyTypeDescription
content
Required		StringContent of .gitlab-ci.yml
dry_runBooleanRun pipeline creation simulation, or only do static check. This is false by default
Default: false
include_jobsBooleanIf the list of jobs that would exist in a static check or pipeline simulation should be included in the response. This is false by default
refStringWhen dry_run is true, sets the branch or tag to use. Defaults to the project’s default branch when not set

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
→