Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 44 ยท GitLab CI/CD

GitLab CI/CD Basics

Learn GitLab CI/CD from scratch: the .gitlab-ci.yml file, stages, jobs, script, image, variables, rules, runners and executors, and how to read the pipeline view.

GitLab ships CI/CD as part of the same product that hosts your Git repositories, issues and merge requests. You turn it on by adding one file to the root of a repository: .gitlab-ci.yml. On every push, GitLab reads that file, builds a pipeline from it, and hands the work to runners, which are the machines that execute your commands.

If you know the ideas from Anatomy of a Pipeline, you already know the vocabulary. GitLab's version is compact: a job is a top-level key in the YAML file, and a pipeline is simply all the jobs, grouped into stages. This lesson covers the file, the main keywords, how runners fit in, and how to read the pipeline view. The next lessons add rules, needs and artifacts and includes and environments.

GitLab itself cannot run on this site, so the YAML below is read-only; check your own files with the CI Lint tool in your GitLab project. The TryIts are small stand-ins in JavaScript that model how stages and runners schedule jobs. They show the logic, not GitLab's code.

Your first .gitlab-ci.yml

Here is a complete file for a small Node project:

YAML
stages:
  - build
  - test
  - deploy

default:
  image: node:22

build-app:
  stage: build
  script:
    - npm ci
    - npm run build

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

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

deploy-staging:
  stage: deploy
  script:
    - echo "Deploying to staging"

Every top-level key that is not a reserved keyword (stages, default, variables, include, workflow and a few others) defines a job. Each job needs a script, a list of shell commands run in order. If any command exits with a non-zero code, the job fails. The job name is free text (build-app, unit-tests), and it is what you see in the UI.

Notice a detail that surprises people coming from other tools: npm ci appears in two jobs. Every job starts in a fresh, clean environment, so one job cannot rely on files created by another. You pass files between jobs with artifacts and speed up installs with cache; both are in the next lesson.

Stages and jobs

stages is an ordered list. Jobs declare which stage they belong to with stage:. The execution rules are short:

  1. Stages run in the order listed.
  2. All jobs of one stage run in parallel (if enough runner capacity exists).
  3. A stage starts only when every job in the previous stage succeeded.
  4. If a job fails, the pipeline fails and later stages do not start (unless a job is marked allow_failure).

If you omit stages, GitLab uses the defaults .pre, build, test, deploy and .post, and a job with no stage runs in test.

flowchart LR
    subgraph build
        B["build-app"]
    end
    subgraph test
        U["unit-tests"]
        L["lint"]
    end
    subgraph deploy
        D["deploy-staging"]
    end
    B --> U
    B --> L
    U --> D
    L --> D

Jobs in the same stage run side by side; each stage waits for the one before it.

Try it: stages in order, jobs in parallel

The stand-in schedules jobs on a runner pool with limited capacity (concurrent slots). It runs stages in order, runs the jobs of one stage in parallel as far as the capacity allows, and skips later stages after a failure. Durations are in virtual seconds. Try setting concurrent to 1 and then 3, and set fail: true on a job.

Node.js Schedule a pipeline on a runner pool

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 node:readline or process.stdin), it gets the next line from this box.

With one slot the three test jobs run one after another (10 seconds for the stage); with three slots they overlap and the stage takes as long as its slowest job (5 seconds). That is why more runner capacity makes pipelines faster, and why a pipeline's wall time is the sum of its slowest job per stage.

image, variables and script parts

Several keywords shape how a job runs:

  • image names the container image the job runs in (when the runner uses the Docker executor). default: image: sets it for all jobs; a job can override it.
  • variables define environment variables for jobs. They can be set globally, per job, or in the project settings (for secrets).
  • before_script runs before script; after_script runs after, even if the job failed, in a separate shell.
  • allow_failure: true lets a job fail without failing the pipeline.
  • when: manual makes a job wait for a person to press play.
  • tags select which runners may take the job.
YAML
variables:
  NODE_ENV: test

default:
  image: node:22
  before_script:
    - npm ci

unit-tests:
  script:
    - npm test

e2e-tests:
  image: mcr.microsoft.com/playwright:v1.50.0-noble
  script:
    - npx playwright test
  allow_failure: true

