Skip to content

GitLab CI pipelines: jobs, stages, runners, and review apps

Lay down a GitLab CI pipeline that builds, tests, and deploys with the right caching, artifacts, and review apps — and clean rules for which branches trigger what.

You inherit a GitLab project where the pipeline takes 22 minutes, every job re-downloads the entire node_modules tree, and the deploy stage uses a shell runner with a permanently-cached SSH key on the host. The CI gives the right answer eventually, but no one trusts it and people merge on a pink dashboard. This article walks the operator changes that take a .gitlab-ci.yml from “works on my MR” to something that holds up in production.

How to verify

Inspect the current pipeline definition and runner topology from the CLI:

cat .gitlab-ci.yml
glab ci view
glab ci status
glab ci list --per-page 20
glab runner list

In the UI, Project → Settings → CI/CD shows the variables (look for protected and masked flags), the runner registration, and the cache settings. A protected variable that isn’t actually protected is a frequent leak path.

What’s happening

A GitLab CI pipeline is the graph of jobs derived from .gitlab-ci.yml and any included files. Jobs are grouped into stages that execute sequentially by default; jobs within a stage run in parallel. Each job is dispatched to a GitLab Runner — a process that polls GitLab for work, picks up a job, runs it in an executor (shell, Docker, Kubernetes, or VM), and reports back. Runners can be shared (provided by GitLab), group-level (shared by all projects in a group), or project-specific.

The properties that separate a first-week pipeline from a production one are: rules: blocks that decide when each job runs based on the branch, the changes, or the pipeline source; a cache: strategy keyed on the lock file so dependency installs are seconds not minutes; an artifacts: declaration that passes only what the next stage actually needs; and needs: keywords that let stages run as a DAG instead of a strict sequence.

The procedure

  1. Pick the right runner executor. Shell runners are a security hole — they execute job scripts directly on the host and one bad job can pwn the runner. Use the Docker or Kubernetes executor for any project where contributors can push changes that hit CI. Register a project runner with a tag so you can route specific jobs to specific machines.

    gitlab-runner register \
      --url https://gitlab.example.com/ \
      --token "$REGISTRATION_TOKEN" \
      --executor docker \
      --docker-image alpine:3.20 \
      --tag-list "linux,docker,project-x"
  2. Define stages explicitly. The default stages: list (build, test, deploy) is fine for most apps; spell it out so future readers can see the contract.

    stages:
      - build
      - test
      - deploy
  3. Cache the dependency tree. Key the cache on the lock file so a manifest change invalidates it; share it across branches with policy: pull-push on the install job and policy: pull on downstream jobs that only read.

    .node-cache: &node-cache
      key:
        files: [package-lock.json]
      paths: [node_modules/]
    
    install:
      stage: build
      image: node:20-alpine
      script: npm ci
      cache:
        <<: *node-cache
        policy: pull-push
  4. Use rules: not only:/except:. The only/except keywords are legacy and ambiguous when combined. rules: is explicit: each rule has an if:, optional changes: or exists:, and a result (when: on_success / manual / never).

    deploy:prod:
      stage: deploy
      rules:
        - if: $CI_COMMIT_BRANCH == "main"
          when: manual
        - when: never
  5. Wire review apps for MRs. A review app is a per-MR ephemeral environment with a unique URL. The environment: block declares it; on_stop: references a teardown job that runs when the MR is closed or merged.

    review:
      stage: deploy
      script: ./deploy-review.sh
      environment:
        name: review/$CI_COMMIT_REF_SLUG
        url: https://$CI_COMMIT_REF_SLUG.review.example.com
        on_stop: review:stop
      rules:
        - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  6. Move secrets to the project’s secret store. GitLab supports HashiCorp Vault and external secrets via OIDC — id_tokens: produces a JWT the runner exchanges for cloud credentials. Long-lived API keys in CI/CD variables are the same problem as long-lived keys in GitHub Actions secrets.

Common pitfalls

  • A shared runner with privileged Docker enabled is effectively root on the host — separate trusted and untrusted workloads onto separate runners.
  • before_script: defined at the top level runs before every job including the cleanup job for the review app, which is rarely what you want.
  • artifacts: expire_in: 1 week is the default but paths: with a wildcard can balloon storage to gigabytes per pipeline.
  • A job that uses tags: [docker] but no runner has that tag will sit in pending forever — the pipeline appears stuck with no error.
  • protected: true on a variable only protects it on protected branches; if the variable is consumed by an MR pipeline, it will be empty.

In the engagements we run, GitLab CI is one of two default CI platforms (alongside GitHub Actions) — Docker-executor runners on isolated hosts, OIDC for cloud auth, review apps wired for every MR on customer-facing services, and pipeline duration tracked as an SLO. See /en/services/managed-operations/.