Running wp-env in GitLab CI: difficulties with versioning and root access

[Antonin06]

Hi 👋

I'm currently working on integrating wp-env into a GitLab CI pipeline for a WordPress plugin project. The goal is to run PHPUnit tests automatically across multiple versions of PHP and WordPress.

So far, I’ve made it work almost completely, but there are a few caveats and unexpected behaviors that are making this more difficult than expected:

Setup

• CI is based on docker:dind
• @wordpress/env is installed via npm
• I provide .wp-env.json and set WP_ENV_HOME dynamically per pipeline using CI_PIPELINE_ID to isolate each environment
• su-exec wpuser is used to simulate a non-root environment (Docker rootless doesn’t fully work with wp-env due to permission errors)

Main issues encountered

1. --allow-root not available
   There is no way to force wp-env to run as root (--allow-root like WP-CLI).
   This makes CI workarounds a bit hacky, requiring:

• manually creating a user with adduser
• using su-exec wpuser to run any command related to wp-env

It would be helpful if wp-env could detect CI or root environments and allow this explicitly with a flag.

2. PHPUnit test files are not installed
   Despite wp-env starting correctly, the test files (/wordpress-phpunit) are not always installed or are missing functions.php, causing:

Could not find /wordpress-phpunit/includes/functions.php, have you run install-wp-tests.sh ?

As a workaround, I now manually clone the wordpress-develop repo and copy over the tests/phpunit/includes and tests/phpunit/data folders into /tmp/wordpress-tests-lib.
Not sure if this is due to a permission issue, or a bug in the way wp-env sets up the test environment in headless CI.

3. WordPress version is not respected in cli and tests-cli containers
   Even when specifying this in .wp-env.json:

"core": "WordPress/WordPress#tags/6.5" or "core": "WordPress/WordPress#6.5"

And setting WP_ENV_CORE and WP_ENV_PHP_VERSION before calling wp-env start, the version of WordPress in the cli and tests-cli containers remains the latest (e.g. 6.7.2).

The docker-compose.yml logs show 6.5 being fetched, but the version reported by wp core version is still 6.7.2 inside the containers. Idk if its related to .wp-env-cache.json. Each new pipeline contains same hash.

Suggestions

• Add a way to force version or reset .wp-env cache manually (--clear-cache?)
• Add a --allow-root option or handle root automatically in CI

gitlab-ci.yml (atm)

  - test

.parallel:
  parallel:
    matrix:
      - PHP_VERSION: ['8.3']
        WP_VERSION: ['6.5']

.installApkDependencies: &installApkDependencies |
  apk add --no-cache \
      subversion \
      shadow \
      nodejs \
      npm \
      unzip \
      git \
      su-exec \
      curl \
      bash \
      php${PHP_VERSION/./} \
      php${PHP_VERSION/./}-curl \
      php${PHP_VERSION/./}-phar \
      php${PHP_VERSION/./}-mbstring \
      php${PHP_VERSION/./}-iconv \
      php${PHP_VERSION/./}-openssl \
      php${PHP_VERSION/./}-dom \
      php${PHP_VERSION/./}-xml \
      php${PHP_VERSION/./}-xmlwriter \
      php${PHP_VERSION/./}-tokenizer \
      php${PHP_VERSION/./}-json \
      php${PHP_VERSION/./}-fileinfo \
      php${PHP_VERSION/./}-simplexml \
      php${PHP_VERSION/./}-xmlreader \
      php${PHP_VERSION/./}-zip \
      unzip \
      php${PHP_VERSION/./}-ctype \
      php${PHP_VERSION/./}-zlib


.installcomposer: &installcomposer |
  curl -sS https://getcomposer.org/installer -o composer-setup.php
  php composer-setup.php --install-dir=/usr/local/bin --filename=composer
  rm -rf composer-setup.php

test:
  stage: test
  image: docker:28.0.4
  services:
    - name: docker:28.0.4-dind
  variables:
    DOCKER_DRIVER: overlay2
    DOCKER_TLS_CERTDIR: "/certs"
    WP_ENV_HOME: "/tmp/wp-env-${CI_PIPELINE_ID}"
  before_script:
    - *installApkDependencies

    - "[ -f /usr/bin/php ] || ln -s /usr/bin/php${PHP_VERSION/./} /usr/bin/php"

    - *installcomposer

    - adduser -D -u 1000 wpuser
    - chown -R wpuser:wpuser .
    - su-exec wpuser composer config platform.php ${PHP_VERSION}
    - su-exec wpuser composer install -o
    - su-exec wpuser npm ci
    - pwd
    - ls -la
    - |
        cat <<EOF > .wp-env.json
        {
          "core": "WordPress/WordPress#${WP_VERSION}",
          "phpVersion": "${PHP_VERSION}",
          "plugins": ["."]
        }
        EOF
    - chown wpuser:wpuser .wp-env.json
    - cat .wp-env.json

  script:
    - echo "🚀 Testing PHP ${PHP_VERSION} on WP ${WP_VERSION}"    
    - su-exec wpuser sh -c "WP_ENV_HOME=${WP_ENV_HOME} WP_ENV_PHP_VERSION=${PHP_VERSION} WP_ENV_CORE=WordPress/WordPress#${WP_VERSION} npm run env:start-ci"
    - su-exec wpuser sh -c "WP_ENV_HOME=${WP_ENV_HOME} npm run env:path"
    - echo "📦 Cat wp-env-cache.json"
    - su-exec wpuser sh -c "cat ${WP_ENV_HOME}/c287f605c1617e6bdaefad1fe642ef53/wp-env-cache.json || echo 'No file!'"  
    - su-exec wpuser sh -c "WP_ENV_HOME=${WP_ENV_HOME} npm run env:cli wp core version"
    - su-exec wpuser sh -c "WP_ENV_HOME=${WP_ENV_HOME} npm run env:tests-cli wp core version"
    - su-exec wpuser sh -c "WP_ENV_HOME=${WP_ENV_HOME} npm run env:cli php -- -v"
    - su-exec wpuser sh -c "WP_ENV_HOME=${WP_ENV_HOME} npm run env run tests-wordpress bash /var/www/html/wp-content/plugins/example-plugin-env-ci/bin/install-wordpress-tests-lib.sh ${WP_VERSION}"
    - su-exec wpuser sh -c "WP_ENV_HOME=${WP_ENV_HOME} npm run env run tests-wordpress composer update -- -W --working-dir=wp-content/plugins/${PWD##*/}"
    - su-exec wpuser sh -c "WP_ENV_HOME=${WP_ENV_HOME} npm run env run tests-wordpress composer update -- --dev yoast/phpunit-polyfills -W --working-dir=wp-content/plugins/${PWD##*/}"
    - su-exec wpuser sh -c "WP_ENV_HOME=${WP_ENV_HOME} npm run env run tests-wordpress --env-cwd="wp-content/plugins/${PWD##*/}" vendor/bin/phpunit -- -c phpunit.xml.dist"

  after_script:
    - echo "AFTER SCRIPT"
    - su-exec wpuser npm run env:stop || true
    - echo "y" | su-exec wpuser npm run env:destroy || true
    - echo "🧹 Cleaning ${WP_ENV_HOME}"
    - su-exec wpuser sh -c 'rm -rf '"${WP_ENV_HOME}" || true
  parallel: !reference [.parallel,parallel]
  resource_group: parallel