Directus Pipeline Template

The directus.yml pipeline template provides a complete CI/CD workflow for Directus CMS applications with GitOps-based Kubernetes deployments.

Overview

This template orchestrates the entire deployment lifecycle for Directus CMS applications, including:

• Docker Compose-based 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: 'directus.yml'
variables:
  PROJECT_ID: 'p222-01'
  DEV_TARGET: 'welance'
  STAGING_TARGET: 'welance'
  PRODUCTION_TARGET: 'welance'

Pipeline Stages

The Directus pipeline template includes the following stages:

1. init - Version validation and preparation
2. build - Docker Compose-based 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 (includes docker-compose-build)

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-compose-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-compose-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-compose-build
• Needs: check_prod, npm_build (optional), composer_build (optional)
• Environment: production
• Runs on: MRs targeting master

Docker Compose Build

The Directus pipeline uses .docker-compose-build which:

• Builds images using docker-compose.yml
• Supports environment-specific .env files (.env.dev, .env.staging, .env.production)
• Tags and pushes images to the container registry

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
• Output: Sets VERSION={RELEASE}, TAG=v{VERSION}, EXTRA_DESCRIPTION

Deployment (Welance/Kubernetes)

The Directus 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: 'directus.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/'

Docker Compose Requirements

The Directus pipeline requires a docker-compose.yml file in the project root. The build process:

1. Copies environment-specific .env file (.env.dev, .env.staging, .env.production)
2. Builds the service using docker compose build
3. Tags the built image with the version
4. Pushes the image to the container registry

Example docker-compose.yml structure:

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    image: ${CI_REGISTRY_IMAGE}:${VERSION}

GitOps Workflow

The Directus 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
3. Argo CD Sync: Pipeline triggers Argo CD to sync the application
4. Deployment: Argo CD deploys the new version to Kubernetes

Differences from Craft Pipeline

• Build Method: Uses Docker Compose instead of plain Docker build
• Deployment Targets: Only supports Welance (Kubernetes), no Docker/VM/Mittwald options
• Optional Dependencies: npm_build and composer_build are optional (may not be needed for Directus)
• Simpler Structure: Fewer deployment paths and configurations

Notes

• Production deployments require manual approval
• All deployments use GitOps workflow with Argo CD
• The pipeline validates semantic versioning before staging/production deployments
• Docker Compose build supports environment-specific configuration files
• Release jobs create GitLab releases with container image links
• Optional build jobs (npm_build, composer_build) allow flexibility for projects that may or may not need them