Skip to main content

Node.js Pipeline Template

The node.yml pipeline template provides a complete CI/CD workflow for Node.js applications with GitOps-based Kubernetes deployments.

Overview​

This template orchestrates the entire deployment lifecycle for Node.js applications, including:

  • Docker image building
  • Version validation
  • GitOps-based deployment to Kubernetes via Argo CD
  • Release management

Usage​

include:
  - project: 'welance/platform/pipelines/templates/pipeline/git-flow'
    ref: release/1.0.0
    file: 'node.yml'
variables:
  PROJECT_ID: 'p222-01'
  DEV_TARGET: 'welance'
  STAGING_TARGET: 'welance'
  PRODUCTION_TARGET: 'welance'

Pipeline Stages​

The Node.js pipeline template includes the following stages:

  1. init - Version validation and preparation
  2. build - Docker image building
  3. deploy - GitOps-based deployment to Kubernetes
  4. release - Release tagging and GitLab release creation

Included Job Templates​

The template includes the following job templates from the ci-jobs repository:

Build Jobs​

  • build/docker-build.yml - Docker image building

Configuration Jobs​

  • config/deploy_config.yml - Infrastructure configuration

Deploy Jobs​

  • deploy/k8s-deploy.yml - Kubernetes deployments
  • deploy/gitops-and-value-sync.yml - GitOps deployments

Release Jobs​

  • release/merge-and-tag.yml - Merge request handling and tagging

Default Variables​

variables:
  CI_ARTIFACT_TOKEN: $CI_ARTIFACT_PULL_TOKEN
  REGISTRY_ID: 4495833
  DEV_TARGET: 'welance'
  STAGING_TARGET: 'welance'
  PRODUCTION_TARGET: 'welance'

Variable Details​

  • CI_ARTIFACT_TOKEN: Token for pulling artifacts from other jobs
  • REGISTRY_ID: Container registry project ID
  • DEV_TARGET: Deployment target for develop environment (only welance supported)
  • STAGING_TARGET: Deployment target for staging environment (only welance supported)
  • PRODUCTION_TARGET: Deployment target for production environment (only welance supported)

Continuous Integration Workflow​

Build Jobs​

build_develop_job​

  • Stage: build
  • Extends: .docker-build
  • Needs: npm_build (optional), composer_build (optional)
  • Environment: develop
  • Runs on: develop branch
  • Artifacts: helm-chart/, infrastructure_code/, .env*, pipeline.env

