← All cheatsheets

CI/CD

GitLab CI/CD — pipelines, jobs, and runners

Fast lookup for GitLab CI/CD under pressure: the .gitlab-ci.yml stages/jobs/script skeleton, rules for when a job runs, needs for DAG ordering, artifacts vs cache, masked/protected CI/CD variables, runners and tags, environments with manual gates, and how to debug a failed job with the job log and CI Lint.

Docs-checkedgitlabci-cdpipelinesrunnersyaml

Quick reference — reach for these first

Pipeline skeletonstages: [build, test] build: stage: build script: ["make build"]stages orders phases; each job names a stage and runs script. No stages key = all jobs in the default test stage.
Run job conditionallyrules: - if: '$CI_COMMIT_BRANCH == "main"' - when: neverrules:if evaluates top-down; first match wins. Replaces only/except. Add when: never as a final catch-all to skip otherwise.
Pass build outputartifacts: paths: [dist/] expire_in: 1 weekProducer job uploads paths; downstream jobs in later stages download them automatically (or scope with needs/dependencies).
Cache dependenciescache: key: $CI_COMMIT_REF_SLUG paths: [node_modules/]Cache is a speed optimization restored across runs by key — not a reliable job-to-job handoff. Use artifacts for build outputs.
DAG ordering (needs)test: stage: test needs: [build]needs starts a job as soon as its listed jobs finish, ignoring stage boundaries, and pulls their artifacts. Empty needs: [] starts immediately.

Pipeline flow: stages, needs, artifacts, runners

GitLab CI/CD pipeline flowA commit triggers a three-stage pipeline (build, test, deploy); build publishes artifacts consumed by test, needs makes test start early, deploy is a manual gate, and all jobs run on runners matched by tag.stage: buildstage: teststage: deploygit pushcommitcompilescript: makeunit testsneeds: [build]deploywhen: manualartifacts: dist/manual gatecache: keyGitLab Runnerpicks a job only when its tags match the job's tags · shared or specific · docker / shell executor

Text equivalent: A commit triggers a pipeline with three stages — build, test, deploy. The build job publishes artifacts that the test job consumes; needs lets test start as soon as build finishes rather than waiting for the whole stage. Deploy is a manual gate to the production environment. All jobs run on GitLab Runners, which pick up a job only when their tags match the job's tags. Cache is restored across pipeline runs by key, separate from artifacts.

Common tasks

Config · Runners · Debug

ConfigRunnersDebug
Create a minimal pipeline# .gitlab-ci.yml build: script: ["echo building"]Push to a branch; a pipeline appears under CI/CD > Pipelines and the job turns green.
Define explicit stage orderstages: [build, test, deploy]Jobs run build then test then deploy; the pipeline graph shows three ordered columns.
Run a job only on the default branchrules: - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'Job appears in main pipelines and is absent from feature-branch pipelines.
Run a job for merge requestsrules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'Opening an MR produces a pipeline that includes the job.
Publish build artifactsartifacts: paths: [dist/] expire_in: 3 daysFinished job shows a Download artifacts button; dist/ is present in later jobs.
Cache dependencies between runscache: key: $CI_COMMIT_REF_SLUG paths: [.npm/]Second pipeline log shows "Successfully extracted cache" and installs faster.
Order jobs as a DAGdeploy: needs: [build, test]deploy starts the moment build and test finish, not after the whole stage.
Add a masked CI/CD variable# Settings > CI/CD > Variables > Add # Flags: MaskedThe value is rendered as [MASKED] in job logs instead of in clear text.
Protect a secret to protected refs# Same variable > Flag: ProtectedVariable is injected on protected branches/tags only; it is empty on an unprotected feature branch.
Register a specific runner with a taggitlab-runner register --tag-list docker,linuxRunner shows in Settings > CI/CD > Runners; a job with tags: [docker] is picked up by it.
Target a job to tagged runnersdeploy: tags: [docker]Job runs only on a runner advertising that tag; otherwise it stays pending.
Add a manual deploy gate to an environmentdeploy_prod: environment: production when: manualPipeline pauses with a play button; production shows in Operate > Environments after the click. [PROD-CHANGING]
Validate the YAML with CI Lint# CI/CD > Pipelines > CI lint # paste .gitlab-ci.ymlShows "Syntax is correct" and lists the jobs it parsed.
Read a failed job's log# Pipeline > failing job > view logLog tail shows the exact failing command and a non-zero exit code.

A job fails — from red log to green pipeline

debug

1
Open the failed job in the pipeline graph and read the end of the log: the failing command and its exit code.
# CI/CD > Pipelines > failed job > scroll to log tail
# $ npm run test
# exit code 1 (3 specs failing)
2
Reproduce that exact script step locally in a clean checkout so you are not debugging through CI.
npm ci && npm run test
# 3 failing — matches CI
3
Fix the code or config and re-run the step locally until it is green.
npm run test
# Tests: 42 passed, 0 failed
4
Validate the pipeline YAML before pushing, so a config typo doesn't cost another round-trip.
# CI/CD > Pipelines > CI lint (paste .gitlab-ci.yml)
# Syntax is correct
5
Commit and push; a new pipeline is created for the branch.
git commit -am 'fix: failing unit tests' && git push
# pipeline #1234 created, running
6
Verify: watch the pipeline finish and confirm every stage is green.
# CI/CD > Pipelines > #1234
# passed — build, test, deploy all green

Troubleshooting — symptom → first check → next check

SymptomFirst checkEstablishesNext check
Pipeline did not run at all after a pushOpen CI/CD > Pipelines; check workflow:rules and each job's rules/only for a condition that excludes this ref, and confirm a runner is available to the project.Whether config filtered the pipeline out (rules/workflow) versus no eligible runner to create it.Loosen or add a matching rules:if (e.g. branch or merge_request_event); if config is fine, enable a shared runner or register one.
Job stuck in pending, never startsCompare the job's tags: to the tags on available runners in Settings > CI/CD > Runners; confirm at least one runner is online and not paused.Whether no runner advertises the required tag, or no runner is online/enabled for the project.Add a runner with the matching tag, remove the unneeded tags: from the job, or un-pause/enable a shared runner.
Secret/variable is empty inside the jobIn Settings > CI/CD > Variables check the variable's Protected and Environment scope flags against the current branch and the job's environment.Whether a Protected variable is being used on an unprotected branch, or the scope/name does not match this job.Run on a protected branch, widen the environment scope, or uncheck Protected for non-protected refs; verify the exact name.
Artifact or cache not available in a later jobConfirm the producer declares artifacts:paths, and the consumer is in a later stage or lists the producer in needs/dependencies; check artifacts did not expire.Whether output was never published, was scoped away by needs, or relied on cache (best-effort) instead of artifacts.Use artifacts for build outputs (not cache); add the producer to the consumer's needs; extend expire_in.
CI complains the YAML is invalidPaste .gitlab-ci.yml into CI/CD > Pipelines > CI lint to get the exact line and keyword at fault.Whether it is a syntax/indentation error versus an unknown or misplaced keyword.Fix the flagged line (indentation, list vs map, unknown key) and re-run CI Lint until it reports Syntax is correct.
A job fails on one of its commandsOpen the job log and read the tail: the last executed command and its exit code.Which script step failed and whether it is a code error, a missing dependency, or an environment difference.Reproduce that exact command locally in a clean checkout, fix, then push and re-run the pipeline.