Lesson 02 beginner

Getting Started with GitLab CI/CD

Create a GitLab project, push a .gitlab-ci.yml, watch your first pipeline run on a hosted runner, read job logs, fix a red pipeline, validate YAML with the pipeline editor and the glab CLI, and turn it into a real build and test pipeline for a Node.js API.

In this lesson you go from an empty repository to a pipeline that builds and tests the Orbit API on every push. You need a free account on GitLab.com, Git installed and about twenty minutes.

Create the project

  1. In GitLab, select New project → Create blank project.
  2. Name it orbit, keep it Private and tick Initialize repository with a README.
  3. Clone it:
$ git clone git@gitlab.com:<your-username>/orbit.git
$ cd orbit

Hosted runners on a Free account: GitLab.com runs your jobs on its own Linux runners and gives Free namespaces a monthly allowance of compute minutes. New accounts are sometimes asked to verify identity (phone or card) before the first job runs. That is an anti-abuse step, not a charge.

Your first pipeline

Create a file called .gitlab-ci.yml at the root of the repository. The leading dot and the exact name matter: GitLab looks for this file and nothing else by default.

hello:
  script:
    - echo "Hello from job $CI_JOB_NAME"
    - echo "Running commit $CI_COMMIT_SHORT_SHA on branch $CI_COMMIT_BRANCH"
    - uname -a

That is a complete pipeline: one job called hello with three shell commands. Commit and push it:

$ git add .gitlab-ci.yml
$ git commit -m "ci: first pipeline"
$ git push

Open Build → Pipelines in the left sidebar. A pipeline appears within seconds, first pending while a runner picks it up, then running, then passed. Click the job to read its log. You will see the runner preparing a container, cloning your repository and running each line of script, with the output under each command.

Notice the variables: CI_JOB_NAME, CI_COMMIT_SHORT_SHA and CI_COMMIT_BRANCH were never defined by you. GitLab injects more than a hundred predefined variables into every job. Lesson 4 covers them.

What just happened

  1. Your push reached GitLab.
  2. GitLab found .gitlab-ci.yml, parsed it and created a pipeline with one job.
  3. A hosted runner claimed the job, started a fresh container, cloned the commit and ran the script.
  4. The runner streamed the log back and reported the exit code. Exit code 0 means passed; anything else means failed.

That last point is the whole contract between you and CI: a job fails when a command exits with a non-zero code. Linters, test runners and compilers all follow that rule, so they plug in without extra work.

Anatomy of a job

Every job is a top-level YAML key that is not a reserved keyword. The keys inside it describe how to run it:

unit-tests:              # job name, shown in the UI
  stage: test            # which column it belongs to
  image: node:24-alpine  # container image the script runs in
  before_script:         # setup commands, run before script
    - npm ci
  script:                # the actual work (required)
    - npm test
  after_script:          # always runs, even when script fails
    - echo "Job finished with status $CI_JOB_STATUS"
KeywordPurpose
scriptShell commands to run. The only required keyword.
imageDocker image for the job. Without it, the runner’s default image is used.
stageThe stage the job belongs to. Defaults to test.
before_script / after_scriptSetup and cleanup around script.
tagsPicks which runners may take the job (lesson 5).
rulesDecides whether the job is added to the pipeline (lesson 6).

Pin your images. image: node means “whatever is latest today”, which changes under your feet. Use a specific major version such as node:24-alpine, and in production pipelines consider a digest (node:24-alpine@sha256:…) so every run is identical.

Add the Orbit API

Let us give the pipeline something real to build. Add a minimal Node.js project. In package.json:

{
  "name": "orbit-api",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "mkdir -p dist && cp -r src/* dist/",
    "lint": "node --check src/server.js",
    "test": "node --test"
  }
}

In src/notes.js:

export function preview(text, max = 40) {
  if (text.length <= max) return text;
  return text.slice(0, max).trimEnd() + "…";
}

In test/notes.test.js:

import { test } from "node:test";
import assert from "node:assert/strict";
import { preview } from "../src/notes.js";

test("short notes are unchanged", () => {
  assert.equal(preview("buy milk"), "buy milk");
});

test("long notes are cut with an ellipsis", () => {
  assert.equal(preview("a".repeat(50), 10), "aaaaaaaaaa…");
});

Add an empty src/server.js for now and run npm install once locally so a package-lock.json exists. CI uses npm ci, which installs exactly what the lock file says and fails if it is missing.

A real build and test pipeline

Replace the contents of .gitlab-ci.yml:

stages:
  - build
  - test

default:
  image: node:24-alpine

build-api:
  stage: build
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

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

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

