Validate a GitLab CI Pipeline

GitLab CI/CD is GitLab's built-in continuous integration and delivery system, configured entirely through a .gitlab-ci.yml file in the repository root. When this file is valid and present, GitLab automatically runs pipelines on push, merge request creation, or manual trigger. When it has YAML errors, the pipeline simply doesn't start, and the error message in the GitLab UI can be vague. Validating locally before pushing catches these issues before they block your team's workflow. This example defines a three-stage pipeline: lint runs first, then test, then deploy. GitLab runs stages sequentially — all jobs in a stage must complete before the next stage starts. This ordering ensures your code is linted before tests run, and tests pass before deployment happens. Within a stage, if you have multiple jobs they run in parallel. Key components explained: the top-level stages list defines the order of execution and the valid stage values that jobs can use. The variables block sets environment variables available to all jobs. Each job block starts with a name (lint, test, deploy-production), declares which stage it belongs to, specifies the Docker image to run in, and lists the script commands to execute. The coverage: field on the test job is a powerful GitLab feature: it's a regex that extracts the coverage percentage from the test output, which GitLab displays on merge requests and tracks over time on the pipeline graph. The regex 'Lines\s*:\s*(\d+\.?\d*)%/' matches common coverage output formats. The only: - main on the deploy-production job is a crucial restriction: it ensures the deployment job only runs on the main branch, not on feature branches or merge request pipelines. The newer rules keyword provides more flexibility — you can use rules: if to match on branch names, variables, or pipeline sources. Common pitfalls: job names must not contain colons without quoting; the script key requires a list (each command on a separate line with a dash); stage values must exactly match what's declared in the top-level stages list (case-sensitive); environment variables in variables are strings and should be quoted if they contain spaces. Real-world scenarios: a monorepo pipeline that runs different jobs for backend and frontend changes using the changes keyword to filter which files triggered the pipeline; a release pipeline that builds Docker images and pushes to a registry when a tag is created.

stages:
  - lint
  - test
  - deploy

variables:
  NODE_ENV: test

lint:
  stage: lint
  image: node:20-alpine
  script:
    - npm ci
    - npm run lint

test:
  stage: test
  image: node:20-alpine
  script:
    - npm ci
    - npm test
  coverage: '/Liness*:s*(d+.?d*)%/'

deploy-production:
  stage: deploy
  script:
    - ./scripts/deploy.sh
  only:
    - main