Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 36 ยท GitLab CI/CD Pipelines

Pipelines and the .gitlab-ci.yml File

Write your first GitLab CI/CD pipeline: the .gitlab-ci.yml file, jobs, scripts, images, how pipelines start, how to read results and how to lint your config.

CI/CD means continuous integration and continuous delivery (or deployment). Every time someone pushes code, a pipeline builds it, tests it and optionally delivers it, automatically and in the same way every time. In GitLab the pipeline is described by one file in your repository, .gitlab-ci.yml, and executed by machines called runners.

The big advantage of keeping the pipeline in the repository is that it is versioned with the code: a branch that changes how the project is built also changes the pipeline that builds it, and you review the change in a merge request like any other.

Vocabulary

  • Pipeline: one run of your CI/CD configuration, created by an event such as a push.
  • Stage: a phase (like build, test, deploy). Stages run one after another.
  • Job: a unit of work, a list of shell commands. Jobs in the same stage run in parallel.
  • Runner: the agent that picks up a job and runs it (see runners).
  • Artifact: files a job saves for later jobs or for download.
flowchart LR
  subgraph build
    B1["compile"]
  end
  subgraph test
    T1["unit-tests"]
    T2["lint"]
  end
  subgraph deploy
    D1["publish"]
  end
  B1 --> T1
  B1 --> T2
  T1 --> D1
  T2 --> D1

Two test jobs run side by side; the deploy stage starts only after both succeed.

Your first pipeline

Create a file named .gitlab-ci.yml at the root of the repository (the leading dot matters). The smallest useful version:

YAML
hello:
  script:
    - echo "Hello from GitLab CI"
    - date

Commit and push it. GitLab detects the file and creates a pipeline. Open Build, then Pipelines in the project to see it, and click the job to read its log. Each key at the top level that is not a reserved keyword defines a job, and each job needs a script: a list of commands run by a shell on the runner, one after another. If any command exits with a non-zero status, the job fails and stops.

A more realistic example for a Node.js project:

YAML
image: node:22

stages:
  - build
  - test

install:
  stage: build
  script:
    - npm ci

unit-tests:
  stage: test
  script:
    - npm ci
    - npm test

lint:
  stage: test
  script:
    - npm ci
    - npm run lint

Key points:

  • image names a Docker image that provides the tools (here, Node 22). It applies to every job unless a job sets its own. It needs a Docker-capable runner (see executors).
  • stages lists phases in order. Without this key GitLab uses the defaults: .pre, build, test, deploy, .post. Jobs without a stage go to test.
  • Every job starts on a clean machine: the repository is cloned fresh and nothing from the previous job exists, which is why npm ci is repeated. The artifacts and cache lesson fixes that.

What starts a pipeline

A pipeline is created by an event, and the event is available to your rules as $CI_PIPELINE_SOURCE:

Source value Event
push A commit pushed to a branch or tag
merge_request_event A merge request created or updated (needs rules that allow it)
schedule A scheduled pipeline (configured in the project)
web Someone pressed New pipeline in the UI
api A call to the pipelines API
trigger A pipeline trigger token
pipeline / parent_pipeline Started from another pipeline

By default a push creates a branch pipeline. Pushing a tag creates a tag pipeline. You decide which jobs run in each case with rules, covered in variables and rules.

To skip the pipeline for one commit, include [ci skip] or [skip ci] in the commit message, or push with -o ci.skip.

Reading a pipeline

The pipeline page shows jobs in columns by stage with a status icon: passed, failed, running, pending (waiting for a runner), skipped, manual (waiting for a person) and canceled. A job log shows the runner that executed it, the image it pulled, each command with its output, and finally the result. When something fails, read the last lines first: the failing command and its error message are almost always at the bottom. You can retry a failed job, or cancel a running pipeline, from the same page.

In a merge request, the widget shows the latest pipeline and links to it, which is why merge request settings can require success before merging.

Linting your configuration

A typo in YAML can stop a pipeline from existing at all. GitLab validates the file when you push, and the editor offers a Pipeline editor (in the Build area) with syntax checking, a visual graph and a Validate tab that simulates the pipeline without running it.

The stand-in below is a tiny linter that loads a configuration with a YAML parser and checks a few real rules: every job needs script (or trigger), and a stage must be listed in stages. It is a teaching model, not GitLab's validator.

Python Stand-in: a tiny .gitlab-ci.yml linter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Real YAML errors you will meet: wrong indentation (use spaces, never tabs), a missing colon, strings with a colon that need quotes, and a script that is not a list of strings. Running a command that contains : often needs quoting, for example - 'echo "result: ok"'.

Choosing the image and default settings

Use default: to set values shared by all jobs and override them per job:

YAML
default:
  image: python:3.13-slim
  before_script:
    - python --version

tests:
  script:
    - python -m unittest

docs:
  image: python:3.13
  script:
    - echo "this job uses a different image"

before_script runs before each job's script in the same shell; after_script runs afterwards even when the script failed (in a separate shell). The stages lesson shows how jobs wait on each other.

Good beginner habits

  • Keep pipelines fast: a pipeline people wait ten minutes for is one they start ignoring.
  • Make jobs idempotent: running them twice should give the same result.
  • Echo only non-secret information. Never print tokens.
  • Commit .gitlab-ci.yml changes in small steps and test on a branch first.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is required for every normal job in .gitlab-ci.yml?

    A job must define script, the commands to run. Stage defaults to test and image can come from the defaults or the runner.
  2. 2. Which jobs run at the same time?

    Stages run in sequence; jobs within a stage run in parallel.
  3. 3. A job's second command fails with a non-zero exit code. What happens?

    Commands in a script run in order and the first failing command fails the job.
  4. 4. What does a job start with on the runner?

    Jobs are isolated. Share files with artifacts and speed up installs with cache.

Summary

  • .gitlab-ci.yml in the repository root defines a pipeline of stages and jobs.
  • Each job needs a script; jobs in a stage run in parallel, stages run in order.
  • image, default, before_script and after_script set shared environment.
  • Pipelines start from events like pushes, merge requests, schedules and the API.
  • Use the pipeline editor and read job logs from the bottom to debug.

Next: Stages and Job Ordering