Skip to main content

WordPress Pipeline Template

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

Overview​

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

  • Yarn-based frontend asset building (themes)
  • Composer-based PHP dependency installation
  • 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: 'wordpress.yml'
variables:
  PROJECT_ID: 'p222-01'
  DEV_TARGET: 'welance'
  STAGING_TARGET: 'welance'
  PRODUCTION_TARGET: 'welance'

Pipeline Stages​

The WordPress pipeline template includes the following stages:

  1. init - Version validation and preparation
  2. build - Frontend asset building, PHP dependency installation, and 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/composer-build.yml - PHP dependency installation
  • build/npm-build.yml - Node.js dependency installation (includes yarn-build)
  • 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​

yarn_build​

  • Stage: build
  • Extends: .yarn-build
  • Runs on: feature/, release/, hotfix/*, develop branches, and MRs targeting master
  • Purpose: Builds WordPress theme frontend assets using Yarn

composer_build​

  • Stage: build
  • Extends: .composer-build
  • Custom Scripts:
    • before_script:
      • Moves build/auth.json to project root
      • Replaces placeholders in auth.json with actual API keys:
        • GITLAB-PACKAGES-GROUP-TOKEN → $GITLAB_PACKAGES_GROUP_TOKEN
        • WPMUDEV_API_KEY → $WPMUDEV_API_KEY
        • ACF-PRO-KEY → $ACF_PRO_KEY
    • after_script: Removes auth.json for security
  • Runs on: feature/, release/, hotfix/*, develop branches, and MRs targeting master
  • Purpose: Installs PHP dependencies via Composer with private package authentication

build_develop_job​

  • Stage: build
  • Extends: .docker-build
  • Needs: yarn_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, yarn_build, composer_build
  • Environment: staging
  • Runs on: release/* and hotfix/* branches

build_production_job​

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

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 WordPress 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

WordPress-Specific Variables​

The composer_build job requires these API keys for private package authentication:

  • GITLAB_PACKAGES_GROUP_TOKEN - GitLab Packages group token for private Composer packages
  • WPMUDEV_API_KEY - WPMU Dev API key for premium plugins
  • ACF_PRO_KEY - Advanced Custom Fields Pro license key

These should be stored as masked and protected CI/CD variables.

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: 'wordpress.yml'
variables:
  PROJECT_ID: 'p222-01'
  DEV_TARGET: 'welance'
  STAGING_TARGET: 'welance'
  PRODUCTION_TARGET: 'welance'
  STORAGE_USER_ID: '1000'
  GITLAB_PACKAGES_GROUP_TOKEN: '$GITLAB_PACKAGES_GROUP_TOKEN'
  WPMUDEV_API_KEY: '$WPMUDEV_API_KEY'
  ACF_PRO_KEY: '$ACF_PRO_KEY'
  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
  • feature/* - Build and test only (yarn_build, composer_build)
  • 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.

Composer Authentication​

The WordPress pipeline includes special handling for Composer authentication:

  1. auth.json Template: A template auth.json file should exist in build/auth.json with placeholders:

    {
      "http-basic": {
        "gitlab.com": {
          "username": "gitlab-ci-token",
          "password": "GITLAB-PACKAGES-GROUP-TOKEN"
        },
        "wpmudev.com": {
          "username": "WPMUDEV_API_KEY",
          "password": "WPMUDEV_API_KEY"
        }
      },
      "github-oauth": {
        "github.com": "ACF-PRO-KEY"
      }
    }

  2. Dynamic Replacement: The composer_build job replaces placeholders with actual API keys from CI/CD variables

  3. Security: The auth.json file is removed after Composer installation to prevent exposure in artifacts

GitOps Workflow​

The WordPress pipeline uses GitOps for all deployments:

  1. Build:
    • Yarn builds theme assets
    • Composer installs PHP dependencies
    • 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 Yarn: WordPress themes typically use Yarn for frontend asset building (not npm)
  • Composer Authentication: Includes special handling for private Composer packages (GitLab Packages, WPMU Dev, ACF Pro)
  • Targets master Branch: Uses master instead of main for production
  • Single Deployment Target: Only supports Welance (Kubernetes), no Docker/VM/Mittwald options
  • Node.js Caching: Includes specific caching for Node.js modules
  • Required Build Dependencies: Both yarn_build and composer_build are required (not optional)

Prerequisites​

  • Dockerfile: Project must have a Dockerfile for building the application
  • auth.json Template: Must have build/auth.json with placeholders for API keys
  • GitLab Container Registry: Must be enabled for storing images
  • GitOps Repository: Must be configured and accessible
  • Argo CD: Must be configured and accessible
  • API Keys: GitLab Packages token, WPMU Dev API key, and ACF Pro key must be configured as CI/CD variables
  • 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
  • Yarn is used for WordPress theme asset building (typically in wp-content/themes/ directory)
  • Composer authentication is handled automatically via auth.json template replacement
  • The auth.json file is removed after use for security
  • 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