gitlab-ci (SchemaStore) JSON Schema

Type	object
File match	`/.gitlab-ci.yml` `/.gitlab-ci.yaml` `*/.gitlab-ci.yml` `*/.gitlab-ci.yaml`
Schema URL	https://catalog.lintel.tools/schemas/schemastore/gitlab-ci/latest.json
Source	https://gitlab.com/gitlab-org/gitlab-foss/-/raw/master/app/assets/javascripts/editor/schema/ci.json

Validate with Lintel

npx @lintel/lintel check

Type: object

GitLab has a built-in solution for doing CI called GitLab CI. It is configured by supplying a file called .gitlab-ci.yml, which will list all the jobs that are going to run for the project. A full list of all options can be found here. Learn More.

Properties

$schema string

format=uri

spec object

Specification for pipeline configuration. Must be declared at the top of a configuration file, in a header section separated from the rest of the configuration with ---. Learn More.

1 nested properties

inputs object

Define input parameters for reusable CI/CD configuration. Config inputs can optionally specify defaults. Learn More.

image string | object

Specifies the docker image to use for the job or globally for all jobs. Job configuration takes precedence over global setting. Requires a certain kind of GitLab runner executor. Learn More.

services string | object[]

Similar to image property, but will link the specified services to the image container. Learn More.

before_script optional_script

Defines scripts that should run before the job. Can be set globally or per job. Learn More.

after_script optional_script

Defines scripts that should run after the job. Can be set globally or per job. Learn More.

variables object

Defines default variables for all jobs. Job level property overrides global variables. Learn More.

cache cache_item | cache_item[]

Use cache to specify a list of files and directories to cache between jobs. You can only use paths that are in the local working copy. Learn More

!reference string[]

default object

14 nested properties

after_script optional_script

Defines scripts that should run after the job. Can be set globally or per job. Learn More.

artifacts object | null

Used to specify a list of files and directories that should be attached to the job if it succeeds. Artifacts are sent to GitLab where they can be downloaded. Learn More.

9 nested properties

paths string[]

A list of paths to files/folders that should be included in the artifact. Learn More.

minItems=1

exclude string[]

A list of paths to files/folders that should be excluded in the artifact. Learn More.

minItems=1

expose_as string

Can be used to expose job artifacts in the merge request UI. GitLab will add a link <expose_as> to the relevant merge request that points to the artifact. Learn More.

name string

Name for the archive created on job success. Can use variables in the name, e.g. '$CI_JOB_NAME' Learn More.

untracked boolean

Whether to add all untracked files (along with 'artifacts.paths') to the artifact. Learn More.

Default: false

when string

Configure when artifacts are uploaded depended on job status. Learn More.

Default: "on_success"

Values: "on_success" "on_failure" "always"

access string

Configure who can access the artifacts. Learn More.

Default: "all"

Values: "none" "developer" "maintainer" "all"

expire_in string

How long artifacts should be kept. They are saved 30 days by default. Artifacts that have expired are removed periodically via cron job. Supports a wide variety of formats, e.g. '1 week', '3 mins 4 sec', '2 hrs 20 min', '2h20min', '6 mos 1 day', '47 yrs 6 mos and 4d', '3 weeks and 2 days'. Learn More.

Default: "30 days"

reports object

Reports will be uploaded as artifacts, and often displayed in the GitLab UI, such as in merge requests. Learn More.

22 nested properties

accessibility string

Path to JSON file with accessibility report.

annotations string

Path to JSON file with annotations report.

junit string | string[]

Path for file(s) that should be parsed as JUnit XML result

browser_performance string

Path to a single file with browser performance metric report(s).

coverage_report object | null

Used to collect coverage reports from the job.

codequality string | string[]

dotenv string | string[]

lsif string | string[]

sast string | string[]

dependency_scanning string | string[]

container_scanning string | string[]

dast string | string[]

license_management string | string[]

license_scanning string | string[]

requirements string | string[]

secret_detection string | string[]

metrics string | string[]

terraform string | string[]

cyclonedx string | string[]

sarif string | string[]

load_performance string | string[]

repository_xray string | string[]

before_script optional_script

Defines scripts that should run before the job. Can be set globally or per job. Learn More.

hooks object

Specifies lists of commands to execute on the runner at certain stages of job execution. Learn More.

