build: stage: build image: node:${NODE_VERSION} script: - npm ci - npm run build artifacts: paths: - dist/ expire_in: 1 hour

test: stage: test image: node:${NODE_VERSION} script: - npm ci - npm run test coverage: '/All files[^|]|[^|]\s+([\d.]+)/'

deploy: stage: deploy script: - npm run deploy only: - main


## Pipeline Configuration

### Stages

```yaml
stages:
  - build
  - test
  - security
  - deploy
  - cleanup

default:
  image: node:20
  before_script:
    - npm ci
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/

Job Structure

job_name:
  stage: test
  image: node:20
  variables:
    NODE_ENV: test
  before_script:
    - npm ci
  script:
    - npm run test
  after_script:
    - npm run cleanup
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  artifacts:
    reports:
      junit: test-results.xml
  cache:
    paths:
      - node_modules/

Rules and Conditions

Basic Rules

deploy_production:
  stage: deploy
  script: npm run deploy:prod
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual
    - if: '$CI_COMMIT_TAG'
      when: on_success
    - when: never

deploy_staging:
  stage: deploy
  script: npm run deploy:staging
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "develop"'

Complex Rules

build:
  rules:
    # Run on MR
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      changes:
        - src/**/*
        - package.json
    # Run on main branch
    - if: '$CI_COMMIT_BRANCH == "main"'
    # Run on tags
    - if: '$CI_COMMIT_TAG'
    # Manual on other branches
    - when: manual
      allow_failure: true

Angular/TypeScript Pipeline

image: node:20

stages:
  - install
  - lint
  - test
  - build
  - deploy

variables:
  npm_config_cache: "$CI_PROJECT_DIR/.npm"
  CYPRESS_CACHE_FOLDER: "$CI_PROJECT_DIR/.cache/Cypress"

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - .npm/
    - .cache/
    - node_modules/

install:
  stage: install
  script:
    - npm ci
  artifacts:
    paths:
      - node_modules/
    expire_in: 1 day

lint:
  stage: lint
  dependencies:
    - install
  script:
    - npm run lint
    - npm run format:check

test:unit:
  stage: test
  dependencies:
    - install
  script:
    - npm run test:ci
  coverage: '/Lines\s*:\s*(\d+\.\d+)%/'
  artifacts:
    reports:
      junit: test-results/junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
    paths:
      - coverage/

test:e2e:
  stage: test
  dependencies:
    - install
  script:
    - npm run e2e:ci
  artifacts:
    when: on_failure
    paths:
      - cypress/screenshots/
      - cypress/videos/
    expire_in: 7 days

build:
  stage: build
  dependencies:
    - install
  script:
    - npm run build -- --configuration production
  artifacts:
    paths:
      - dist/
    expire_in: 1 week

deploy:staging:
  stage: deploy
  dependencies:
    - build
  script:
    - npm run deploy:staging
  environment:
    name: staging
    url: https://staging.example.com
  rules:
    - if: '$CI_COMMIT_BRANCH == "develop"'

deploy:production:
  stage: deploy
  dependencies:
    - build
  script:
    - npm run deploy:production
  environment:
    name: production
    url: https://example.com
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual
  only:
    - main

Docker Build Pipeline

stages:
  - build
  - test
  - release

variables:
  DOCKER_DRIVER: overlay2
  DOCKER_TLS_CERTDIR: "/certs"
  IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG

build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker build -t $IMAGE_TAG .
    - docker push $IMAGE_TAG

test:
  stage: test
  image: $IMAGE_TAG
  script:
    - npm run test

release:
  stage: release
  image: docker:24
  services:
    - docker:24-dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    - docker pull $IMAGE_TAG
    - docker tag $IMAGE_TAG $CI_REGISTRY_IMAGE:latest
    - docker push $CI_REGISTRY_IMAGE:latest
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

Artifacts

Upload Artifacts

build:
  script:
    - npm run build
  artifacts:
    name: "$CI_COMMIT_REF_SLUG-$CI_COMMIT_SHORT_SHA"
    paths:
      - dist/
      - coverage/
    reports:
      junit: test-results.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
    expire_in: 1 week
    when: on_success

Download Artifacts

deploy:
  dependencies:
    - build
  script:
    - ls dist/  # Artifacts from build job

Cache

Global Cache

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/
    - .npm/
  policy: pull-push

Job-specific Cache

install:
  cache:
    key: dependencies-$CI_COMMIT_REF_SLUG
    paths:
      - node_modules/
    policy: push

test:
  cache:
    key: dependencies-$CI_COMMIT_REF_SLUG
    paths:
      - node_modules/
    policy: pull

Environments

deploy:staging:
  stage: deploy
  script: ./deploy.sh staging
  environment:
    name: staging
    url: https://staging.example.com
    on_stop: stop:staging
    auto_stop_in: 1 week

stop:staging:
  stage: deploy
  script: ./cleanup.sh staging
  environment:
    name: staging
    action: stop
  when: manual

deploy:production:
  stage: deploy
  script: ./deploy.sh production
  environment:
    name: production
    url: https://example.com
  when: manual
  only:
    - main

Templates and Includes

Using Templates

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml
  - local: '.gitlab/ci/build.yml'
  - remote: 'https://gitlab.com/my-group/ci-templates/-/raw/main/node.yml'

# Or from project
include:
  - project: 'my-group/ci-templates'
    file: '/templates/node.yml'

Creating Templates

# .gitlab/ci/build.yml
.build_template:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

# Use in main .gitlab-ci.yml
build:app:
  extends: .build_template
  variables:
    APP_NAME: frontend

build:admin:
  extends: .build_template
  variables:
    APP_NAME: admin

Parallel Jobs

test:unit:
  parallel:
    matrix:
      - NODE_VERSION: ["18", "20", "22"]
        OS: ["ubuntu", "alpine"]
  image: node:${NODE_VERSION}-${OS}
  script:
    - npm run test

Monorepo (Nx) Pipeline

stages:
  - setup
  - affected

variables:
  NX_BRANCH: $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
  NX_BASE: origin/$NX_BRANCH

setup:
  stage: setup
  script:
    - npm ci
  cache:
    key: $CI_COMMIT_REF_SLUG
    paths:
      - node_modules/
  artifacts:
    paths:
      - node_modules/

affected:lint:
  stage: affected
  dependencies:
    - setup
  script:
    - npx nx affected -t lint --base=$NX_BASE --head=HEAD --parallel=3
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

affected:test:
  stage: affected
  dependencies:
    - setup
  script:
    - npx nx affected -t test --base=$NX_BASE --head=HEAD --parallel=3 --coverage
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

affected:build:
  stage: affected
  dependencies:
    - setup
  script:
    - npx nx affected -t build --base=$NX_BASE --head=HEAD --parallel=3
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

Security Scanning

include:
  - template: Security/SAST.gitlab-ci.yml
  - template: Security/Secret-Detection.gitlab-ci.yml
  - template: Security/Dependency-Scanning.gitlab-ci.yml

# Custom security job
security:npm:audit:
  stage: test
  script:
    - npm audit --production
  allow_failure: true

Variables

Predefined Variables

deploy:
  script:
    - echo "Branch: $CI_COMMIT_BRANCH"
    - echo "SHA: $CI_COMMIT_SHA"
    - echo "Tag: $CI_COMMIT_TAG"
    - echo "Pipeline ID: $CI_PIPELINE_ID"
    - echo "Project: $CI_PROJECT_NAME"

Custom Variables

variables:
  DEPLOY_SITE: "https://example.com"
  API_VERSION: "v2"
  
deploy:
  variables:
    DEPLOY_ENV: production
  script:
    - echo "Deploying to $DEPLOY_SITE"

Pages Deployment

pages:
  stage: deploy
  script:
    - npm run build
    - mv dist/ public/
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

Review Apps

review:
  stage: deploy
  script:
    - ./deploy-review.sh
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: https://$CI_COMMIT_REF_SLUG.review.example.com
    on_stop: stop_review
    auto_stop_in: 1 week
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

stop_review:
  stage: deploy
  script:
    - ./cleanup-review.sh
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop
  when: manual
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

Best Practices

Use cache effectively - Speed up pipelines
Artifact expiration - Save storage costs
Parallel jobs - Reduce pipeline duration
Rules over only/except - More flexible conditions
Templates for reusability - DRY pipelines
Environment management - Proper deployment tracking
Security scanning - Built-in templates
Resource optimization - Cancel redundant pipelines

Troubleshooting

Debug Pipeline

debug:
  script:
    - echo "CI_COMMIT_BRANCH=$CI_COMMIT_BRANCH"
    - echo "CI_PIPELINE_SOURCE=$CI_PIPELINE_SOURCE"
    - env | sort

Cancel Redundant Pipelines

workflow:
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
      when: never
    - if: '$CI_COMMIT_BRANCH'

Resources

GitLab CI Docs: https://docs.gitlab.com/ee/ci
Pipeline Reference: https://docs.gitlab.com/ee/ci/yaml
CI/CD Examples: https://docs.gitlab.com/ee/ci/examples

gitlab-ci

GitLab CI/CD

Basic Pipeline Structure