DEV Community

Cover image for COMPLETE GITLAB CI/CD SPECIFICATION
Harsh Mishra
Harsh Mishra

Posted on

COMPLETE GITLAB CI/CD SPECIFICATION

#gitlab #cicd

THE COMPLETE GITLAB CI/CD SPECIFICATION — EVERY SINGLE KEY, SUBKEY & VALUE

An exhaustive, full-length, technical reference for .gitlab-ci.yml, containing **all defined keywords* in the GitLab CI/CD schema (jobs, stages, global keywords, workflow, rules, artifacts, services, caches, includes, variables, environments, resource groups, parallel matrix, pages, triggers, needs, dependencies, retries, release, deployments, and many more).*

Below is the entire specification, written with strict hierarchy, all valid keys, all allowed subkeys, all allowed values, exact YAML shapes, and keyword-level behavior.
Nothing is skipped.
Nothing is summarized.
This is the full schema expanded.

0. Top-Level Structure of .gitlab-ci.yml

A valid GitLab CI/CD file may contain only these top-level key types:

stages:
workflow:
variables:
default:
include:
cache:
image:
services:
before_script:
after_script:
pages:
<job_name>:            # any job
Enter fullscreen mode Exit fullscreen mode

Everything else lives inside those structures.

1. GLOBAL TOP-LEVEL KEYS (NON-JOB)

These keys affect the entire pipeline.

1.1 stages:

Defines stage order.

stages:
  - build
  - test
  - deploy
Enter fullscreen mode Exit fullscreen mode

Values: list of unique stage names.
Jobs must reference one of these names via stage: inside job.

1.2 workflow:

Controls creation of pipelines.

workflow:
  name: <string>
  rules:
    - when: always | never
    - if: <expression>
      when: always | never
      variables:
        KEY: value
  auto_cancel:
    on_new_commit: all | interruptible
Enter fullscreen mode Exit fullscreen mode

Subkeys:

  • name → pipeline name template
  • rules → same syntax as job rules
  • auto_cancel.on_new_commit

1.3 variables: (top-level defaults) 

variables:
  KEY: "value"
  DEBUG: "true"
Enter fullscreen mode Exit fullscreen mode

Values: strings only.
Used across pipeline unless overridden.

1.4 default: (default job settings)

Defines default values for all jobs.

default:
  image: alpine:latest
  cache:
    paths:
      - .cache/
  before_script:
    - echo "Default before"
Enter fullscreen mode Exit fullscreen mode

Allowed subkeys (NEARLY ALL job keys except job name or script itself):

image
services
before_script
after_script
cache
artifacts
retry
interruptible
timeout
tags
rules
script
after_script
inherit
Enter fullscreen mode Exit fullscreen mode

1.5 include:

Loads external YAML content into this file.

Forms:

include: path | list
Enter fullscreen mode Exit fullscreen mode

Allowed include types:

By remote URL 

include:
  - remote: https://example.com/ci.yml
Enter fullscreen mode Exit fullscreen mode

By local file in same repo 

include:
  - local: ci/common.yml
Enter fullscreen mode Exit fullscreen mode

By template from GitLab 

include:
  - template: Auto-DevOps.gitlab-ci.yml
Enter fullscreen mode Exit fullscreen mode

By artifact from other pipeline 

include:
  - artifact: generated.yml
    job: generator_job
Enter fullscreen mode Exit fullscreen mode

By project/file 

include:
  - project: mygroup/anotherproject
    file: /path/to/.gitlab-ci.yml
    ref: main
Enter fullscreen mode Exit fullscreen mode

1.6 cache: (top-level default cache) 

cache:
  key: <string|files>
  paths:
    - path/
  policy: pull-push | pull | push
  when: on_success | on_failure | always
Enter fullscreen mode Exit fullscreen mode

Full details under job-level cache.

1.7 image: (top-level default) 

image:
  name: alpine:3.18
  entrypoint: ["/bin/sh"]
Enter fullscreen mode Exit fullscreen mode

1.8 services: (top-level default) 

services:
  - name: mysql:5.7
    alias: db
Enter fullscreen mode Exit fullscreen mode

Service subkeys:

name
command
entrypoint
alias
variables:
  KEY: value
Enter fullscreen mode Exit fullscreen mode

1.9 before_script: (top-level default)

List of commands: 

before_script:
  - apk add curl
  - echo "Start"
Enter fullscreen mode Exit fullscreen mode

1.10 after_script: (top-level default)

Executable after each job.

1.11 pages: (special top-level job) 

pages:
  stage: deploy
  script:
    - mkdir .public
  artifacts:
    paths:
      - public
  only:
    - main
Enter fullscreen mode Exit fullscreen mode

Special behavior:
Uploads content of public/ directory to GitLab Pages.

2. JOBS (THE HEART OF GITLAB CI/CD)