1 nested properties

pre_get_sources_script string | string | string[][]

cache cache_item | cache_item[]

Use cache to specify a list of files and directories to cache between jobs. You can only use paths that are in the local working copy. Learn More

image string | object

Specifies the docker image to use for the job or globally for all jobs. Job configuration takes precedence over global setting. Requires a certain kind of GitLab runner executor. Learn More.

interruptible boolean

Interruptible is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Learn More.

Default: false

id_tokens object

Defines JWTs to be injected as environment variables.

identity string

Sets a workload identity (experimental), allowing automatic authentication with the external system. Learn More.

Values: "google_cloud"

retry retry_max | object

Retry a job if it fails. Can be a simple integer or object definition. Learn More.

services string | object[]

Similar to image property, but will link the specified services to the image container. Learn More.

tags string | string[][]

Used to select runners from the list of available runners. A runner must have all tags listed here to run the job. Learn More.

minItems=1

timeout string

Allows you to configure a timeout for a specific job (e.g. 1 minute, 1h 30m 12s). Learn More.

minLength=1

!reference string[]

stages string | string[][]

Groups jobs into stages. All jobs in one stage must complete before next stage is executed. Defaults to ['build', 'test', 'deploy']. Learn More.

Default:

[
  "build",
  "test",
  "deploy"
]

minItems=1uniqueItems=true

include include_item | include_item[]

Can be IncludeItem or IncludeItem[]. Each IncludeItem will be a string, or an object with properties for the method if including external YAML file. The external content will be fetched, included and evaluated along the .gitlab-ci.yml. Learn More.

pages

All of: job_template object

workflow object

3 nested properties

name string

Defines the pipeline name. Learn More.

minLength=1maxLength=255

auto_cancel object

Define the rules for when pipeline should be automatically cancelled.

2 nested properties

on_job_failure string

Define which jobs to stop after a job fails.

Default: "none"

Values: "none" "all"

on_new_commit string

Configure the behavior of the auto-cancel redundant pipelines feature. Learn More

Values: "conservative" "interruptible" "none"

rules object[]

Definitions

artifacts object | null

Used to specify a list of files and directories that should be attached to the job if it succeeds. Artifacts are sent to GitLab where they can be downloaded. Learn More.

paths string[]

A list of paths to files/folders that should be included in the artifact. Learn More.

minItems=1

exclude string[]

A list of paths to files/folders that should be excluded in the artifact. Learn More.

minItems=1

expose_as string

Can be used to expose job artifacts in the merge request UI. GitLab will add a link <expose_as> to the relevant merge request that points to the artifact. Learn More.

name string

Name for the archive created on job success. Can use variables in the name, e.g. '$CI_JOB_NAME' Learn More.

untracked boolean

Whether to add all untracked files (along with 'artifacts.paths') to the artifact. Learn More.

Default: false

when string

Configure when artifacts are uploaded depended on job status. Learn More.

Default: "on_success"

Values: "on_success" "on_failure" "always"

access string

Configure who can access the artifacts. Learn More.

Default: "all"

Values: "none" "developer" "maintainer" "all"

expire_in string

Default: "30 days"

reports object

Reports will be uploaded as artifacts, and often displayed in the GitLab UI, such as in merge requests. Learn More.

22 nested properties

accessibility string

Path to JSON file with accessibility report.

annotations string

Path to JSON file with annotations report.

junit string | string[]

Path for file(s) that should be parsed as JUnit XML result

browser_performance string

Path to a single file with browser performance metric report(s).

coverage_report object | null

Used to collect coverage reports from the job.

2 nested properties

coverage_format enum

Code coverage format used by the test framework.

Values: "cobertura" "jacoco"

path string

Path to the coverage report file that should be parsed.

minLength=1

codequality string | string[]

dotenv string | string[]

lsif string | string[]

sast string | string[]

dependency_scanning string | string[]

container_scanning string | string[]

dast string | string[]

license_management string | string[]

license_scanning string | string[]

requirements string | string[]

secret_detection string | string[]

metrics string | string[]

terraform string | string[]

cyclonedx string | string[]

sarif string | string[]

load_performance string | string[]

repository_xray string | string[]

string_file_list string | string[]

baseInput object

type string

