liminfo

GitLab CI Reference

Free reference guide: GitLab CI Reference

27 results

About GitLab CI Reference

The GitLab CI Reference is a searchable YAML syntax cheat sheet for .gitlab-ci.yml, the pipeline configuration file used by GitLab's built-in CI/CD system. It covers six major areas: Pipeline-level configuration (stages, include, workflow rules, global default settings), Stage ordering and DAG dependencies (stage assignment, .pre/.post reserved stages, needs for out-of-order execution, dependencies for artifact propagation), Job definitions (script, image, before_script/after_script, rules, only/except, service containers), Variable management (inline variables, built-in CI_COMMIT_SHA and CI_PIPELINE_ID variables, CI_REGISTRY_IMAGE for container builds, dotenv artifact for cross-job variable passing), Cache configuration (cache key strategies, file-based keys using package-lock.json, pull-only cache policy), and Artifact handling (path-based artifacts, JUnit and Cobertura report artifacts, conditional artifact saving, MR preview links with expose_as).

GitLab CI is widely adopted by software development teams for automating build, test, and deployment pipelines directly within GitLab repositories. Platform engineers, backend developers, and DevOps practitioners use it to implement merge request pipelines, container registry builds with CI_REGISTRY_IMAGE, scheduled jobs, and multi-environment deployments. The DAG execution model via needs: enables parallel job execution that bypasses strict stage ordering, significantly reducing pipeline duration for complex projects.

Every entry in this reference shows the YAML directive name, a plain-language description, and a complete, indented YAML block that can be copied directly into a .gitlab-ci.yml file. The reference distinguishes between modern rules: syntax and the legacy only/except approach, explains the difference between cache (speeds up repeated pipelines) and artifacts (passes build outputs between jobs), and demonstrates how dotenv artifacts enable dynamic variable passing between pipeline jobs.

Key Features

  • Pipeline config: .gitlab-ci.yml structure, stages, include (template/local/remote), workflow rules, default block
  • Stage ordering: .pre/.post reserved stages, needs for DAG parallel execution, dependencies for artifact control
  • Job definition: script, Docker image selection, before_script/after_script, rules with if/when, service containers
  • Variables: inline variables, $CI_COMMIT_SHA, $CI_PIPELINE_ID, $CI_REGISTRY_IMAGE, dotenv artifact for cross-job passing
  • Cache: branch-scoped cache keys, file-based cache keys (package-lock.json), pull-only cache policy for read jobs
  • Artifacts: path-based artifacts with expiry, JUnit/Cobertura test reports, on_failure artifact saving, expose_as for MR links
  • Built-in CI_ predefined variable examples alongside custom variable definitions
  • Modern rules: syntax shown alongside legacy only/except for teams migrating pipelines

Frequently Asked Questions

What is .gitlab-ci.yml and where does it go?

.gitlab-ci.yml is the GitLab CI/CD pipeline configuration file. It must be placed at the root of your Git repository. When GitLab detects this file, it automatically creates a pipeline for each push or merge request based on the job definitions and trigger conditions inside the file.

What is the difference between needs: and dependencies: in GitLab CI?

needs: allows a job to start as soon as its listed prerequisite jobs finish, bypassing the strict stage-by-stage ordering. This enables DAG (Directed Acyclic Graph) pipelines that run jobs in parallel across different stages. dependencies: only controls which jobs' artifacts are downloaded into the current job — it does not change execution order.

What is the difference between cache: and artifacts: in GitLab CI?

cache: stores files between pipeline runs to speed up repeated operations like npm install or pip install. The files are shared across runs of the same branch. artifacts: passes build outputs (compiled binaries, test reports, static files) between jobs within the same pipeline run. Artifacts are deleted after the pipeline expires; cache persists between pipeline runs.

How do I pass a variable from one job to another in GitLab CI?

Use the dotenv artifact mechanism. In the source job, write KEY=VALUE pairs to a file and declare it under artifacts.reports.dotenv. GitLab will inject those variables into all subsequent jobs that declare the source job under their dependencies or needs. This allows dynamic values like version numbers or build hashes to flow through the pipeline.

What is the difference between rules: and only/except in GitLab CI?

rules: is the modern, recommended approach. It supports complex conditional logic with if expressions, changes filters, exists checks, and when: conditions in a single list. only/except is the legacy approach that only supports branch name patterns and predefined keywords. New pipelines should use rules: as only/except is being phased out.

What are .pre and .post stages in GitLab CI?

.pre is a reserved stage that always runs before all other stages, regardless of the order defined in stages:. .post runs after all other stages. These are useful for global setup and cleanup jobs that should bracket every pipeline execution without requiring them to be listed in the stages array.

What are the most useful built-in GitLab CI variables?

The most frequently used are: $CI_COMMIT_SHA (the full commit hash), $CI_COMMIT_BRANCH (branch name), $CI_PIPELINE_ID (unique pipeline identifier), $CI_JOB_ID (unique job identifier), $CI_REGISTRY_IMAGE (the container registry image path for the project), and $CI_COMMIT_REF_SLUG (URL-safe branch name, useful as a cache key).

How do I build and push a Docker image using GitLab CI?

Use $CI_REGISTRY_IMAGE as the image name and $CI_COMMIT_SHA as the tag in your docker build and docker push commands. GitLab provides a built-in container registry accessible at $CI_REGISTRY with credentials available via $CI_REGISTRY_USER and $CI_REGISTRY_PASSWORD. Log in first with docker login $CI_REGISTRY.