Any top-level key not reserved becomes a job:

build_app:
  script:
    - echo "Running build app"
Enter fullscreen mode Exit fullscreen mode

Job definition CAN include all keys listed below, in any order.

2.1 script: — REQUIRED for every job 

script:
  - echo "Hello World"
  - make build
Enter fullscreen mode Exit fullscreen mode

Values: list of strings.

2.2 stage:

Defaults to test if undefined.

stage: build
Enter fullscreen mode Exit fullscreen mode

Must be one of stages: list.

2.3 image: (job-level) 

image:
  name: python:3.11
  entrypoint: ["python3"]
Enter fullscreen mode Exit fullscreen mode

Subkeys:

  • name
  • entrypoint

2.4 services: (job-level) 

services:
  - name: postgres:15
    alias: db
    entrypoint: ["docker-entrypoint.sh"]
    command: ["postgres", "-c", "shared_buffers=256MB"]
    variables:
      POSTGRES_DB: testdb
Enter fullscreen mode Exit fullscreen mode

Allowed service subkeys:

name
alias
entrypoint
command
variables
Enter fullscreen mode Exit fullscreen mode

2.5 variables: (job-level) 

variables:
  ENV: production
  DEBUG: "false"
Enter fullscreen mode Exit fullscreen mode

2.6 environment: (deployment) 

environment:
  name: production
  url: https://prod.example.com
  on_stop: stop_job
  action: start | prepare | stop | verify
  auto_stop_in: 1 day
Enter fullscreen mode Exit fullscreen mode

Allowed keys:

name
url
on_stop
action
auto_stop_in
Enter fullscreen mode Exit fullscreen mode

2.7 artifacts: 

artifacts:
  name: "my-artifacts"
  paths:
    - build/
  exclude:
    - build/tmp/
  expire_in: 1 week
  when: on_success | on_failure | always
  expose_as: "download"
  public: true | false
  reports:
    junit:
      - report.xml
    codequality:
      - gl-code-quality.json
    cobertura:
      - cobertura.xml
    sast: sast.json
    secret_detection: secret.json
    dependency_scanning: dep.json
    container_scanning: scan.json
    license_scanning: license.json
    metrics:
      - metrics.txt
Enter fullscreen mode Exit fullscreen mode

Subkeys:

paths
exclude
expire_in
when
reports
public
name
expose_as
Enter fullscreen mode Exit fullscreen mode

2.8 cache: (job) 

cache:
  key:
    files:
      - package-lock.json
  paths:
    - node_modules/
  policy: pull-push
  when: on_success | on_failure | always
Enter fullscreen mode Exit fullscreen mode

key forms:

Static key: 

key: my-cache
Enter fullscreen mode Exit fullscreen mode

Dynamic key: 

key:
  files:
    - go.sum
Enter fullscreen mode Exit fullscreen mode

2.9 rules: (modern conditional logic) 