Input type. Defaults to 'string' when not specified.

Default: "string"

Values: "array" "boolean" "number" "string"

description string

Human-readable explanation of the parameter.

maxLength=1024

options string | number | boolean[]

List of allowed values for this input.

regex string

Regular expression that string values must match.

default

Default value for this input.

configInputs object

Define input parameters for reusable CI/CD configuration. Config inputs can optionally specify defaults. Learn More.

jobInputs object

Define input parameters for a job. Job inputs must always include a default value. Learn More.

!reference string[]

image string | object

Specifies the docker image to use for the job or globally for all jobs. Job configuration takes precedence over global setting. Requires a certain kind of GitLab runner executor. Learn More.

services string | object[]

Similar to image property, but will link the specified services to the image container. Learn More.

id_tokens object

Defines JWTs to be injected as environment variables.

identity string

Sets a workload identity (experimental), allowing automatic authentication with the external system. Learn More.

secrets object

Defines secrets to be injected as environment variables. Learn More.

script string | string | string[][]

steps step[]

optional_script string | string | string[][]

before_script string | string | string[][]

after_script string | string | string[][]

rules array | null

Rules allows for an array of individual rule objects to be evaluated in order, until one matches and dynamically provides attributes to the job. Learn More.

includeRules array | null

You can use rules to conditionally include other configuration files. Learn More.

workflowName string

Defines the pipeline name. Learn More.

workflowAutoCancel object

Define the rules for when pipeline should be automatically cancelled.

on_job_failure string

Define which jobs to stop after a job fails.

Default: "none"

Values: "none" "all"

on_new_commit string

Configure the behavior of the auto-cancel redundant pipelines feature. Learn More

Values: "conservative" "interruptible" "none"

globalVariables object

Defines default variables for all jobs. Job level property overrides global variables. Learn More.

jobVariables object

Defines variables for a job. Learn More.

rulesVariables object

Defines variables for a rule result. Learn More.

if string

Expression to evaluate whether additional attributes should be provided to the job. Learn More.

changes object | string[]

Additional attributes will be provided to job if any of the provided paths matches a modified file. Learn More.

exists string[] | object | object

Additional attributes will be provided to job if any of the provided paths matches an existing file in the repository. Learn More.

timeout string

Allows you to configure a timeout for a specific job (e.g. 1 minute, 1h 30m 12s). Learn More.

start_in string

Used in conjunction with 'when: delayed' to set how long to delay before starting a job. e.g. '5', 5 seconds, 30 minutes, 1 week, etc. Learn More.

rulesNeeds string | object[]

Use needs in rules to update job needs for specific conditions. When a condition matches a rule, the job's needs configuration is completely replaced with the needs in the rule. Learn More.

allow_failure boolean | object | object

Allow job to fail. A failed job does not cause the pipeline to fail. Learn More.

parallel integer | object

Splits up a single job into multiple that run in parallel. Provides CI_NODE_INDEX and CI_NODE_TOTAL environment variables to the jobs.

parallel_matrix object

Use the needs:parallel:matrix keyword to specify parallelized jobs needed to be completed for the job to run. Learn More

when string

Describes the conditions for when to run the job. Defaults to 'on_success'. Learn More.

cache cache_item | cache_item[]

Use cache to specify a list of files and directories to cache between jobs. You can only use paths that are in the local working copy. Learn More

cache_item object

key string | object

Use the cache:key keyword to give each cache a unique identifying key. All jobs that use the same cache key use the same cache, including in different pipelines. Must be used with cache:path, or nothing is cached. Learn More.

paths string[]

Use the cache:paths keyword to choose which files or directories to cache. Learn More

policy string

Determines the strategy for downloading and updating the cache. Learn More

Default: "pull-push"

pattern=pull-push|pull|push|\$\w{1,255}

unprotect boolean

Use unprotect: true to set a cache to be shared between protected and unprotected branches.

Default: false

untracked boolean

Use untracked: true to cache all files that are untracked in your Git repository. Learn More

Default: false

when string

Defines when to save the cache, based on the status of the job. Learn More.

Default: "on_success"

Values: "on_success" "on_failure" "always"

fallback_keys string[]

List of keys to download cache from if no cache hit occurred for key

maxItems=5

Filter job by different keywords that determine origin or state, or by supplying string/regex to check against branch/tag names.

