Skip to main content

Craft Pipeline Template

The craft.yml pipeline template provides a complete CI/CD workflow for Craft CMS applications with support for multiple deployment targets.

Overview​

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

  • Dependency installation (Composer and NPM)
  • Docker image building
  • Testing and validation
  • Deployment to multiple targets (Kubernetes, Docker hosts, Virtual Machines, Mittwald)
  • GitOps-based deployments
  • Release management

Usage​

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

Pipeline Stages​

The Craft pipeline template includes the following stages:

  1. init - Version validation and preparation
  2. build - Dependency installation and Docker image building
  3. deploy - Deployment to target environment
  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/composer-build.yml - PHP dependency installation
  • build/npm-build.yml - Node.js dependency installation
  • 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
  • deploy/rsync-deploy-mittwald.yml - Mittwald deployments
  • deploy/craft-docker-deploy.yml - Docker host deployments
  • deploy/craft-vm-deploy.yml - Virtual Machine 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 (welance, docker, virtualmachine, mittwald)
  • STAGING_TARGET: Deployment target for staging environment
  • PRODUCTION_TARGET: Deployment target for production environment

Continuous Integration Workflow​

Build Jobs​

npm_build​

  • Stage: build
  • Extends: .npm-build
  • Runs on: feature/, release/, hotfix/*, develop branches, and MRs targeting master

composer_build​

  • Stage: build
  • Extends: .composer-build
  • Runs on: feature/, release/, hotfix/*, develop branches, and MRs targeting master

build_develop_job​

  • Stage: build
  • Extends: .docker-build
  • Needs: npm_build, composer_build
  • 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, composer_build
  • Environment: staging
  • Runs on: release/* and hotfix/* branches (when STAGING_TARGET != "mittwald")

build_production_job​

  • Stage: build
  • Extends: .docker-build
  • Needs: check_prod, npm_build, composer_build
  • Environment: production
  • Runs on: MRs targeting master (when PRODUCTION_TARGET != "mittwald")

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 Targets​

The pipeline supports four deployment targets:

1. Welance (Kubernetes/GitOps)​

Develop Deployment:

  • Job: deploy_develop_job
  • Extends: .gitops-update-values-and-sync
  • Target: Argo CD application
  • Runs on: develop branch (when DEV_TARGET == "welance")

Staging Deployment:

  • Job: deploy_staging_job
  • Extends: .gitops-update-values-and-sync
  • Target: Argo CD application
  • Runs on: release/* and hotfix/* branches (when STAGING_TARGET == "welance")

Production Deployment:

  • Job: deploy_production_job
  • Extends: .gitops-update-values-and-sync
  • Target: Argo CD application
  • Runs on: MRs targeting master (when PRODUCTION_TARGET == "welance")
  • When: manual

2. Docker Host​

Staging Deployment:

  • Job: deploy_staging_docker_job
  • Extends: .ansible-craft-docker-deploy
  • Runs on: release/* and hotfix/* branches (when STAGING_TARGET == "docker")

Production Deployment:

  • Job: deploy_production_docker_job
  • Extends: .ansible-craft-docker-deploy
  • Runs on: MRs targeting master (when PRODUCTION_TARGET == "docker")
  • When: manual

3. Virtual Machine​

Staging Deployment:

  • Prep Job: deploy_staging-prep_vm_job (extends .docker-build-vm-setup)
  • Deploy Job: deploy_staging_vm_job (extends .ansible-craft-vm-deploy)
  • Runs on: release/* and hotfix/* branches (when STAGING_TARGET == "virtualmachine")

Production Deployment:

  • Prep Job: deploy_production-prep_vm_job (extends .docker-build-vm-setup)
  • Deploy Job: deploy_production_vm_job (extends .ansible-craft-vm-deploy)
  • Runs on: MRs targeting master (when PRODUCTION_TARGET == "virtualmachine")
  • When: manual

4. Mittwald​

Staging Deployment:

  • Job: deploy_staging_mittwald_job
  • Extends: .ansible-craft-deploy
  • Runs on: release/* branches or "mittwald-deploy" branch (when STAGING_TARGET == "mittwald")

Production Deployment:

  • Job: deploy_production_mittwald_job
  • Extends: .ansible-craft-deploy
  • Runs on: MRs targeting master (when PRODUCTION_TARGET == "mittwald")
  • When: manual

Release Jobs​

Each deployment target has its own release workflow:

  1. merge_and_tag (or `merge_and_tag-{target}`)

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

  2. release_job (or `release_job-{target}`)

    • Stage: release
    • Image: registry.gitlab.com/gitlab-org/release-cli:latest
    • Needs: merge_and_tag job
    • 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

For Docker Host Deployments​

  • STAGING_HOST / PRODUCTION_HOST - Target host addresses
  • STAGING_USER / PRODUCTION_USER - SSH usernames
  • STAGING_PORT / PRODUCTION_PORT - SSH ports
  • REGISTRY_USERNAME / REGISTRY_PASSWORD - Docker registry credentials

For Virtual Machine Deployments​

  • STAGING_HOST / PRODUCTION_HOST - Target VM addresses
  • STAGING_USER / PRODUCTION_USER - SSH usernames
  • STAGING_PORT / PRODUCTION_PORT - SSH ports

Example Configuration​

Kubernetes Deployment (Welance)​

include:
  - project: 'welance/platform/pipelines/templates/pipeline/git-flow'
    ref: release/1.0.0
    file: 'craft.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'

Docker Host Deployment​

include:
  - project: 'welance/platform/pipelines/templates/pipeline/git-flow'
    ref: release/1.0.0
    file: 'craft.yml'
variables:
  PROJECT_ID: 'p222-01'
  DEV_TARGET: 'welance'
  STAGING_TARGET: 'docker'
  PRODUCTION_TARGET: 'docker'
  STORAGE_USER_ID: '1000'
  STAGING_HOST: 'staging.example.com'
  PRODUCTION_HOST: 'prod.example.com'
  STAGING_USER: 'deploy'
  PRODUCTION_USER: 'deploy'
  STAGING_PORT: '22'
  PRODUCTION_PORT: '22'

Virtual Machine Deployment​

include:
  - project: 'welance/platform/pipelines/templates/pipeline/git-flow'
    ref: release/1.0.0
    file: 'craft.yml'
variables:
  PROJECT_ID: 'p222-01'
  DEV_TARGET: 'welance'
  STAGING_TARGET: 'virtualmachine'
  PRODUCTION_TARGET: 'virtualmachine'
  STORAGE_USER_ID: '1000'
  STAGING_HOST: 'staging-vm.example.com'
  PRODUCTION_HOST: 'prod-vm.example.com'

Branch Strategy​

  • develop - Continuous integration and deployment to develop environment
  • feature/* - Build and test only
  • 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/'

Notes​

  • Production deployments require manual approval
  • Each deployment target has its own release workflow
  • GitOps deployments update Helm values and sync Argo CD applications
  • Docker and VM deployments use Ansible playbooks
  • Mittwald deployments use rsync-based deployment
  • The pipeline validates semantic versioning before staging/production deployments
  • Release jobs create GitLab releases with container image links