GitHub Actions Workflows – WordPress Plugin Boilerplate

The plugin ships three GitHub Actions workflows in .github/workflows/. They share a reusable setup step to keep dependency installation fast.

Workflows at a Glance

Workflow	File	Trigger	Purpose
Setup Environment	setup.yml	workflow_call	Installs and caches PHP/Node dependencies; shared by the other two workflows
Test / Analyse	test-analyse.yml	Push to any branch	Lints JS/CSS, builds assets, runs PHPStan, PHPCS, and PHPUnit application tests
Deploy	deploy.yml	Push of any tag	Builds the distributable archive and publishes a GitHub release

setup.yml

A reusable workflow (workflow_call) that the other two workflows call via uses: ./.github/workflows/setup.yml. It:

• Generates cache keys from composer.lock and package-lock.json.
• Installs Composer and NPM dependencies (skipped on cache hit).
• In prod mode, also runs npm run build to compile assets.
• Passes cache keys back as outputs so dependent jobs can restore the exact same cache.

test-analyse.yml

Runs on every branch push (with concurrency cancellation so stale runs are skipped). It calls setup.yml in dev mode, then runs jobs in two stages:

Stage 1 — parallel fast feedback

test-js — JS/CSS quality and build

• Lints JavaScript with npm run lint:js
• Lints styles with npm run lint:style
• Verifies the production build succeeds with npm run build

test-php — PHP static analysis

• Runs PHPStan static analysis (composer run phpstan:ci)
• Runs PHPCS (composer run phpcs:ci) and surfaces violations as inline PR annotations via cs2pr

Stage 2 — application tests

test-application — PHPUnit integration tests (runs after both stage 1 jobs pass)

• Runs PHPUnit in the isolated wp-env environment

Sequencing test-application after the static analysis jobs avoids spinning up Docker when faster checks have already found a problem.

deploy.yml

Triggered when any tag is pushed.

Release process

1. Update version files — replaces the version string in:

   • src/Demo_Plugin.php (PLUGIN_VERSION constant)
   • demo-plugin.php (plugin header Version:)
   • README.txt (Stable tag:)

2. Build — starts wp-env, compiles translations inside the container, then generates the distributable .zip with wp dist-archive. Files listed in .distignore (e.g. source maps, dev dependencies, test files) are automatically excluded from the archive — no manual cleanup needed.

3. Persist stable release versions — for stable tags only, the workflow commits the three changed files and pushes them back to the repository default branch. Stable releases are assumed to be created from that default branch.

4. Publish GitHub release — attaches the .zip as a release artifact.

Stable vs. prerelease tags

Tags whose name contains -alpha, -beta, or -rc (e.g. v1.0.0-beta.1) are automatically published as prereleases and are not marked as the latest release.

Prerelease tags can be created from any branch. The workflow will only replace version tags in the bundled ZIP and not persist them back to the repo.

All other tags produce stable releases that are eligible to become latest.

PHP Version Configuration

Changing the PHP version requires updates in multiple places.

composer.json

Update both the require constraint and the config.platform version:

"require": {
    "php": ">=8.0"
},
"config": {
    "platform": {
        "php": "8.0"
    }
}

Run composer update after changing these values.

Workflow files

Update the PHP version in both workflow files that invoke shivammathur/setup-php:

.github/workflows/setup.yml

- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.2'

.github/workflows/test-analyse.yml

- uses: shivammathur/setup-php@v2
  with:
    php-version: '8.0'
    tools: cs2pr

Also check phpstan.neon and phpcs.xml for any PHP-version-specific settings that may need updating.