Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท Administration and Best Practices

Pipeline Efficiency Best Practices

Make GitLab pipelines faster and cheaper: needs and the DAG, rules:changes, caching, interruptible jobs, parallel tests, small images and shallow clones, with a critical-path model.

A slow pipeline is a tax paid on every change. If it takes 40 minutes, developers batch their work, switch to other tasks and lose focus; if it takes 8 minutes, they iterate quickly. Minutes also cost money on shared runners. Optimizing a pipeline is the same as optimizing any program: measure first, then fix the biggest cost.

This lesson gives a checklist of the techniques with the biggest effect, plus a simulator that computes a pipeline's duration so you can see why each one helps. The YAML is read-only (it needs a GitLab instance); the examples are runnable JavaScript models.

Measure first

Open Build > Pipelines and look at a typical run: the pipeline duration and the individual job durations, and in the CI/CD analytics page the trend of duration and failure rate. Ask three questions:

  1. Which stage or job dominates the critical path (the longest chain of dependent jobs)?
  2. Which jobs spend most of their time waiting for a runner (queue time) instead of working?
  3. Which jobs run when they are not needed (a docs change that runs the full test suite)?

Without those answers you may speed up a job that was never on the critical path, and the pipeline total does not move.

Use needs to build a DAG

By default, jobs of the next stage wait for all jobs of the previous stage. If build_web takes 2 minutes and build_docs takes 10, test_web still waits 10. The needs keyword creates a directed acyclic graph (DAG): a job starts as soon as the jobs it names are done.

YAML
stages: [build, test, deploy]

build_web:
  stage: build
  script: ./build-web.sh

build_docs:
  stage: build
  script: ./build-docs.sh

test_web:
  stage: test
  needs: [build_web]
  script: ./test-web.sh

deploy_web:
  stage: deploy
  needs: [test_web]
  script: ./deploy-web.sh

Now test_web and deploy_web do not wait for the slow documentation build. needs also controls which artifacts a job downloads: with needs, a job fetches artifacts only from the listed jobs instead of every earlier job, which saves time too.

flowchart LR
  BW["build_web 2m"] --> TW["test_web 5m"]
  BD["build_docs 10m"] --> DD["deploy_docs 1m"]
  TW --> DW["deploy_web 1m"]

With needs the web path takes 8 minutes while documentation finishes in parallel.

Run only what a change requires

  • rules:changes starts a job only when certain files changed, for example paths: ["frontend/**/*"]. Backend-only changes skip the frontend tests. Take care in a monorepo that shared files also trigger the right jobs (see Project: Release Automation for rule patterns).
  • Merge request pipelines ($CI_PIPELINE_SOURCE == "merge_request_event") avoid running two pipelines for the same commit (a branch pipeline plus an MR pipeline). Use workflow:rules to choose one.
  • Parent-child pipelines and dynamic child pipelines split a big monorepo into parts, each with its own small file.
  • Run the expensive jobs (full end-to-end tests, DAST) on merge to main or nightly, and cheap checks on every push.

Fail fast and cancel the rest

Put quick checks (lint, unit tests, secret detection) first, so errors show up in one minute instead of thirty. Use interruptible: true on jobs that are safe to stop, and enable auto-cancel redundant pipelines so a new push cancels the older, now pointless pipeline of the same branch:

YAML
workflow:
  auto_cancel:
    on_new_commit: interruptible

test:
  interruptible: true
  script: ./run-tests.sh

deploy_production:
  interruptible: false
  script: ./deploy.sh

Never mark deploy jobs interruptible; stopping a deploy halfway can leave a broken state.

Caching and artifacts

Reinstalling dependencies is the biggest hidden cost. Use cache with a key based on the lock file, so it changes only when dependencies change:

YAML
default:
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - .npm/
    policy: pull-push

install_check:
  script:
    - npm ci --cache .npm --prefer-offline

Remember: a cache is an optimization that may be missing (it is stored on the runner or in shared storage, per runner configuration) and an artifact is a result that later jobs rely on. Set expire_in on artifacts so storage does not grow, and policy: pull on jobs that only read the cache.

Other speed-ups

  1. Small, pre-built images. Pulling a 1.5 GB image for each job costs more than running the job. Build a company CI image with your tools baked in and use a slim base. Use the dependency proxy to avoid public-registry limits and slow pulls (see Container Registry).
  2. Shallow clones. GIT_DEPTH: 20 (the default in newer projects) fetches only recent history. Set GIT_STRATEGY: none for jobs that need no source.
  3. Parallel tests. parallel: 4 runs four copies of a job, each with CI_NODE_INDEX and CI_NODE_TOTAL, so your test runner can split files; parallel: matrix: runs a grid of versions.
  4. Right-sized runners. A queue of jobs on a tiny runner is slower than a bigger machine; autoscaling runners scale with demand.
  5. Retry only flaky steps with retry: { max: 1, when: runner_system_failure }, and track flaky tests rather than hiding them.
  6. Clean YAML with extends, include and !reference, so a fix to one place helps all pipelines.
  7. Keep job logs reasonable. Printing megabytes of output slows jobs and the page.

Stand-in: the critical path of a pipeline

The first example computes pipeline duration two ways: stage-by-stage (each stage waits for the slowest job of the previous stage) and with needs (each job starts when its dependencies finish).

JS Stages versus needs

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

No output.

Run it: stage by stage takes 17 minutes, with needs 11. The longest chain (build_docs then deploy_docs, 10 + 1) sets the time, so speeding up a job that is not on it changes nothing.

The second example estimates the effect of caching and parallel tests on a test job, using a small cost model.

JS Cache and parallel tests

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does needs change about job order?

    needs builds a dependency graph, so independent paths run in parallel regardless of stage boundaries.
  2. 2. Which jobs should never be marked interruptible?

    Stopping a deploy halfway can leave an inconsistent environment, so deploy jobs should run to completion.
  3. 3. What is a good cache key for npm dependencies?

    A key derived from the lock file changes exactly when the dependencies change. A fixed key never refreshes; the SHA never reuses.
  4. 4. Why does making a job that is off the critical path faster not shorten the pipeline?

    Total time equals the critical path. Optimize jobs on that path first.

Summary

  • Measure pipeline and job times, find the critical path and the queue time, then optimize what dominates.
  • Use needs for a DAG, rules:changes and workflow:rules to run less, and fail fast with cheap checks first.
  • Cache by lock-file key, keep images small, clone shallowly, and split slow test suites with parallel.
  • Cancel redundant pipelines with interruptible, but never deploy jobs.

Next: Branching and Workflow Best Practices