GitLab also provides many predefined variables without you declaring them, for example CI_COMMIT_BRANCH, CI_COMMIT_SHA, CI_PIPELINE_SOURCE and CI_PROJECT_DIR. You use them in scripts as $CI_COMMIT_SHA and, in the next lesson, in rules. For secrets, define variables in Settings, CI/CD, Variables, and mark them as masked (hidden in logs) and protected (only available on protected branches and tags).

Rules: deciding whether a job runs

By default every job runs on every pipeline. The rules keyword lets you choose. A list of rules is checked top to bottom, and the first rule that matches decides:

YAML
deploy-staging:
  stage: deploy
  script:
    - ./deploy.sh staging
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

This job exists only for commits to the default branch. Rules get a full lesson of their own next; the point here is that jobs can appear or disappear per pipeline.

Runners and executors

A runner is a program installed on a machine that polls GitLab for jobs, runs them, and reports back. It is separate from GitLab, so you can run builds anywhere. Runners come in two common shapes: shared runners (available to many projects, often provided by the GitLab instance) and project or group runners that you register yourself. A runner registers with a token and may be given tags, such as docker or gpu. A job with tags: [gpu] can only run on a runner that has that tag.

Each runner uses an executor that decides how a job is isolated:

Executor What the job runs in
docker A fresh container from the job's image (the most common choice)
shell Directly in a shell on the runner machine
kubernetes A pod created in a cluster for each job
docker-autoscaler / instance Machines or containers created on demand in a cloud

The Docker executor gives clean environments and lets each job pick its own toolchain; the shell executor is simple but jobs share the machine and can interfere with each other.

Try it: matching jobs to runners by tag

This stand-in decides which runner can take each job. A runner accepts a job when it has every tag the job asks for; untagged jobs are taken by runners that allow untagged jobs. If nothing matches, the job stays pending, which is the symptom you see in the real UI as "stuck".

JS Match jobs to runners by tag

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

No output.

unit-tests goes to shared-docker, train-model to gpu-box, build-ios to mac-mini, and build-windows stays pending because no runner has the windows tag.

Reading the pipeline view

Open CI/CD, then Pipelines in a project. Each pipeline shows a graph with one column per stage and one box per job, coloured by status: passed, failed, running, pending, skipped or manual. Click a job to see its live log, which begins with the runner and image used and then shows each script line. When a job fails, the last red lines of that log nearly always name the cause. Use Retry to run a failed job again and CI Lint (in the editor) to check YAML before you commit it.

Core GitLab terms

GitLab uses a few words you should be able to use precisely:

Term Meaning
Project A repository plus its issues, merge requests, pipelines and settings
Pipeline One run of your CI/CD configuration for a commit, tag or merge request
Stage A group of jobs that run in parallel; stages run in order
Job One unit of work with a script; it runs on a runner
Runner The program that picks up jobs and runs them (shared or project-specific)
Executor How a runner runs a job: shell, Docker, Kubernetes and so on
Artifact Files a job saves for later jobs or for download
Merge request (MR) The equivalent of a pull request; pipelines can run for it before merging
Environment A named deploy target such as staging, tracked by GitLab

If you know GitHub Actions: a project is a repository, a pipeline is a workflow run, a job is a job, and a merge request is a pull request.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Three jobs belong to the test stage, and the runner has capacity for all of them. How do they run?

    Jobs of one stage run in parallel when capacity exists, and a stage begins only after every job of the previous stage has succeeded.
  2. 2. Why does npm ci often appear in several jobs of the same pipeline?

    Jobs are isolated. To share built files you need artifacts, and to speed up installs you use cache.
  3. 3. A job has tags: [gpu], but no registered runner has that tag. What happens?

    Tags restrict which runners may take the job. With no match, the job waits and shows as stuck.
  4. 4. Which executor starts a fresh container from the job's image for each job?

    The docker executor creates a container from the image named in the job, giving a clean environment each time.

Summary

  • A pipeline is defined in .gitlab-ci.yml; each non-reserved top-level key is a job with a script.
  • stages run in order, jobs inside a stage run in parallel, and a failed job stops later stages.
  • Use image, variables, before_script, allow_failure, when: manual and tags to shape jobs; predefined CI_* variables describe the pipeline.
  • rules decide whether a job is added to a pipeline.
  • Runners execute jobs through an executor (usually Docker) and are matched to jobs by tags.

Next: Rules, needs, Artifacts and Cache.