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.
Quick reference — reach for these first
stages: [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.rules:
- 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.artifacts:
paths: [dist/]
expire_in: 1 weekProducer job uploads paths; downstream jobs in later stages download them automatically (or scope with needs/dependencies).cache:
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.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
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
| Config | Runners | Debug |
|---|---|---|
| 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 order | stages: [build, test, deploy] | Jobs run build then test then deploy; the pipeline graph shows three ordered columns. |
| Run a job only on the default branch | rules:
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' | Job appears in main pipelines and is absent from feature-branch pipelines. |
| Run a job for merge requests | rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"' | Opening an MR produces a pipeline that includes the job. |
| Publish build artifacts | artifacts:
paths: [dist/]
expire_in: 3 days | Finished job shows a Download artifacts button; dist/ is present in later jobs. |
| Cache dependencies between runs | cache:
key: $CI_COMMIT_REF_SLUG
paths: [.npm/] | Second pipeline log shows "Successfully extracted cache" and installs faster. |
| Order jobs as a DAG | deploy:
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: Masked | The value is rendered as [MASKED] in job logs instead of in clear text. |
| Protect a secret to protected refs | # Same variable > Flag: Protected | Variable is injected on protected branches/tags only; it is empty on an unprotected feature branch. |
| Register a specific runner with a tag | gitlab-runner register --tag-list docker,linux | Runner shows in Settings > CI/CD > Runners; a job with tags: [docker] is picked up by it. |
| Target a job to tagged runners | deploy:
tags: [docker] | Job runs only on a runner advertising that tag; otherwise it stays pending. |
| Add a manual deploy gate to an environment | deploy_prod:
environment: production
when: manual | Pipeline 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.yml | Shows "Syntax is correct" and lists the jobs it parsed. |
| Read a failed job's log | # Pipeline > failing job > view log | Log tail shows the exact failing command and a non-zero exit code. |
A job fails — from red log to green pipeline
debug
# CI/CD > Pipelines > failed job > scroll to log tail
# $ npm run test
# exit code 1 (3 specs failing)npm ci && npm run test
# 3 failing — matches CInpm run test
# Tests: 42 passed, 0 failed# CI/CD > Pipelines > CI lint (paste .gitlab-ci.yml)
# Syntax is correctgit commit -am 'fix: failing unit tests' && git push
# pipeline #1234 created, running# CI/CD > Pipelines > #1234
# passed — build, test, deploy all greenTroubleshooting — symptom → first check → next check
| Symptom | First check | Establishes | Next check |
|---|---|---|---|
| Pipeline did not run at all after a push | Open 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 starts | Compare 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 job | In 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 job | Confirm 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 invalid | Paste .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 commands | Open 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. |
References
- GitLab .gitlab-ci.yml keyword referencedocs.gitlab.com
- rules keyword — control when jobs rundocs.gitlab.com
- CI/CD variables (masked & protected)docs.gitlab.com
- GitLab Runner (tags & executors)docs.gitlab.com
- Validate CI configuration with CI Lintdocs.gitlab.com