GitLab CI/CD Pipelines

Overview

GitLab CI/CD runs pipelines defined in .gitlab-ci.yml. Jobs execute in stages on runners, producing artifacts and reporting status back to commits and merge requests.

• Built-in container images and caching
• First-class MR integration (statuses, environments)
• Flexible rules, needs, variables, schedules

Key concepts

• Pipeline: stages of jobs (build, test, deploy)
• Runner: executes jobs (shared or specific)
• Variables: project/group/instance or job-level
• Artifacts & Cache: share outputs between jobs
• Needs: DAG-style dependencies for parallelization

Example .gitlab-ci.yml (Node + Astro)

stages: [install, build, deploy]

variables:
  NODE_VERSION: 20
  NPM_FLAGS: --no-audit --no-fund

.default_node:
  image: node:$NODE_VERSION
  cache:
    key: ${CI_PROJECT_NAME}
    paths:
      - .npm/
  before_script:
    - npm config set cache .npm --global
    - npm ci $NPM_FLAGS

install:
  stage: install
  extends: .default_node
  script:
    - echo "Dependencies installed"
  artifacts:
    paths:
      - node_modules/
    expire_in: 1h

build:
  stage: build
  extends: .default_node
  needs: ["install"]
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

pages:
  stage: deploy
  image: alpine:3.19
  needs: ["build"]
  script:
    - mkdir -p public
    - cp -r dist/* public/
  artifacts:
    paths: [public]
  rules:
    - if: "$CI_COMMIT_BRANCH == 'main'"

Schedules

Use Pipeline Schedules to run periodic jobs (nightly builds, maintenance). See: ./gitlab-pipelines/scheduled-pipelines

Notifications

Configure notifications for job failures or pipeline completions via integrations (Slack, Teams) or webhooks. See: ./gitlab-pipelines/notifications

Failure handling

Use allow_failure, retries, and on_failure hooks; capture logs/artifacts for debugging. See: ./gitlab-pipelines/failure-handling

Subpages

• Introduction: ./gitlab-pipelines/introduction
• Scheduled pipelines: ./gitlab-pipelines/scheduled-pipelines
• Notifications: ./gitlab-pipelines/notifications
• Failure handling: ./gitlab-pipelines/failure-handling
• Templates & reuse: ./gitlab-pipelines/templates

Best practices

• Keep jobs fast and parallelize with needs
• Cache wisely; avoid caching node_modules unless necessary
• Use environment variables and masked CI variables for secrets
• Validate .gitlab-ci.yml with GitLab Lint before committing