filter null | filter_refs | object

retry retry_max | object

Retry a job if it fails. Can be a simple integer or object definition. Learn More.

retry_max integer

The number of times the job will be retried if it fails. Defaults to 0 and can max be retried 2 times (3 times total).

interruptible boolean

Interruptible is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Learn More.

inputs object

Used to pass input values to included templates, components, downstream pipelines, or child pipelines. Learn More.

job

job_template object

image string | object

Specifies the docker image to use for the job or globally for all jobs. Job configuration takes precedence over global setting. Requires a certain kind of GitLab runner executor. Learn More.

services string | object[]

Similar to image property, but will link the specified services to the image container. Learn More.

before_script optional_script

Defines scripts that should run before the job. Can be set globally or per job. Learn More.

after_script optional_script

Defines scripts that should run after the job. Can be set globally or per job. Learn More.

hooks object

Specifies lists of commands to execute on the runner at certain stages of job execution. Learn More.

1 nested properties

pre_get_sources_script string | string | string[][]

rules array | null

Rules allows for an array of individual rule objects to be evaluated in order, until one matches and dynamically provides attributes to the job. Learn More.

variables object

Defines variables for a job. Learn More.

cache cache_item | cache_item[]

Use cache to specify a list of files and directories to cache between jobs. You can only use paths that are in the local working copy. Learn More

id_tokens object

Defines JWTs to be injected as environment variables.

identity string

Sets a workload identity (experimental), allowing automatic authentication with the external system. Learn More.

Values: "google_cloud"

inputs object

Define input parameters for a job. Job inputs must always include a default value. Learn More.

secrets object

Defines secrets to be injected as environment variables. Learn More.

script string | string | string[][]

run step[]

stage string | string[]

Define what stage the job will run in.

only null | filter_refs | object

extends string | string[]

The name of one or more jobs to inherit configuration from.

needs string | object | object | object | !reference[]

The list of jobs in previous stages whose sole completion is needed to start the current job.

except null | filter_refs | object

tags string | string[][]

Used to select runners from the list of available runners. A runner must have all tags listed here to run the job. Learn More.

minItems=1

allow_failure boolean | object | object

Allow job to fail. A failed job does not cause the pipeline to fail. Learn More.

timeout string

Allows you to configure a timeout for a specific job (e.g. 1 minute, 1h 30m 12s). Learn More.

minLength=1

when string

Describes the conditions for when to run the job. Defaults to 'on_success'. Learn More.

Default: "on_success"

Values: "on_success" "on_failure" "always" "never" "manual" "delayed"

start_in string

Used in conjunction with 'when: delayed' to set how long to delay before starting a job. e.g. '5', 5 seconds, 30 minutes, 1 week, etc. Learn More.

minLength=1

manual_confirmation string

Describes the Custom confirmation message for a manual job Learn More.

dependencies string[]

Specify a list of job names from earlier stages from which artifacts should be loaded. By default, all previous artifacts are passed. Use an empty array to skip downloading artifacts.

artifacts object | null

Used to specify a list of files and directories that should be attached to the job if it succeeds. Artifacts are sent to GitLab where they can be downloaded. Learn More.

9 nested properties

paths string[]

A list of paths to files/folders that should be included in the artifact. Learn More.

minItems=1

exclude string[]

A list of paths to files/folders that should be excluded in the artifact. Learn More.

minItems=1

expose_as string

Can be used to expose job artifacts in the merge request UI. GitLab will add a link <expose_as> to the relevant merge request that points to the artifact. Learn More.

name string

Name for the archive created on job success. Can use variables in the name, e.g. '$CI_JOB_NAME' Learn More.

untracked boolean

Whether to add all untracked files (along with 'artifacts.paths') to the artifact. Learn More.

Default: false

when string

Configure when artifacts are uploaded depended on job status. Learn More.

Default: "on_success"

Values: "on_success" "on_failure" "always"

access string

Configure who can access the artifacts. Learn More.

Default: "all"

Values: "none" "developer" "maintainer" "all"

expire_in string

Default: "30 days"

reports object

Reports will be uploaded as artifacts, and often displayed in the GitLab UI, such as in merge requests. Learn More.

22 nested properties

accessibility string