build_staging_job​

  • Stage: build
  • Extends: .docker-build
  • Needs: check_test, npm_build (optional), composer_build (optional)
  • Environment: staging
  • Runs on: release/* and hotfix/* branches

build_production_job​

  • Stage: build
  • Extends: .docker-build
  • Needs: check_prod, npm_build (optional), composer_build (optional)
  • Environment: production
  • Runs on: MRs targeting master branch

Optional Build Dependencies​

All build jobs support optional dependencies:

  • npm_build (optional) - If the application includes Node.js dependencies
  • composer_build (optional) - If the application includes PHP dependencies

These are marked as optional: true, so the pipeline will continue even if these jobs don't exist.

Continuous Delivery Workflow​

Version Validation​

check_test​

  • Stage: init
  • Purpose: Validates semantic versioning for staging deployments
  • Runs on: release/* and hotfix/* branches
  • Output: Sets VERSION={RELEASE}.rc{CI_PIPELINE_IID} (e.g., 1.0.0.rc42)

check_prod​

  • Stage: init
  • Purpose: Validates semantic versioning for production deployments
  • Runs on: MRs targeting master branch
  • Output: Sets VERSION={RELEASE}, TAG=v{VERSION}, EXTRA_DESCRIPTION

Deployment (Welance/Kubernetes)​

The Node.js pipeline only supports Welance (Kubernetes/GitOps) deployments:

deploy_develop_job​

  • Stage: deploy
  • Extends: .gitops-update-values-and-sync
  • Target: Argo CD application
  • Runs on: develop branch (when DEV_TARGET == "welance")
  • Updates: GitOps repository with new image tag and environment variables

deploy_staging_job​

  • Stage: deploy
  • Extends: .gitops-update-values-and-sync
  • Target: Argo CD application
  • Runs on: release/* and hotfix/* branches (when STAGING_TARGET == "welance")
  • Updates: GitOps repository with new image tag and environment variables

deploy_production_job​

  • Stage: deploy
  • Extends: .gitops-update-values-and-sync
  • Target: Argo CD application
  • Runs on: MRs targeting master (when PRODUCTION_TARGET == "welance")
  • When: manual
  • Updates: GitOps repository with new image tag and environment variables

Release Jobs​

merge_and_tag​

  • Stage: release
  • Extends: .merge_and_tag_job
  • Needs: deploy_production_job
  • When: manual (for production)
  • Merges MR, creates realign branch, creates alignment MR

release_job​

  • Stage: release
  • Image: registry.gitlab.com/gitlab-org/release-cli:latest
  • Needs: merge_and_tag
  • Creates GitLab release with tag and description

Required Variables​

  • PROJECT_ID - Your project identifier (e.g., p222-01)
  • STORAGE_USER_ID - User ID for storage permissions

Environment-Specific Variables​

For Welance (Kubernetes) Deployments​

  • NOPROD_TARGET_REPO - GitOps repository for non-production
  • PROD_TARGET_REPO - GitOps repository for production
  • NOPROD_ARGOCD_SERVER - Argo CD server for non-production
  • PROD_ARGOCD_SERVER - Argo CD server for production
  • NOPROD_ARGOCD_USER / NOPROD_ARGOCD_PASSWORD - Argo CD credentials
  • PROD_ARGOCD_USER / PROD_ARGOCD_PASSWORD - Argo CD credentials
  • NOPROD_GITLAB_USER / NOPROD_GITLAB_PASSWORD - GitLab credentials for GitOps

Example Configuration​

include:
  - project: 'welance/platform/pipelines/templates/pipeline/git-flow'
    ref: release/1.0.0
    file: 'node.yml'
variables:
  PROJECT_ID: 'p222-01'
  DEV_TARGET: 'welance'
  STAGING_TARGET: 'welance'
  PRODUCTION_TARGET: 'welance'
  STORAGE_USER_ID: '1000'
  NOPROD_TARGET_REPO: 'https://gitlab.com/welance/platform/gitops/noprod.git'
  PROD_TARGET_REPO: 'https://gitlab.com/welance/platform/gitops/prod.git'
  NOPROD_ARGOCD_SERVER: 'argocd-noprod.welance.com'
  PROD_ARGOCD_SERVER: 'argocd-prod.welance.com'

Branch Strategy​

  • develop - Continuous integration and deployment to develop environment
  • release/{version} - Build, test, and deploy to staging
  • hotfix/{version} - Build, test, and deploy to staging
  • master (via MR) - Build, test, and deploy to production (manual)

Version Tagging​

  • Develop: Uses pipeline ID for unique versions
  • Staging: `{RELEASE}.rc{CI_PIPELINE_IID}` (e.g., 1.0.0.rc42)
  • Production: `{RELEASE}` (e.g., 1.0.0)

Caching​

The pipeline caches Node.js modules:

cache:
  key: "$CI_PROJECT_NAME"
  paths:
    - './.node_modules/'

This speeds up subsequent pipeline runs by reusing installed dependencies.

GitOps Workflow​

The Node.js pipeline uses GitOps for all deployments:

  1. Build: Docker image is built and pushed to registry
  2. GitOps Update: Pipeline updates Helm values in GitOps repository:
    • Updates image.tag with new version
    • Updates image.commit.* with commit information
    • Updates envFileContent with environment variables from .env.dev, .env.staging, or .env.production
  3. Argo CD Sync: Pipeline triggers Argo CD to sync the application
  4. Deployment: Argo CD deploys the new version to Kubernetes

Differences from Other Pipelines​

  • Uses .docker-build: Unlike Directus which uses .docker-compose-build, Node.js uses .docker-build
  • Targets master Branch: Uses master instead of main for production
  • Optional Dependencies: Supports optional npm_build and composer_build for flexibility
  • Single Deployment Target: Only supports Welance (Kubernetes), no Docker/VM/Mittwald options
  • Node.js Caching: Includes specific caching for Node.js modules

Prerequisites​

  • Dockerfile: Project must have a Dockerfile for building the application
  • GitLab Container Registry: Must be enabled for storing images
  • GitOps Repository: Must be configured and accessible
  • Argo CD: Must be configured and accessible
  • Semantic Versioning: Branch names must follow release/{version} or hotfix/{version} format

Notes​

  • Production deployments require manual approval
  • All deployments use GitOps workflow with Argo CD
  • The pipeline validates semantic versioning before staging/production deployments
  • Optional build jobs (npm_build, composer_build) allow flexibility for projects that may or may not need them
  • Node.js modules are cached to speed up pipeline execution
  • Release jobs create GitLab releases with container image links
  • The pipeline targets master branch (not main) for production
  • Environment-specific .env files (.env.dev, .env.staging, .env.production) are used for GitOps deployments