What changed:

  • **stages** declares the order: build first, then test.
  • **default** sets the image once for every job instead of repeating it.
  • **artifacts** saves dist/ when build-api finishes. Later stages download it automatically, and you can download it from the job page. expire_in stops old artifacts from filling your storage.
  • lint and unit-tests share the test stage, so they run in parallel once build-api passes.

Push it and open the pipeline graph. You see two columns: build-api in the first, lint and unit-tests side by side in the second.

Break it on purpose

Learning to read a red pipeline is as important as writing a green one. Change the second test so it expects the wrong value:

assert.equal(preview("a".repeat(50), 10), "aaaaaaaaaa");

Push it. unit-tests turns red and the pipeline fails. Open the job log and scroll to the end:

$ npm test
✖ long notes are cut with an ellipsis
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  + actual - expected
  + 'aaaaaaaaaa…'
  - 'aaaaaaaaaa'
ℹ tests 2
ℹ pass 1
ℹ fail 1
ERROR: Job failed: exit code 1

The log names the test, shows expected versus actual and ends with the exit code that failed the job. Fix the assertion, push again and watch the pipeline turn green. Every failed pipeline you will ever debug follows this pattern: find the failing job, read the last screen of its log, reproduce locally.

Check your YAML before you push

A typo in .gitlab-ci.yml gives you a pipeline that never starts, with a yellow “yaml invalid” badge. Three ways to catch it earlier:

  • Pipeline editor: Build → Pipeline editor validates the file as you type, shows the merged configuration and draws the stages before you commit.
  • CI Lint: in the pipeline editor, the Validate tab simulates a pipeline for a branch.
  • **The glab CLI**: GitLab’s official command-line tool lints from your terminal and follows pipelines without opening the browser.
$ glab auth login
$ glab ci lint
Validating...
✓ CI/CD YAML is valid!
$ glab ci status
$ glab ci view

glab ci view opens an interactive view of the current branch’s pipeline where you can read logs and retry jobs.

Run a pipeline by hand

Not every pipeline comes from a push. Build → Pipelines → New pipeline lets you pick a branch and set variables for a one-off run, which is handy to re-run a deploy or test a change to the CI file. The same is possible from the CLI with glab ci run.

Exercise

A job’s script runs three commands. The second one is a test runner that exits with code 1. What happens?

  1. The job passes because the third command still runs
  2. The job stops at the second command and fails
  3. The job is marked as a warning
  4. GitLab retries the command until it succeeds
Show answer

Answer: B. Each line of script runs in order and the job fails at the first command that returns a non-zero exit code. That is how test runners and linters fail a pipeline.

Exercise

build-api saves dist/ as an artifact. lint and unit-tests are in the next stage. What do they see?

  1. Nothing, because every job starts from an empty folder
  2. The repository files plus the dist/ folder downloaded from build-api
  3. Only dist/, without the repository
  4. node_modules from build-api
Show answer

Answer: B. Every job gets a fresh clone of the commit. Artifacts from jobs in earlier stages are downloaded on top of it. node_modules was not listed as an artifact, which is why each job runs npm ci.

Key takeaways

  • A pipeline is defined by .gitlab-ci.yml at the repository root; a push is enough to start it.
  • A job is a name, an image and a script. It fails when any command exits non-zero.
  • stages set the order; jobs in the same stage run in parallel.
  • artifacts pass files to later stages and make them downloadable.
  • Validate the YAML in the pipeline editor or with glab ci lint before pushing.

FAQ

Why does my pipeline not start at all?

Check the file name (.gitlab-ci.yml, with the dot), that it is on the branch you pushed, and that the YAML is valid. Also check Settings → CI/CD → General pipelines to make sure CI/CD is enabled for the project.

My job is stuck in “pending”. What does that mean?

No runner has picked it up. On GitLab.com this usually means the account needs verification or the compute minutes are used up. On self-managed GitLab it often means no runner matches the job’s tags. Lesson 5 covers runners.

Why does every job run npm ci again?

Each job starts in a fresh container with only the repository and the artifacts. That isolation is what makes results repeatable. Lesson 3 shows how a cache makes those repeated installs fast.

Can I test my pipeline locally?

Partly. glab ci lint checks the syntax and you can run the same commands in the same image with docker run -it node:24-alpine sh. For anything involving GitLab variables or runners, the fastest loop is a branch and a push.

Is .gitlab-ci.yml the only place the configuration can live?

It is the default. You can change the path in project settings, and lesson 12 shows how to pull in configuration from other files, projects and the CI/CD Catalog with include.

↑ ↓ navigate Enter open Esc close