Path to JSON file with accessibility report.

annotations string

Path to JSON file with annotations report.

junit string | string[]

Path for file(s) that should be parsed as JUnit XML result

browser_performance string

Path to a single file with browser performance metric report(s).

coverage_report object | null

Used to collect coverage reports from the job.

codequality string | string[]

dotenv string | string[]

lsif string | string[]

sast string | string[]

dependency_scanning string | string[]

container_scanning string | string[]

dast string | string[]

license_management string | string[]

license_scanning string | string[]

requirements string | string[]

secret_detection string | string[]

metrics string | string[]

terraform string | string[]

cyclonedx string | string[]

sarif string | string[]

load_performance string | string[]

repository_xray string | string[]

environment string | object

Used to associate environment metadata with a deploy. Environment can have a name and URL attached to it, and will be displayed under /environments under the project.

release object

Indicates that the job creates a Release.

8 nested properties

tag_name string required

The tag_name must be specified. It can refer to an existing Git tag or can be specified by the user.

minLength=1

description string required

Specifies the longer description of the Release.

minLength=1

tag_message string

Message to use if creating a new annotated tag.

name string

The Release name. If omitted, it is populated with the value of release: tag_name.

ref string

If the release: tag_name doesn’t exist yet, the release is created from ref. ref can be a commit SHA, another tag name, or a branch name.

milestones string[]

The title of each milestone the release is associated with.

released_at string

The date and time when the release is ready. Defaults to the current date and time if not defined. Should be enclosed in quotes and expressed in ISO 8601 format.

format=date-timepattern=^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:Z|[+-][01]\d:[0-5]\d)$

assets object

1 nested properties

links object[] required

Include asset links in the release.

minItems=1

coverage string

Must be a regular expression, optionally but recommended to be quoted, and must be surrounded with '/'. Example: '/Code coverage: \d+.\d+/'

format=regexpattern=^/.+/$

retry retry_max | object

Retry a job if it fails. Can be a simple integer or object definition. Learn More.

parallel integer | object

Splits up a single job into multiple that run in parallel. Provides CI_NODE_INDEX and CI_NODE_TOTAL environment variables to the jobs.

interruptible boolean

Interruptible is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Learn More.

Default: false

resource_group string

Limit job concurrency. Can be used to ensure that the Runner will not run certain jobs simultaneously.

trigger object | object | string

Trigger allows you to define downstream pipeline trigger. When a job created from trigger definition is started by GitLab, a downstream pipeline gets created. Learn More.

inherit object

Controls inheritance of globally-defined defaults and variables. Boolean values control inheritance of all default: or variables: keywords. To inherit only a subset of default: or variables: keywords, specify what you wish to inherit. Anything not listed is not inherited. Learn More.

2 nested properties

default boolean | string[]

Whether to inherit all globally-defined defaults or not. Or subset of inherited defaults. Learn more.

variables boolean | string[]

Whether to inherit all globally-defined variables or not. Or subset of inherited variables. Learn More.

publish string

Deprecated. Use pages.publish instead. A path to a directory that contains the files to be published with Pages.

pages object | boolean

tags string | string[][]

Used to select runners from the list of available runners. A runner must have all tags listed here to run the job. Learn More.

hooks object

Specifies lists of commands to execute on the runner at certain stages of job execution. Learn More.

pre_get_sources_script string | string | string[][]

step object | object

Any of these function use cases are valid.

stepName string

stepNamedStrings object

stepNamedValues object

stepGitReference object

GitReference is a reference to a function in a Git repository.

git object required

4 nested properties

url string required

rev string required

dir string

file string

stepOciReference object

OCIReference is a reference to a function hosted in an OCI repository.

oci object required

5 nested properties

registry string required

The [:] of the container registry server.

Examples: "registry.gitlab.com"

repository string required

A path within the registry containing related OCI images. Typically the namespace, project, and image name.

Examples: "my_group/my_project/image"

tag string required

A pointer to the image manifest hosted in the OCI repository.

Examples: "latest", "1", "1.5", "1.5.0"

dir string

A directory inside the OCI image where the function can be found.

Examples: "/my_steps/hello_world"

file string

The name of the file that defines the function, defaults to func.yml.

Examples: "func.yml"

stepFuncReference string | stepGitReference | stepOciReference