How GitLab CI/CD works

In GitLab, a pipeline is defined in a file named .gitlab-ci.yml at the root of the repository. When you push a commit or open a merge request, GitLab reads that file and creates a pipeline made of jobs, which are executed by runners.

The pieces

• Job: a named set of commands, the basic unit of work.
• Stage: a group of jobs. By default, all jobs in a stage run in parallel, and the next stage starts when the previous one succeeds.
• Pipeline: all the jobs for one commit or merge request.
• Runner: an agent that picks up jobs and runs them, usually in a fresh container. GitLab.com provides hosted runners; you can also register your own.

A minimal pipeline

stages: [test, build]

default:
  image: python:3.13-slim

unit-tests:
  stage: test
  script:
    - pip install -r requirements.txt
    - pytest -q

lint:
  stage: test
  script:
    - pip install ruff
    - ruff check .

package:
  stage: build
  script:
    - python -m build
  artifacts:
    paths: [dist/]

Commit this file and open Build > Pipelines in GitLab. You will see unit-tests and lint running in parallel, followed by package.

Each job starts clean

Every job runs in a new environment, typically a fresh container from the image you specify. Files created in one job do not exist in the next unless you pass them as artifacts or restore them from a cache. This keeps jobs independent and reproducible, and it is the source of many first day surprises.

Where configuration comes from

Besides the YAML file, pipelines use CI/CD variables defined in project, group or instance settings, and predefined variables such as CI_COMMIT_SHA, CI_COMMIT_BRANCH and CI_PIPELINE_SOURCE that describe the current pipeline. Variables are how you pass configuration and credentials without putting them in the repository.

Validate before you push

GitLab's pipeline editor validates your YAML and can show the fully merged configuration, including anything pulled in with include. Use it whenever a pipeline does not behave as expected; most problems are visible there before any job runs.