The Idea

Every time you push code, GitLab runs a set of automated tasks for you — testing, building, deploying — without you lifting a finger.

Key Terms

Pipeline — the full list of tasks that runs when you push code. Think of it as the to-do list.

Job — a single task inside the pipeline. „Run the tests“ is a job. „Build the app“ is a job.

Stage — a group of jobs that run together. Typical stages are test, build, and deploy.

Runner — the machine (or container) that actually does the work. GitLab tells the runner what to run; the runner runs it and reports back.

A Minimal Example

All of this lives in a file called .gitlab-ci.yml at the root of your project.

yaml

stages:
  - test
  - deploy
run_tests:
  stage: test
  script:
    - echo "Running tests..."
    - mvn compile test
deploy_app:
  stage: deploy
  script:
    - echo "Deploying..."
    - ./deploy.sh

That’s it. When you push, GitLab reads this file and:

1. Runs run_tests first (stage: test)
2. If tests pass, runs deploy_app (stage: deploy)
3. If tests fail, it stops — deploy never runs

How the Runner Fits In

The runner is a separate program that sits on a server (or runs in the cloud) and listens for jobs from GitLab.

GitLab offers shared runners for free — you don’t need to set anything up to get started. If you need more control (custom tools, more power, private network access), you can register your own runner on any machine.

Only Run on Certain Branches

You often don’t want to deploy from every branch. Use only or rules to control this:

yaml

deploy_app:
  stage: deploy
  script:
    - ./deploy.sh
  only:
    - main

Now deploy_app only runs when you push to main. Test jobs can still run on every branch.

What Happens When a Job Fails?

GitLab stops the pipeline at the failed job and marks the whole pipeline as failed. You get a notification, and the later stages (like deploy) are skipped automatically.

You can mark a job as allow_failure: true if it’s okay for it to fail without blocking everything else.