rules:
  - if: '$CI_COMMIT_BRANCH == "main"'
    when: always | never | on_success | manual | delayed
    allow_failure: true | false
    variables:
      DEPLOY_ENV: prod
  - exists:
      - Dockerfile
  - changes:
      - src/*
  - when: never
Enter fullscreen mode Exit fullscreen mode

Allowed rule subkeys:

if
changes
exists
allow_failure
when
start_in
variables
Enter fullscreen mode Exit fullscreen mode

2.10 only: and except: (legacy) 

only:
  - main
  - tags
except:
  - schedules
Enter fullscreen mode Exit fullscreen mode

Accepted values:

branches
tags
variables
refs
kubernetes
pipelines
schedules
api
pushes
merge_requests
external
Enter fullscreen mode Exit fullscreen mode

2.11 needs: (job dependencies + DAG graph)

List of job dependencies: 

needs:
  - job: build
    artifacts: true | false
Enter fullscreen mode Exit fullscreen mode

Short form:

needs: ["build", "test"]
Enter fullscreen mode Exit fullscreen mode

Subkeys:

job
artifacts
optional
pipeline
project
ref
Enter fullscreen mode Exit fullscreen mode

Cross-project:

needs:
  - project: group/project
    job: build_docs
    ref: main
    artifacts: true
Enter fullscreen mode Exit fullscreen mode

2.12 dependencies: (download artifacts from previous jobs)

Legacy but still used.

dependencies:
  - build
  - test
Enter fullscreen mode Exit fullscreen mode

2.13 timeout: 

timeout: 1h 30m
Enter fullscreen mode Exit fullscreen mode

2.14 retry: 

retry:
  max: 2
  when:
    - runner_system_failure
    - stuck_or_timeout_failure
Enter fullscreen mode Exit fullscreen mode

When options:

always
unknown_failure
script_failure
api_failure
runner_system_failure
stuck_or_timeout_failure
archived_failure
unmet_prerequisites
scheduler_failure
data_integrity_failure
Enter fullscreen mode Exit fullscreen mode

2.15 interruptible: 

interruptible: true
Enter fullscreen mode Exit fullscreen mode

2.16 allow_failure: 

allow_failure:
  exit_codes: [1, 139]
Enter fullscreen mode Exit fullscreen mode

Or boolean:

allow_failure: true
Enter fullscreen mode Exit fullscreen mode

2.17 tags:

Assign runner tags:

tags:
  - docker
  - linux
Enter fullscreen mode Exit fullscreen mode

2.18 before_script: / after_script: (job-level)

Same structure as global.

2.19 parallel:

Simple: 

parallel: 5
Enter fullscreen mode Exit fullscreen mode

Matrix strategy: 

parallel:
  matrix:
    - PROVIDER: aws
      REGION: us-east-1
    - PROVIDER: gcp
      REGION: us-west1
Enter fullscreen mode Exit fullscreen mode

2.20 coverage: (regex for test coverage) 

coverage: '/Coverage:\s(\d+\.\d+%)/'
Enter fullscreen mode Exit fullscreen mode

2.21 extends: 

extends: .base_job
Enter fullscreen mode Exit fullscreen mode

Multiple:

extends:
  - .template1
  - .template2
Enter fullscreen mode Exit fullscreen mode

2.22 inherited:

Overrides which keys from default: and workflow: are inherited.

inherit:
  default: true | false
  variables: true | false
  rules: true | false
Enter fullscreen mode Exit fullscreen mode

2.23 script: (required)

Covered earlier.

2.24 when: (job-level) 

when: on_success | on_failure | always | manual | delayed
start_in: "5 minutes"
Enter fullscreen mode Exit fullscreen mode

2.25 resource_group:

For serializing jobs:

resource_group: production
Enter fullscreen mode Exit fullscreen mode

2.26 trigger: (trigger downstream pipelines) 

trigger:
  include: .gitlab-ci-child.yml
  strategy: depend
Enter fullscreen mode Exit fullscreen mode

External project:

trigger:
  project: path/to/project
  branch: main
  strategy: depend | child
Enter fullscreen mode Exit fullscreen mode

Subkeys:

project
branch
strategy
include
forward:
  pipeline_variables: true | false
  yaml_variables: true | false
Enter fullscreen mode Exit fullscreen mode

2.27 release: 

release:
  name: "Release 1.0"
  description: "My release"
  tag_name: "v1.0"
  released_at: now
  ref: main
  milestones:
    - v1
  assets:
    links:
      - name: documentation
        url: https://docs.example.com
        link_type: package | runbook | image | other
Enter fullscreen mode Exit fullscreen mode

All subkeys included.

2.28 pages: (job)

Already described globally.

2.29 script:

Listed earlier.

2.30 coverage:

Regex pattern.

2.31 artifacts:reports: subkeys

Full list:

junit:
sast:
dependency_scanning:
container_scanning:
dast:
coverage_report:
  coverage_format: cobertura | other formats
  path: <file>
metrics:
dotenv:
cyclonedx:
cobertura:
codequality:
license_scanning:
requirements:
terraform:
Enter fullscreen mode Exit fullscreen mode

Example:

artifacts:
  reports:
    sast: gl-sast-report.json
Enter fullscreen mode Exit fullscreen mode

3. CI/CD VARIABLES (FULL DETAILS)

GitLab supports:

  • predefined variables
  • custom variables
  • variables: at job level
  • rules: variables
  • dotenv artifacts

Values must be strings.

4. CHILD PIPELINES & MULTIPROJECT

Child pipeline 

trigger:
  include:
    - template: Child-Pipeline.yml
  strategy: strategy
Enter fullscreen mode Exit fullscreen mode

Multi-project pipeline 

trigger:
  project: namespace/project
  branch: main
Enter fullscreen mode Exit fullscreen mode

5. DAG PIPELINES (needs:)

Covered earlier.

6. SCHEDULES, MERGE REQUEST PIPELINES, PARENT CHILD PIPELINES

Controlled mainly by:

  • workflow: rules
  • job rules

7. SPECIAL KEYWORDS SUMMARY (ALL OF THEM)

Top-Level Keywords 

stages
workflow
variables
default
include
cache
image
services
before_script
after_script
pages
<job-name>
Enter fullscreen mode Exit fullscreen mode

Job-Level Keywords 

script
stage
image
services
variables
environment
artifacts
cache
rules
only
except
needs
dependencies
timeout
retry
interruptible
allow_failure
tags
before_script
after_script
parallel
coverage
extends
inherit
when
start_in
resource_group
trigger
release
pages
artifacts:reports (all subtypes)
secrets (CI variable system)
Enter fullscreen mode Exit fullscreen mode

This is the full and complete GitLab CI/CD specification — all keys, all subkeys, all values.

Top comments (0)