From dbc56953f3a8c8a7977d54aef0369992fd285d75 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Tue, 12 May 2026 13:57:07 +0530 Subject: [PATCH 01/43] feat(ci): add ci-test-js reusable workflow Single-job Jest runner with optional cross-run cache (enable-cache), monorepo support (working-dir), and overridable test-command. The Jest cache path is resolved via $HOME in a step output so both the actions/cache path and the JEST_CACHE_DIRECTORY env point at the same directory --- .claude/issues/3-ci-test-js.md | 62 ++++++++++++++++++++++++++++++++ .github/workflows/ci-test-js.yml | 61 +++++++++++++++++++++++++++++++ .yamllint.yml | 2 +- CHANGELOG.md | 11 ++++++ README.md | 22 ++++++++++++ 5 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 .claude/issues/3-ci-test-js.md create mode 100644 .github/workflows/ci-test-js.yml create mode 100644 CHANGELOG.md diff --git a/.claude/issues/3-ci-test-js.md b/.claude/issues/3-ci-test-js.md new file mode 100644 index 0000000..a5f7473 --- /dev/null +++ b/.claude/issues/3-ci-test-js.md @@ -0,0 +1,62 @@ +# Issue #3 — ci-test-js.yml reusable workflow + +**Status:** in-progress +**Branch:** `v1.0.0/task/ci-test-js` +**PR:** #4 +**Assignee:** @Adi-ty + +--- + +## Summary + +Every rtCamp WordPress project that ships JS runs the same Jest pipeline — `Test and Measure`'s `unit-tests-js` job is copy-pasted across plugins, themes, and Composer packages with minor drift. Centralising this as a reusable workflow lets every consumer adopt one canonical implementation via `uses: rtCamp/shared-workflows/.github/workflows/ci-test-js.yml@v1`, and adds Jest cache support that the legacy job didn't have. + +--- + +## Decisions made + +- [2026-05-12] `node-version` ships with `default: "22"`, not `required: true`. CLAUDE.md says "Node 22 (overridable per call)"; required-with-no-default would be boilerplate tax for a workflow library where every consumer wants the org default anyway. Major bumps go to `@v2` per tag strategy, so silent drift is already prevented. +- [2026-05-12] Jest cache path resolved at runtime via `$HOME/.jest-cache` in a step output, not literal `~/.jest-cache` in the env. Reason: Node doesn't expand `~` from `process.env.JEST_CACHE_DIRECTORY`, but `actions/cache` *does* expand `~` for its `path:` field — mixing both forms silently breaks caching. Computing once with `$HOME` keeps both ends pointing at the same directory. +- [2026-05-12] When `enable-cache: false`, the resolve step is skipped, `steps.jest-cache.outputs.dir` is empty, and `JEST_CACHE_DIRECTORY` becomes `""`. Jest treats empty as falsy and falls back to its OS-temp default — same end-state as not setting the var at all. +- [2026-05-12] `--ci` baked into the default `test-command`. Legacy used `env: CI: true` (still set by the runner automatically); the explicit flag in the default communicates intent at the call site. +- [2026-05-12] Cache key keyed by OS only (`jest-${{ runner.os }}`) per spec. Jest manages its own internal invalidation; no need to mix `node-version` or content hashes into the key. +- [2026-05-12] Job display name `Jest` — matches the tool-name pattern from the lint-trio PR (`Stylelint`, `ESLint`). + +--- + +## Files changed so far + +- `.github/workflows/ci-test-js.yml` — new +- `.claude/issues/3-ci-test-js.md` — new +- `CHANGELOG.md` — new +- `README.md` — edited +- `.yamllint.yml` — edited (drive-by: removed stray spaces in `truthy.allowed-values` flow sequence so the starter-kit config passes its own linter; same fix also lives on the lint PR — merge order produces a trivial no-op conflict) + +--- + +## Verification run + +```bash +$ pipx run yamllint .github/workflows/ci-test-js.yml +(no output — clean) +``` + +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- SHA pins resolved: `actions/checkout@v4.2.2` → `11bd71901bbe5b1630ceea73d27597364c9af683`, `actions/setup-node@v4.1.0` → `39370e3970a6d050c480ffad4ff0ed4d3fdee5af`, `actions/cache@v4.2.0` → `1bd1e32a3bdc45362d1e726936510720a7c30a57`. All three are direct commit refs (not annotated tag objects — verified via `gh api .../git/refs/tags/...`). +- README's "Individual workflows" section is new in this PR. +- Smoke test deferred to consumer-side run — call this branch from a Jest-configured throwaway repo and confirm: clean exit on green tests, non-zero on a failing test, cache restore visible in `actions/cache` step logs on the second run. + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.github/workflows/ci-test-js.yml b/.github/workflows/ci-test-js.yml new file mode 100644 index 0000000..45b22c7 --- /dev/null +++ b/.github/workflows/ci-test-js.yml @@ -0,0 +1,61 @@ +name: CI / Test JS + +on: + workflow_call: + inputs: + node-version: + description: "Node.js version." + type: string + default: "22" + test-command: + description: "Shell command that runs Jest." + type: string + default: "npm run test:js -- --ci" + enable-cache: + description: "Cache Jest transform/result data across runs." + type: boolean + default: true + working-dir: + description: "Working directory for monorepos." + type: string + default: "." + +permissions: + contents: read + +jobs: + test-js: + name: Jest + runs-on: ubuntu-latest + defaults: + run: + working-directory: ${{ inputs.working-dir }} + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Set up Node.js + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 + with: + node-version: ${{ inputs.node-version }} + cache: npm + + - name: Resolve Jest cache directory + id: jest-cache + if: ${{ inputs.enable-cache }} + run: echo "dir=$HOME/.jest-cache" >> "$GITHUB_OUTPUT" + + - name: Set up Jest cache + if: ${{ inputs.enable-cache }} + uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0 + with: + path: ${{ steps.jest-cache.outputs.dir }} + key: jest-${{ runner.os }} + + - name: Install npm dependencies + run: npm ci + + - name: Run Jest + run: ${{ inputs.test-command }} + env: + JEST_CACHE_DIRECTORY: ${{ steps.jest-cache.outputs.dir }} diff --git a/.yamllint.yml b/.yamllint.yml index af04e50..9d33a61 100644 --- a/.yamllint.yml +++ b/.yamllint.yml @@ -11,7 +11,7 @@ rules: # Allow quoted 'on:' to avoid YAML 1.1 truthy pitfalls. truthy: - allowed-values: [ 'true', 'false', 'on', 'off' ] + allowed-values: ['true', 'false', 'on', 'off'] check-keys: false # Comments can start at any column. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..514c5d2 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog + +All notable changes to `@rtcamp/wp-shared-workflows` are documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). + +## Unreleased + +### Added + +- `ci-test-js.yml` — reusable Jest unit-test workflow with optional cross-run cache (`enable-cache`), monorepo support (`working-dir`), and a consumer-overridable command (`test-command`). Replaces the copy-pasted `unit-tests-js` job from the legacy `Test and Measure` workflow. diff --git a/README.md b/README.md index a9a94a8..2951d45 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,28 @@ jobs: project-type: "plugin" ``` +### Individual workflows + +Each workflow is independently callable — wire them into your own job graph if the orchestrator preset doesn't fit. Defaults match the legacy `Test and Measure` workflow, so most consumers don't need any inputs. + +```yaml +# .github/workflows/ci.yml +name: CI +on: [push, pull_request] +jobs: + test-js: + uses: rtCamp/shared-workflows/.github/workflows/ci-test-js.yml@v1 +``` + +Available inputs: + +| Workflow | Input | Default | +|---|---|---| +| `ci-test-js.yml` | `node-version` | `"22"` | +| | `test-command` | `npm run test:js -- --ci` | +| | `enable-cache` | `true` | +| | `working-dir` | `"."` | + ## License GPL-2.0-or-later From f2af4779ddf909087afe3fe0380788e2f8e47db9 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Tue, 12 May 2026 17:15:41 +0530 Subject: [PATCH 02/43] feat(ci): add ci-test-php reusable workflow Single-job PHPUnit runner with a use-wp-env toggle: when true (default) boots @wordpress/env around the tests for WordPress integration runs and tears down with always(); when false skips Node and wp-env entirely for Composer-only packages. Composer install always runs; npm ci is split into its own conditional step so standalone mode doesn't require Node. --- .claude/issues/5-ci-test-php.md | 72 +++++++++++++++++++++++++++++ .github/workflows/ci-test-php.yml | 75 +++++++++++++++++++++++++++++++ .yamllint.yml | 2 +- CHANGELOG.md | 11 +++++ README.md | 33 ++++++++++++++ 5 files changed, 192 insertions(+), 1 deletion(-) create mode 100644 .claude/issues/5-ci-test-php.md create mode 100644 .github/workflows/ci-test-php.yml create mode 100644 CHANGELOG.md diff --git a/.claude/issues/5-ci-test-php.md b/.claude/issues/5-ci-test-php.md new file mode 100644 index 0000000..f15776f --- /dev/null +++ b/.claude/issues/5-ci-test-php.md @@ -0,0 +1,72 @@ +# Issue #5 — Add PHP unit tests reusable workflow + +**Status:** in-progress +**Branch:** `v1.0.0/task/ci-test-php` +**PR:** #6 +**Assignee:** @Adi-ty + +--- + +## Summary + +Every rtCamp WordPress project that ships PHP currently copy-pastes the same `unit-test-php` job from the legacy `Test and Measure` workflow. Some consumers need a full WordPress integration environment via `@wordpress/env`; Composer-only packages and libraries do not. This task adds `ci-test-php.yml` — a single reusable workflow with a `use-wp-env` toggle that covers both modes so every consumer can adopt one canonical implementation via `uses: rtCamp/shared-workflows/.github/workflows/ci-test-php.yml@v1`. + +--- + +## Decisions made + +- [2026-05-12] `php-version` gets a default of `"8.3"` rather than `required: true` — matches CLAUDE.md ("PHP in workflows: 8.3, overridable per call") and the input-design convention adopted in the lint-trio PR. `required: true` is reserved for unguessable identity (deploy slugs, bucket names) on future CD workflows. +- [2026-05-12] `composer-flags` default carries `--no-scripts` — supply-chain hygiene, mirrors `ci-lint-php.yml`. Consumers that need post-install scripts must opt in explicitly by overriding the input. +- [2026-05-12] `npm ci` is split into its own step gated on `use-wp-env`. The planning doc combined `npm ci && composer install`; that breaks standalone mode because there is no Node setup. Composer install always runs; npm install only when wp-env is enabled. +- [2026-05-12] `coverage: none` on `shivammathur/setup-php` — skips the Xdebug install cost. Coverage is a follow-up concern (will become a `coverage` input flipping Xdebug/PCOV on, plus Codecov / artifact upload). +- [2026-05-12] `tools: composer` on `shivammathur/setup-php` — pins Composer explicitly so we do not rely on whatever `ubuntu-latest` happens to ship. +- [2026-05-12] `wp-version` input deferred. `WP_ENV_CORE` works but needs a format transform (`6.7` → `WordPress/WordPress#tags/6.7`); writing `.wp-env.override.json` clobbers consumer overrides. Both are sharp edges and the legacy workflow did not expose this — defer to a clean follow-up issue. +- [2026-05-12] No Composer or wp-env caching in v1.0.0. Composer install is fast relative to wp-env Docker pulls; wp-env caching is genuinely tricky (Docker layer cache vs `~/.wp-env`). Both can be added later without breaking the input schema. +- [2026-05-12] Drive-by fix to `.yamllint.yml` line 14 (bracket spacing) — same starter-kit bug surfaces here as it did on the ci-test-js branch. yamllint would otherwise fail on the very file that defines its own rules. + +### Action SHA pins recorded + +- `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683` — v4.2.2. +- `actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af` — v4.1.0. +- `shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f` — 2.37.0 (annotated tag dereferenced via `gh api repos/.../git/tags/`). + +--- + +## Files changed so far + +- `.github/workflows/ci-test-php.yml` — new +- `.claude/issues/5-ci-test-php.md` — new +- `CHANGELOG.md` — new (first entry under `## Unreleased`) +- `README.md` — edited (caller example + inputs row) +- `.yamllint.yml` — edited (drive-by bracket-spacing fix on line 14) + +--- + +## Verification run + +```bash +$ pipx run yamllint . +# (clean exit) +``` + +`act --dryrun` not run locally — `act` is not installed on this machine. Full end-to-end verification deferred to a smoke-test consumer repo with `@wordpress/env`, `composer.json`, and a passing PHPUnit fixture; reviewer to confirm during PR review. + +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- The biggest deviation from the planning doc is the **split `npm ci` / `composer install` steps**. The doc's combined step would fail in standalone mode (no Node = `npm ci` cannot run). Splitting is cheap and keeps the dependency graph honest. +- `wp-version` is intentionally absent from v1.0.0. If reviewers want it shipped now, the cleanest wire is `env: WP_ENV_CORE: WordPress/WordPress#tags/${{ inputs.wp-version }}` on the wp-env start step, gated on the input being non-empty. Happy to fold that in if requested — flagging here so it is a conscious decision rather than an oversight. +- Same `.yamllint.yml` bracket-spacing fix lives in the other open PR. Whichever PR merges second will conflict on that single line. + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.github/workflows/ci-test-php.yml b/.github/workflows/ci-test-php.yml new file mode 100644 index 0000000..8e86e20 --- /dev/null +++ b/.github/workflows/ci-test-php.yml @@ -0,0 +1,75 @@ +name: CI / Test PHP + +on: + workflow_call: + inputs: + php-version: + description: "PHP version to install." + type: string + default: "8.3" + node-version: + description: "Node.js version (used only when use-wp-env is true)." + type: string + default: "22" + use-wp-env: + description: "Start @wordpress/env before tests for WordPress integration runs." + type: boolean + default: true + test-command: + description: "Shell command that runs PHPUnit." + type: string + default: "npm run test:php" + composer-flags: + description: "Flags passed to composer install." + type: string + default: "--no-interaction --prefer-dist --no-progress --no-scripts" + working-dir: + description: "Working directory for monorepos." + type: string + default: "." + +permissions: + contents: read + +jobs: + test-php: + name: PHPUnit + runs-on: ubuntu-latest + defaults: + run: + working-directory: ${{ inputs.working-dir }} + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Set up PHP + uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # 2.37.0 + with: + php-version: ${{ inputs.php-version }} + coverage: none + tools: composer + + - name: Set up Node.js + if: ${{ inputs.use-wp-env }} + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 + with: + node-version: ${{ inputs.node-version }} + cache: npm + + - name: Install Composer dependencies + run: composer install ${{ inputs.composer-flags }} + + - name: Install npm dependencies + if: ${{ inputs.use-wp-env }} + run: npm ci + + - name: Start wp-env + if: ${{ inputs.use-wp-env }} + run: npm run wp-env start + + - name: Run PHPUnit + run: ${{ inputs.test-command }} + + - name: Stop wp-env + if: ${{ inputs.use-wp-env && always() }} + run: npm run wp-env stop diff --git a/.yamllint.yml b/.yamllint.yml index af04e50..9d33a61 100644 --- a/.yamllint.yml +++ b/.yamllint.yml @@ -11,7 +11,7 @@ rules: # Allow quoted 'on:' to avoid YAML 1.1 truthy pitfalls. truthy: - allowed-values: [ 'true', 'false', 'on', 'off' ] + allowed-values: ['true', 'false', 'on', 'off'] check-keys: false # Comments can start at any column. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..2667c48 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog + +All notable changes to `@rtcamp/wp-shared-workflows` are documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). + +## Unreleased + +### Added + +- `ci-test-php.yml` — reusable PHPUnit workflow with a `use-wp-env` toggle (default `true`) for WordPress integration tests via `@wordpress/env`, or standalone PHPUnit for Composer-only packages and libraries. Inputs: `php-version`, `node-version`, `use-wp-env`, `test-command`, `composer-flags`, `working-dir`. \ No newline at end of file diff --git a/README.md b/README.md index a9a94a8..d92c28b 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,39 @@ jobs: project-type: "plugin" ``` +## Individual workflows + +### `ci-test-php.yml` — PHPUnit + +Runs PHPUnit either against a real WordPress environment via [`@wordpress/env`](https://github.com/WordPress/gutenberg/tree/trunk/packages/env) (default) or standalone for Composer libraries. + +```yaml +# Plugin or theme — WordPress integration tests via wp-env (default) +jobs: + test-php: + uses: rtCamp/shared-workflows/.github/workflows/ci-test-php.yml@v1 + with: + php-version: "8.3" + +# Composer package — standalone PHPUnit, no Node, no Docker +jobs: + test-php: + uses: rtCamp/shared-workflows/.github/workflows/ci-test-php.yml@v1 + with: + php-version: "8.3" + use-wp-env: false + test-command: "vendor/bin/phpunit" +``` + +| Input | Type | Default | Description | +| ---------------- | ------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- | +| `php-version` | string | `"8.3"` | PHP version to install. | +| `node-version` | string | `"22"` | Node.js version. Consumed only when `use-wp-env: true`. | +| `use-wp-env` | boolean | `true` | Start `@wordpress/env` before tests for WordPress integration runs. | +| `test-command` | string | `"npm run test:php"` | Shell command that runs PHPUnit. | +| `composer-flags` | string | `"--no-interaction --prefer-dist --no-progress --no-scripts"` | Flags passed to `composer install`. Keep `--no-scripts` for supply-chain hygiene. | +| `working-dir` | string | `"."` | Working directory for monorepos. | + ## License GPL-2.0-or-later From 69a719fa3278c7a2191bcb3955499a66c18aa5f7 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Tue, 12 May 2026 17:22:26 +0530 Subject: [PATCH 03/43] chore: update verification run section with dry run output for ci-test-php workflow --- .claude/issues/5-ci-test-php.md | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/.claude/issues/5-ci-test-php.md b/.claude/issues/5-ci-test-php.md index f15776f..dcb3c5a 100644 --- a/.claude/issues/5-ci-test-php.md +++ b/.claude/issues/5-ci-test-php.md @@ -45,12 +45,32 @@ Every rtCamp WordPress project that ships PHP currently copy-pastes the same `un ## Verification run ```bash -$ pipx run yamllint . -# (clean exit) + pipx run yamllint . +❯ act workflow_call -W .github/workflows/ci-test-php.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Set up job +*DRYRUN* [CI / Test PHP/PHPUnit] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CI / Test PHP/PHPUnit] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CI / Test PHP/PHPUnit] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Test PHP/PHPUnit] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Set up job +*DRYRUN* [CI / Test PHP/PHPUnit] ☁ git clone 'https://github.com/shivammathur/setup-php' # ref=accd6127cb78bee3e8082180cb391013d204ef9f +*DRYRUN* [CI / Test PHP/PHPUnit] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af +*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Main Checkout repository +*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Main Checkout repository [5.999542ms] +*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Main Set up PHP +*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Main Set up PHP [5.649958ms] +*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Main Install Composer dependencies +*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Main Install Composer dependencies [13.607667ms] +*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Main Run PHPUnit +*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Main Run PHPUnit [12.081917ms] +*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Complete job +*DRYRUN* [CI / Test PHP/PHPUnit] Cleaning up container for job PHPUnit +*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Complete job +*DRYRUN* [CI / Test PHP/PHPUnit] 🏁 Job succeeded ``` -`act --dryrun` not run locally — `act` is not installed on this machine. Full end-to-end verification deferred to a smoke-test consumer repo with `@wordpress/env`, `composer.json`, and a passing PHPUnit fixture; reviewer to confirm during PR review. - --- ## Open questions From f0e23e6e8d8ae74675aaa9e0293646ccbdabbf10 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Tue, 12 May 2026 17:23:54 +0530 Subject: [PATCH 04/43] docs: update ci-test-js.md with verification run details --- .claude/issues/3-ci-test-js.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/.claude/issues/3-ci-test-js.md b/.claude/issues/3-ci-test-js.md index a5f7473..580f0a1 100644 --- a/.claude/issues/3-ci-test-js.md +++ b/.claude/issues/3-ci-test-js.md @@ -37,8 +37,32 @@ Every rtCamp WordPress project that ships JS runs the same Jest pipeline — `Te ## Verification run ```bash -$ pipx run yamllint .github/workflows/ci-test-js.yml -(no output — clean) +❯ pipx run yamllint . +❯ act workflow_call -W .github/workflows/ci-test-js.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CI / Test JS/Jest] ⭐ Run Set up job +*DRYRUN* [CI / Test JS/Jest] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CI / Test JS/Jest] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CI / Test JS/Jest] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Test JS/Jest] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Test JS/Jest] ✅ Success - Set up job +*DRYRUN* [CI / Test JS/Jest] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af +*DRYRUN* [CI / Test JS/Jest] ☁ git clone 'https://github.com/actions/cache' # ref=1bd1e32a3bdc45362d1e726936510720a7c30a57 +*DRYRUN* [CI / Test JS/Jest] ⭐ Run Main Checkout repository +*DRYRUN* [CI / Test JS/Jest] ✅ Success - Main Checkout repository [5.413291ms] +*DRYRUN* [CI / Test JS/Jest] ⭐ Run Main Set up Node.js +*DRYRUN* [CI / Test JS/Jest] ✅ Success - Main Set up Node.js [5.880042ms] +*DRYRUN* [CI / Test JS/Jest] ⭐ Run Main Install npm dependencies +*DRYRUN* [CI / Test JS/Jest] ✅ Success - Main Install npm dependencies [16.523709ms] +*DRYRUN* [CI / Test JS/Jest] ⭐ Run Main Run Jest +*DRYRUN* [CI / Test JS/Jest] ✅ Success - Main Run Jest [17.757417ms] +*DRYRUN* [CI / Test JS/Jest] ⭐ Run Post Set up Node.js +*DRYRUN* [CI / Test JS/Jest] ✅ Success - Post Set up Node.js [4.301542ms] +*DRYRUN* [CI / Test JS/Jest] ⭐ Run Complete job +*DRYRUN* [CI / Test JS/Jest] Cleaning up container for job Jest +*DRYRUN* [CI / Test JS/Jest] ✅ Success - Complete job +*DRYRUN* [CI / Test JS/Jest] 🏁 Job succeeded ``` --- From 3d0ddd532396d71c89925d098ffc2c4cec3e7504 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Tue, 12 May 2026 17:55:48 +0530 Subject: [PATCH 05/43] feat(ci): add ci-build reusable workflow Production-build runner with optional artifact upload. Default shape is build-only (no artifact); flip upload-artifact to true to hand the output to a downstream CD job. Composes path as working-dir/artifact-path so monorepo callers don't double-prefix, and sets if-no-files-found: error so a misconfigured artifact-path surfaces at the upload step rather than producing a silent empty artifact downstream. --- .claude/issues/7-ci-build.md | 95 ++++++++++++++++++++++++++++++++++ .github/workflows/ci-build.yml | 68 ++++++++++++++++++++++++ .yamllint.yml | 2 +- CHANGELOG.md | 11 ++++ README.md | 35 +++++++++++++ 5 files changed, 210 insertions(+), 1 deletion(-) create mode 100644 .claude/issues/7-ci-build.md create mode 100644 .github/workflows/ci-build.yml create mode 100644 CHANGELOG.md diff --git a/.claude/issues/7-ci-build.md b/.claude/issues/7-ci-build.md new file mode 100644 index 0000000..51fe062 --- /dev/null +++ b/.claude/issues/7-ci-build.md @@ -0,0 +1,95 @@ +# Issue #7 — Add ci-build reusable workflow + +**Status:** in-progress +**Branch:** `v1.0.0/task/ci-build` +**PR:** #8 +**Assignee:** @Adi-ty + +--- + +## Summary + +Every rtCamp WordPress project that ships JS or CSS runs the same production build — `Test and Measure`'s `build-prod` job is copy-pasted across plugins, themes, and packages. Most callers only need to verify the build exits 0; CD callers also need the built files handed to a downstream deploy job. This task adds `ci-build.yml` — a single reusable workflow with an `upload-artifact` toggle (default `false`) that covers both shapes so every consumer can adopt one canonical implementation via `uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1`. + +--- + +## Decisions made + +- [2026-05-12] `node-version` defaults to `"22"` rather than `required: true` — matches CLAUDE.md ("Node in workflows: 22, overridable per call") and the input-design convention adopted in the lint-trio / test-js / test-php PRs. `required: true` is reserved for unguessable identity (deploy slugs, bucket names) on future CD workflows. +- [2026-05-12] `if-no-files-found: error` set on `actions/upload-artifact`. The action's default is `warn`, which silently produces an empty artifact and breaks any downstream CD job that tries to `actions/download-artifact` it. Failing loudly is the right shape for a reusable workflow — a misconfigured `artifact-path` should surface at the upload step, not three jobs later. +- [2026-05-12] Artifact `path` is composed as `${{ inputs.working-dir }}/${{ inputs.artifact-path }}`. `actions/upload-artifact`'s `path` is repo-root-relative, not working-directory-relative, so monorepo callers would otherwise have to double-prefix. Composing here means `working-dir: "plugins/foo"` + `artifact-path: "build/"` does what a consumer expects. +- [2026-05-12] No `env: CI: true` on the build step. GitHub Actions sets `CI=true` automatically on hosted runners. The legacy workflow set it explicitly — that was redundant. Mirrors the convention from `ci-test-js` / `ci-test-php`. +- [2026-05-12] No build-output caching in v1.0.0. `actions/setup-node`'s `cache: npm` already covers the slow part (dependency install); build outputs are reproducible from `package-lock.json` + source and rarely benefit from caching. Can be added later without breaking the input schema. +- [2026-05-12] `actions/upload-artifact` pinned to `v4.6.2`, not `v5`/`v6`/`v7`. v4 is the stable major referenced in the planning doc; v5+ introduced breaking changes around upload behaviour that aren't needed here. We can move forward on a future minor when consumers ask for it. +- [2026-05-12] `upload-artifact` defaults to `false`. The CI-verification path (no upload) is the common case; defaulting to `true` would burn artifact storage on every CI run for callers that don't need it. +- [2026-05-12] Drive-by fix to `.yamllint.yml` line 14 (bracket spacing) — same starter-kit bug that the lint-trio, ci-test-js, and ci-test-php PRs all touch. Whichever PR merges first wins; later ones hit a one-line conflict. + +### Action SHA pins recorded + +- `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683` — v4.2.2. +- `actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af` — v4.1.0. +- `actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02` — v4.6.2. + +--- + +## Files changed so far + +- `.github/workflows/ci-build.yml` — new +- `.claude/issues/7-ci-build.md` — new +- `CHANGELOG.md` — new (first entry under `## Unreleased`) +- `README.md` — edited (caller example + inputs row) +- `.yamllint.yml` — edited (drive-by bracket-spacing fix on line 14) + +--- + +## Verification run + +```bash +❯ pipx run yamllint . +❯ act workflow_call -W .github/workflows/ci-build.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CI / Build/Build] ⭐ Run Set up job +*DRYRUN* [CI / Build/Build] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CI / Build/Build] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CI / Build/Build] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Build/Build] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Build/Build] ✅ Success - Set up job +*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af +*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/actions/upload-artifact' # ref=ea165f8d65b6e75b540449e92b4886f43607fa02 +*DRYRUN* [CI / Build/Build] ⭐ Run Main Checkout repository +*DRYRUN* [CI / Build/Build] ✅ Success - Main Checkout repository [6.052542ms] +*DRYRUN* [CI / Build/Build] ⭐ Run Main Set up Node.js +*DRYRUN* [CI / Build/Build] ✅ Success - Main Set up Node.js [5.587041ms] +*DRYRUN* [CI / Build/Build] ⭐ Run Main Install npm dependencies +*DRYRUN* [CI / Build/Build] ✅ Success - Main Install npm dependencies [14.779ms] +*DRYRUN* [CI / Build/Build] ⭐ Run Main Build production assets +*DRYRUN* [CI / Build/Build] ✅ Success - Main Build production assets [14.293167ms] +*DRYRUN* [CI / Build/Build] ⭐ Run Post Set up Node.js +*DRYRUN* [CI / Build/Build] ✅ Success - Post Set up Node.js [4.254167ms] +*DRYRUN* [CI / Build/Build] ⭐ Run Complete job +*DRYRUN* [CI / Build/Build] Cleaning up container for job Build +*DRYRUN* [CI / Build/Build] ✅ Success - Complete job +*DRYRUN* [CI / Build/Build] 🏁 Job succeeded +``` + +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- The `path: ${{ inputs.working-dir }}/${{ inputs.artifact-path }}` composition is the only non-obvious bit. `defaults.run.working-directory` only affects `run:` steps; action inputs (`uses:` blocks) still resolve relative to the repo root. Composing the two inputs here is the cheapest way to keep monorepo callers ergonomic without exposing the GitHub Actions quirk. +- `if-no-files-found: error` is a deliberate hardening over the planning doc, which didn't mention it. Worth a sanity-check during smoke testing — confirm that misconfiguring `artifact-path` produces a clear failure rather than a silent empty artifact. +- `actions/upload-artifact` v7.0.1 exists but pins live at v4.6.2. Happy to bump if reviewers prefer staying on the latest major; v4 was chosen for stability and alignment with the planning doc. +`.yamllint.yml` fix is duplicated across the PRs. Whichever merges first wins; later ones hit a one-line conflict. + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.github/workflows/ci-build.yml b/.github/workflows/ci-build.yml new file mode 100644 index 0000000..352196d --- /dev/null +++ b/.github/workflows/ci-build.yml @@ -0,0 +1,68 @@ +name: CI / Build + +on: + workflow_call: + inputs: + node-version: + description: "Node.js version to install." + type: string + default: "22" + build-command: + description: "Shell command that produces the production build." + type: string + default: "npm run build:prod" + upload-artifact: + description: "Upload the build output as a GitHub Actions artifact for downstream jobs." + type: boolean + default: false + artifact-name: + description: "Name used when uploading the artifact (and when a CD job downloads it)." + type: string + default: "build" + artifact-path: + description: "Path to upload. Relative to working-dir." + type: string + default: "build/" + retention-days: + description: "Days to keep the artifact before GitHub deletes it." + type: number + default: 7 + working-dir: + description: "Working directory for monorepos." + type: string + default: "." + +permissions: + contents: read + +jobs: + build: + name: Build + runs-on: ubuntu-latest + defaults: + run: + working-directory: ${{ inputs.working-dir }} + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Set up Node.js + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 + with: + node-version: ${{ inputs.node-version }} + cache: npm + + - name: Install npm dependencies + run: npm ci + + - name: Build production assets + run: ${{ inputs.build-command }} + + - name: Upload build artifact + if: ${{ inputs.upload-artifact }} + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: ${{ inputs.artifact-name }} + path: ${{ inputs.working-dir }}/${{ inputs.artifact-path }} + retention-days: ${{ inputs.retention-days }} + if-no-files-found: error diff --git a/.yamllint.yml b/.yamllint.yml index af04e50..9d33a61 100644 --- a/.yamllint.yml +++ b/.yamllint.yml @@ -11,7 +11,7 @@ rules: # Allow quoted 'on:' to avoid YAML 1.1 truthy pitfalls. truthy: - allowed-values: [ 'true', 'false', 'on', 'off' ] + allowed-values: ['true', 'false', 'on', 'off'] check-keys: false # Comments can start at any column. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..860a384 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog + +All notable changes to `@rtcamp/wp-shared-workflows` are documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). + +## Unreleased + +### Added + +- `ci-build.yml` — reusable production-build workflow with an optional `upload-artifact` step (default `false`) so consumers can either verify the build exits 0 (CI-only) or hand the built files to a downstream CD job. Inputs: `node-version`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. Uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. diff --git a/README.md b/README.md index a9a94a8..503edac 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,41 @@ jobs: project-type: "plugin" ``` +## Individual workflows + +### `ci-build.yml` — production build + +Runs the consumer's production build, with an optional artifact upload for downstream CD jobs. Default shape is build-only (no artifact written). + +```yaml +# Verify the build exits 0 — no artifact written +jobs: + build: + uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + with: + node-version: "22" + +# Build and hand the output to a downstream CD job +jobs: + build: + uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + with: + node-version: "22" + upload-artifact: true +``` + +| Input | Type | Default | Description | +| ----------------- | ------- | --------------------- | ---------------------------------------------------------------------------- | +| `node-version` | string | `"22"` | Node.js version to install. | +| `build-command` | string | `"npm run build:prod"`| Shell command that produces the production build. | +| `upload-artifact` | boolean | `false` | Upload the build output as a GitHub Actions artifact for downstream jobs. | +| `artifact-name` | string | `"build"` | Artifact name. Must match the name in the downstream `actions/download-artifact` step. | +| `artifact-path` | string | `"build/"` | Path to upload. Resolved as `working-dir/artifact-path`. | +| `retention-days` | number | `7` | Days to keep the artifact before GitHub deletes it. | +| `working-dir` | string | `"."` | Working directory for monorepos. | + +A misconfigured `artifact-path` fails loudly (`if-no-files-found: error`) — no silent empty artifacts. + ## License GPL-2.0-or-later From 39401a9aea590514fa46d8de301a544db81ae347 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Wed, 13 May 2026 08:54:48 +0530 Subject: [PATCH 06/43] feat(ci): add ci-test-a11y reusable workflow pa11y-ci WCAG2AA accessibility testing against a wp-env site. Builds assets, starts wp-env, runs pa11y-ci, tears down with if: always(). Label-triggered at the caller level; the workflow itself is trigger-agnostic. --- .claude/issues/9-ci-test-a11y.md | 97 ++++++++++++++++++++++++++++++ .github/workflows/ci-test-a11y.yml | 57 ++++++++++++++++++ .yamllint.yml | 2 +- CHANGELOG.md | 11 ++++ README.md | 29 +++++++++ 5 files changed, 195 insertions(+), 1 deletion(-) create mode 100644 .claude/issues/9-ci-test-a11y.md create mode 100644 .github/workflows/ci-test-a11y.yml create mode 100644 CHANGELOG.md diff --git a/.claude/issues/9-ci-test-a11y.md b/.claude/issues/9-ci-test-a11y.md new file mode 100644 index 0000000..677b3db --- /dev/null +++ b/.claude/issues/9-ci-test-a11y.md @@ -0,0 +1,97 @@ +# Issue #9 — Add ci-test-a11y reusable workflow + +**Status:** in-progress +**Branch:** `v1.0.0/task/ci-test-a11y` +**PR:** #10 +**Assignee:** @Adi-ty + +--- + +## Summary + +Every rtCamp WordPress project that ships UI runs the same accessibility regression check — pa11y-ci against the built site served by `@wordpress/env`. The wiring (build → wp-env start → pa11y → wp-env stop) is tedious to maintain and copy-pasted across consumers; some projects skip a11y entirely as a result. This task adds `ci-test-a11y.yml` — a single reusable workflow that captures that sequence with `if: always()` cleanup, so every consumer can adopt one canonical implementation via `uses: rtCamp/shared-workflows/.github/workflows/ci-test-a11y.yml@v1`. The reusable workflow stays trigger-agnostic; consumers wire the `Run a11y` label gate at the caller level per CLAUDE.md. + +--- + +## Decisions made + +- [2026-05-12] `node-version` defaults to `"22"` rather than `required: true` — matches CLAUDE.md ("Node in workflows: 22, overridable per call") and the input-design convention adopted in the lint-trio / test-js / test-php / build PRs. `required: true` is reserved for unguessable identity (deploy slugs, bucket names) on future CD workflows. +- [2026-05-12] Build runs before `wp-env start`, not after. pa11y crawls user-facing pages served by WordPress; those pages need compiled CSS/JS. Swapping the order would silently let pa11y inspect un-built markup and might still pass — a false-green. Order is load-bearing and called out in "Things to avoid". +- [2026-05-12] `wp-env stop` carries `if: always()` so a failing pa11y run does not leak a Docker stack into the next job. Without it, repeat runs on the same runner hit port-in-use flakes. +- [2026-05-12] No `setup-php` / `composer install` step in v1.0.0. pa11y serves pages from inside the wp-env Docker containers which carry their own PHP; the consumer's plugin/theme code is mounted in. Plugins with Composer autoloaders that fatal without `vendor/` are a real edge case but uncommon enough to defer behind a follow-up `install-composer-deps` opt-in input rather than baking host-side composer setup into every a11y run. +- [2026-05-12] Reusable workflow stays trigger-agnostic. CLAUDE.md notes a11y is "label-triggered by default", but that wiring (`if: contains(github.event.pull_request.labels.*.name, 'Run a11y')`) belongs at the caller — embedding it here would force the gate on every consumer. +- [2026-05-12] No `env: CI: true` on any step. GitHub Actions sets `CI=true` automatically on hosted runners. The legacy workflow set it explicitly — that was redundant. +- [2026-05-12] No HTML report artifact upload in v1.0.0. pa11y can emit HTML reports and uploading them as a GitHub artifact is genuinely useful for debugging failing runs, but it adds an `actions/upload-artifact` step and a path-resolution decision. Defer to a follow-up. +- [2026-05-12] No browser / wp-env Docker / build-output caching in v1.0.0. `setup-node` `cache: npm` covers the slow part (dependency install). wp-env Docker image caching is genuinely tricky and rarely worth the complexity for the first cut. +- [2026-05-12] Drive-by fix to `.yamllint.yml` line 14 (bracket spacing) — same starter-kit bug that the lint-trio, ci-test-js, ci-test-php, and ci-build PRs all touch. Whichever PR merges first wins; later ones hit a one-line conflict. + +### Action SHA pins recorded + +- `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683` — v4.2.2. +- `actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af` — v4.1.0. + +--- + +## Files changed so far + +- `.github/workflows/ci-test-a11y.yml` — new +- `.claude/issues/9-ci-test-a11y.md` — new (rename to match the issue number once filed) +- `CHANGELOG.md` — new (first entry under `## Unreleased`) +- `README.md` — edited (Individual workflows section + caller example with label gate + inputs row) +- `.yamllint.yml` — edited (drive-by bracket-spacing fix on line 14) + +--- + +## Verification run + +```bash +❯ pipx run yamllint . +❯ act workflow_call -W .github/workflows/ci-test-a11y.yml --dryrun +*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Set up job +*DRYRUN* [CI / Test a11y/pa11y-ci] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CI / Test a11y/pa11y-ci] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CI / Test a11y/pa11y-ci] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Test a11y/pa11y-ci] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Set up job +*DRYRUN* [CI / Test a11y/pa11y-ci] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af +*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Checkout repository +*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Checkout repository [7.135916ms] +*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Set up Node.js +*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Set up Node.js [11.4295ms] +*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Install npm dependencies +*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Install npm dependencies [16.7305ms] +*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Build production assets +*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Build production assets [16.109583ms] +*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Start wp-env +*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Start wp-env [16.489ms] +*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Run pa11y-ci +*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Run pa11y-ci [16.027583ms] +*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Stop wp-env +*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Stop wp-env [13.088125ms] +*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Post Set up Node.js +*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Post Set up Node.js [4.724833ms] +*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Complete job +*DRYRUN* [CI / Test a11y/pa11y-ci] Cleaning up container for job pa11y-ci +*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Complete job +*DRYRUN* [CI / Test a11y/pa11y-ci] 🏁 Job succeeded +``` + +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- The `if: always()` on `wp-env stop` is non-negotiable — without it, a failing pa11y leaves containers running and the next CI run on the same runner hits port-in-use errors. +- Composer install is deliberately absent. If reviewers want it for v1.0.0, the cleanest shape is an `install-composer-deps` boolean (default `false`) that conditionally sets up PHP and runs `composer install --no-scripts` before the build step. Happy to fold that in if requested — flagging here so it is a conscious decision rather than an oversight. +- `.yamllint.yml` fix is duplicated across the PRs. Whichever merges first wins; later ones hit a one-line conflict. + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.github/workflows/ci-test-a11y.yml b/.github/workflows/ci-test-a11y.yml new file mode 100644 index 0000000..2cfa760 --- /dev/null +++ b/.github/workflows/ci-test-a11y.yml @@ -0,0 +1,57 @@ +name: CI / Test a11y + +on: + workflow_call: + inputs: + node-version: + description: "Node.js version to install." + type: string + default: "22" + build-command: + description: "Shell command that produces the production build pa11y will test against." + type: string + default: "npm run build:prod" + test-command: + description: "Shell command that runs pa11y-ci." + type: string + default: "npm run test:a11y" + working-dir: + description: "Working directory for monorepos." + type: string + default: "." + +permissions: + contents: read + +jobs: + test-a11y: + name: pa11y-ci + runs-on: ubuntu-latest + defaults: + run: + working-directory: ${{ inputs.working-dir }} + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Set up Node.js + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 + with: + node-version: ${{ inputs.node-version }} + cache: npm + + - name: Install npm dependencies + run: npm ci + + - name: Build production assets + run: ${{ inputs.build-command }} + + - name: Start wp-env + run: npm run wp-env start + + - name: Run pa11y-ci + run: ${{ inputs.test-command }} + + - name: Stop wp-env + if: always() + run: npm run wp-env stop diff --git a/.yamllint.yml b/.yamllint.yml index af04e50..9d33a61 100644 --- a/.yamllint.yml +++ b/.yamllint.yml @@ -11,7 +11,7 @@ rules: # Allow quoted 'on:' to avoid YAML 1.1 truthy pitfalls. truthy: - allowed-values: [ 'true', 'false', 'on', 'off' ] + allowed-values: ['true', 'false', 'on', 'off'] check-keys: false # Comments can start at any column. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..0646ad0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog + +All notable changes to `@rtcamp/wp-shared-workflows` are documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). + +## Unreleased + +### Added + +- `ci-test-a11y.yml` — reusable pa11y-ci accessibility test workflow. Order: `npm ci` → build → `wp-env start` → pa11y → `wp-env stop` (with `if: always()` so cleanup runs on failure). Inputs: `node-version`, `build-command`, `test-command`, `working-dir`. Trigger-agnostic — consumers wire the `Run a11y` label gate at the caller level. \ No newline at end of file diff --git a/README.md b/README.md index a9a94a8..8f4efbb 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,35 @@ jobs: project-type: "plugin" ``` +## Individual workflows + +### `ci-test-a11y.yml` — accessibility tests + +Runs `pa11y-ci` against the built site served by `@wordpress/env`. The reusable workflow is trigger-agnostic — wire the `Run a11y` label gate at the caller because a11y runs are slower than the rest of the CI matrix. + +```yaml +# .github/workflows/ci.yml in the consumer +name: CI +on: + pull_request: + types: [labeled, synchronize, reopened] +jobs: + test-a11y: + if: contains(github.event.pull_request.labels.*.name, 'Run a11y') + uses: rtCamp/shared-workflows/.github/workflows/ci-test-a11y.yml@v1 + with: + node-version: "22" +``` + +| Input | Type | Default | Description | +| --------------- | ------ | ---------------------- | ------------------------------------------------------------------------ | +| `node-version` | string | `"22"` | Node.js version to install. | +| `build-command` | string | `"npm run build:prod"` | Shell command that produces the production build pa11y will test against. | +| `test-command` | string | `"npm run test:a11y"` | Shell command that runs pa11y-ci. | +| `working-dir` | string | `"."` | Working directory for monorepos. | + +Step order is load-bearing: build runs **before** `wp-env start` so pa11y sees compiled CSS/JS. `wp-env stop` uses `if: always()` so a failing pa11y run does not leak a Docker stack into the next job. + ## License GPL-2.0-or-later From de722cc1dcc29a9379cc1c1c1fa34fec0b0b6121 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Wed, 13 May 2026 16:31:44 +0530 Subject: [PATCH 07/43] feat(ci): add install-node-deps / install-composer-deps toggles Both stacks are now individually optional. Three consumer shapes: Node-only (default), Composer-only, both. Composer flags default to --no-dev for production builds. Node setup + npm ci gated on install-node-deps; PHP setup + composer install gated on install-composer-deps. --- .claude/issues/7-ci-build.md | 44 +++++++++++++++++++++++++------- .github/workflows/ci-build.yml | 32 ++++++++++++++++++++++- CHANGELOG.md | 2 +- README.md | 46 ++++++++++++++++++++++++++-------- 4 files changed, 102 insertions(+), 22 deletions(-) diff --git a/.claude/issues/7-ci-build.md b/.claude/issues/7-ci-build.md index 51fe062..51c228e 100644 --- a/.claude/issues/7-ci-build.md +++ b/.claude/issues/7-ci-build.md @@ -23,12 +23,14 @@ Every rtCamp WordPress project that ships JS or CSS runs the same production bui - [2026-05-12] `actions/upload-artifact` pinned to `v4.6.2`, not `v5`/`v6`/`v7`. v4 is the stable major referenced in the planning doc; v5+ introduced breaking changes around upload behaviour that aren't needed here. We can move forward on a future minor when consumers ask for it. - [2026-05-12] `upload-artifact` defaults to `false`. The CI-verification path (no upload) is the common case; defaulting to `true` would burn artifact storage on every CI run for callers that don't need it. - [2026-05-12] Drive-by fix to `.yamllint.yml` line 14 (bracket spacing) — same starter-kit bug that the lint-trio, ci-test-js, and ci-test-php PRs all touch. Whichever PR merges first wins; later ones hit a one-line conflict. +- [2026-05-13] Added `install-composer-deps` / `install-node-deps` toggles (+ `php-version`, `composer-flags`) in response to PR review. Both stacks are individually optional — three consumer shapes: Node-only (default), Composer-only, both. `composer-flags` defaults to `--no-dev` (production build, not dev). Node defaults on; Composer defaults off. Backwards-compatible. ### Action SHA pins recorded - `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683` — v4.2.2. - `actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af` — v4.1.0. - `actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02` — v4.6.2. +- `shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f` — 2.37.0. --- @@ -56,17 +58,39 @@ WARN ⚠ You are using Apple M-series chip and you have not specified container *DRYRUN* [CI / Build/Build] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" *DRYRUN* [CI / Build/Build] ✅ Success - Set up job *DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af +*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/shivammathur/setup-php' # ref=accd6127cb78bee3e8082180cb391013d204ef9f +*DRYRUN* [CI / Build/Build] Non-terminating error while running 'git clone': some refs were not updated *DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/actions/upload-artifact' # ref=ea165f8d65b6e75b540449e92b4886f43607fa02 *DRYRUN* [CI / Build/Build] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Build/Build] ✅ Success - Main Checkout repository [6.052542ms] -*DRYRUN* [CI / Build/Build] ⭐ Run Main Set up Node.js -*DRYRUN* [CI / Build/Build] ✅ Success - Main Set up Node.js [5.587041ms] -*DRYRUN* [CI / Build/Build] ⭐ Run Main Install npm dependencies -*DRYRUN* [CI / Build/Build] ✅ Success - Main Install npm dependencies [14.779ms] +*DRYRUN* [CI / Build/Build] ✅ Success - Main Checkout repository [6.2005ms] *DRYRUN* [CI / Build/Build] ⭐ Run Main Build production assets -*DRYRUN* [CI / Build/Build] ✅ Success - Main Build production assets [14.293167ms] -*DRYRUN* [CI / Build/Build] ⭐ Run Post Set up Node.js -*DRYRUN* [CI / Build/Build] ✅ Success - Post Set up Node.js [4.254167ms] +*DRYRUN* [CI / Build/Build] ✅ Success - Main Build production assets [13.612625ms] +*DRYRUN* [CI / Build/Build] ⭐ Run Complete job +*DRYRUN* [CI / Build/Build] Cleaning up container for job Build +*DRYRUN* [CI / Build/Build] ✅ Success - Complete job +*DRYRUN* [CI / Build/Build] 🏁 Job succeeded +❯ act workflow_call -W .github/workflows/ci-build.yml --dryrun \ + --input install-node-deps=false --input install-composer-deps=true +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CI / Build/Build] ⭐ Run Set up job +*DRYRUN* [CI / Build/Build] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CI / Build/Build] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CI / Build/Build] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Build/Build] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Build/Build] ✅ Success - Set up job +*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af +*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/shivammathur/setup-php' # ref=accd6127cb78bee3e8082180cb391013d204ef9f +*DRYRUN* [CI / Build/Build] Non-terminating error while running 'git clone': some refs were not updated +*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/actions/upload-artifact' # ref=ea165f8d65b6e75b540449e92b4886f43607fa02 +*DRYRUN* [CI / Build/Build] ⭐ Run Main Checkout repository +*DRYRUN* [CI / Build/Build] ✅ Success - Main Checkout repository [5.398708ms] +*DRYRUN* [CI / Build/Build] ⭐ Run Main Set up PHP +*DRYRUN* [CI / Build/Build] ✅ Success - Main Set up PHP [5.585334ms] +*DRYRUN* [CI / Build/Build] ⭐ Run Main Install Composer dependencies +*DRYRUN* [CI / Build/Build] ✅ Success - Main Install Composer dependencies [26.049167ms] +*DRYRUN* [CI / Build/Build] ⭐ Run Main Build production assets +*DRYRUN* [CI / Build/Build] ✅ Success - Main Build production assets [13.907375ms] *DRYRUN* [CI / Build/Build] ⭐ Run Complete job *DRYRUN* [CI / Build/Build] Cleaning up container for job Build *DRYRUN* [CI / Build/Build] ✅ Success - Complete job @@ -86,7 +110,9 @@ WARN ⚠ You are using Apple M-series chip and you have not specified container - The `path: ${{ inputs.working-dir }}/${{ inputs.artifact-path }}` composition is the only non-obvious bit. `defaults.run.working-directory` only affects `run:` steps; action inputs (`uses:` blocks) still resolve relative to the repo root. Composing the two inputs here is the cheapest way to keep monorepo callers ergonomic without exposing the GitHub Actions quirk. - `if-no-files-found: error` is a deliberate hardening over the planning doc, which didn't mention it. Worth a sanity-check during smoke testing — confirm that misconfiguring `artifact-path` produces a clear failure rather than a silent empty artifact. - `actions/upload-artifact` v7.0.1 exists but pins live at v4.6.2. Happy to bump if reviewers prefer staying on the latest major; v4 was chosen for stability and alignment with the planning doc. -`.yamllint.yml` fix is duplicated across the PRs. Whichever merges first wins; later ones hit a one-line conflict. +- Default `composer-flags` use `--no-dev` because this is a production-build workflow — different from `ci-lint-php` / `ci-test-php`, which need dev deps (PHPCS, PHPUnit). The inconsistency is deliberate, not a copy-paste oversight. +- Both stacks are individually toggleable (`install-node-deps`, `install-composer-deps`) because rtCamp consumes this workflow from plugins, themes, AND pure-PHP packages. Defaults reflect the most common case (Node-only). Setting both to `false` runs `build-command` on a bare checkout — degenerate but not broken. +- `.yamllint.yml` fix is duplicated across the PRs. Whichever merges first wins; later ones hit a one-line conflict. --- diff --git a/.github/workflows/ci-build.yml b/.github/workflows/ci-build.yml index 352196d..f9b15e4 100644 --- a/.github/workflows/ci-build.yml +++ b/.github/workflows/ci-build.yml @@ -3,10 +3,26 @@ name: CI / Build on: workflow_call: inputs: + install-node-deps: + description: "Install Node dependencies before the build." + type: boolean + default: true node-version: - description: "Node.js version to install." + description: "Node.js version (used only when install-node-deps is true)." type: string default: "22" + install-composer-deps: + description: "Install Composer dependencies before the build." + type: boolean + default: false + php-version: + description: "PHP version (used only when install-composer-deps is true)." + type: string + default: "8.3" + composer-flags: + description: "Flags passed to composer install." + type: string + default: "--no-dev --prefer-dist --optimize-autoloader --no-progress --no-interaction --no-scripts" build-command: description: "Shell command that produces the production build." type: string @@ -47,12 +63,26 @@ jobs: uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - name: Set up Node.js + if: ${{ inputs.install-node-deps }} uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 with: node-version: ${{ inputs.node-version }} cache: npm + - name: Set up PHP + if: ${{ inputs.install-composer-deps }} + uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # 2.37.0 + with: + php-version: ${{ inputs.php-version }} + coverage: none + tools: composer + + - name: Install Composer dependencies + if: ${{ inputs.install-composer-deps }} + run: composer install ${{ inputs.composer-flags }} + - name: Install npm dependencies + if: ${{ inputs.install-node-deps }} run: npm ci - name: Build production assets diff --git a/CHANGELOG.md b/CHANGELOG.md index 860a384..501e430 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,4 +8,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added -- `ci-build.yml` — reusable production-build workflow with an optional `upload-artifact` step (default `false`) so consumers can either verify the build exits 0 (CI-only) or hand the built files to a downstream CD job. Inputs: `node-version`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. Uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. +- `ci-build.yml` — reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. diff --git a/README.md b/README.md index 503edac..d05ba03 100644 --- a/README.md +++ b/README.md @@ -38,31 +38,55 @@ jobs: Runs the consumer's production build, with an optional artifact upload for downstream CD jobs. Default shape is build-only (no artifact written). ```yaml -# Verify the build exits 0 — no artifact written +# Node-only build — frontend-heavy plugin/theme (default shape) jobs: build: uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 with: node-version: "22" -# Build and hand the output to a downstream CD job +# Node-only build, hand the output to a downstream CD job jobs: build: uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 with: node-version: "22" upload-artifact: true + +# Node + Composer — plugin that ships vendor/ alongside compiled JS +jobs: + build: + uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + with: + node-version: "22" + install-composer-deps: true + php-version: "8.3" + upload-artifact: true + +# Composer-only — pure PHP package, no JS toolchain +jobs: + build: + uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + with: + install-node-deps: false + install-composer-deps: true + php-version: "8.3" + build-command: "composer run-script build" ``` -| Input | Type | Default | Description | -| ----------------- | ------- | --------------------- | ---------------------------------------------------------------------------- | -| `node-version` | string | `"22"` | Node.js version to install. | -| `build-command` | string | `"npm run build:prod"`| Shell command that produces the production build. | -| `upload-artifact` | boolean | `false` | Upload the build output as a GitHub Actions artifact for downstream jobs. | -| `artifact-name` | string | `"build"` | Artifact name. Must match the name in the downstream `actions/download-artifact` step. | -| `artifact-path` | string | `"build/"` | Path to upload. Resolved as `working-dir/artifact-path`. | -| `retention-days` | number | `7` | Days to keep the artifact before GitHub deletes it. | -| `working-dir` | string | `"."` | Working directory for monorepos. | +| Input | Type | Default | Description | +| ----------------------- | ------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `install-node-deps` | boolean | `true` | Install Node dependencies before the build. | +| `node-version` | string | `"22"` | Node.js version (used only when `install-node-deps` is true). | +| `install-composer-deps` | boolean | `false` | Install Composer dependencies before the build. | +| `php-version` | string | `"8.3"` | PHP version (used only when `install-composer-deps` is true). | +| `composer-flags` | string | `"--no-dev --prefer-dist --optimize-autoloader --no-progress --no-interaction --no-scripts"` | Flags passed to `composer install`. | +| `build-command` | string | `"npm run build:prod"` | Shell command that produces the production build. | +| `upload-artifact` | boolean | `false` | Upload the build output as a GitHub Actions artifact for downstream jobs. | +| `artifact-name` | string | `"build"` | Artifact name. Must match the name in the downstream `actions/download-artifact` step. | +| `artifact-path` | string | `"build/"` | Path to upload. Resolved as `working-dir/artifact-path`. | +| `retention-days` | number | `7` | Days to keep the artifact before GitHub deletes it. | +| `working-dir` | string | `"."` | Working directory for monorepos. | A misconfigured `artifact-path` fails loudly (`if-no-files-found: error`) — no silent empty artifacts. From 953ed1c7b968511753d33ab57f9fd8bf7e6d4ff5 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Fri, 15 May 2026 12:43:10 +0530 Subject: [PATCH 08/43] docs: update ci-test-js section in README.md to clarify caching and inputs --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 485ca2c..5c2e4c4 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ Each workflow can be called independently, so you can wire them into your own jo ### `ci-test-js.yml` — Jest tests -Runs JavaScript unit tests using Jest. Defaults match the legacy `Test and Measure` workflow, so most consumers do not need to provide any inputs. +Runs JavaScript unit tests using Jest with optional transform/result caching across runs. ```yaml # .github/workflows/ci.yml @@ -46,16 +46,16 @@ on: [push, pull_request] jobs: test-js: uses: rtCamp/shared-workflows/.github/workflows/ci-test-js.yml@v1 + with: + node-version: "22" ``` -Available inputs: - -| Workflow | Input | Default | -|---|---|---| -| `ci-test-js.yml` | `node-version` | `"22"` | -| | `test-command` | `npm run test:js -- --ci` | -| | `enable-cache` | `true` | -| | `working-dir` | `"."` | +| Input | Type | Default | Description | +| -------------- | ------- | -------------------------- | ------------------------------------------------ | +| `node-version` | string | `"22"` | Node.js version to install. | +| `test-command` | string | `"npm run test:js -- --ci"`| Shell command that runs Jest. | +| `enable-cache` | boolean | `true` | Cache Jest transform/result data across runs. | +| `working-dir` | string | `"."` | Working directory for monorepos. | ### `ci-test-a11y.yml` — accessibility tests From 14f11fe8f62d3a88cab5c4f3030196c9058e89ee Mon Sep 17 00:00:00 2001 From: AnuragVasanwala <75766877+AnuragVasanwala@users.noreply.github.com> Date: Thu, 21 May 2026 10:50:53 +0530 Subject: [PATCH 09/43] feat(ci): enhance test-command input handling for PHPUnit execution --- .github/workflows/ci-test-php.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci-test-php.yml b/.github/workflows/ci-test-php.yml index 8e86e20..85282e1 100644 --- a/.github/workflows/ci-test-php.yml +++ b/.github/workflows/ci-test-php.yml @@ -16,9 +16,9 @@ on: type: boolean default: true test-command: - description: "Shell command that runs PHPUnit." + description: "Shell command that runs PHPUnit. When empty, defaults to 'npm run test:php' if use-wp-env is true, otherwise 'vendor/bin/phpunit'." type: string - default: "npm run test:php" + default: "" composer-flags: description: "Flags passed to composer install." type: string @@ -68,7 +68,7 @@ jobs: run: npm run wp-env start - name: Run PHPUnit - run: ${{ inputs.test-command }} + run: ${{ inputs.test-command != '' && inputs.test-command || (inputs.use-wp-env && 'npm run test:php' || 'vendor/bin/phpunit') }} - name: Stop wp-env if: ${{ inputs.use-wp-env && always() }} From f361b08109d213cb57b33fbd314f9b89cc0bc2cd Mon Sep 17 00:00:00 2001 From: AnuragVasanwala <75766877+AnuragVasanwala@users.noreply.github.com> Date: Thu, 21 May 2026 10:51:08 +0530 Subject: [PATCH 10/43] docs: update README and CHANGELOG for ci-test-php workflow enhancements --- CHANGELOG.md | 2 +- README.md | 13 ++++++++----- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2667c48..fec4c26 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,4 +8,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added -- `ci-test-php.yml` — reusable PHPUnit workflow with a `use-wp-env` toggle (default `true`) for WordPress integration tests via `@wordpress/env`, or standalone PHPUnit for Composer-only packages and libraries. Inputs: `php-version`, `node-version`, `use-wp-env`, `test-command`, `composer-flags`, `working-dir`. \ No newline at end of file +- `ci-test-php.yml`: reusable PHPUnit workflow with a `use-wp-env` toggle (default `true`) for WordPress integration tests via `@wordpress/env`, or standalone PHPUnit for Composer-only packages and libraries. Inputs: `php-version`, `node-version`, `use-wp-env`, `test-command`, `composer-flags`, `working-dir`. The `test-command` default is empty and selects `npm run test:php` in wp-env mode, `vendor/bin/phpunit` standalone. diff --git a/README.md b/README.md index d92c28b..1ed7ba5 100644 --- a/README.md +++ b/README.md @@ -33,26 +33,29 @@ jobs: ## Individual workflows -### `ci-test-php.yml` — PHPUnit +### `ci-test-php.yml`: PHPUnit Runs PHPUnit either against a real WordPress environment via [`@wordpress/env`](https://github.com/WordPress/gutenberg/tree/trunk/packages/env) (default) or standalone for Composer libraries. +**Plugin or theme:** WordPress integration tests via `wp-env` (default). + ```yaml -# Plugin or theme — WordPress integration tests via wp-env (default) jobs: test-php: uses: rtCamp/shared-workflows/.github/workflows/ci-test-php.yml@v1 with: php-version: "8.3" +``` -# Composer package — standalone PHPUnit, no Node, no Docker +**Composer package:** standalone PHPUnit, no Node, no Docker. + +```yaml jobs: test-php: uses: rtCamp/shared-workflows/.github/workflows/ci-test-php.yml@v1 with: php-version: "8.3" use-wp-env: false - test-command: "vendor/bin/phpunit" ``` | Input | Type | Default | Description | @@ -60,7 +63,7 @@ jobs: | `php-version` | string | `"8.3"` | PHP version to install. | | `node-version` | string | `"22"` | Node.js version. Consumed only when `use-wp-env: true`. | | `use-wp-env` | boolean | `true` | Start `@wordpress/env` before tests for WordPress integration runs. | -| `test-command` | string | `"npm run test:php"` | Shell command that runs PHPUnit. | +| `test-command` | string | `""` | PHPUnit command. Empty means `npm run test:php` in wp-env mode, `vendor/bin/phpunit` standalone. | | `composer-flags` | string | `"--no-interaction --prefer-dist --no-progress --no-scripts"` | Flags passed to `composer install`. Keep `--no-scripts` for supply-chain hygiene. | | `working-dir` | string | `"."` | Working directory for monorepos. | From 466b8c98963f9f39dfd9d3628f3e81494cc7959d Mon Sep 17 00:00:00 2001 From: AnuragVasanwala <75766877+AnuragVasanwala@users.noreply.github.com> Date: Thu, 21 May 2026 11:28:35 +0530 Subject: [PATCH 11/43] feat(ci): enhance build-command input handling for dynamic defaults --- .github/workflows/ci-build.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci-build.yml b/.github/workflows/ci-build.yml index f9b15e4..c67a5bd 100644 --- a/.github/workflows/ci-build.yml +++ b/.github/workflows/ci-build.yml @@ -24,9 +24,9 @@ on: type: string default: "--no-dev --prefer-dist --optimize-autoloader --no-progress --no-interaction --no-scripts" build-command: - description: "Shell command that produces the production build." + description: "Shell command that produces the production build. When empty, defaults to 'npm run build:prod' if install-node-deps is true, otherwise 'composer run-script build'." type: string - default: "npm run build:prod" + default: "" upload-artifact: description: "Upload the build output as a GitHub Actions artifact for downstream jobs." type: boolean @@ -86,7 +86,7 @@ jobs: run: npm ci - name: Build production assets - run: ${{ inputs.build-command }} + run: ${{ inputs.build-command != '' && inputs.build-command || (inputs.install-node-deps && 'npm run build:prod' || 'composer run-script build') }} - name: Upload build artifact if: ${{ inputs.upload-artifact }} From b9f8ff21f053de7f9242e50bdc1cd3fe53a816cd Mon Sep 17 00:00:00 2001 From: AnuragVasanwala <75766877+AnuragVasanwala@users.noreply.github.com> Date: Thu, 21 May 2026 11:29:07 +0530 Subject: [PATCH 12/43] docs: update README and CHANGELOG for ci-build.yml workflow details --- CHANGELOG.md | 2 +- README.md | 25 +++++++++++++++++-------- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 501e430..a67d656 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,4 +8,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added -- `ci-build.yml` — reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. +- `ci-build.yml`: reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. The `build-command` default is empty and selects `npm run build:prod` when Node deps install, `composer run-script build` otherwise. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. diff --git a/README.md b/README.md index d05ba03..06204cd 100644 --- a/README.md +++ b/README.md @@ -33,27 +33,34 @@ jobs: ## Individual workflows -### `ci-build.yml` — production build +### `ci-build.yml`: production build Runs the consumer's production build, with an optional artifact upload for downstream CD jobs. Default shape is build-only (no artifact written). +**Node-only build (default):** frontend-heavy plugin or theme. + ```yaml -# Node-only build — frontend-heavy plugin/theme (default shape) jobs: build: uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 with: node-version: "22" +``` + +**Node-only build with artifact upload:** hand the output to a downstream CD job. -# Node-only build, hand the output to a downstream CD job +```yaml jobs: build: uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 with: node-version: "22" upload-artifact: true +``` -# Node + Composer — plugin that ships vendor/ alongside compiled JS +**Node + Composer:** plugin that ships `vendor/` alongside compiled JS. + +```yaml jobs: build: uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 @@ -62,8 +69,11 @@ jobs: install-composer-deps: true php-version: "8.3" upload-artifact: true +``` -# Composer-only — pure PHP package, no JS toolchain +**Composer-only:** pure PHP package, no JS toolchain. + +```yaml jobs: build: uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 @@ -71,7 +81,6 @@ jobs: install-node-deps: false install-composer-deps: true php-version: "8.3" - build-command: "composer run-script build" ``` | Input | Type | Default | Description | @@ -81,14 +90,14 @@ jobs: | `install-composer-deps` | boolean | `false` | Install Composer dependencies before the build. | | `php-version` | string | `"8.3"` | PHP version (used only when `install-composer-deps` is true). | | `composer-flags` | string | `"--no-dev --prefer-dist --optimize-autoloader --no-progress --no-interaction --no-scripts"` | Flags passed to `composer install`. | -| `build-command` | string | `"npm run build:prod"` | Shell command that produces the production build. | +| `build-command` | string | `""` | Build command. Empty means `npm run build:prod` when `install-node-deps` is true, otherwise `composer run-script build`. | | `upload-artifact` | boolean | `false` | Upload the build output as a GitHub Actions artifact for downstream jobs. | | `artifact-name` | string | `"build"` | Artifact name. Must match the name in the downstream `actions/download-artifact` step. | | `artifact-path` | string | `"build/"` | Path to upload. Resolved as `working-dir/artifact-path`. | | `retention-days` | number | `7` | Days to keep the artifact before GitHub deletes it. | | `working-dir` | string | `"."` | Working directory for monorepos. | -A misconfigured `artifact-path` fails loudly (`if-no-files-found: error`) — no silent empty artifacts. +A misconfigured `artifact-path` fails loudly via `if-no-files-found: error`. No silent empty artifacts. ## License From 24d3939325ae564245b0617043b94cdc84f80215 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Thu, 14 May 2026 15:55:12 +0530 Subject: [PATCH 13/43] feat: add CI build artifact gate workflow --- .github/workflows/ci-build-artifact-gate.yml | 74 ++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 .github/workflows/ci-build-artifact-gate.yml diff --git a/.github/workflows/ci-build-artifact-gate.yml b/.github/workflows/ci-build-artifact-gate.yml new file mode 100644 index 0000000..cfae065 --- /dev/null +++ b/.github/workflows/ci-build-artifact-gate.yml @@ -0,0 +1,74 @@ +name: CI / Build Artifact Gate + +on: + workflow_call: + inputs: + gated-paths: + description: "Newline-separated path prefixes whose contents must not be committed in a PR." + type: string + default: "assets/build/" + working-dir: + description: "Working directory for monorepos." + type: string + default: "." + +permissions: + contents: read + +jobs: + build-artifact-gate: + name: Block committed build artifacts + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Detect committed build artifacts + shell: bash + env: + GATED_PATHS: ${{ inputs.gated-paths }} + WORKING_DIR: ${{ inputs.working-dir }} + BASE_REF: ${{ github.base_ref }} + run: | + set -euo pipefail + + if [[ -z "$BASE_REF" ]]; then + echo "::notice::Not a pull_request event (no base ref); skipping gate." + exit 0 + fi + + git fetch --no-tags --depth=1 origin "+refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}" + + PATTERN=$(printf '%s\n' "$GATED_PATHS" \ + | sed 's/^[[:space:]]*//; s/[[:space:]]*$//' \ + | grep -v '^$' \ + | sed 's/\./\\./g' \ + | paste -sd '|' -) + + if [[ -z "$PATTERN" ]]; then + echo "::notice::No gated paths configured; skipping." + exit 0 + fi + + WORKING_DIR="${WORKING_DIR%/}" + if [[ -n "$WORKING_DIR" && "$WORKING_DIR" != "." ]]; then + ANCHORED="^${WORKING_DIR}/(${PATTERN})" + else + ANCHORED="^(${PATTERN})" + fi + + echo "Comparing origin/${BASE_REF}..HEAD against pattern: ${ANCHORED}" + + CHANGED=$(git diff --name-only --diff-filter=ACMR "origin/${BASE_REF}..HEAD" \ + | grep -E "${ANCHORED}" || true) + + if [[ -n "$CHANGED" ]]; then + echo "::error::Build artifacts must not be committed. Offending files:" + printf '%s\n' "$CHANGED" | sed 's/^/ - /' + echo + echo "These paths are produced by CI on merge. Remove them from the PR" + echo "(e.g. 'git rm --cached ') and ensure they are gitignored." + exit 1 + fi + + echo "No committed build artifacts detected." From f1bb0c079d593557d9a25bd95297bd87af32dab4 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Thu, 14 May 2026 16:09:44 +0530 Subject: [PATCH 14/43] docs: update README to include details on ci-build-artifact-gate workflow --- README.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/README.md b/README.md index db980cf..62706d0 100644 --- a/README.md +++ b/README.md @@ -182,6 +182,44 @@ jobs: Step order is load-bearing: build runs **before** `wp-env start` so pa11y sees compiled CSS/JS. `wp-env stop` uses `if: always()` so a failing pa11y run does not leak a Docker stack into the next job. +## Individual workflows + +### `ci-build-artifact-gate.yml` — block committed build artifacts + +Fails a PR if it touches any file under the configured path prefixes (default: `assets/build/`). Pair it with `ci-build.yml` so the build output produced by CI is the only source of truth, never a stale tree committed by hand. + +```yaml +# Default — gate assets/build/ in a flat repo +jobs: + artifact-gate: + uses: rtCamp/shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 + +# Multiple gated paths +jobs: + artifact-gate: + uses: rtCamp/shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 + with: + gated-paths: | + assets/build/ + dist/ + public/build/ + +# Monorepo — scope the gate to one sub-package +jobs: + artifact-gate: + uses: rtCamp/shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 + with: + gated-paths: "assets/build/" + working-dir: "packages/admin-ui" +``` + +| Input | Type | Default | Description | +| ------------- | ------ | ----------------- | --------------------------------------------------------------------------------- | +| `gated-paths` | string | `"assets/build/"` | Newline-separated path prefixes whose contents must not be committed in a PR. | +| `working-dir` | string | `"."` | Working directory for monorepos. Path prefixes are anchored under this directory. | + +Only meaningful on `pull_request` events — on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. The check compares `origin/..HEAD` with `--diff-filter=ACMR`, so deletions are ignored: removing a previously-committed artifact in the PR does not trip the gate. + ## License GPL-2.0-or-later From c1ad9e490bf80176ae81a5d66fb96f0bc06bc64c Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Thu, 21 May 2026 16:30:43 +0530 Subject: [PATCH 15/43] fix(ci): harden build artifact gate pattern parsing --- .github/workflows/ci-build-artifact-gate.yml | 5 ++--- CHANGELOG.md | 1 + README.md | 13 ++++++++++--- 3 files changed, 13 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci-build-artifact-gate.yml b/.github/workflows/ci-build-artifact-gate.yml index cfae065..b0fe05b 100644 --- a/.github/workflows/ci-build-artifact-gate.yml +++ b/.github/workflows/ci-build-artifact-gate.yml @@ -40,9 +40,8 @@ jobs: git fetch --no-tags --depth=1 origin "+refs/heads/${BASE_REF}:refs/remotes/origin/${BASE_REF}" PATTERN=$(printf '%s\n' "$GATED_PATHS" \ - | sed 's/^[[:space:]]*//; s/[[:space:]]*$//' \ - | grep -v '^$' \ - | sed 's/\./\\./g' \ + | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//' -e '/^$/d' \ + | sed 's/[][\\.|^$()*+?{}]/\\&/g' \ | paste -sd '|' -) if [[ -z "$PATTERN" ]]; then diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c882c8..f5f049f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,3 +12,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `ci-test-js.yml` — reusable Jest unit-test workflow with optional cross-run cache (`enable-cache`), monorepo support (`working-dir`), and a consumer-overridable command (`test-command`). Replaces the copy-pasted `unit-tests-js` job from the legacy `Test and Measure` workflow. - `ci-test-a11y.yml` — reusable pa11y-ci accessibility test workflow. Order: `npm ci` → build → `wp-env start` → pa11y → `wp-env stop` (with `if: always()` so cleanup runs on failure). Inputs: `node-version`, `build-command`, `test-command`, `working-dir`. Trigger-agnostic — consumers wire the `Run a11y` label gate at the caller level. - `ci-build.yml`: reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. The `build-command` default is empty and selects `npm run build:prod` when Node deps install, `composer run-script build` otherwise. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. +- `ci-build-artifact-gate.yml` — reusable workflow that fails a PR if it commits files under configured path prefixes (default: `assets/build/`). Pair with `ci-build.yml` so the CI-produced bundle is the only source of truth for build output. Compares `origin/..HEAD` with `--diff-filter=ACMR`, so additions/modifications/renames trip the gate and deletions are ignored (removing a previously-committed artifact is welcome). Runs only on `pull_request` events; on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. Empty `gated-paths` input skips gracefully. Path prefixes are anchored as literal strings — regex metacharacters in path names (`. + * ( ) [ ] { } | ^ $ ? \`) are escaped automatically. Inputs: `gated-paths`, `working-dir`. diff --git a/README.md b/README.md index 62706d0..bf7e3e7 100644 --- a/README.md +++ b/README.md @@ -188,13 +188,17 @@ Step order is load-bearing: build runs **before** `wp-env start` so pa11y sees c Fails a PR if it touches any file under the configured path prefixes (default: `assets/build/`). Pair it with `ci-build.yml` so the build output produced by CI is the only source of truth, never a stale tree committed by hand. +**Default — gate `assets/build/` in a flat repo:** + ```yaml -# Default — gate assets/build/ in a flat repo jobs: artifact-gate: uses: rtCamp/shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 +``` -# Multiple gated paths +**Multiple gated paths:** + +```yaml jobs: artifact-gate: uses: rtCamp/shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 @@ -203,8 +207,11 @@ jobs: assets/build/ dist/ public/build/ +``` + +**Monorepo — scope the gate to one sub-package:** -# Monorepo — scope the gate to one sub-package +```yaml jobs: artifact-gate: uses: rtCamp/shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 From 58a4470515ff27dc8c89dc1660421fad293e753f Mon Sep 17 00:00:00 2001 From: AnuragVasanwala <75766877+AnuragVasanwala@users.noreply.github.com> Date: Fri, 22 May 2026 14:52:30 +0530 Subject: [PATCH 16/43] feat: add ci-build-artifact-gate documentation and update changelog --- .claude/issues/19-ci-build-artifact-gate.md | 97 +++++++++++++++++++++ CHANGELOG.md | 2 +- README.md | 8 +- 3 files changed, 102 insertions(+), 5 deletions(-) create mode 100644 .claude/issues/19-ci-build-artifact-gate.md diff --git a/.claude/issues/19-ci-build-artifact-gate.md b/.claude/issues/19-ci-build-artifact-gate.md new file mode 100644 index 0000000..e494a10 --- /dev/null +++ b/.claude/issues/19-ci-build-artifact-gate.md @@ -0,0 +1,97 @@ +# Issue #19: Add ci-build-artifact-gate reusable workflow + +**Status:** in-review +**Branch:** `v1.0.0/task/ci-build-artifact-gate` +**PR:** #19 +**Closes:** `rtCamp/theme-elementary#642` (external) +**Assignee:** @Adi-ty + +--- + +## Summary + +Every rtCamp WordPress project that produces build output (compiled CSS/JS, Composer `vendor/`, etc.) needs a gate that fails any PR which commits those files. The build is meant to be produced by CI on merge, not committed by hand. Without a gate, stale build trees creep into the repo and silently override what CI produces. + +This task lifts the inline `rtcamp-standard.yml` workflow from `rtCamp/theme-elementary` (issue [#642](https://github.com/rtCamp/theme-elementary/issues/642)) into shared-workflows as `ci-build-artifact-gate.yml`, so every rtCamp repo can consume it via `uses:` instead of copy-pasting. Default gated path is `assets/build/`. Consumers can pass a newline-separated list of prefixes and an optional `working-dir` for monorepos. + +--- + +## Decisions made + +- [2026-05-21] Implementation lifted from `theme-elementary`'s inline `.github/workflows/rtcamp-standard.yml`. Same diff-based detection, but reworked to take inputs (`gated-paths`, `working-dir`) so consumers can configure rather than fork. +- [2026-05-21] Inputs passed to bash via `env:` rather than direct GHA expression interpolation. Prevents expression injection if a consumer ever passes a value with backticks or `$(...)` in it. `set -euo pipefail` guards against silent failures in the script body. +- [2026-05-21] `--diff-filter=ACMR` chosen so deletions of previously-committed artifacts are explicitly allowed. Cleaning up an old committed `assets/build/` is a welcome change, not something the gate should block. +- [2026-05-21] Non-PR triggers (missing `github.base_ref`) skip gracefully with a `::notice::`. Lets a consumer wire this into a generic `on: [push, pull_request]` workflow without it firing on direct pushes to main. +- [2026-05-21] `permissions: contents: read`. Least-privilege; the workflow only reads the diff, never writes anywhere. +- [2026-05-21] Drive-by fix to `.yamllint.yml` line 14 (bracket spacing). Same starter-kit bug other PRs in this milestone also touched. Whichever lands first wins. +- [2026-05-21] In response to PR review (PR #19): switched empty-line removal from `grep -v '^$'` to `sed -e '/^$/d'`. `grep -v` returns exit 1 when no matches are found, which under `set -e` + `pipefail` would crash the script before the empty-`PATTERN` check could fire. `sed` exits 0 even on empty input, so the graceful-skip branch is now actually reachable. Verified by reproduction. +- [2026-05-21] In response to PR review (PR #19): broadened the regex escape from `sed 's/\./\\./g'` to `sed 's/[][\\.|^$()*+?{}]/\\&/g'` so all regex metacharacters in path names are neutralised. A directory like `c++build/` or `dist[v2]/` now matches as a literal path, not as a regex pattern. + +### Action SHA pins recorded + +- `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683`: v4.2.2. + +--- + +## Files changed so far + +- `.github/workflows/ci-build-artifact-gate.yml`: new +- `.claude/issues/19-ci-build-artifact-gate.md`: new (this file) +- `README.md`: edited (caller examples + inputs table) +- `CHANGELOG.md`: edited (new entry under `## Unreleased`) +- `.yamllint.yml`: edited (drive-by bracket-spacing fix on line 14) + +--- + +## Verification run + +```bash +$ python3 -m yamllint . +# exit 0 + +$ act workflow_call -W .github/workflows/ci-build-artifact-gate.yml --dryrun --container-architecture linux/amd64 +*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ⭐ Run Set up job +*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ✅ Success - Set up job +*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ⭐ Run Main Checkout repository +*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ✅ Success - Main Checkout repository +*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ⭐ Run Main Detect committed build artifacts +*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ✅ Success - Main Detect committed build artifacts +*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ✅ Success - Complete job +*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] 🏁 Job succeeded +``` + +Standalone reproduction of the PATTERN pipeline against the post-review code (commit `c1ad9e4`): + +``` +case=empty PATTERN=[] + -> graceful-skip-reached +case=whitespace-only PATTERN=[] + -> graceful-skip-reached +case=single-path PATTERN=[assets/build/] + -> continues to diff phase +case=multi-path-with-regex-chars PATTERN=[assets/build/|c\+\+build/|dist\[v2\]/] + -> continues to diff phase +overall-exit=0 +``` + +Confirms: empty and whitespace-only `gated-paths` reach the graceful-skip branch (acceptance criterion), and paths with regex metacharacters (`c++build/`, `dist[v2]/`) are escaped as literal strings. + +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- A full end-to-end smoke test against a real `pull_request` payload is still outstanding. `act --dryrun` cannot exercise the actual GitHub event context, so the "detects a committed `assets/build/` file, surfaces a clear error, exits 1" path is unverified locally. Recommend running once against a throwaway consumer repo before tagging. +- This PR closes an external issue (`rtCamp/theme-elementary#642`), so there was no internal GitHub issue in this repo. This file was created retroactively to keep the decision log alongside the other v1.0.0 task issues. +- `.yamllint.yml` line 14 conflicts with PRs #6 and #8. PR #6 already merged, so this branch was rebased and the conflict resolved before final review. + +--- + +## Handoff log + +_(no rotations yet; delete this line when the first entry is added)_ diff --git a/CHANGELOG.md b/CHANGELOG.md index f5f049f..f792741 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,4 +12,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `ci-test-js.yml` — reusable Jest unit-test workflow with optional cross-run cache (`enable-cache`), monorepo support (`working-dir`), and a consumer-overridable command (`test-command`). Replaces the copy-pasted `unit-tests-js` job from the legacy `Test and Measure` workflow. - `ci-test-a11y.yml` — reusable pa11y-ci accessibility test workflow. Order: `npm ci` → build → `wp-env start` → pa11y → `wp-env stop` (with `if: always()` so cleanup runs on failure). Inputs: `node-version`, `build-command`, `test-command`, `working-dir`. Trigger-agnostic — consumers wire the `Run a11y` label gate at the caller level. - `ci-build.yml`: reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. The `build-command` default is empty and selects `npm run build:prod` when Node deps install, `composer run-script build` otherwise. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. -- `ci-build-artifact-gate.yml` — reusable workflow that fails a PR if it commits files under configured path prefixes (default: `assets/build/`). Pair with `ci-build.yml` so the CI-produced bundle is the only source of truth for build output. Compares `origin/..HEAD` with `--diff-filter=ACMR`, so additions/modifications/renames trip the gate and deletions are ignored (removing a previously-committed artifact is welcome). Runs only on `pull_request` events; on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. Empty `gated-paths` input skips gracefully. Path prefixes are anchored as literal strings — regex metacharacters in path names (`. + * ( ) [ ] { } | ^ $ ? \`) are escaped automatically. Inputs: `gated-paths`, `working-dir`. +- `ci-build-artifact-gate.yml`: reusable workflow that fails a PR if it commits files under configured path prefixes (default: `assets/build/`). Pair with `ci-build.yml` so the CI-produced bundle is the only source of truth for build output. Compares `origin/..HEAD` with `--diff-filter=ACMR`, so additions/modifications/renames trip the gate and deletions are ignored (removing a previously-committed artifact is welcome). Runs only on `pull_request` events; on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. Empty `gated-paths` input skips gracefully. Path prefixes are anchored as literal strings, and regex metacharacters in path names (`. + * ( ) [ ] { } | ^ $ ? \`) are escaped automatically. Inputs: `gated-paths`, `working-dir`. diff --git a/README.md b/README.md index bf7e3e7..b61f508 100644 --- a/README.md +++ b/README.md @@ -184,11 +184,11 @@ Step order is load-bearing: build runs **before** `wp-env start` so pa11y sees c ## Individual workflows -### `ci-build-artifact-gate.yml` — block committed build artifacts +### `ci-build-artifact-gate.yml`: block committed build artifacts Fails a PR if it touches any file under the configured path prefixes (default: `assets/build/`). Pair it with `ci-build.yml` so the build output produced by CI is the only source of truth, never a stale tree committed by hand. -**Default — gate `assets/build/` in a flat repo:** +**Default:** gate `assets/build/` in a flat repo. ```yaml jobs: @@ -209,7 +209,7 @@ jobs: public/build/ ``` -**Monorepo — scope the gate to one sub-package:** +**Monorepo:** scope the gate to one sub-package. ```yaml jobs: @@ -225,7 +225,7 @@ jobs: | `gated-paths` | string | `"assets/build/"` | Newline-separated path prefixes whose contents must not be committed in a PR. | | `working-dir` | string | `"."` | Working directory for monorepos. Path prefixes are anchored under this directory. | -Only meaningful on `pull_request` events — on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. The check compares `origin/..HEAD` with `--diff-filter=ACMR`, so deletions are ignored: removing a previously-committed artifact in the PR does not trip the gate. +Only meaningful on `pull_request` events. On other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. The check compares `origin/..HEAD` with `--diff-filter=ACMR`, so deletions are ignored: removing a previously-committed artifact in the PR does not trip the gate. ## License From 2e45e672fc3ab1d3f146fad227f522078184f4ce Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Mon, 25 May 2026 16:50:09 +0530 Subject: [PATCH 17/43] feat(cd): add reusable split packages workflow --- .github/workflows/cd-split-packages.yml | 135 ++++++++++++++++++++++++ CHANGELOG.md | 1 + README.md | 75 +++++++++++++ 3 files changed, 211 insertions(+) create mode 100644 .github/workflows/cd-split-packages.yml diff --git a/.github/workflows/cd-split-packages.yml b/.github/workflows/cd-split-packages.yml new file mode 100644 index 0000000..9a23580 --- /dev/null +++ b/.github/workflows/cd-split-packages.yml @@ -0,0 +1,135 @@ +name: CD / Split Composer Packages + +# Splits Composer-package subtrees out of a monorepo into standalone mirror +# repos (the Symfony "monorepo split" pattern), so Packagist can serve each +# package from its own repository. +# +# * (default splitsh.json) is the single source of truth for +# mirror-repo name -> monorepo subdirectory. It lives in the CALLING +# monorepo (e.g. wp-tooling), NOT in this repo: as a reusable workflow, +# actions/checkout here pulls the caller's repository by default, so the +# config is read from the caller's checkout at the triggering ref. +# * build-matrix reads it once and emits a matrix. +# * split runs splitsh-lite (via the danharrin action) per subtree, in +# parallel, force-pushing each subtree to its mirror. +# +# To add/remove a package: edit the config file. No workflow change needed. + +on: + workflow_call: + inputs: + tag: + description: "Tag to push to the mirror repos. When empty, falls back to the ref that triggered the caller (github.ref_name)." + type: string + default: "" + config-file: + description: "Path to the splitsh config file, relative to the repo root." + type: string + default: "splitsh.json" + secrets: + split-token: + description: "Token (fine-grained PAT or GitHub App token) with 'contents: write' on every mirror repo listed in the config file." + required: true + +permissions: + contents: read + +jobs: + build-matrix: + name: Build split matrix from config + runs-on: ubuntu-latest + outputs: + matrix: ${{ steps.parse.outputs.matrix }} + organization: ${{ steps.parse.outputs.organization }} + branch: ${{ steps.parse.outputs.branch }} + user_name: ${{ steps.parse.outputs.user_name }} + user_email: ${{ steps.parse.outputs.user_email }} + tag: ${{ steps.parse.outputs.tag }} + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Parse config into a matrix + id: parse + shell: bash + env: + CONFIG_FILE: ${{ inputs.config-file }} + INPUT_TAG: ${{ inputs.tag }} + run: | + set -euo pipefail + + if [[ ! -f "$CONFIG_FILE" ]]; then + echo "::error::Config file '$CONFIG_FILE' not found at the repo root." + exit 1 + fi + + if ! jq empty "$CONFIG_FILE" 2>/dev/null; then + echo "::error::Config file '$CONFIG_FILE' is not valid JSON." + exit 1 + fi + + # Normalise both the shorthand string form ("composer-packages/foo") + # and the object form ({ "prefixes": [{ "from": "..." }] }). + matrix=$(jq -c '{ + include: [ + .subtrees // {} | to_entries[] | { + mirror_repo: .key, + package_directory: ( + if (.value | type) == "string" then .value + else .value.prefixes[0].from + end + ) + } + ] + }' "$CONFIG_FILE") + + count=$(jq -r '.include | length' <<<"$matrix") + if [[ "$count" -eq 0 ]]; then + echo "::error::No subtrees defined in '$CONFIG_FILE'. Nothing to split." + exit 1 + fi + + # Resolve the tag: explicit input wins, else the caller's ref name. + tag="$INPUT_TAG" + if [[ -z "$tag" ]]; then + tag="${{ github.ref_name }}" + fi + + { + echo "matrix=$matrix" + echo "organization=$(jq -r '.organization' "$CONFIG_FILE")" + echo "branch=$(jq -r '.defaults.branch' "$CONFIG_FILE")" + echo "user_name=$(jq -r '.defaults.user_name' "$CONFIG_FILE")" + echo "user_email=$(jq -r '.defaults.user_email' "$CONFIG_FILE")" + echo "tag=$tag" + } >> "$GITHUB_OUTPUT" + + - name: Echo resolved matrix + run: echo '${{ steps.parse.outputs.matrix }}' | jq . + + split: + name: Split ${{ matrix.mirror_repo }} + needs: build-matrix + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: ${{ fromJson(needs.build-matrix.outputs.matrix) }} + steps: + - name: Checkout monorepo (full history) + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + # splitsh-lite needs every commit that ever touched the subtree. + fetch-depth: 0 + + - name: Split and push subtree to mirror + uses: danharrin/monorepo-split-github-action@14e42e2437f674b8987c1f50ca3689116aea1893 # v2.4.5 + with: + package_directory: ${{ matrix.package_directory }} + repository_organization: ${{ needs.build-matrix.outputs.organization }} + repository_name: ${{ matrix.mirror_repo }} + branch: ${{ needs.build-matrix.outputs.branch }} + tag: ${{ needs.build-matrix.outputs.tag }} + user_name: ${{ needs.build-matrix.outputs.user_name }} + user_email: ${{ needs.build-matrix.outputs.user_email }} + env: + GITHUB_TOKEN: ${{ secrets.split-token }} diff --git a/CHANGELOG.md b/CHANGELOG.md index f792741..03ae3c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,3 +13,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `ci-test-a11y.yml` — reusable pa11y-ci accessibility test workflow. Order: `npm ci` → build → `wp-env start` → pa11y → `wp-env stop` (with `if: always()` so cleanup runs on failure). Inputs: `node-version`, `build-command`, `test-command`, `working-dir`. Trigger-agnostic — consumers wire the `Run a11y` label gate at the caller level. - `ci-build.yml`: reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. The `build-command` default is empty and selects `npm run build:prod` when Node deps install, `composer run-script build` otherwise. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. - `ci-build-artifact-gate.yml`: reusable workflow that fails a PR if it commits files under configured path prefixes (default: `assets/build/`). Pair with `ci-build.yml` so the CI-produced bundle is the only source of truth for build output. Compares `origin/..HEAD` with `--diff-filter=ACMR`, so additions/modifications/renames trip the gate and deletions are ignored (removing a previously-committed artifact is welcome). Runs only on `pull_request` events; on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. Empty `gated-paths` input skips gracefully. Path prefixes are anchored as literal strings, and regex metacharacters in path names (`. + * ( ) [ ] { } | ^ $ ? \`) are escaped automatically. Inputs: `gated-paths`, `working-dir`. +- `cd-split-packages.yml`: reusable "monorepo split" workflow (Symfony pattern) that mirrors each Composer-package subtree to its own standalone repo so Packagist can serve it. A `build-matrix` job parses `splitsh.json` (`organization`, `subtrees` map, `defaults.branch`/`user_name`/`user_email`) with jq — accepting both the shorthand string form and the object/`prefixes` form — and a matrixed `split` job runs `danharrin/monorepo-split-github-action` (pinned to `14e42e2`, v2.4.5) per subtree with `fail-fast: false`. `tag` falls back to the caller's `github.ref_name` when empty; missing or empty config fails loudly. Inputs: `tag`, `config-file`. Secret: `split-token` (PAT/App token with `contents: write` on every mirror repo). diff --git a/README.md b/README.md index b61f508..12d5e91 100644 --- a/README.md +++ b/README.md @@ -227,6 +227,81 @@ jobs: Only meaningful on `pull_request` events. On other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. The check compares `origin/..HEAD` with `--diff-filter=ACMR`, so deletions are ignored: removing a previously-committed artifact in the PR does not trip the gate. +### `cd-split-packages.yml`: split Composer packages to mirror repos + +Splits Composer-package subtrees out of a monorepo into standalone mirror repos (the Symfony "monorepo split" pattern), so Packagist can serve each package from its own repository. A `splitsh.json` at the repo root is the single source of truth — to add or remove a package, edit that file, never the workflow. + +`splitsh.json` lives in the **calling** monorepo (e.g. `wp-tooling`), not in this repo. As a reusable workflow, `actions/checkout` pulls the caller's repository by default, so the config is read from the caller's checkout — `config-file` is a path relative to that checkout, never the file's contents. + +`splitsh.json`: + +```json +{ + "organization": "rtCamp", + "subtrees": { + "wp-phpcs": "composer-packages/phpcs", + "wp-phpstan": "composer-packages/phpstan" + }, + "defaults": { + "branch": "main", + "user_name": "github-actions[bot]", + "user_email": "github-actions[bot]@users.noreply.github.com" + } +} +``` + +Caller — split on every `v*` tag push: + +```yaml +# .github/workflows/split.yml in the monorepo +name: Split Composer Packages +on: + push: + tags: ["v*"] +jobs: + split: + uses: rtCamp/shared-workflows/.github/workflows/cd-split-packages.yml@v1 + with: + tag: ${{ github.ref_name }} + secrets: + split-token: ${{ secrets.SPLIT_TOKEN }} +``` + +The reusable workflow owns no trigger of its own — the caller decides when it runs. To also allow a manual smoke-test run (the `workflow_dispatch` path the standalone version had), add the trigger and pass the tag through. On a manual run `github.ref_name` is a **branch**, not a tag, so the dispatch input must win: + +```yaml +# .github/workflows/split.yml in the monorepo +name: Split Composer Packages +on: + push: + tags: ["v*"] + workflow_dispatch: + inputs: + test_tag: + description: "Throwaway tag to push to mirrors (e.g. v0.0.0-test)" + required: true + default: "v0.0.0-test" +jobs: + split: + uses: rtCamp/shared-workflows/.github/workflows/cd-split-packages.yml@v1 + with: + # Manual run → use the dispatch input; tag push → the pushed tag. + tag: ${{ github.event.inputs.test_tag || github.ref_name }} + secrets: + split-token: ${{ secrets.SPLIT_TOKEN }} +``` + +| Input | Type | Default | Description | +| ------------- | ------ | ---------------- | ---------------------------------------------------------------------------------------- | +| `tag` | string | `""` | Tag to push to the mirror repos. When empty, falls back to the caller's `github.ref_name`. | +| `config-file` | string | `"splitsh.json"` | Path to the splitsh config file, relative to the repo root. | + +| Secret | Required | Description | +| ------------- | -------- | ------------------------------------------------------------------------------------------------------ | +| `split-token` | yes | Token (fine-grained PAT or GitHub App token) with `contents: write` on every mirror repo in the config. | + +The `subtrees` map accepts both the shorthand string form (`"mirror": "path/in/monorepo"`) and the object form (`"mirror": { "prefixes": [{ "from": "path" }] }`). Each subtree is force-pushed to its mirror in parallel with `fail-fast: false`, so one failing package does not abort the rest. A missing or empty config fails the run loudly. + ## License GPL-2.0-or-later From 142c63e538e66be8ec70d875babdf064340abb94 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Mon, 25 May 2026 17:00:00 +0530 Subject: [PATCH 18/43] docs(cd): track split packages workflow issue --- .claude/issues/19-ci-build-artifact-gate.md | 2 +- .claude/issues/20-cd-split-packages.md | 103 ++++++++++++++++++++ .claude/issues/3-ci-test-js.md | 2 +- .claude/issues/5-ci-test-php.md | 2 +- .claude/issues/7-ci-build.md | 2 +- .claude/issues/9-ci-test-a11y.md | 2 +- 6 files changed, 108 insertions(+), 5 deletions(-) create mode 100644 .claude/issues/20-cd-split-packages.md diff --git a/.claude/issues/19-ci-build-artifact-gate.md b/.claude/issues/19-ci-build-artifact-gate.md index e494a10..e5aa32e 100644 --- a/.claude/issues/19-ci-build-artifact-gate.md +++ b/.claude/issues/19-ci-build-artifact-gate.md @@ -1,6 +1,6 @@ # Issue #19: Add ci-build-artifact-gate reusable workflow -**Status:** in-review +**Status:** done **Branch:** `v1.0.0/task/ci-build-artifact-gate` **PR:** #19 **Closes:** `rtCamp/theme-elementary#642` (external) diff --git a/.claude/issues/20-cd-split-packages.md b/.claude/issues/20-cd-split-packages.md new file mode 100644 index 0000000..6519c47 --- /dev/null +++ b/.claude/issues/20-cd-split-packages.md @@ -0,0 +1,103 @@ +# Issue #20 — Add cd-split-packages reusable workflow (monorepo → mirror repos) + +**Status:** in-review +**Branch:** `v1.0.0/task/cd-split-packages` +**PR:** #21 +**Assignee:** @Adi-ty + +--- + +## Summary + +rtCamp's tooling lives in a monorepo, but Packagist serves each Composer package from its own repository with its own tags. This adds a reusable `workflow_call` workflow that splits each package subtree out into a standalone mirror repo (the Symfony "monorepo split" pattern) on a release tag, so every rtCamp monorepo shares one copy instead of copy-pasting the split logic. Derived from the working standalone `release-php.yml` in the tooling monorepo. + +--- + +## Decisions made + +- [2026-05-25] Modelled on the standalone `release-php.yml` (two-job `build-matrix` → matrixed `split`), converted to `on: workflow_call`. Core split logic (jq matrix, danharrin action, `fetch-depth: 0`) is byte-for-byte equivalent in behaviour. +- [2026-05-25] Inputs kept minimal: `tag` (default `""`) and `config-file` (default `"splitsh.json"`). `organization`/`branch`/`user_name`/`user_email` stay sourced from `splitsh.json` so it remains the single source of truth (Symfony pattern) — no redundant inputs. +- [2026-05-25] Secret `split-token` (required) reaches the danharrin action only via `env.GITHUB_TOKEN`; never echoed. +- [2026-05-25] `permissions: contents: read` at top level — the mirror push uses `split-token`, not the workflow's `GITHUB_TOKEN`, so read-only is sufficient and correct. +- [2026-05-25] Triggers move to the caller (a reusable workflow owns none). Tag resolution: explicit `tag` input wins, else `github.ref_name`. The `ref_name` fallback only covers the tag-push case — on `workflow_dispatch` `ref_name` is a branch, so the caller must pass the tag from its own dispatch input. Documented both caller shapes in the README. +- [2026-05-25] Hardening beyond the reference: fail loudly on missing config file / invalid JSON / empty `subtrees` (jq `// {}` guard avoids a null-deref on missing `subtrees`). +- [2026-05-25] Every action pinned to a commit SHA with a version comment: `actions/checkout@11bd719` (v4.2.2, matching the rest of the repo), `danharrin/monorepo-split-github-action@14e42e2` (v2.4.5, resolved from the tag). +- [2026-05-25] Named `cd-split-packages.yml` to sit in the CD family. + +--- + +## Files changed so far + +- `.github/workflows/cd-split-packages.yml` — new +- `README.md` — edited (new `cd-split-packages.yml` section: config shape, tag-push + dispatch caller examples, inputs + secret tables) +- `CHANGELOG.md` — edited (Unreleased entry) + +--- + +## Verification run + +```bash +❯ act workflow_call -W .github/workflows/cd-split-packages.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ⭐ Run Set up job +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ✅ Success - Set up job +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ⭐ Run Main Checkout repository +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ✅ Success - Main Checkout repository [6.708375ms] +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ⭐ Run Main Parse config into a matrix +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ✅ Success - Main Parse config into a matrix [21.030167ms] +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ⭐ Run Main Echo resolved matrix +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ✅ Success - Main Echo resolved matrix [17.754917ms] +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ⭐ Run Complete job +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] Cleaning up container for job Build split matrix from config +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ✅ Success - Complete job +*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] 🏁 Job succeeded +ERRO[0000] Error while evaluating matrix: Invalid JSON: unexpected end of JSON input +*DRYRUN* [CD / Split Composer Packages/Split ] ⭐ Run Set up job +*DRYRUN* [CD / Split Composer Packages/Split ] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CD / Split Composer Packages/Split ] ✅ Success - Set up job +*DRYRUN* [CD / Split Composer Packages/Split ] ☁ git clone 'https://github.com/danharrin/monorepo-split-github-action' # ref=14e42e2437f674b8987c1f50ca3689116aea1893 +*DRYRUN* [CD / Split Composer Packages/Split ] ⭐ Run Main Checkout monorepo (full history) +*DRYRUN* [CD / Split Composer Packages/Split ] ✅ Success - Main Checkout monorepo (full history) [9.643417ms] +*DRYRUN* [CD / Split Composer Packages/Split ] ⭐ Run Main Split and push subtree to mirror +*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker build -t act-danharrin-monorepo-split-github-action-14e42e2437f674b8987c1f50ca3689116aea1893-dockeraction:latest /Users/adi/.cache/act/danharrin-monorepo-split-github-action@14e42e2437f674b8987c1f50ca3689116aea1893 +*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker pull image=act-danharrin-monorepo-split-github-action-14e42e2437f674b8987c1f50ca3689116aea1893-dockeraction:latest platform= username= forcePull=false +*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker create image=act-danharrin-monorepo-split-github-action-14e42e2437f674b8987c1f50ca3689116aea1893-dockeraction:latest platform= entrypoint=[] cmd=["" "github.com" "" "" "" "" "" ""] network="container:act-CD--Split-Composer-Packages-Split-dc5f2bbaabb4c8d86f0a7386db3ec2a110255f2a742a58f5a5007f0ea266e004" +*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker run image=act-danharrin-monorepo-split-github-action-14e42e2437f674b8987c1f50ca3689116aea1893-dockeraction:latest platform= entrypoint=[] cmd=["" "github.com" "" "" "" "" "" ""] network="container:act-CD--Split-Composer-Packages-Split-dc5f2bbaabb4c8d86f0a7386db3ec2a110255f2a742a58f5a5007f0ea266e004" +*DRYRUN* [CD / Split Composer Packages/Split ] ✅ Success - Main Split and push subtree to mirror [41.679417ms] +*DRYRUN* [CD / Split Composer Packages/Split ] ⭐ Run Complete job +*DRYRUN* [CD / Split Composer Packages/Split ] Cleaning up container for job Split +*DRYRUN* [CD / Split Composer Packages/Split ] ✅ Success - Complete job +*DRYRUN* [CD / Split Composer Packages/Split ] 🏁 Job succeeded + +# jq matrix confirmed on both value forms (shorthand + prefixes): +jq -c '{ include: [ .subtrees | to_entries[] | { mirror_repo: .key, package_directory: (if (.value|type)=="string" then .value else .value.prefixes[0].from end) } ] }' splitsh.json +{"include":[{"mirror_repo":"wp-phpcs","package_directory":"composer-packages/phpcs"},{"mirror_repo":"wp-phpstan","package_directory":"composer-packages/phpstan"}]} + +``` + +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- **Optional hardening, not yet added (awaiting steer):** a guard in `build-matrix` that fails when the tag came from the `ref_name` fallback while `github.ref_type != 'tag'` — turns a silent "pushed a branch-named tag" (dispatch without an explicit tag) into a clear error. +- Mirror repos must already exist and `split-token` must hold `contents: write` on each for a real run to succeed. + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/3-ci-test-js.md b/.claude/issues/3-ci-test-js.md index 580f0a1..0252cd9 100644 --- a/.claude/issues/3-ci-test-js.md +++ b/.claude/issues/3-ci-test-js.md @@ -1,6 +1,6 @@ # Issue #3 — ci-test-js.yml reusable workflow -**Status:** in-progress +**Status:** done **Branch:** `v1.0.0/task/ci-test-js` **PR:** #4 **Assignee:** @Adi-ty diff --git a/.claude/issues/5-ci-test-php.md b/.claude/issues/5-ci-test-php.md index dcb3c5a..924dbc8 100644 --- a/.claude/issues/5-ci-test-php.md +++ b/.claude/issues/5-ci-test-php.md @@ -1,6 +1,6 @@ # Issue #5 — Add PHP unit tests reusable workflow -**Status:** in-progress +**Status:** done **Branch:** `v1.0.0/task/ci-test-php` **PR:** #6 **Assignee:** @Adi-ty diff --git a/.claude/issues/7-ci-build.md b/.claude/issues/7-ci-build.md index 51c228e..8d89ac7 100644 --- a/.claude/issues/7-ci-build.md +++ b/.claude/issues/7-ci-build.md @@ -1,6 +1,6 @@ # Issue #7 — Add ci-build reusable workflow -**Status:** in-progress +**Status:** done **Branch:** `v1.0.0/task/ci-build` **PR:** #8 **Assignee:** @Adi-ty diff --git a/.claude/issues/9-ci-test-a11y.md b/.claude/issues/9-ci-test-a11y.md index 677b3db..a35d9d4 100644 --- a/.claude/issues/9-ci-test-a11y.md +++ b/.claude/issues/9-ci-test-a11y.md @@ -1,6 +1,6 @@ # Issue #9 — Add ci-test-a11y reusable workflow -**Status:** in-progress +**Status:** done **Branch:** `v1.0.0/task/ci-test-a11y` **PR:** #10 **Assignee:** @Adi-ty From abeef0bfd808bc2c349c7d936d3cc1c86e4644e5 Mon Sep 17 00:00:00 2001 From: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> Date: Wed, 10 Jun 2026 14:51:53 +0530 Subject: [PATCH 19/43] [v1.0.0] Add ci-test-build-artifact reusable workflow (#23) * feat(ci): add ci-test-build-artifact reusable workflow Downloads the build artifact, boots wp-env with pinned php-version/wp-version, activates plugin/theme, runs wp doctor check --all, and tears down. Catches files referenced but missing from the bundle, over eager .distignore rules, and case-sensitivity bugs that survive a bare build step. * docs(ci): clarify decisions made in ci-test-build-artifact documentation --- .claude/issues/11-ci-test-build-artifact.md | 119 +++++++++++++++ .github/workflows/ci-test-build-artifact.yml | 153 +++++++++++++++++++ CHANGELOG.md | 1 + README.md | 50 ++++++ 4 files changed, 323 insertions(+) create mode 100644 .claude/issues/11-ci-test-build-artifact.md create mode 100644 .github/workflows/ci-test-build-artifact.yml diff --git a/.claude/issues/11-ci-test-build-artifact.md b/.claude/issues/11-ci-test-build-artifact.md new file mode 100644 index 0000000..024c388 --- /dev/null +++ b/.claude/issues/11-ci-test-build-artifact.md @@ -0,0 +1,119 @@ +# Issue #11 — ci-test-build-artifact reusable workflow + +**Status:** in-progress +**Branch:** `v1.0.0/task/ci-test-build-artifact` +**PR:** # +**Assignee:** @Adi-ty + +--- + +## Summary + +A green `ci-build.yml` run only proves the build did not crash — not that the packaged output installs and boots in WordPress. This workflow downloads the build artifact, boots a real WordPress in `@wordpress/env`, activates the plugin/theme, and runs `wp doctor`, so failures like a PHP file referenced but never copied into the bundle, an over-eager `.distignore`, or a path-cased file that breaks on Linux fail CI loudly. It lives here because every consuming skeleton needs the same flow against its own artifact. + +--- + +## Decisions made + +- [2026-05-28] README-only delivery (repo house style): reusable workflow + README caller examples + CHANGELOG entry. No committed fixture, no `_examples/` file, no in-PR self-test wrapper — matches how #3/#5/#7/#9/#19 shipped. Verify via `act` dry-run and a real consumer repo's CI. +- [2026-05-28] Workflow-owned wp-env: the workflow runs `npx --yes @wordpress/env` itself and writes a `.wp-env.override.json` to pin `phpVersion`/`core` and mount the artifact, rather than reusing the consumer's `npm run wp-env` (which `ci-test-a11y.yml` does). Keeps version pinning self-contained. +- [2026-05-28] Override mounts the artifact **in isolation** — it sets `plugins: []` and `themes: []` so the consumer's `.wp-env.json` (standard rtCamp config mounts the dev source `"."`) does not collide with the artifact mapping at the same destination. Discovered during smoke testing (a standard rtCamp `.wp-env.json` mounts the dev source as `plugins: ["."]`). +- [2026-05-28] Explicit `slug` input (the directory to activate) instead of deriving it from plugin headers / composer.json — deterministic across project shapes. Added `node-version` too (needed to drive `npx`, parity with sibling workflows). Both go beyond the issue's literal four-input contract. +- [2026-05-28] Used `wp doctor check --all --format=json` (runs the checks, returns per-check `status`) — the issue's reference used `wp doctor list`, which only lists available checks. Fail only on `error` severity; warnings allowed. Verified against the doctor-command docs: `check` runs, `--all` = every registered check, results are `{name, status, message}` with `status` ∈ `success|warning|error`. +- [2026-05-28] Artifact contract documented: the artifact must be a complete installable plugin/theme directory, so consumers point `ci-build.yml`'s `artifact-path` at a packaged dist dir, not bare `build/`. `actions/download-artifact` restores contents uncompressed — no unzip step. +- [2026-05-28] `wp doctor check --all` flagged `constant-wp-debug-falsy` as `error` during smoke testing (a real CI run, after the visibility fix). Cause: wp-env enables `WP_DEBUG` by default (dev environment), and that check is production-oriented — so it errors for every consumer regardless of the artifact (`core-verify-checksums` passed; my earlier guess was wrong). Fix: added a `doctor-ignore-checks` input (default `constant-wp-debug-falsy`) and filter those names out of the error gate in jq; all other error-severity checks still fail the build. +- [2026-05-28] Theme-path + pinned-version were exercised during smoke testing (`install-path: wp-content/themes`, `wp-version: 6.9.4`). Pinned `6.9.4` (latest in its 6.9.x line) so only a *major* (7.0) update is offered → doctor `core-update` returns `warning`, not `error`. Verified via the doctor-command source: `core-update` sets `error` for an available *minor* update, `warning` for a major. Also passed `doctor-ignore-checks: "constant-wp-debug-falsy,core-update"` so the test stays durable as releases advance (core updates are about WordPress core, not the artifact). +- [2026-05-28] `permissions: contents: read` is sufficient — the artifact is downloaded from the same run (consumer calls `ci-build` then this), so no `actions: read` / cross-run id needed. `wp-env stop` runs in an `if: always()` step with its own `timeout-minutes: 2` so no container leaks. + +--- + +## Files changed so far + +- `.github/workflows/ci-test-build-artifact.yml` — new +- `README.md` — edited (new `### ci-test-build-artifact.yml` section under Individual workflows) +- `CHANGELOG.md` — edited (Unreleased → Added bullet) +- `.claude/issues/11-ci-test-build-artifact.md` — new (this file) + +Consumer-side verification was done separately via smoke testing (external, not tracked here). + +--- + +## Verification run + +```bash +❯ act workflow_call -W .github/workflows/ci-test-build-artifact.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Set up job +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Set up job +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] Non-terminating error while running 'git clone': some refs were not updated +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ☁ git clone 'https://github.com/actions/download-artifact' # ref=d3f86a106a0bac45b974a628896c90dbdf5c8093 +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Checkout repository +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Checkout repository [6.879458ms] +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Set up Node.js +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Set up Node.js [6.783ms] +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Download build artifact +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Download build artifact [6.240375ms] +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Write wp-env override +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Write wp-env override [15.153375ms] +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Start wp-env +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Start wp-env [17.473208ms] +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Activate plugin or theme +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Activate plugin or theme [19.252875ms] +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Run wp doctor +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Run wp doctor [14.417958ms] +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Stop wp-env +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Stop wp-env [13.550458ms] +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Post Set up Node.js +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Post Set up Node.js [4.557333ms] +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Complete job +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] Cleaning up container for job Boot artifact in wp-env +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Complete job +*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] 🏁 Job succeeded + +WP_VERSION=latest PHP_VERSION=8.3 INSTALL_PATH=wp-content/plugins SLUG=my-plugin \ + jq -n --arg wp "$WP_VERSION" --arg php "$PHP_VERSION" --arg dest "${INSTALL_PATH%/}/${SLUG}" \ + '{ + core: (if $wp == "latest" then null else "WordPress/WordPress#\($wp)" end), + phpVersion: $php, + plugins: [], + themes: [], + mappings: { ($dest): "./artifact" } + }' +{ + "core": "WordPress/WordPress#", + "phpVersion": "", + "plugins": [], + "themes": [], + "mappings": { + "/": "./artifact" + } +} +``` + +Binding test (boots wp-env + Docker, which `act` cannot do reliably) is done via smoke testing: a real CI run boots `ci-build` → `ci-test-build-artifact` against a packaged plugin/theme, confirming activate + `wp doctor` pass and `wp-env stop` runs on failure. + +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- Doctor output parsing is safe without stderr suppression: wp-env spawns the cli command with `stdio: 'inherit'` (`node_modules/@wordpress/env/lib/runtime/docker/index.js`), so the WP-CLI JSON is alone on stdout while wp-env's ora spinner writes status to stderr. `result=$(…)` captures only stdout. Earlier `2>/dev/null` was removed (it only hid useful diagnostics). `wp doctor check` exits 1 on an error-severity check, so the capture uses `|| true` to always print the report; the explicit `jq` is the gate (and fails the step under `set -e` on empty/garbage output). +- `npx --yes @wordpress/env` first-run install counts against the ~6 min target; `--update` + runner Docker cache should keep it under budget. +- Isolation override clears `plugins`/`themes`; a consumer that needs companion plugins active during the smoke test is not covered yet (would be a future `companion-plugins` input). + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.github/workflows/ci-test-build-artifact.yml b/.github/workflows/ci-test-build-artifact.yml new file mode 100644 index 0000000..853b3b4 --- /dev/null +++ b/.github/workflows/ci-test-build-artifact.yml @@ -0,0 +1,153 @@ +name: CI / Test Build Artifact + +on: + workflow_call: + inputs: + artifact-name: + description: "Artifact to download. Must match the artifact-name uploaded by ci-build.yml in the same run." + type: string + required: true + slug: + description: "Plugin or theme directory slug to activate inside wp-env." + type: string + required: true + node-version: + description: "Node.js version used to run @wordpress/env." + type: string + default: "22" + php-version: + description: "PHP version wp-env boots with." + type: string + default: "8.3" + wp-version: + description: "WordPress version wp-env boots with. 'latest' uses the newest stable release." + type: string + default: "latest" + install-path: + description: "Destination under the WordPress root to mount the artifact. A path ending in 'themes' activates a theme; otherwise a plugin." + type: string + default: "wp-content/plugins" + smoke-script: + description: "Optional path inside the artifact to a shell script, run in the wp-env container after activation. Empty skips the step." + type: string + default: "" + doctor-ignore-checks: + description: "Comma-separated wp doctor check names excluded from the error gate. Defaults to production-oriented checks that wp-env's dev defaults always trip (e.g. WP_DEBUG being on)." + type: string + default: "constant-wp-debug-falsy" + +permissions: + contents: read + +jobs: + test-build-artifact: + name: Boot artifact in wp-env + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Set up Node.js + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 + with: + node-version: ${{ inputs.node-version }} + + - name: Download build artifact + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: ${{ inputs.artifact-name }} + path: artifact + + - name: Write wp-env override + shell: bash + env: + WP_VERSION: ${{ inputs.wp-version }} + PHP_VERSION: ${{ inputs.php-version }} + INSTALL_PATH: ${{ inputs.install-path }} + SLUG: ${{ inputs.slug }} + run: | + set -euo pipefail + + # Mount only the artifact; a consumer's .wp-env.json usually mounts the dev source (".") at the same path. + jq -n \ + --arg wp "$WP_VERSION" \ + --arg php "$PHP_VERSION" \ + --arg dest "${INSTALL_PATH%/}/${SLUG}" \ + '{ + core: (if $wp == "latest" then null else "WordPress/WordPress#\($wp)" end), + phpVersion: $php, + plugins: [], + themes: [], + mappings: { ($dest): "./artifact" } + }' > .wp-env.override.json + + echo "Generated .wp-env.override.json:" + cat .wp-env.override.json + + - name: Start wp-env + shell: bash + run: | + set -euo pipefail + npx --yes @wordpress/env start --update + + - name: Activate plugin or theme + shell: bash + env: + INSTALL_PATH: ${{ inputs.install-path }} + SLUG: ${{ inputs.slug }} + run: | + set -euo pipefail + + case "${INSTALL_PATH%/}" in + */themes) TYPE=theme ;; + *) TYPE=plugin ;; + esac + + echo "Activating ${TYPE}: ${SLUG}" + npx --yes @wordpress/env run cli wp "$TYPE" activate "$SLUG" + + - name: Run wp doctor + shell: bash + env: + DOCTOR_IGNORE_CHECKS: ${{ inputs.doctor-ignore-checks }} + run: | + set -euo pipefail + + npx --yes @wordpress/env run cli wp package install wp-cli/doctor-command:@stable + + # `wp doctor check` exits 1 on an error check; capture anyway (|| true) so the report prints before we gate. + result=$(npx --yes @wordpress/env run cli wp doctor check --all --format=json) || true + echo "$result" + + # wp-env enables WP_DEBUG by default, tripping production-only checks unrelated to the artifact; drop those. + failed=$(jq -c --arg ignore "$DOCTOR_IGNORE_CHECKS" ' + ($ignore | split(",") | map(gsub("(^\\s+|\\s+$)"; "")) | map(select(length > 0))) as $skip + | [ .[] | select(.status == "error") | select([.name] | inside($skip) | not) ] + ' <<<"$result") + + count=$(jq 'length' <<<"$failed") + if [[ "$count" -gt 0 ]]; then + echo "::error::wp doctor reported ${count} error-severity check(s):" + jq -r '.[] | " - \(.name): \(.message)"' <<<"$failed" + exit 1 + fi + + echo "wp doctor passed (no error-severity checks; ignored: ${DOCTOR_IGNORE_CHECKS:-none})." + + - name: Run smoke script + if: ${{ inputs.smoke-script != '' }} + shell: bash + env: + INSTALL_PATH: ${{ inputs.install-path }} + SLUG: ${{ inputs.slug }} + SMOKE_SCRIPT: ${{ inputs.smoke-script }} + run: | + set -euo pipefail + npx --yes @wordpress/env run cli bash "${INSTALL_PATH%/}/${SLUG}/${SMOKE_SCRIPT}" + + - name: Stop wp-env + if: always() + timeout-minutes: 2 + shell: bash + run: npx --yes @wordpress/env stop diff --git a/CHANGELOG.md b/CHANGELOG.md index f792741..43badc9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,3 +13,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `ci-test-a11y.yml` — reusable pa11y-ci accessibility test workflow. Order: `npm ci` → build → `wp-env start` → pa11y → `wp-env stop` (with `if: always()` so cleanup runs on failure). Inputs: `node-version`, `build-command`, `test-command`, `working-dir`. Trigger-agnostic — consumers wire the `Run a11y` label gate at the caller level. - `ci-build.yml`: reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. The `build-command` default is empty and selects `npm run build:prod` when Node deps install, `composer run-script build` otherwise. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. - `ci-build-artifact-gate.yml`: reusable workflow that fails a PR if it commits files under configured path prefixes (default: `assets/build/`). Pair with `ci-build.yml` so the CI-produced bundle is the only source of truth for build output. Compares `origin/..HEAD` with `--diff-filter=ACMR`, so additions/modifications/renames trip the gate and deletions are ignored (removing a previously-committed artifact is welcome). Runs only on `pull_request` events; on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. Empty `gated-paths` input skips gracefully. Path prefixes are anchored as literal strings, and regex metacharacters in path names (`. + * ( ) [ ] { } | ^ $ ? \`) are escaped automatically. Inputs: `gated-paths`, `working-dir`. +- `ci-test-build-artifact.yml`: reusable workflow that boots the packaged build artifact in a real WordPress to prove it installs, not just that the build compiled. Downloads the named artifact (via `actions/download-artifact` pinned to `d3f86a1`, v4.3.0), writes a `.wp-env.override.json` to pin `phpVersion`/`core` and mount only the downloaded artifact (clearing `plugins`/`themes` from the consumer config so the dev source tree never collides with the packaged output), boots `@wordpress/env` with `npx --yes @wordpress/env start --update`, activates the plugin or theme (selected from `install-path`), then runs `wp doctor check --all --format=json` and fails only on `error`-severity checks (warnings allowed). The artifact must be a complete installable plugin/theme directory, so point `ci-build.yml`'s `artifact-path` at a packaged dist directory rather than bare `build/`. An optional `smoke-script` runs inside the container after activation, and `wp-env stop` runs in an `if: always()` step (with its own timeout) so no container leaks into the next job. Production-oriented doctor checks that a dev wp-env always trips (e.g. `constant-wp-debug-falsy`, since wp-env enables `WP_DEBUG`) are excluded from the gate via the `doctor-ignore-checks` input. Inputs: `artifact-name`, `slug`, `node-version`, `php-version`, `wp-version`, `install-path`, `smoke-script`, `doctor-ignore-checks`. diff --git a/README.md b/README.md index b61f508..6cf8057 100644 --- a/README.md +++ b/README.md @@ -227,6 +227,56 @@ jobs: Only meaningful on `pull_request` events. On other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. The check compares `origin/..HEAD` with `--diff-filter=ACMR`, so deletions are ignored: removing a previously-committed artifact in the PR does not trip the gate. +### `ci-test-build-artifact.yml`: boot the built artifact + +A green `ci-build.yml` run only proves the build did not crash — not that the packaged output installs and boots. This workflow downloads the artifact, boots a real WordPress in [`@wordpress/env`](https://github.com/WordPress/gutenberg/tree/trunk/packages/env), activates the plugin/theme, and runs `wp doctor`. It catches PHP files referenced but never copied into the bundle, an over-eager `.distignore`, and path-cased files that break on Linux. Pair it with `ci-build.yml`. + +**Plugin:** build with an uploaded artifact, then boot it. + +```yaml +jobs: + build: + uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + with: + upload-artifact: true + artifact-name: "plugin-dist" + artifact-path: "dist/my-plugin/" # a complete installable plugin dir, not bare build/ + test-artifact: + needs: build + uses: rtCamp/shared-workflows/.github/workflows/ci-test-build-artifact.yml@v1 + with: + artifact-name: "plugin-dist" + slug: "my-plugin" +``` + +**Theme:** install under `wp-content/themes` and activate as a theme. + +```yaml +jobs: + test-artifact: + needs: build + uses: rtCamp/shared-workflows/.github/workflows/ci-test-build-artifact.yml@v1 + with: + artifact-name: "theme-dist" + slug: "my-theme" + install-path: "wp-content/themes" +``` + +| Input | Type | Default | Description | +| --------------- | ------ | --------------------- | ------------------------------------------------------------------------------------------------- | +| `artifact-name` | string | _required_ | Artifact to download. Must match the `artifact-name` uploaded by `ci-build.yml` in the same run. | +| `slug` | string | _required_ | Plugin or theme directory slug to activate. | +| `node-version` | string | `"22"` | Node.js version used to run `@wordpress/env`. | +| `php-version` | string | `"8.3"` | PHP version wp-env boots with. | +| `wp-version` | string | `"latest"` | WordPress version wp-env boots with. `latest` uses the newest stable release. | +| `install-path` | string | `"wp-content/plugins"`| Destination under the WordPress root. A path ending in `themes` activates a theme, else a plugin. | +| `smoke-script` | string | `""` | Optional path inside the artifact to a shell script, run in the container after activation. | +| `doctor-ignore-checks` | string | `"constant-wp-debug-falsy"` | Comma-separated `wp doctor` check names excluded from the error gate (production-oriented checks that wp-env's dev defaults always trip). | + +`wp doctor check --all` includes production-oriented checks that a dev wp-env always trips — notably `constant-wp-debug-falsy`, because wp-env enables `WP_DEBUG` by default. Those are excluded from the gate via `doctor-ignore-checks` (extend the comma-separated list if your wp-env config trips others); every other `error`-severity check still fails the build. + +The artifact must be a **complete installable plugin/theme directory** (main PHP file plus assets), so point `ci-build.yml`'s `artifact-path` at a packaged dist directory, not bare `build/`. `actions/download-artifact` restores the uploaded directory contents uncompressed, so there is no unzip step. The workflow writes a `.wp-env.override.json` that pins `phpVersion`/`core` and mounts **only** the downloaded artifact — it clears `plugins`/`themes` from the consumer's `.wp-env.json` so the test reflects the packaged output in isolation, not the dev source tree. It then runs `wp activate ` and `wp doctor check --all` (failing only on `error` severity), and always runs `wp-env stop` so no container leaks into the next job. + ## License GPL-2.0-or-later From 6253cf013983500480722eb6e5aeebe6e01ebf10 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Wed, 10 Jun 2026 14:55:41 +0530 Subject: [PATCH 20/43] feat(cd): add reusable cd-split-composer-packages workflow for mirroring Composer packages --- ...-packages.md => 20-cd-split-composer-packages.md} | 12 ++++++------ ...t-packages.yml => cd-split-composer-packages.yml} | 0 CHANGELOG.md | 2 +- README.md | 6 +++--- 4 files changed, 10 insertions(+), 10 deletions(-) rename .claude/issues/{20-cd-split-packages.md => 20-cd-split-composer-packages.md} (94%) rename .github/workflows/{cd-split-packages.yml => cd-split-composer-packages.yml} (100%) diff --git a/.claude/issues/20-cd-split-packages.md b/.claude/issues/20-cd-split-composer-packages.md similarity index 94% rename from .claude/issues/20-cd-split-packages.md rename to .claude/issues/20-cd-split-composer-packages.md index 6519c47..494033e 100644 --- a/.claude/issues/20-cd-split-packages.md +++ b/.claude/issues/20-cd-split-composer-packages.md @@ -1,7 +1,7 @@ -# Issue #20 — Add cd-split-packages reusable workflow (monorepo → mirror repos) +# Issue #20 — Add cd-split-composer-packages reusable workflow (monorepo → mirror repos) **Status:** in-review -**Branch:** `v1.0.0/task/cd-split-packages` +**Branch:** `v1.0.0/task/cd-split-composer-packages` **PR:** #21 **Assignee:** @Adi-ty @@ -22,14 +22,14 @@ rtCamp's tooling lives in a monorepo, but Packagist serves each Composer package - [2026-05-25] Triggers move to the caller (a reusable workflow owns none). Tag resolution: explicit `tag` input wins, else `github.ref_name`. The `ref_name` fallback only covers the tag-push case — on `workflow_dispatch` `ref_name` is a branch, so the caller must pass the tag from its own dispatch input. Documented both caller shapes in the README. - [2026-05-25] Hardening beyond the reference: fail loudly on missing config file / invalid JSON / empty `subtrees` (jq `// {}` guard avoids a null-deref on missing `subtrees`). - [2026-05-25] Every action pinned to a commit SHA with a version comment: `actions/checkout@11bd719` (v4.2.2, matching the rest of the repo), `danharrin/monorepo-split-github-action@14e42e2` (v2.4.5, resolved from the tag). -- [2026-05-25] Named `cd-split-packages.yml` to sit in the CD family. +- [2026-05-25] Named `cd-split-composer-packages.yml` to sit in the CD family. --- ## Files changed so far -- `.github/workflows/cd-split-packages.yml` — new -- `README.md` — edited (new `cd-split-packages.yml` section: config shape, tag-push + dispatch caller examples, inputs + secret tables) +- `.github/workflows/cd-split-composer-packages.yml` — new +- `README.md` — edited (new `cd-split-composer-packages.yml` section: config shape, tag-push + dispatch caller examples, inputs + secret tables) - `CHANGELOG.md` — edited (Unreleased entry) --- @@ -37,7 +37,7 @@ rtCamp's tooling lives in a monorepo, but Packagist serves each Composer package ## Verification run ```bash -❯ act workflow_call -W .github/workflows/cd-split-packages.yml --dryrun +❯ act workflow_call -W .github/workflows/cd-split-composer-packages.yml --dryrun INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ *DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ⭐ Run Set up job diff --git a/.github/workflows/cd-split-packages.yml b/.github/workflows/cd-split-composer-packages.yml similarity index 100% rename from .github/workflows/cd-split-packages.yml rename to .github/workflows/cd-split-composer-packages.yml diff --git a/CHANGELOG.md b/CHANGELOG.md index 03ae3c0..db02edb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,4 +13,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `ci-test-a11y.yml` — reusable pa11y-ci accessibility test workflow. Order: `npm ci` → build → `wp-env start` → pa11y → `wp-env stop` (with `if: always()` so cleanup runs on failure). Inputs: `node-version`, `build-command`, `test-command`, `working-dir`. Trigger-agnostic — consumers wire the `Run a11y` label gate at the caller level. - `ci-build.yml`: reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. The `build-command` default is empty and selects `npm run build:prod` when Node deps install, `composer run-script build` otherwise. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. - `ci-build-artifact-gate.yml`: reusable workflow that fails a PR if it commits files under configured path prefixes (default: `assets/build/`). Pair with `ci-build.yml` so the CI-produced bundle is the only source of truth for build output. Compares `origin/..HEAD` with `--diff-filter=ACMR`, so additions/modifications/renames trip the gate and deletions are ignored (removing a previously-committed artifact is welcome). Runs only on `pull_request` events; on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. Empty `gated-paths` input skips gracefully. Path prefixes are anchored as literal strings, and regex metacharacters in path names (`. + * ( ) [ ] { } | ^ $ ? \`) are escaped automatically. Inputs: `gated-paths`, `working-dir`. -- `cd-split-packages.yml`: reusable "monorepo split" workflow (Symfony pattern) that mirrors each Composer-package subtree to its own standalone repo so Packagist can serve it. A `build-matrix` job parses `splitsh.json` (`organization`, `subtrees` map, `defaults.branch`/`user_name`/`user_email`) with jq — accepting both the shorthand string form and the object/`prefixes` form — and a matrixed `split` job runs `danharrin/monorepo-split-github-action` (pinned to `14e42e2`, v2.4.5) per subtree with `fail-fast: false`. `tag` falls back to the caller's `github.ref_name` when empty; missing or empty config fails loudly. Inputs: `tag`, `config-file`. Secret: `split-token` (PAT/App token with `contents: write` on every mirror repo). +- `cd-split-composer-packages.yml`: reusable "monorepo split" workflow (Symfony pattern) that mirrors each Composer-package subtree to its own standalone repo so Packagist can serve it. A `build-matrix` job parses `splitsh.json` (`organization`, `subtrees` map, `defaults.branch`/`user_name`/`user_email`) with jq — accepting both the shorthand string form and the object/`prefixes` form — and a matrixed `split` job runs `danharrin/monorepo-split-github-action` (pinned to `14e42e2`, v2.4.5) per subtree with `fail-fast: false`. `tag` falls back to the caller's `github.ref_name` when empty; missing or empty config fails loudly. Inputs: `tag`, `config-file`. Secret: `split-token` (PAT/App token with `contents: write` on every mirror repo). diff --git a/README.md b/README.md index 12d5e91..c2503db 100644 --- a/README.md +++ b/README.md @@ -227,7 +227,7 @@ jobs: Only meaningful on `pull_request` events. On other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. The check compares `origin/..HEAD` with `--diff-filter=ACMR`, so deletions are ignored: removing a previously-committed artifact in the PR does not trip the gate. -### `cd-split-packages.yml`: split Composer packages to mirror repos +### `cd-split-composer-packages.yml`: split Composer packages to mirror repos Splits Composer-package subtrees out of a monorepo into standalone mirror repos (the Symfony "monorepo split" pattern), so Packagist can serve each package from its own repository. A `splitsh.json` at the repo root is the single source of truth — to add or remove a package, edit that file, never the workflow. @@ -260,7 +260,7 @@ on: tags: ["v*"] jobs: split: - uses: rtCamp/shared-workflows/.github/workflows/cd-split-packages.yml@v1 + uses: rtCamp/shared-workflows/.github/workflows/cd-split-composer-packages.yml@v1 with: tag: ${{ github.ref_name }} secrets: @@ -283,7 +283,7 @@ on: default: "v0.0.0-test" jobs: split: - uses: rtCamp/shared-workflows/.github/workflows/cd-split-packages.yml@v1 + uses: rtCamp/shared-workflows/.github/workflows/cd-split-composer-packages.yml@v1 with: # Manual run → use the dispatch input; tag push → the pushed tag. tag: ${{ github.event.inputs.test_tag || github.ref_name }} From 2b1ef1399f7f2fddb47adb1bf1676cf03f4a3fcd Mon Sep 17 00:00:00 2001 From: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> Date: Wed, 10 Jun 2026 15:04:51 +0530 Subject: [PATCH 21/43] Error message rewording for better clarity Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .github/workflows/cd-split-composer-packages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/cd-split-composer-packages.yml b/.github/workflows/cd-split-composer-packages.yml index 9a23580..3a178b7 100644 --- a/.github/workflows/cd-split-composer-packages.yml +++ b/.github/workflows/cd-split-composer-packages.yml @@ -59,7 +59,7 @@ jobs: set -euo pipefail if [[ ! -f "$CONFIG_FILE" ]]; then - echo "::error::Config file '$CONFIG_FILE' not found at the repo root." + echo "::error::Config file '$CONFIG_FILE' not found (path is relative to the repo root)." exit 1 fi From 4e11c785bdbd61b82ee55a7737b7962bf90abacd Mon Sep 17 00:00:00 2001 From: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> Date: Wed, 10 Jun 2026 15:06:35 +0530 Subject: [PATCH 22/43] docs(cd): Clarify splitish.json location Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9911792..3233b4e 100644 --- a/README.md +++ b/README.md @@ -229,7 +229,7 @@ Only meaningful on `pull_request` events. On other triggers it logs a notice and ### `cd-split-composer-packages.yml`: split Composer packages to mirror repos -Splits Composer-package subtrees out of a monorepo into standalone mirror repos (the Symfony "monorepo split" pattern), so Packagist can serve each package from its own repository. A `splitsh.json` at the repo root is the single source of truth — to add or remove a package, edit that file, never the workflow. +Splits Composer-package subtrees out of a monorepo into standalone mirror repos (the Symfony "monorepo split" pattern), so Packagist can serve each package from its own repository. A `splitsh.json` (by default at the repo root) is the single source of truth — to add or remove a package, edit that file, never the workflow. `splitsh.json` lives in the **calling** monorepo (e.g. `wp-tooling`), not in this repo. As a reusable workflow, `actions/checkout` pulls the caller's repository by default, so the config is read from the caller's checkout — `config-file` is a path relative to that checkout, never the file's contents. From 457a682756ba6ed02411979b8cdb04cc430369f2 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Wed, 10 Jun 2026 15:12:26 +0530 Subject: [PATCH 23/43] feat(cd): enhance validation for subtrees in config file and ensure required keys are set --- .../workflows/cd-split-composer-packages.yml | 35 ++++++++++++++----- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/.github/workflows/cd-split-composer-packages.yml b/.github/workflows/cd-split-composer-packages.yml index 3a178b7..62470b0 100644 --- a/.github/workflows/cd-split-composer-packages.yml +++ b/.github/workflows/cd-split-composer-packages.yml @@ -70,18 +70,25 @@ jobs: # Normalise both the shorthand string form ("composer-packages/foo") # and the object form ({ "prefixes": [{ "from": "..." }] }). - matrix=$(jq -c '{ + if ! matrix=$(jq -c '{ include: [ - .subtrees // {} | to_entries[] | { + (.subtrees // {}) | to_entries[] | { mirror_repo: .key, package_directory: ( if (.value | type) == "string" then .value - else .value.prefixes[0].from + elif ((.value | type) == "object") + and ((.value.prefixes | type) == "array") + and ((.value.prefixes | length) > 0) + and ((.value.prefixes[0].from | type) == "string") then .value.prefixes[0].from + else error("invalid subtrees entry for \"" + .key + "\": expected a string path or { prefixes: [{ from: \"...\" }] }") end ) } ] - }' "$CONFIG_FILE") + }' "$CONFIG_FILE"); then + echo "::error::Invalid 'subtrees' entry in '$CONFIG_FILE' — each value must be a string path or { prefixes: [{ from: \"...\" }] } (see jq error above)." + exit 1 + fi count=$(jq -r '.include | length' <<<"$matrix") if [[ "$count" -eq 0 ]]; then @@ -95,12 +102,24 @@ jobs: tag="${{ github.ref_name }}" fi + # `// empty` turns a missing/null key into an empty string instead + # of the literal "null", so the presence check below actually works. + organization=$(jq -r '.organization // empty' "$CONFIG_FILE") + branch=$(jq -r '.defaults.branch // empty' "$CONFIG_FILE") + user_name=$(jq -r '.defaults.user_name // empty' "$CONFIG_FILE") + user_email=$(jq -r '.defaults.user_email // empty' "$CONFIG_FILE") + + if [[ -z "$organization" || -z "$branch" || -z "$user_name" || -z "$user_email" ]]; then + echo "::error::Missing required keys in '$CONFIG_FILE' — organization, defaults.branch, defaults.user_name and defaults.user_email must all be set." + exit 1 + fi + { echo "matrix=$matrix" - echo "organization=$(jq -r '.organization' "$CONFIG_FILE")" - echo "branch=$(jq -r '.defaults.branch' "$CONFIG_FILE")" - echo "user_name=$(jq -r '.defaults.user_name' "$CONFIG_FILE")" - echo "user_email=$(jq -r '.defaults.user_email' "$CONFIG_FILE")" + echo "organization=$organization" + echo "branch=$branch" + echo "user_name=$user_name" + echo "user_email=$user_email" echo "tag=$tag" } >> "$GITHUB_OUTPUT" From 12ae9136bdca93b580c735dee5fdb7af80804629 Mon Sep 17 00:00:00 2001 From: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> Date: Mon, 15 Jun 2026 11:32:37 +0530 Subject: [PATCH 24/43] [v1.0.0] Add cd-github-release workflow (#24) * feat(cd): add cd-github-release workflow * docs(cd): update verification run section in cd-github-release documentation --- .claude/issues/14-cd-github-release.md | 87 ++++++++++++++++++++ .github/workflows/cd-github-release.yml | 103 ++++++++++++++++++++++++ CHANGELOG.md | 1 + README.md | 37 +++++++++ 4 files changed, 228 insertions(+) create mode 100644 .claude/issues/14-cd-github-release.md create mode 100644 .github/workflows/cd-github-release.yml diff --git a/.claude/issues/14-cd-github-release.md b/.claude/issues/14-cd-github-release.md new file mode 100644 index 0000000..e014ed6 --- /dev/null +++ b/.claude/issues/14-cd-github-release.md @@ -0,0 +1,87 @@ +# Issue #14 — Add CD GitHub Releases workflow (`cd-github-release.yml`) + +**Status:** in-review +**Branch:** `v1.0.0/task/cd-github-release` +**PR:** #24 +**Assignee:** @Adi-ty + +--- + +## Summary + +Tagging a release should produce a Git tag, a GitHub Release carrying the changelog notes, and the build artifact attached to that Release — without every skeleton wiring it by hand. `cd-github-release.yml` does exactly that on a `v*.*.*` tag push: download the named artifact, extract the matching `CHANGELOG.md` section as the body, and create the Release. It is the first CD workflow in the repo and the GitHub-target option the CD orchestrator (`wp-cd.yml`, #17) will call. + +--- + +## Decisions made + +- [2026-05-29] Create the Release with the **`gh` CLI** (`gh release create`), not `softprops/action-gh-release`. gh is preinstalled on runners, needs no third-party SHA to pin/track, and matches the repo's "prefer official/built-in tooling" rule. Overrides the issue's softprops suggestion. +- [2026-05-29] **README-only** delivery — no `.github/workflows/_examples/` file. The dir does not exist and every prior workflow shipped README-only. Overrides the issue's literal `_examples/` acceptance criterion for consistency. +- [2026-05-29] **Tolerant changelog heading match.** The awk does a literal first-token compare after stripping `## `, surrounding brackets, and a leading `v` — so `## v1.2.3`, `## 1.2.3`, `## [1.2.3]`, `## [v1.2.3]`, and `## v1.2.3 - ` all match `v1.2.3`, while `## Unreleased` and `## v1.2.30` do not. Avoids dynamic-regex escaping entirely. +- [2026-05-29] **Injection-safe:** `tag` / paths / booleans pass through step-level `env:` and are referenced as `$VARS`; nothing is interpolated as `${{ inputs.* }}` inside a shell/awk script (hardens the issue's reference snippet). +- [2026-05-29] **Fail closed:** missing changelog file, empty/absent section, or an empty downloaded artifact each `::error::` + `exit 1` — never publish a Release with no notes or no asset. `gh release create` runs with `--verify-tag` so a wrong/absent tag errors rather than silently creating a tag off the default branch. +- [2026-05-29] Inputs are exactly the five from the contract: `tag` (required), `artifact-name` (required), `changelog-path` (`CHANGELOG.md`), `draft` (`false`), `prerelease` (`false`). No extra knobs added. + +--- + +## Files changed so far + +- `.github/workflows/cd-github-release.yml` — new +- `README.md` — edited (new `### cd-github-release.yml` section) +- `CHANGELOG.md` — edited (bullet under Unreleased → Added) +- `.claude/issues/14-cd-github-release.md` — new (this file) + +--- + +## Verification run + +```bash +❯ pipx run yamllint . +❯ act workflow_call -W .github/workflows/cd-github-release.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Set up job +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Set up job +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ☁ git clone 'https://github.com/actions/download-artifact' # ref=d3f86a106a0bac45b974a628896c90dbdf5c8093 +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Main Checkout repository +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Main Checkout repository [8.740416ms] +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Main Download release artifact +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Main Download release artifact [7.706667ms] +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Main Extract changelog section +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Main Extract changelog section [19.298167ms] +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Main Create GitHub Release +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Main Create GitHub Release [19.135125ms] +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Complete job +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] Cleaning up container for job Publish GitHub Release +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Complete job +*DRYRUN* [CD / GitHub Release/Publish GitHub Release] 🏁 Job succeeded +``` + +All pass. `## v1.2.3` and `## [1.2.3]` extract the right body; `## Unreleased` and `## v1.2.30` are not matched for tag `v1.2.3`; a tag with no section returns empty → exit 1. (A degenerate `tag: vUnreleased` would match `## Unreleased`, but a `v*.*.*` trigger can never produce that, so no special-casing.) + +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- **Same-run artifact:** `actions/download-artifact@v4` only sees the current run's artifacts. The intended model is orchestrator-driven (build → release in one run); a standalone tag-push call with no in-run build finds nothing. +- **Re-runs:** `gh release create` fails if the Release already exists. Acceptable for "create a Release" — no idempotency was requested. Flag if reviewers want upsert behaviour. +- **Asset shape:** attaches each file under `artifact/` as a Release asset (mirrors the issue's `files: artifact/*`). A single zipped asset would be a follow-up. +- **End-to-end is deferred:** `act` cannot create a real Release. Real proof is a `v*.*.*` tag push in a throwaway consumer (or via the orchestrator) with `contents: write`. +- **Soft deps:** #11 (artifact contract) and #17 (orchestrator) are open but non-blocking — the upload contract already lives in `ci-build.yml`, and the orchestrator is downstream. +- **Action pins:** `actions/checkout@…v4.2.2` (reused), `actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0` (matches the v4 `upload-artifact` producer). + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.github/workflows/cd-github-release.yml b/.github/workflows/cd-github-release.yml new file mode 100644 index 0000000..e22cf1c --- /dev/null +++ b/.github/workflows/cd-github-release.yml @@ -0,0 +1,103 @@ +name: CD / GitHub Release + +on: + workflow_call: + inputs: + tag: + description: "Tag that triggered the release, e.g. v1.2.3." + type: string + required: true + artifact-name: + description: "Name of the build artifact to download and attach. Must match the name used by the producing job (e.g. ci-build.yml's artifact-name)." + type: string + required: true + changelog-path: + description: "Path to the changelog whose matching section becomes the release body." + type: string + default: "CHANGELOG.md" + draft: + description: "Create the GitHub Release as a draft." + type: boolean + default: false + prerelease: + description: "Mark the GitHub Release as a prerelease." + type: boolean + default: false + +permissions: + contents: write + +jobs: + release: + name: Publish GitHub Release + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Download release artifact + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: ${{ inputs.artifact-name }} + path: artifact + + - name: Extract changelog section + id: notes + shell: bash + env: + TAG: ${{ inputs.tag }} + CHANGELOG_PATH: ${{ inputs.changelog-path }} + run: | + set -euo pipefail + if [ ! -f "$CHANGELOG_PATH" ]; then + echo "::error::Changelog not found at '$CHANGELOG_PATH'" + exit 1 + fi + ver="${TAG#v}" + # Capture the body under the heading whose first token matches the tag's + # version, tolerating "## v1.2.3", "## 1.2.3", "## [1.2.3]", "## [v1.2.3]" + # and an optional trailing " - date". Exact token compare keeps "## Unreleased" + # and "## v1.2.30" from matching "v1.2.3". + awk -v ver="$ver" ' + /^## / { + if (capture) { exit } + line = $0 + sub(/^##[ \t]+/, "", line) + split(line, parts, /[ \t]+/) + head = parts[1] + gsub(/^\[|\]$/, "", head) + sub(/^v/, "", head) + if (head == ver) { capture = 1 } + next + } + capture { print } + ' "$CHANGELOG_PATH" > release-notes.md + if ! grep -q '[^[:space:]]' release-notes.md; then + echo "::error::No changelog section found for $TAG in $CHANGELOG_PATH" + exit 1 + fi + + - name: Create GitHub Release + shell: bash + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ inputs.tag }} + ARTIFACT_NAME: ${{ inputs.artifact-name }} + DRAFT: ${{ inputs.draft }} + PRERELEASE: ${{ inputs.prerelease }} + run: | + set -euo pipefail + shopt -s nullglob + files=(artifact/*) + if [ ${#files[@]} -eq 0 ]; then + echo "::error::Downloaded artifact '$ARTIFACT_NAME' contains no files to attach" + exit 1 + fi + args=(release create "$TAG" "${files[@]}" --verify-tag --title "$TAG" --notes-file release-notes.md) + if [ "$DRAFT" = "true" ]; then + args+=(--draft) + fi + if [ "$PRERELEASE" = "true" ]; then + args+=(--prerelease) + fi + gh "${args[@]}" diff --git a/CHANGELOG.md b/CHANGELOG.md index 791d34e..802fdf6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,3 +15,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `ci-build-artifact-gate.yml`: reusable workflow that fails a PR if it commits files under configured path prefixes (default: `assets/build/`). Pair with `ci-build.yml` so the CI-produced bundle is the only source of truth for build output. Compares `origin/..HEAD` with `--diff-filter=ACMR`, so additions/modifications/renames trip the gate and deletions are ignored (removing a previously-committed artifact is welcome). Runs only on `pull_request` events; on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. Empty `gated-paths` input skips gracefully. Path prefixes are anchored as literal strings, and regex metacharacters in path names (`. + * ( ) [ ] { } | ^ $ ? \`) are escaped automatically. Inputs: `gated-paths`, `working-dir`. - `cd-split-composer-packages.yml`: reusable "monorepo split" workflow (Symfony pattern) that mirrors each Composer-package subtree to its own standalone repo so Packagist can serve it. A `build-matrix` job parses `splitsh.json` (`organization`, `subtrees` map, `defaults.branch`/`user_name`/`user_email`) with jq — accepting both the shorthand string form and the object/`prefixes` form — and a matrixed `split` job runs `danharrin/monorepo-split-github-action` (pinned to `14e42e2`, v2.4.5) per subtree with `fail-fast: false`. `tag` falls back to the caller's `github.ref_name` when empty; missing or empty config fails loudly. Inputs: `tag`, `config-file`. Secret: `split-token` (PAT/App token with `contents: write` on every mirror repo). - `ci-test-build-artifact.yml`: reusable workflow that boots the packaged build artifact in a real WordPress to prove it installs, not just that the build compiled. Downloads the named artifact (via `actions/download-artifact` pinned to `d3f86a1`, v4.3.0), writes a `.wp-env.override.json` to pin `phpVersion`/`core` and mount only the downloaded artifact (clearing `plugins`/`themes` from the consumer config so the dev source tree never collides with the packaged output), boots `@wordpress/env` with `npx --yes @wordpress/env start --update`, activates the plugin or theme (selected from `install-path`), then runs `wp doctor check --all --format=json` and fails only on `error`-severity checks (warnings allowed). The artifact must be a complete installable plugin/theme directory, so point `ci-build.yml`'s `artifact-path` at a packaged dist directory rather than bare `build/`. An optional `smoke-script` runs inside the container after activation, and `wp-env stop` runs in an `if: always()` step (with its own timeout) so no container leaks into the next job. Production-oriented doctor checks that a dev wp-env always trips (e.g. `constant-wp-debug-falsy`, since wp-env enables `WP_DEBUG`) are excluded from the gate via the `doctor-ignore-checks` input. Inputs: `artifact-name`, `slug`, `node-version`, `php-version`, `wp-version`, `install-path`, `smoke-script`, `doctor-ignore-checks`. +- `cd-github-release.yml`: reusable workflow that publishes a GitHub Release on a `v*.*.*` tag push. Downloads the named build artifact, extracts the release body from the matching `CHANGELOG.md` section (tolerant heading match — `## v1.2.3` or `## [1.2.3]` with an optional trailing date; `## Unreleased` is never matched and a missing/empty section fails the workflow rather than publishing empty notes), then creates the Release via the `gh` CLI (no third-party action) with `--verify-tag` so a non-existent tag errors instead of silently creating one. Attaches the artifact files and honours `draft` / `prerelease`. Requires the caller to grant `contents: write`; the artifact must be produced in the same run. Inputs: `tag`, `artifact-name`, `changelog-path`, `draft`, `prerelease`. diff --git a/README.md b/README.md index 3233b4e..deeace0 100644 --- a/README.md +++ b/README.md @@ -351,6 +351,43 @@ jobs: The artifact must be a **complete installable plugin/theme directory** (main PHP file plus assets), so point `ci-build.yml`'s `artifact-path` at a packaged dist directory, not bare `build/`. `actions/download-artifact` restores the uploaded directory contents uncompressed, so there is no unzip step. The workflow writes a `.wp-env.override.json` that pins `phpVersion`/`core` and mounts **only** the downloaded artifact — it clears `plugins`/`themes` from the consumer's `.wp-env.json` so the test reflects the packaged output in isolation, not the dev source tree. It then runs `wp activate ` and `wp doctor check --all` (failing only on `error` severity), and always runs `wp-env stop` so no container leaks into the next job. +### `cd-github-release.yml`: GitHub Release + +On a `v*.*.*` tag push, publishes a GitHub Release: the body is pulled from the matching `CHANGELOG.md` section, the named build artifact is attached, and `draft` / `prerelease` are honoured. Uses the `gh` CLI (no third-party action). Usually called by `wp-cd.yml`, but works standalone. + +```yaml +# .github/workflows/release.yml in the consumer +name: Release +on: + push: + tags: + - "v*.*.*" +jobs: + build: + uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + with: + upload-artifact: true + artifact-name: "release" + github-release: + needs: build + permissions: + contents: write + uses: rtCamp/shared-workflows/.github/workflows/cd-github-release.yml@v1 + with: + tag: ${{ github.ref_name }} + artifact-name: "release" +``` + +| Input | Type | Default | Description | +| ---------------- | ------- | ---------------- | --------------------------------------------------------------------------------- | +| `tag` | string | _(required)_ | Tag that triggered the release, e.g. `v1.2.3`. | +| `artifact-name` | string | _(required)_ | Build artifact to download and attach. Must match the producing job's name. | +| `changelog-path` | string | `"CHANGELOG.md"` | Changelog whose matching section becomes the release body. | +| `draft` | boolean | `false` | Create the Release as a draft. | +| `prerelease` | boolean | `false` | Mark the Release as a prerelease. | + +The calling job must grant `permissions: contents: write`. The artifact must be produced **in the same workflow run** — `download-artifact` only sees the current run's artifacts. The changelog heading must contain the tag's version (`## v1.2.3` or `## [1.2.3]`, with an optional trailing date); `## Unreleased` is never matched. A missing or empty section fails the workflow rather than publishing a Release with no notes. + ## License GPL-2.0-or-later From cb9ae6e5e999a2fdb6bb55c2798a7cb07407ab5f Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Fri, 29 May 2026 16:49:36 +0530 Subject: [PATCH 25/43] feat(cd): add cd-wp-org deploy workflow --- .claude/issues/15-cd-wp-org.md | 101 ++++++++++++++++++ .../workflows/_examples/caller-cd-wp-org.yml | 36 +++++++ .github/workflows/cd-wp-org.yml | 88 +++++++++++++++ CHANGELOG.md | 1 + README.md | 52 +++++++++ 5 files changed, 278 insertions(+) create mode 100644 .claude/issues/15-cd-wp-org.md create mode 100644 .github/workflows/_examples/caller-cd-wp-org.yml create mode 100644 .github/workflows/cd-wp-org.yml diff --git a/.claude/issues/15-cd-wp-org.md b/.claude/issues/15-cd-wp-org.md new file mode 100644 index 0000000..e8bff2a --- /dev/null +++ b/.claude/issues/15-cd-wp-org.md @@ -0,0 +1,101 @@ +# Issue #15 — Add CD WP.org deploy workflow (`cd-wp-org.yml`) + +**Status:** in-review +**Branch:** `v1.0.0/task/cd-wp-org` +**PR:** #26 +**Assignee:** @Adi-ty + +--- + +## Summary + +Plugins on the WordPress.org directory deploy over SVN to `https://plugins.svn.wordpress.org//` — a fiddly flow (trunk vs `tags/`, the `/assets/` dir, `readme.txt` `Stable tag` validation). `cd-wp-org.yml` wraps the proven `10up/action-wordpress-plugin-deploy` so a consuming plugin skeleton deploys with one tag-triggered caller: it downloads the build artifact, fails fast unless `readme.txt`'s `Stable tag` matches the tag, then deploys to `trunk/` + `tags//` and syncs assets to SVN `/assets/`. It is the second CD workflow (with `cd-github-release.yml`) and the WP.org target the CD orchestrator (`wp-cd.yml`, #17) will call. + +--- + +## Decisions made + +- [2026-05-29] **No blocker — proceeded.** Runs entirely in the caller's repo with its own WP.org credentials. The issue's "depends on #11" is a *logical/runtime* dependency: the workflow only downloads an artifact by name (like `cd-github-release.yml`), with no code-level `uses:` on `ci-test-build-artifact`. The producer `ci-build.yml` is already merged. No private cross-repo dependency, no impossible-input blocker (unlike the deferred BC workflow). +- [2026-05-29] **Branched off `release/v1.0.0`** (needs nothing from detect-changes/lint); PR targets `release/v1.0.0`. No stacking. +- [2026-05-29] **Use `10up/action-wordpress-plugin-deploy@54bd289b8525fd23a5c365ec369185f2966529c2 # v2.3.0`, SHA-pinned.** Third-party, but no official WordPress/Automattic WP.org deploy action exists, so this is the de-facto standard — justified under CLAUDE.md's "build custom only when there's a real gap." Mandated by the issue. +- [2026-05-29] **Corrected the issue's reference snippet.** Verified against the action's `action.yml` + `deploy.sh` at 2.3.0: the only `with:` inputs are `generate-zip` and `dry-run`. Everything else is **environment variables** — `SVN_USERNAME`, `SVN_PASSWORD`, `SLUG`, `VERSION`, `ASSETS_DIR`, `BUILD_DIR`. The issue's `with: slug / assets-dir` would silently do nothing. +- [2026-05-29] **`VERSION` computed by us, not the action.** The action only strips a leading `v` when it *derives* `VERSION` from the git ref; a passed `VERSION` is used as-is. So the readme-verify step strips `v`, emits the bare version as a step output, and the deploy step passes it as `VERSION` — keeping it equal to the readme `Stable tag` and the SVN `tags/`. +- [2026-05-29] **Artifact → `BUILD_DIR`.** The action rsyncs `$BUILD_DIR/` into `trunk/`; we download the artifact to `artifact/` and set `BUILD_DIR: artifact`. Assets are read from the *workspace* (`$GITHUB_WORKSPACE/$ASSETS_DIR/`), so the job also checks out the repo. +- [2026-05-29] **Injection-safe + fail-fast:** `tag` / `artifact-name` pass via step `env:` and are referenced as `$VARS`; nothing interpolated as `${{ inputs.* }}` inside a script. Missing `readme.txt`, missing `Stable tag:` header, or a mismatch each `::error::` + `exit 1` before the action runs (matches `cd-github-release.yml`). +- [2026-05-29] **`permissions: contents: read`** — only `checkout` reads the repo; the SVN deploy authenticates with the secrets, not the GitHub token. +- [2026-05-29] **Inputs = the five from the contract** + secrets `WP_ORG_USERNAME` / `WP_ORG_PASSWORD`. `generate-zip` not exposed (out of scope). Added the `_examples/caller-cd-wp-org.yml` reference caller. + +--- + +## Files changed so far + +- `.github/workflows/cd-wp-org.yml` — new (the workflow) +- `.github/workflows/_examples/caller-cd-wp-org.yml` — new (tag-triggered caller with secrets) +- `README.md` — edited (new `### cd-wp-org.yml` section under Individual workflows) +- `CHANGELOG.md` — edited (bullet under Unreleased → Added) +- `.claude/issues/15-cd-wp-org.md` — new (this file) + +--- + +## Verification run + +```bash +❯ pipx run yamllint .github/workflows/cd-wp-org.yml .github/workflows/_examples/caller-cd-wp-org.yml +❯ act workflow_call -W .github/workflows/cd-wp-org.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Set up job +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Set up job +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ☁ git clone 'https://github.com/actions/download-artifact' # ref=d3f86a106a0bac45b974a628896c90dbdf5c8093 +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ☁ git clone 'https://github.com/10up/action-wordpress-plugin-deploy' # ref=54bd289b8525fd23a5c365ec369185f2966529c2 +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Pre Deploy to WordPress.org +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Pre Deploy to WordPress.org [22.511292ms] +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Main Checkout repository +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Main Checkout repository [6.783791ms] +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Main Download build artifact +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Main Download build artifact [9.202ms] +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Main Verify readme.txt stable tag matches the release tag +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Main Verify readme.txt stable tag matches the release tag [21.101542ms] +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Main Deploy to WordPress.org +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Main /var/run/act/actions/10up-action-wordpress-plugin-deploy@54bd289b8525fd23a5c365ec369185f2966529c2/deploy.sh +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Main /var/run/act/actions/10up-action-wordpress-plugin-deploy@54bd289b8525fd23a5c365ec369185f2966529c2/deploy.sh [15.179166ms] +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⚙ ::set-output:: zip-path= +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Main Deploy to WordPress.org [52.698916ms] +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Post Deploy to WordPress.org +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Post Deploy to WordPress.org [30.75µs] +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Complete job +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] Cleaning up container for job Deploy to WordPress.org +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Complete job +*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] 🏁 Job succeeded +``` + +yamllint clean; `act` resolves the full step graph (checkout → download-artifact → verify → 10up composite deploy). + +readme `Stable tag` check (local awk unit-test, all pass): `Stable tag: 1.2.3` matches `tag: v1.2.3`; a mismatched tag, a `Stable tag: trunk`, and a missing `Stable tag:` header each exit 1; case-insensitive and CRLF/space-tolerant. + +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- **`Stable tag: trunk` plugins are rejected** by the strict match. +- **Same-run artifact** — `download-artifact@v4` only sees the current run's artifacts; the model is build → deploy in one run (mirrors `cd-github-release.yml`). +- **Idempotent re-run** — the action exits 0 if `tags/` already exists on WP.org. +- **Third-party action** — not WordPress/Automattic org, but no official option exists; SHA-pinned to v2.3.0 and tracked. +- **README merge order** — `cd-github-release.yml` (PR #24) also adds a section before `## License`; whichever merges second may need a trivial conflict resolution. +- **Action pins:** `actions/checkout@…v4.2.2`, `actions/download-artifact@…v4.3.0` (reuse the CD sibling's pins), `10up/action-wordpress-plugin-deploy@54bd289… # v2.3.0`. + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.github/workflows/_examples/caller-cd-wp-org.yml b/.github/workflows/_examples/caller-cd-wp-org.yml new file mode 100644 index 0000000..1ccc94a --- /dev/null +++ b/.github/workflows/_examples/caller-cd-wp-org.yml @@ -0,0 +1,36 @@ +# Reference caller for cd-wp-org.yml — copy into a plugin repo as +# .github/workflows/deploy-wp-org.yml. Lives in _examples/ (a subdirectory) so GitHub +# never auto-runs it: only files at the top of .github/workflows/ are discovered. +name: Deploy to WordPress.org + +on: + push: + tags: ["v*.*.*"] + +# Only checkout reads the repo; the SVN deploy authenticates with the secrets below. +permissions: + contents: read + +jobs: + # Build and upload the shippable plugin files in the SAME run — download-artifact + # only sees the current run's artifacts. The artifact root must contain readme.txt. + build: + uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + with: + upload-artifact: true + artifact-name: wp-org-build + # Override build-command / artifact-path so the artifact root holds the + # shippable plugin files (readme.txt at the top). See the ci-build.yml docs. + + deploy: + needs: build + uses: rtCamp/shared-workflows/.github/workflows/cd-wp-org.yml@v1 + with: + slug: my-plugin + tag: ${{ github.ref_name }} + artifact-name: wp-org-build + # assets-path: ".wordpress-org" # default; override if assets live elsewhere + # dry-run: true # test without committing to SVN + secrets: + WP_ORG_USERNAME: ${{ secrets.WP_ORG_USERNAME }} + WP_ORG_PASSWORD: ${{ secrets.WP_ORG_PASSWORD }} diff --git a/.github/workflows/cd-wp-org.yml b/.github/workflows/cd-wp-org.yml new file mode 100644 index 0000000..436deb4 --- /dev/null +++ b/.github/workflows/cd-wp-org.yml @@ -0,0 +1,88 @@ +name: CD / WordPress.org Deploy + +on: + workflow_call: + inputs: + slug: + description: "Plugin slug on wordpress.org (the directory under plugins.svn.wordpress.org)." + type: string + required: true + tag: + description: "Release tag, e.g. v1.2.3. A leading 'v' is stripped; the result must match readme.txt's Stable tag and becomes the SVN tags/." + type: string + required: true + artifact-name: + description: "Name of the build artifact to download and deploy. Must match the name used by the producing job (e.g. ci-build.yml's artifact-name)." + type: string + required: true + assets-path: + description: "Local directory (in the checked-out repo) mapped to SVN /assets/. Skipped if it does not exist." + type: string + default: ".wordpress-org" + dry-run: + description: "Run the full deploy except the final SVN commit." + type: boolean + default: false + secrets: + WP_ORG_USERNAME: + description: "WordPress.org account username with commit access to the plugin." + required: true + WP_ORG_PASSWORD: + description: "WordPress.org account password." + required: true + +permissions: + contents: read + +jobs: + deploy: + name: Deploy to WordPress.org + runs-on: ubuntu-latest + steps: + # Needed so the 10up action can read assets-path from the workspace; the + # plugin files themselves come from the downloaded artifact (BUILD_DIR). + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Download build artifact + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: ${{ inputs.artifact-name }} + path: artifact + + - name: Verify readme.txt stable tag matches the release tag + id: check + shell: bash + env: + TAG: ${{ inputs.tag }} + ARTIFACT_NAME: ${{ inputs.artifact-name }} + run: | + set -euo pipefail + if [ ! -f artifact/readme.txt ]; then + echo "::error::artifact/readme.txt not found in downloaded artifact '$ARTIFACT_NAME'" + exit 1 + fi + expected="${TAG#v}" + stable="$(awk -F':' 'tolower($1) ~ /^[[:space:]]*stable tag[[:space:]]*$/ {sub(/^[^:]*:/, "", $0); gsub(/[[:space:]]/, "", $0); print; exit}' artifact/readme.txt)" + if [ -z "$stable" ]; then + echo "::error::No 'Stable tag:' header found in artifact/readme.txt" + exit 1 + fi + if [ "$stable" != "$expected" ]; then + echo "::error::readme.txt Stable tag ($stable) does not match release tag ($expected)" + exit 1 + fi + echo "version=$expected" >> "$GITHUB_OUTPUT" + + - name: Deploy to WordPress.org + uses: 10up/action-wordpress-plugin-deploy@54bd289b8525fd23a5c365ec369185f2966529c2 # v2.3.0 + timeout-minutes: 15 + with: + dry-run: ${{ inputs.dry-run }} + env: + SVN_USERNAME: ${{ secrets.WP_ORG_USERNAME }} + SVN_PASSWORD: ${{ secrets.WP_ORG_PASSWORD }} + SLUG: ${{ inputs.slug }} + VERSION: ${{ steps.check.outputs.version }} + ASSETS_DIR: ${{ inputs.assets-path }} + BUILD_DIR: artifact diff --git a/CHANGELOG.md b/CHANGELOG.md index 43badc9..032fd50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,3 +14,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `ci-build.yml`: reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. The `build-command` default is empty and selects `npm run build:prod` when Node deps install, `composer run-script build` otherwise. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. - `ci-build-artifact-gate.yml`: reusable workflow that fails a PR if it commits files under configured path prefixes (default: `assets/build/`). Pair with `ci-build.yml` so the CI-produced bundle is the only source of truth for build output. Compares `origin/..HEAD` with `--diff-filter=ACMR`, so additions/modifications/renames trip the gate and deletions are ignored (removing a previously-committed artifact is welcome). Runs only on `pull_request` events; on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. Empty `gated-paths` input skips gracefully. Path prefixes are anchored as literal strings, and regex metacharacters in path names (`. + * ( ) [ ] { } | ^ $ ? \`) are escaped automatically. Inputs: `gated-paths`, `working-dir`. - `ci-test-build-artifact.yml`: reusable workflow that boots the packaged build artifact in a real WordPress to prove it installs, not just that the build compiled. Downloads the named artifact (via `actions/download-artifact` pinned to `d3f86a1`, v4.3.0), writes a `.wp-env.override.json` to pin `phpVersion`/`core` and mount only the downloaded artifact (clearing `plugins`/`themes` from the consumer config so the dev source tree never collides with the packaged output), boots `@wordpress/env` with `npx --yes @wordpress/env start --update`, activates the plugin or theme (selected from `install-path`), then runs `wp doctor check --all --format=json` and fails only on `error`-severity checks (warnings allowed). The artifact must be a complete installable plugin/theme directory, so point `ci-build.yml`'s `artifact-path` at a packaged dist directory rather than bare `build/`. An optional `smoke-script` runs inside the container after activation, and `wp-env stop` runs in an `if: always()` step (with its own timeout) so no container leaks into the next job. Production-oriented doctor checks that a dev wp-env always trips (e.g. `constant-wp-debug-falsy`, since wp-env enables `WP_DEBUG`) are excluded from the gate via the `doctor-ignore-checks` input. Inputs: `artifact-name`, `slug`, `node-version`, `php-version`, `wp-version`, `install-path`, `smoke-script`, `doctor-ignore-checks`. +- `cd-wp-org.yml`: reusable workflow that deploys a plugin to the WordPress.org directory over SVN on a release tag, wrapping `10up/action-wordpress-plugin-deploy` (SHA-pinned to v2.3.0). Downloads the named build artifact, fails fast unless `readme.txt`'s `Stable tag` matches the tag (leading `v` stripped), then deploys the artifact to `trunk/` + `tags//` via the action's `BUILD_DIR` and syncs `assets-path` (default `.wordpress-org`, read from the checked-out repo) to SVN `/assets/`. The action is configured through environment variables (`SLUG`, `VERSION`, `ASSETS_DIR`, `BUILD_DIR`, `SVN_USERNAME`, `SVN_PASSWORD`); `dry-run` runs everything except the SVN commit; re-publishing an existing version is a no-op. Inputs: `slug`, `tag`, `artifact-name`, `assets-path`, `dry-run`. Required secrets: `WP_ORG_USERNAME`, `WP_ORG_PASSWORD`. diff --git a/README.md b/README.md index 6cf8057..a419056 100644 --- a/README.md +++ b/README.md @@ -277,6 +277,58 @@ jobs: The artifact must be a **complete installable plugin/theme directory** (main PHP file plus assets), so point `ci-build.yml`'s `artifact-path` at a packaged dist directory, not bare `build/`. `actions/download-artifact` restores the uploaded directory contents uncompressed, so there is no unzip step. The workflow writes a `.wp-env.override.json` that pins `phpVersion`/`core` and mounts **only** the downloaded artifact — it clears `plugins`/`themes` from the consumer's `.wp-env.json` so the test reflects the packaged output in isolation, not the dev source tree. It then runs `wp activate ` and `wp doctor check --all` (failing only on `error` severity), and always runs `wp-env stop` so no container leaks into the next job. +### `cd-wp-org.yml`: WordPress.org deploy + +Deploys a plugin to the [WordPress.org plugin directory](https://plugins.svn.wordpress.org/) over SVN on a release tag, wrapping the standard [`10up/action-wordpress-plugin-deploy`](https://github.com/10up/action-wordpress-plugin-deploy) (SHA-pinned). Before deploying it fails fast unless `readme.txt`'s `Stable tag` matches the release tag, then syncs the build artifact to `trunk/` + `tags//` and the `assets-path` directory to SVN `/assets/`. `dry-run` runs everything except the final commit. + +```yaml +# .github/workflows/deploy-wp-org.yml in the consumer +name: Deploy to WordPress.org +on: + push: + tags: ["v*.*.*"] +permissions: + contents: read + artifact-name: wp-org-build + # build-command / artifact-path must place the shippable plugin files + # (readme.txt at the artifact root) — see ci-build.yml above. + deploy: + needs: build + uses: rtCamp/shared-workflows/.github/workflows/cd-wp-org.yml@v1 + with: + slug: my-plugin + tag: ${{ github.ref_name }} + artifact-name: wp-org-build + secrets: + WP_ORG_USERNAME: ${{ secrets.WP_ORG_USERNAME }} + WP_ORG_PASSWORD: ${{ secrets.WP_ORG_PASSWORD }} +``` + +The full copy-paste caller lives at [`.github/workflows/_examples/caller-cd-wp-org.yml`](.github/workflows/_examples/caller-cd-wp-org.yml). + +| Input | Type | Default | Description | +| --------------- | ------- | ------------------ | ---------------------------------------------------------------------------- | +| `slug` | string | — | **Required.** Plugin slug on wordpress.org. | +| `tag` | string | — | **Required.** Release tag, e.g. `v1.2.3`. A leading `v` is stripped. | +| `artifact-name` | string | — | **Required.** Build artifact to download and deploy (must match the producer). | +| `assets-path` | string | `".wordpress-org"` | Local directory mapped to SVN `/assets/`. Skipped if absent. | +| `dry-run` | boolean | `false` | Run the full deploy except the final SVN commit. | + +| Secret | Required | Description | +| ----------------- | -------- | -------------------------------------------------------------------- | +| `WP_ORG_USERNAME` | yes | WordPress.org account username with commit access to the plugin. | +| `WP_ORG_PASSWORD` | yes | WordPress.org account password. | + +Add the secrets under the consumer repo's **Settings → Secrets and variables → Actions**, then pass them through as shown above (reusable-workflow secrets are not inherited automatically). + +Notes: + +- **Same-run artifact** — `actions/download-artifact` only sees the current run's artifacts, so build and deploy must run in the same workflow (`deploy` `needs: build`). +- **Assets** are read from the *checked-out repo* at `assets-path` (not from the artifact); the build artifact supplies the plugin files for `trunk/`. +- **`Stable tag`** in `readme.txt` must equal the tag with any leading `v` removed (`v1.2.3` → `1.2.3`). Plugins using `Stable tag: trunk` are not supported by the strict check. +- **Idempotent** — if `tags/` already exists on WP.org the action exits successfully without re-committing. +- **`dry-run`** still checks out the live WP.org SVN repo for the slug; it only skips the commit, so exercising it end to end needs a real published slug. + ## License GPL-2.0-or-later From 39c03b525251a0d1022a38561b6eeb3c7ea5c742 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Mon, 15 Jun 2026 12:36:06 +0530 Subject: [PATCH 26/43] feat: update README with build command and artifact path for cd-wp-org workflow --- .claude/issues/15-cd-wp-org.md | 4 +-- .../workflows/_examples/caller-cd-wp-org.yml | 36 ------------------- README.md | 16 ++++++--- 3 files changed, 12 insertions(+), 44 deletions(-) delete mode 100644 .github/workflows/_examples/caller-cd-wp-org.yml diff --git a/.claude/issues/15-cd-wp-org.md b/.claude/issues/15-cd-wp-org.md index e8bff2a..15159d4 100644 --- a/.claude/issues/15-cd-wp-org.md +++ b/.claude/issues/15-cd-wp-org.md @@ -23,14 +23,12 @@ Plugins on the WordPress.org directory deploy over SVN to `https://plugins.svn.w - [2026-05-29] **Artifact → `BUILD_DIR`.** The action rsyncs `$BUILD_DIR/` into `trunk/`; we download the artifact to `artifact/` and set `BUILD_DIR: artifact`. Assets are read from the *workspace* (`$GITHUB_WORKSPACE/$ASSETS_DIR/`), so the job also checks out the repo. - [2026-05-29] **Injection-safe + fail-fast:** `tag` / `artifact-name` pass via step `env:` and are referenced as `$VARS`; nothing interpolated as `${{ inputs.* }}` inside a script. Missing `readme.txt`, missing `Stable tag:` header, or a mismatch each `::error::` + `exit 1` before the action runs (matches `cd-github-release.yml`). - [2026-05-29] **`permissions: contents: read`** — only `checkout` reads the repo; the SVN deploy authenticates with the secrets, not the GitHub token. -- [2026-05-29] **Inputs = the five from the contract** + secrets `WP_ORG_USERNAME` / `WP_ORG_PASSWORD`. `generate-zip` not exposed (out of scope). Added the `_examples/caller-cd-wp-org.yml` reference caller. --- ## Files changed so far - `.github/workflows/cd-wp-org.yml` — new (the workflow) -- `.github/workflows/_examples/caller-cd-wp-org.yml` — new (tag-triggered caller with secrets) - `README.md` — edited (new `### cd-wp-org.yml` section under Individual workflows) - `CHANGELOG.md` — edited (bullet under Unreleased → Added) - `.claude/issues/15-cd-wp-org.md` — new (this file) @@ -40,7 +38,7 @@ Plugins on the WordPress.org directory deploy over SVN to `https://plugins.svn.w ## Verification run ```bash -❯ pipx run yamllint .github/workflows/cd-wp-org.yml .github/workflows/_examples/caller-cd-wp-org.yml +❯ pipx run yamllint .github/workflows/cd-wp-org.yml ❯ act workflow_call -W .github/workflows/cd-wp-org.yml --dryrun INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ diff --git a/.github/workflows/_examples/caller-cd-wp-org.yml b/.github/workflows/_examples/caller-cd-wp-org.yml deleted file mode 100644 index 1ccc94a..0000000 --- a/.github/workflows/_examples/caller-cd-wp-org.yml +++ /dev/null @@ -1,36 +0,0 @@ -# Reference caller for cd-wp-org.yml — copy into a plugin repo as -# .github/workflows/deploy-wp-org.yml. Lives in _examples/ (a subdirectory) so GitHub -# never auto-runs it: only files at the top of .github/workflows/ are discovered. -name: Deploy to WordPress.org - -on: - push: - tags: ["v*.*.*"] - -# Only checkout reads the repo; the SVN deploy authenticates with the secrets below. -permissions: - contents: read - -jobs: - # Build and upload the shippable plugin files in the SAME run — download-artifact - # only sees the current run's artifacts. The artifact root must contain readme.txt. - build: - uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 - with: - upload-artifact: true - artifact-name: wp-org-build - # Override build-command / artifact-path so the artifact root holds the - # shippable plugin files (readme.txt at the top). See the ci-build.yml docs. - - deploy: - needs: build - uses: rtCamp/shared-workflows/.github/workflows/cd-wp-org.yml@v1 - with: - slug: my-plugin - tag: ${{ github.ref_name }} - artifact-name: wp-org-build - # assets-path: ".wordpress-org" # default; override if assets live elsewhere - # dry-run: true # test without committing to SVN - secrets: - WP_ORG_USERNAME: ${{ secrets.WP_ORG_USERNAME }} - WP_ORG_PASSWORD: ${{ secrets.WP_ORG_PASSWORD }} diff --git a/README.md b/README.md index a419056..91b7f32 100644 --- a/README.md +++ b/README.md @@ -289,9 +289,17 @@ on: tags: ["v*.*.*"] permissions: contents: read - artifact-name: wp-org-build - # build-command / artifact-path must place the shippable plugin files - # (readme.txt at the artifact root) — see ci-build.yml above. +jobs: + build: + uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + with: + upload-artifact: true + artifact-name: wp-org-build + # The artifact root must contain readme.txt, so point artifact-path at a + # packaged plugin dir (not bare build/). Adjust build-command to whatever + # produces that dir in your repo. + build-command: "npm run build:prod" + artifact-path: "dist/my-plugin/" deploy: needs: build uses: rtCamp/shared-workflows/.github/workflows/cd-wp-org.yml@v1 @@ -304,8 +312,6 @@ permissions: WP_ORG_PASSWORD: ${{ secrets.WP_ORG_PASSWORD }} ``` -The full copy-paste caller lives at [`.github/workflows/_examples/caller-cd-wp-org.yml`](.github/workflows/_examples/caller-cd-wp-org.yml). - | Input | Type | Default | Description | | --------------- | ------- | ------------------ | ---------------------------------------------------------------------------- | | `slug` | string | — | **Required.** Plugin slug on wordpress.org. | From 38b5fe8a25599ad6940117139f6154d88b9822c0 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Mon, 15 Jun 2026 12:52:00 +0530 Subject: [PATCH 27/43] docs: update README to clarify required inputs for deployment --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 91b7f32..931c27a 100644 --- a/README.md +++ b/README.md @@ -314,9 +314,9 @@ jobs: | Input | Type | Default | Description | | --------------- | ------- | ------------------ | ---------------------------------------------------------------------------- | -| `slug` | string | — | **Required.** Plugin slug on wordpress.org. | -| `tag` | string | — | **Required.** Release tag, e.g. `v1.2.3`. A leading `v` is stripped. | -| `artifact-name` | string | — | **Required.** Build artifact to download and deploy (must match the producer). | +| `slug` | string | _(required)_ | **Required.** Plugin slug on wordpress.org. | +| `tag` | string | _(required)_ | **Required.** Release tag, e.g. `v1.2.3`. A leading `v` is stripped. | +| `artifact-name` | string | _(required)_ | **Required.** Build artifact to download and deploy (must match the producer). | | `assets-path` | string | `".wordpress-org"` | Local directory mapped to SVN `/assets/`. Skipped if absent. | | `dry-run` | boolean | `false` | Run the full deploy except the final SVN commit. | From c902ea83f962ca3d06664c3fc56fa0ddfdd95abc Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Mon, 15 Jun 2026 13:06:55 +0530 Subject: [PATCH 28/43] feat: update CI build job to upload artifact with specified name --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 52f46f4..edcc717 100644 --- a/README.md +++ b/README.md @@ -400,7 +400,12 @@ on: tags: ["v*.*.*"] permissions: contents: read - artifact-name: wp-org-build +jobs: + build: + uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + with: + upload-artifact: true + artifact-name: wp-org-build # The artifact root must contain readme.txt, so point artifact-path at a # packaged plugin dir (not bare build/). Adjust build-command to whatever # produces that dir in your repo. From e2ad3f2b218af71461d6b48186142b59492be641 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Mon, 15 Jun 2026 13:30:30 +0530 Subject: [PATCH 29/43] fix(cd-wp-org): skip absent assets dir; correct immutable-tag docs --- .claude/issues/15-cd-wp-org.md | 2 +- .github/workflows/cd-wp-org.yml | 19 ++++++++++++++++++- CHANGELOG.md | 2 +- README.md | 2 +- 4 files changed, 21 insertions(+), 4 deletions(-) diff --git a/.claude/issues/15-cd-wp-org.md b/.claude/issues/15-cd-wp-org.md index 15159d4..b57faec 100644 --- a/.claude/issues/15-cd-wp-org.md +++ b/.claude/issues/15-cd-wp-org.md @@ -87,7 +87,7 @@ readme `Stable tag` check (local awk unit-test, all pass): `Stable tag: 1.2.3` m - **`Stable tag: trunk` plugins are rejected** by the strict match. - **Same-run artifact** — `download-artifact@v4` only sees the current run's artifacts; the model is build → deploy in one run (mirrors `cd-github-release.yml`). -- **Idempotent re-run** — the action exits 0 if `tags/` already exists on WP.org. +- **Immutable tags** — the action errors (non-zero) if `tags/` already exists on WP.org; it will not overwrite an existing tag, so re-deploying the same version fails. - **Third-party action** — not WordPress/Automattic org, but no official option exists; SHA-pinned to v2.3.0 and tracked. - **README merge order** — `cd-github-release.yml` (PR #24) also adds a section before `## License`; whichever merges second may need a trivial conflict resolution. - **Action pins:** `actions/checkout@…v4.2.2`, `actions/download-artifact@…v4.3.0` (reuse the CD sibling's pins), `10up/action-wordpress-plugin-deploy@54bd289… # v2.3.0`. diff --git a/.github/workflows/cd-wp-org.yml b/.github/workflows/cd-wp-org.yml index 436deb4..4fcf85a 100644 --- a/.github/workflows/cd-wp-org.yml +++ b/.github/workflows/cd-wp-org.yml @@ -74,6 +74,23 @@ jobs: fi echo "version=$expected" >> "$GITHUB_OUTPUT" + # The 10up action errors if ASSETS_DIR points at a missing directory; it + # only skips assets when ASSETS_DIR is empty. Resolve to empty when the + # path is absent so repos without an assets dir deploy without failing. + - name: Resolve assets directory + id: assets + shell: bash + env: + ASSETS_PATH: ${{ inputs.assets-path }} + run: | + set -euo pipefail + if [ -n "$ASSETS_PATH" ] && [ -d "$ASSETS_PATH" ]; then + echo "assets_dir=$ASSETS_PATH" >> "$GITHUB_OUTPUT" + else + echo "::notice::assets-path '$ASSETS_PATH' not found; skipping assets sync" + echo "assets_dir=" >> "$GITHUB_OUTPUT" + fi + - name: Deploy to WordPress.org uses: 10up/action-wordpress-plugin-deploy@54bd289b8525fd23a5c365ec369185f2966529c2 # v2.3.0 timeout-minutes: 15 @@ -84,5 +101,5 @@ jobs: SVN_PASSWORD: ${{ secrets.WP_ORG_PASSWORD }} SLUG: ${{ inputs.slug }} VERSION: ${{ steps.check.outputs.version }} - ASSETS_DIR: ${{ inputs.assets-path }} + ASSETS_DIR: ${{ steps.assets.outputs.assets_dir }} BUILD_DIR: artifact diff --git a/CHANGELOG.md b/CHANGELOG.md index e4b1a7e..96389f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,4 +16,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `cd-split-composer-packages.yml`: reusable "monorepo split" workflow (Symfony pattern) that mirrors each Composer-package subtree to its own standalone repo so Packagist can serve it. A `build-matrix` job parses `splitsh.json` (`organization`, `subtrees` map, `defaults.branch`/`user_name`/`user_email`) with jq — accepting both the shorthand string form and the object/`prefixes` form — and a matrixed `split` job runs `danharrin/monorepo-split-github-action` (pinned to `14e42e2`, v2.4.5) per subtree with `fail-fast: false`. `tag` falls back to the caller's `github.ref_name` when empty; missing or empty config fails loudly. Inputs: `tag`, `config-file`. Secret: `split-token` (PAT/App token with `contents: write` on every mirror repo). - `ci-test-build-artifact.yml`: reusable workflow that boots the packaged build artifact in a real WordPress to prove it installs, not just that the build compiled. Downloads the named artifact (via `actions/download-artifact` pinned to `d3f86a1`, v4.3.0), writes a `.wp-env.override.json` to pin `phpVersion`/`core` and mount only the downloaded artifact (clearing `plugins`/`themes` from the consumer config so the dev source tree never collides with the packaged output), boots `@wordpress/env` with `npx --yes @wordpress/env start --update`, activates the plugin or theme (selected from `install-path`), then runs `wp doctor check --all --format=json` and fails only on `error`-severity checks (warnings allowed). The artifact must be a complete installable plugin/theme directory, so point `ci-build.yml`'s `artifact-path` at a packaged dist directory rather than bare `build/`. An optional `smoke-script` runs inside the container after activation, and `wp-env stop` runs in an `if: always()` step (with its own timeout) so no container leaks into the next job. Production-oriented doctor checks that a dev wp-env always trips (e.g. `constant-wp-debug-falsy`, since wp-env enables `WP_DEBUG`) are excluded from the gate via the `doctor-ignore-checks` input. Inputs: `artifact-name`, `slug`, `node-version`, `php-version`, `wp-version`, `install-path`, `smoke-script`, `doctor-ignore-checks`. - `cd-github-release.yml`: reusable workflow that publishes a GitHub Release on a `v*.*.*` tag push. Downloads the named build artifact, extracts the release body from the matching `CHANGELOG.md` section (tolerant heading match — `## v1.2.3` or `## [1.2.3]` with an optional trailing date; `## Unreleased` is never matched and a missing/empty section fails the workflow rather than publishing empty notes), then creates the Release via the `gh` CLI (no third-party action) with `--verify-tag` so a non-existent tag errors instead of silently creating one. Attaches the artifact files and honours `draft` / `prerelease`. Requires the caller to grant `contents: write`; the artifact must be produced in the same run. Inputs: `tag`, `artifact-name`, `changelog-path`, `draft`, `prerelease`. -- `cd-wp-org.yml`: reusable workflow that deploys a plugin to the WordPress.org directory over SVN on a release tag, wrapping `10up/action-wordpress-plugin-deploy` (SHA-pinned to v2.3.0). Downloads the named build artifact, fails fast unless `readme.txt`'s `Stable tag` matches the tag (leading `v` stripped), then deploys the artifact to `trunk/` + `tags//` via the action's `BUILD_DIR` and syncs `assets-path` (default `.wordpress-org`, read from the checked-out repo) to SVN `/assets/`. The action is configured through environment variables (`SLUG`, `VERSION`, `ASSETS_DIR`, `BUILD_DIR`, `SVN_USERNAME`, `SVN_PASSWORD`); `dry-run` runs everything except the SVN commit; re-publishing an existing version is a no-op. Inputs: `slug`, `tag`, `artifact-name`, `assets-path`, `dry-run`. Required secrets: `WP_ORG_USERNAME`, `WP_ORG_PASSWORD`. +- `cd-wp-org.yml`: reusable workflow that deploys a plugin to the WordPress.org directory over SVN on a release tag, wrapping `10up/action-wordpress-plugin-deploy` (SHA-pinned to v2.3.0). Downloads the named build artifact, fails fast unless `readme.txt`'s `Stable tag` matches the tag (leading `v` stripped), then deploys the artifact to `trunk/` + `tags//` via the action's `BUILD_DIR` and syncs `assets-path` (default `.wordpress-org`, read from the checked-out repo) to SVN `/assets/`. The action is configured through environment variables (`SLUG`, `VERSION`, `ASSETS_DIR`, `BUILD_DIR`, `SVN_USERNAME`, `SVN_PASSWORD`); `dry-run` runs everything except the SVN commit; deploying a version that already exists fails (WP.org tags are immutable). Inputs: `slug`, `tag`, `artifact-name`, `assets-path`, `dry-run`. Required secrets: `WP_ORG_USERNAME`, `WP_ORG_PASSWORD`. diff --git a/README.md b/README.md index edcc717..63029a0 100644 --- a/README.md +++ b/README.md @@ -443,7 +443,7 @@ Notes: - **Same-run artifact** — `actions/download-artifact` only sees the current run's artifacts, so build and deploy must run in the same workflow (`deploy` `needs: build`). - **Assets** are read from the *checked-out repo* at `assets-path` (not from the artifact); the build artifact supplies the plugin files for `trunk/`. - **`Stable tag`** in `readme.txt` must equal the tag with any leading `v` removed (`v1.2.3` → `1.2.3`). Plugins using `Stable tag: trunk` are not supported by the strict check. -- **Idempotent** — if `tags/` already exists on WP.org the action exits successfully without re-committing. +- **Immutable tags** — WordPress.org SVN tags are release snapshots; the deploy action errors (non-zero) if `tags/` already exists, so re-deploying the same version fails rather than overwriting it. - **`dry-run`** still checks out the live WP.org SVN repo for the slug; it only skips the commit, so exercising it end to end needs a real published slug. ## License From 4781309169b6d195d07141b2be0e57cf8183897f Mon Sep 17 00:00:00 2001 From: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> Date: Tue, 16 Jun 2026 20:51:01 +0530 Subject: [PATCH 30/43] Merge pull request #27 from rtCamp/v1.0.0/task/cd-s3 [v1.0.0] Add cd-s3 deploy workflow --- .claude/issues/16-cd-s3.md | 95 +++++++++++++++++++++++++++++ .github/workflows/cd-s3.yml | 105 ++++++++++++++++++++++++++++++++ CHANGELOG.md | 1 + README.md | 117 +++++++++++++++++++++++++++++------- 4 files changed, 297 insertions(+), 21 deletions(-) create mode 100644 .claude/issues/16-cd-s3.md create mode 100644 .github/workflows/cd-s3.yml diff --git a/.claude/issues/16-cd-s3.md b/.claude/issues/16-cd-s3.md new file mode 100644 index 0000000..a02cc24 --- /dev/null +++ b/.claude/issues/16-cd-s3.md @@ -0,0 +1,95 @@ +# Issue #16 — Add CD S3 deploy workflow (`cd-s3.yml`) + +**Status:** in-review +**Branch:** `v1.0.0/task/cd-s3` +**PR:** #27 +**Assignee:** @Adi-ty + +--- + +## Summary + +Private / customer plugins not published on WP.org are distributed via an S3 bucket the customer can read. `cd-s3.yml` uploads the release artifact to a configured S3 path — a versioned object (`.zip`) plus a rolling `latest.zip` — and optionally invalidates a CloudFront distribution so the new `latest.zip` is served immediately. It is the third CD workflow (with `cd-github-release.yml` and `cd-wp-org.yml`) and the S3 target the CD orchestrator (`wp-cd.yml`, #17) will call. + +--- + +## Decisions made + +- [2026-05-29] **No blocker — proceeded.** `aws-actions/configure-aws-credentials@v6.1.3` is official and SHA-pinnable; the AWS CLI is preinstalled on `ubuntu-latest`. The issue's "depends on #11" is a *logical/runtime* dependency: the workflow only downloads an artifact by name (the producer `ci-build.yml` is merged), with no code-level `uses:` on `ci-test-build-artifact`. Secrets declare via `workflow_call`; no checkout needed; no private cross-repo dependency. +- [2026-05-29] **Versioned object keyed by `tag`** (chosen with the user): `s3:///.zip` + an always-overwritten `latest.zip`. Predictable URL; uses the required `tag` input. Supersedes the issue's `` key, which left `tag` unused. +- [2026-05-29] **`aws-actions/configure-aws-credentials@99214aa6889fcddfa57764031d71add364327e59 # v6.1.3`, SHA-pinned** (latest stable; static access keys via inputs still supported). The issue's "v4.x" was illustrative. +- [2026-05-29] **Static access-key auth** via the two required secrets (per the issue), not OIDC. +- [2026-05-29] **Injection-safe:** `tag` / `bucket` / `prefix` / `cloudfront-distribution-id` pass through step `env:` and are referenced as `$VARS`; nothing interpolated as `${{ inputs.* }}` inside a shell script (the issue's reference inlined them — a shell-injection risk). Matches `cd-github-release` / `cd-wp-org`. +- [2026-05-29] **No checkout; `permissions: contents: read`.** The job only downloads an artifact and talks to AWS; `download-artifact@v4` is same-run and independent of `GITHUB_TOKEN` scopes. +- [2026-05-29] **Single `.zip` enforced:** fail with `::error::` if the artifact contains zero or more than one `.zip`, so a misconfigured `artifact-path` can never deploy the wrong bundle. +- [2026-05-29] **Branched off `release/v1.0.0`**; PR targets `release/v1.0.0`. + +--- + +## Files changed so far + +- `.github/workflows/cd-s3.yml` — new (the workflow) +- `README.md` — edited (new `### cd-s3.yml` section with inline caller + required IAM permissions block) +- `CHANGELOG.md` — edited (bullet under Unreleased → Added) +- `.claude/issues/16-cd-s3.md` — new (this file) + +--- + +## Verification run + +```bash +❯ pipx run yamllint .github/workflows/cd-s3.yml +❯ act workflow_call -W .github/workflows/cd-s3.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Set up job +*DRYRUN* [CD / S3 Deploy/Upload to S3] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CD / S3 Deploy/Upload to S3] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CD / S3 Deploy/Upload to S3] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CD / S3 Deploy/Upload to S3] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Set up job +*DRYRUN* [CD / S3 Deploy/Upload to S3] ☁ git clone 'https://github.com/actions/download-artifact' # ref=d3f86a106a0bac45b974a628896c90dbdf5c8093 +*DRYRUN* [CD / S3 Deploy/Upload to S3] ☁ git clone 'https://github.com/aws-actions/configure-aws-credentials' # ref=99214aa6889fcddfa57764031d71add364327e59 +*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Main Download build artifact +*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Main Download build artifact [7.01175ms] +*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Main Configure AWS credentials +*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Main Configure AWS credentials [8.5785ms] +*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Main Upload to S3 +*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Main Upload to S3 [16.170417ms] +*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Post Configure AWS credentials +*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Post Configure AWS credentials [4.981459ms] +*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Complete job +*DRYRUN* [CD / S3 Deploy/Upload to S3] Cleaning up container for job Upload to S3 +*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Complete job +*DRYRUN* [CD / S3 Deploy/Upload to S3] 🏁 Job succeeded +``` + +yamllint clean; `act` resolves the full graph (download-artifact + configure-aws-credentials). The CloudFront step is correctly skipped when no distribution id is passed. + +Local logic test (aws stubbed on PATH, run under bash, all pass): +- single zip, `prefix=plugins/acme/`, `tag=v1.2.3` → `aws s3 cp ... s3://my-bucket/plugins/acme/v1.2.3.zip` and `.../latest.zip`. +- no zip → `::error::` + exit 1. +- multiple zips, empty prefix → `::error::` + exit 1 (lists the matched `.zip` files) so a misconfigured `artifact-path` can't deploy the wrong bundle. +- CloudFront path: `/plugins/acme/*` (prefix set) and `/*` (empty prefix). + +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- **CLAUDE.md deferral note.** The directory-layout section lists the S3 deploy as "optional; deferred to v1.1.0", conflicting with this PR's v1.0.0 target. That section's names are already stale (`cd-release`/`cd-deploy-wporg`/`cd-deploy-s3` vs the actual `cd-github-release`/`cd-wp-org`/`cd-s3`), so the note is treated as outdated. Updating that line is suggested but not done here. +- **Real S3 upload deferred.** `act` validates the graph and the zip-discovery / key construction is unit-testable locally (stub `aws`), but a true upload needs a real bucket + credentials (or localstack). Out of scope for this PR. +- **Bucket region** should match `region` or `aws s3 cp` redirects (slower); the bucket + distribution must pre-exist. +- **README merge order** — `cd-github-release` (#24) and `cd-wp-org` also add a section before `## License`; whichever merges later may need a trivial conflict resolution. +- **Action pins:** `actions/download-artifact@…v4.3.0`, `aws-actions/configure-aws-credentials@99214aa… # v6.1.3`. + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.github/workflows/cd-s3.yml b/.github/workflows/cd-s3.yml new file mode 100644 index 0000000..2405581 --- /dev/null +++ b/.github/workflows/cd-s3.yml @@ -0,0 +1,105 @@ +name: CD / S3 Deploy + +on: + workflow_call: + inputs: + tag: + description: "Release tag, e.g. v1.2.3. Used as the versioned object key (.zip)." + type: string + required: true + artifact-name: + description: "Name of the build artifact to download. Must match the name used by the producing job (e.g. ci-build.yml's artifact-name)." + type: string + required: true + bucket: + description: "Target S3 bucket name." + type: string + required: true + prefix: + description: "Optional S3 key prefix, e.g. 'plugins/myplugin/'. Include the trailing slash." + type: string + default: "" + cloudfront-distribution-id: + description: "If set, invalidate /* on this CloudFront distribution after upload." + type: string + default: "" + region: + description: "AWS region of the bucket. Mismatched regions make 'aws s3 cp' redirect (slower)." + type: string + default: "us-east-1" + secrets: + AWS_ACCESS_KEY_ID: + description: "AWS access key id with s3:PutObject on the prefix (and cloudfront:CreateInvalidation if a distribution id is set)." + required: true + AWS_SECRET_ACCESS_KEY: + description: "AWS secret access key for the above key id." + required: true + +permissions: + contents: read + +jobs: + deploy: + name: Upload to S3 + runs-on: ubuntu-latest + steps: + - name: Download build artifact + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: ${{ inputs.artifact-name }} + path: artifact + + - name: Configure AWS credentials + uses: aws-actions/configure-aws-credentials@99214aa6889fcddfa57764031d71add364327e59 # v6.1.3 + with: + aws-region: ${{ inputs.region }} + aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} + aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + + - name: Upload to S3 + shell: bash + env: + TAG: ${{ inputs.tag }} + BUCKET: ${{ inputs.bucket }} + PREFIX: ${{ inputs.prefix }} + run: | + set -euo pipefail + if [[ "$BUCKET" == */* ]]; then + echo "::error::bucket must be a bucket name only (no '/'); put any path in 'prefix' (got '$BUCKET')" + exit 1 + fi + if [[ -n "$PREFIX" ]]; then + if [[ "$PREFIX" == /* ]]; then + echo "::error::prefix must not start with '/' (got '$PREFIX')" + exit 1 + fi + if [[ "$PREFIX" != */ ]]; then + echo "::error::prefix must end with '/' (got '$PREFIX')" + exit 1 + fi + fi + # Search recursively: download-artifact preserves the producer's + # directory structure, so the zip may sit under a subdirectory. + mapfile -d '' zips < <(find artifact -type f -name '*.zip' -print0) + if [ ${#zips[@]} -eq 0 ]; then + echo "::error::No .zip file found in the downloaded artifact" + exit 1 + fi + if [ ${#zips[@]} -gt 1 ]; then + echo "::error::Multiple .zip files found in the downloaded artifact; expected exactly one." + printf ' - %s\n' "${zips[@]}" + exit 1 + fi + src="${zips[0]}" + aws s3 cp "$src" "s3://${BUCKET}/${PREFIX}${TAG}.zip" + aws s3 cp "$src" "s3://${BUCKET}/${PREFIX}latest.zip" + + - name: Invalidate CloudFront + if: ${{ inputs.cloudfront-distribution-id != '' }} + shell: bash + env: + DISTRIBUTION_ID: ${{ inputs.cloudfront-distribution-id }} + PREFIX: ${{ inputs.prefix }} + run: | + set -euo pipefail + aws cloudfront create-invalidation --distribution-id "$DISTRIBUTION_ID" --paths "/${PREFIX}*" diff --git a/CHANGELOG.md b/CHANGELOG.md index 96389f3..738d53d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,4 +16,5 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `cd-split-composer-packages.yml`: reusable "monorepo split" workflow (Symfony pattern) that mirrors each Composer-package subtree to its own standalone repo so Packagist can serve it. A `build-matrix` job parses `splitsh.json` (`organization`, `subtrees` map, `defaults.branch`/`user_name`/`user_email`) with jq — accepting both the shorthand string form and the object/`prefixes` form — and a matrixed `split` job runs `danharrin/monorepo-split-github-action` (pinned to `14e42e2`, v2.4.5) per subtree with `fail-fast: false`. `tag` falls back to the caller's `github.ref_name` when empty; missing or empty config fails loudly. Inputs: `tag`, `config-file`. Secret: `split-token` (PAT/App token with `contents: write` on every mirror repo). - `ci-test-build-artifact.yml`: reusable workflow that boots the packaged build artifact in a real WordPress to prove it installs, not just that the build compiled. Downloads the named artifact (via `actions/download-artifact` pinned to `d3f86a1`, v4.3.0), writes a `.wp-env.override.json` to pin `phpVersion`/`core` and mount only the downloaded artifact (clearing `plugins`/`themes` from the consumer config so the dev source tree never collides with the packaged output), boots `@wordpress/env` with `npx --yes @wordpress/env start --update`, activates the plugin or theme (selected from `install-path`), then runs `wp doctor check --all --format=json` and fails only on `error`-severity checks (warnings allowed). The artifact must be a complete installable plugin/theme directory, so point `ci-build.yml`'s `artifact-path` at a packaged dist directory rather than bare `build/`. An optional `smoke-script` runs inside the container after activation, and `wp-env stop` runs in an `if: always()` step (with its own timeout) so no container leaks into the next job. Production-oriented doctor checks that a dev wp-env always trips (e.g. `constant-wp-debug-falsy`, since wp-env enables `WP_DEBUG`) are excluded from the gate via the `doctor-ignore-checks` input. Inputs: `artifact-name`, `slug`, `node-version`, `php-version`, `wp-version`, `install-path`, `smoke-script`, `doctor-ignore-checks`. - `cd-github-release.yml`: reusable workflow that publishes a GitHub Release on a `v*.*.*` tag push. Downloads the named build artifact, extracts the release body from the matching `CHANGELOG.md` section (tolerant heading match — `## v1.2.3` or `## [1.2.3]` with an optional trailing date; `## Unreleased` is never matched and a missing/empty section fails the workflow rather than publishing empty notes), then creates the Release via the `gh` CLI (no third-party action) with `--verify-tag` so a non-existent tag errors instead of silently creating one. Attaches the artifact files and honours `draft` / `prerelease`. Requires the caller to grant `contents: write`; the artifact must be produced in the same run. Inputs: `tag`, `artifact-name`, `changelog-path`, `draft`, `prerelease`. +- `cd-s3.yml`: reusable workflow that distributes a private/customer plugin to an S3 bucket on a release tag. Downloads the named build artifact and uploads its single `.zip` to a versioned key (`s3:///.zip`) plus an always-overwritten `latest.zip` (fails if the artifact contains zero or more than one `.zip`, so a misconfigured `artifact-path` can never deploy the wrong bundle), then optionally invalidates `/*` on a CloudFront distribution when `cloudfront-distribution-id` is set. Uses the official `aws-actions/configure-aws-credentials` (SHA-pinned to v6.1.3) with static access keys and the preinstalled AWS CLI — no third-party action, no checkout. User inputs pass through step `env:` (injection-safe). Inputs: `tag`, `artifact-name`, `bucket`, `prefix`, `cloudfront-distribution-id`, `region`. Required secrets: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (need `s3:PutObject` on the prefix, plus `cloudfront:CreateInvalidation` when invalidating). - `cd-wp-org.yml`: reusable workflow that deploys a plugin to the WordPress.org directory over SVN on a release tag, wrapping `10up/action-wordpress-plugin-deploy` (SHA-pinned to v2.3.0). Downloads the named build artifact, fails fast unless `readme.txt`'s `Stable tag` matches the tag (leading `v` stripped), then deploys the artifact to `trunk/` + `tags//` via the action's `BUILD_DIR` and syncs `assets-path` (default `.wordpress-org`, read from the checked-out repo) to SVN `/assets/`. The action is configured through environment variables (`SLUG`, `VERSION`, `ASSETS_DIR`, `BUILD_DIR`, `SVN_USERNAME`, `SVN_PASSWORD`); `dry-run` runs everything except the SVN commit; deploying a version that already exists fails (WP.org tags are immutable). Inputs: `slug`, `tag`, `artifact-name`, `assets-path`, `dry-run`. Required secrets: `WP_ORG_USERNAME`, `WP_ORG_PASSWORD`. diff --git a/README.md b/README.md index 63029a0..bbb56a0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# shared-workflows +# wp-shared-workflows -Reusable GitHub Actions workflows for rtCamp WordPress projects. Pure YAML — zero JavaScript. Consumed by every rtCamp repo via `uses: rtCamp/shared-workflows/.github/workflows/.yml@v1`. +Reusable GitHub Actions workflows for rtCamp WordPress projects. Pure YAML — zero JavaScript. Consumed by every rtCamp repo via `uses: rtCamp/wp-shared-workflows/.github/workflows/.yml@v1`. ## What's inside @@ -24,7 +24,7 @@ name: CI on: [push, pull_request] jobs: ci: - uses: rtCamp/shared-workflows/.github/workflows/wp-ci.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/wp-ci.yml@v1 with: php-version: "8.3" node-version: "22" @@ -42,7 +42,7 @@ Runs the consumer's production build, with an optional artifact upload for downs ```yaml jobs: build: - uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 with: node-version: "22" ``` @@ -52,7 +52,7 @@ jobs: ```yaml jobs: build: - uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 with: node-version: "22" upload-artifact: true @@ -63,7 +63,7 @@ jobs: ```yaml jobs: build: - uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 with: node-version: "22" install-composer-deps: true @@ -76,7 +76,7 @@ jobs: ```yaml jobs: build: - uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 with: install-node-deps: false install-composer-deps: true @@ -107,7 +107,7 @@ Runs PHPUnit either against a real WordPress environment via [`@wordpress/env`]( ```yaml jobs: test-php: - uses: rtCamp/shared-workflows/.github/workflows/ci-test-php.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-php.yml@v1 with: php-version: "8.3" ``` @@ -117,7 +117,7 @@ jobs: ```yaml jobs: test-php: - uses: rtCamp/shared-workflows/.github/workflows/ci-test-php.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-php.yml@v1 with: php-version: "8.3" use-wp-env: false @@ -143,7 +143,7 @@ name: CI on: [push, pull_request] jobs: test-js: - uses: rtCamp/shared-workflows/.github/workflows/ci-test-js.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-js.yml@v1 with: node-version: "22" ``` @@ -168,7 +168,7 @@ on: jobs: test-a11y: if: contains(github.event.pull_request.labels.*.name, 'Run a11y') - uses: rtCamp/shared-workflows/.github/workflows/ci-test-a11y.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-a11y.yml@v1 with: node-version: "22" ``` @@ -193,7 +193,7 @@ Fails a PR if it touches any file under the configured path prefixes (default: ` ```yaml jobs: artifact-gate: - uses: rtCamp/shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 ``` **Multiple gated paths:** @@ -201,7 +201,7 @@ jobs: ```yaml jobs: artifact-gate: - uses: rtCamp/shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 with: gated-paths: | assets/build/ @@ -214,7 +214,7 @@ jobs: ```yaml jobs: artifact-gate: - uses: rtCamp/shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 with: gated-paths: "assets/build/" working-dir: "packages/admin-ui" @@ -260,7 +260,7 @@ on: tags: ["v*"] jobs: split: - uses: rtCamp/shared-workflows/.github/workflows/cd-split-composer-packages.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/cd-split-composer-packages.yml@v1 with: tag: ${{ github.ref_name }} secrets: @@ -283,7 +283,7 @@ on: default: "v0.0.0-test" jobs: split: - uses: rtCamp/shared-workflows/.github/workflows/cd-split-composer-packages.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/cd-split-composer-packages.yml@v1 with: # Manual run → use the dispatch input; tag push → the pushed tag. tag: ${{ github.event.inputs.test_tag || github.ref_name }} @@ -310,14 +310,14 @@ A green `ci-build.yml` run only proves the build did not crash — not that the ```yaml jobs: build: - uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 with: upload-artifact: true artifact-name: "plugin-dist" artifact-path: "dist/my-plugin/" # a complete installable plugin dir, not bare build/ test-artifact: needs: build - uses: rtCamp/shared-workflows/.github/workflows/ci-test-build-artifact.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-build-artifact.yml@v1 with: artifact-name: "plugin-dist" slug: "my-plugin" @@ -329,7 +329,7 @@ jobs: jobs: test-artifact: needs: build - uses: rtCamp/shared-workflows/.github/workflows/ci-test-build-artifact.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-build-artifact.yml@v1 with: artifact-name: "theme-dist" slug: "my-theme" @@ -364,7 +364,7 @@ on: - "v*.*.*" jobs: build: - uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 with: upload-artifact: true artifact-name: "release" @@ -372,7 +372,7 @@ jobs: needs: build permissions: contents: write - uses: rtCamp/shared-workflows/.github/workflows/cd-github-release.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/cd-github-release.yml@v1 with: tag: ${{ github.ref_name }} artifact-name: "release" @@ -446,6 +446,81 @@ Notes: - **Immutable tags** — WordPress.org SVN tags are release snapshots; the deploy action errors (non-zero) if `tags/` already exists, so re-deploying the same version fails rather than overwriting it. - **`dry-run`** still checks out the live WP.org SVN repo for the slug; it only skips the commit, so exercising it end to end needs a real published slug. +### `cd-s3.yml`: S3 deploy + +Distributes a private / customer plugin by uploading the build artifact to an S3 bucket on a release tag — a versioned object (`.zip`) plus a rolling `latest.zip` that always overwrites — and optionally invalidates a CloudFront distribution so the new `latest.zip` is served immediately. Uses the official [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials) (SHA-pinned) and the preinstalled AWS CLI. + +```yaml +# .github/workflows/deploy-s3.yml in the consumer +name: Deploy to S3 +on: + push: + tags: ["v*.*.*"] +permissions: + contents: read +jobs: + build: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 + with: + upload-artifact: true + artifact-name: s3-build + # build-command / artifact-path must produce exactly one .zip in the artifact. + deploy: + needs: build + uses: rtCamp/wp-shared-workflows/.github/workflows/cd-s3.yml@v1 + with: + tag: ${{ github.ref_name }} + artifact-name: s3-build + bucket: my-customer-bucket + prefix: "plugins/my-plugin/" + # cloudfront-distribution-id: "E123ABC" # optional + secrets: + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} +``` + +| Input | Type | Default | Description | +| ---------------------------- | ------ | ------------- | ------------------------------------------------------------------------ | +| `tag` | string | _(required)_ | **Required.** Release tag; the versioned object is keyed `.zip`. | +| `artifact-name` | string | _(required)_ | **Required.** Build artifact to download (must match the producer). | +| `bucket` | string | _(required)_ | **Required.** Target S3 bucket name. | +| `prefix` | string | `""` | Optional S3 key prefix, e.g. `plugins/myplugin/` (include the trailing slash). | +| `cloudfront-distribution-id` | string | `""` | If set, invalidate `/*` on this distribution after upload. | +| `region` | string | `"us-east-1"` | AWS region of the bucket. | + +| Secret | Required | Description | +| ----------------------- | -------- | -------------------------------- | +| `AWS_ACCESS_KEY_ID` | yes | AWS access key id (see IAM below). | +| `AWS_SECRET_ACCESS_KEY` | yes | AWS secret access key. | + +**Required IAM permissions.** The credentials need write access to the prefix, plus +`cloudfront:CreateInvalidation` only if you pass a distribution id: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "s3:PutObject", + "Resource": "arn:aws:s3:::my-customer-bucket/plugins/my-plugin/*" + }, + { + "Effect": "Allow", + "Action": "cloudfront:CreateInvalidation", + "Resource": "arn:aws:cloudfront:::distribution/E123ABC" + } + ] +} +``` + +Notes: + +- **Same-run artifact** — `actions/download-artifact` only sees the current run's artifacts, so build and deploy must run in the same workflow (`deploy` `needs: build`), and the artifact must contain exactly one `.zip`. +- **Bucket region** should match `region`; otherwise `aws s3 cp` issues a redirect and runs slower. +- **Pre-existing infra** — the bucket and (if used) the CloudFront distribution must already exist; this workflow does not create or configure them. +- **`latest.zip` is CloudFront-cached** — the invalidation step is what makes "always-latest" actually serve the new build. + ## License GPL-2.0-or-later From bf3d23aed558c967977a63ab96c9b155e5e0172e Mon Sep 17 00:00:00 2001 From: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> Date: Wed, 17 Jun 2026 18:52:55 +0530 Subject: [PATCH 31/43] [v1.0.0] Add detect-changes + lint-css/js/php reusable workflows (#2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(ci): add lint-css, lint-js, lint-php reusable workflows Individual CI lint workflows callable via workflow_call: - ci-lint-css.yml — Stylelint via configurable command - ci-lint-js.yml — ESLint + optional package.json validation - ci-lint-php.yml — PHPCS (cs2pr-annotated) + optional PHPStan * fix(ci): pin actions to SHAs, add permissions, align with spec - Pin actions/checkout, actions/setup-node, actions/cache to commit SHAs (supply-chain hygiene per CLAUDE.md) - Add permissions: contents: read to all three lint workflows - Drop redundant composer tool from setup-php (pre-installed on runner) - Add --optimize-autoloader and --no-scripts to composer install - Reformat phpcs-command default as multi-line for readability - Reorder lint-js steps: validate package.json before ESLint - Tighten input descriptions across all three workflows * feat(ci): add monorepo support and tuning knobs to lint workflows - Add working-dir input on all three lint workflows for monorepo subdirs - Add phpstan-level, composer-flags, validate-composer inputs to ci-lint-php - Reshape phpcs-command to a bare binary path; cs2pr pipeline + soft-exit live in the step - Switch phpstan-command default to vendor/bin/phpstan analyse so phpstan-level appends cleanly - Collapse JS validation to a single validate-package-json toggle - Trim input descriptions to one line each * feat(ci): add changed-files input to lint workflows PHPCS, ESLint, and Stylelint can now lint only the changed files passed from detect-changes. Newline-separated file list via changed-files input; empty = lint the whole project. PHPCS uses --file-list for robustness against ARG_MAX; ESLint and Stylelint use xargs. PHPStan always runs whole-project — it analyses cross-file dependencies. * feat: add reusable detect-changes workflow and update documentation * fix: address PR review feedback across CI workflows * fix: update workflow files to improve linting commands and documentation * fix: update workflow references to use wp-shared-workflows path * fix(ci): add optional wp-tooling-token secret for private-repo clone * docs(ci): add wp-tooling-token secret to ci-detect-changes example * fix: update actions/checkout and actions/setup-node versions across workflows * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Anurag Vasanwala <75766877+AnuragVasanwala@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .claude/issues/1-ci-lint-workflows.md | 168 ++++++++++++++++++++ .claude/issues/19-ci-build-artifact-gate.md | 2 +- .claude/issues/3-ci-test-js.md | 2 +- .claude/issues/5-ci-test-php.md | 2 +- .claude/issues/7-ci-build.md | 2 +- .claude/issues/9-ci-test-a11y.md | 2 +- .github/workflows/ci-detect-changes.yml | 121 ++++++++++++++ .github/workflows/ci-lint-css.yml | 55 +++++++ .github/workflows/ci-lint-js.yml | 63 ++++++++ .github/workflows/ci-lint-php.yml | 107 +++++++++++++ CHANGELOG.md | 4 + CLAUDE.md | 6 +- README.md | 112 ++++++++++++- 13 files changed, 636 insertions(+), 10 deletions(-) create mode 100644 .claude/issues/1-ci-lint-workflows.md create mode 100644 .github/workflows/ci-detect-changes.yml create mode 100644 .github/workflows/ci-lint-css.yml create mode 100644 .github/workflows/ci-lint-js.yml create mode 100644 .github/workflows/ci-lint-php.yml diff --git a/.claude/issues/1-ci-lint-workflows.md b/.claude/issues/1-ci-lint-workflows.md new file mode 100644 index 0000000..7c5d5f4 --- /dev/null +++ b/.claude/issues/1-ci-lint-workflows.md @@ -0,0 +1,168 @@ +# Issue #1 — Add detect-changes + lint-css/js/php reusable workflows + +**Status:** in-review +**Branch:** `v1.0.0/task/ci-lint-workflows` +**PR:** #2 +**Assignee:** @Adi-ty + +--- + +## Summary + +Every rtCamp WordPress project duplicates the same lint pipeline (the copy-pasted `Test and Measure` workflow, with drift). This issue centralises the four pre-CI lint stages — changed-file detection plus CSS / JS / PHP linting — into individually callable reusable workflows so every consumer adopts one canonical implementation via `uses: rtCamp/wp-shared-workflows/.github/workflows/ci-*.yml@v1`. + +--- + +## Decisions made + +- [2026-05-29] `ci-detect-changes.yml` wraps the `wp-tooling detect-changes` CLI rather than re-implementing the legacy git-diff bash dance. Base-ref resolution (PR via `GITHUB_BASE_REF`, push via the event `before` SHA / `HEAD~1`), bucket regexes, and the ignore default all live in the CLI — the workflow only passes flags and promotes outputs. +- [2026-05-29] wp-tooling is installed by cloning `https://github.com/rtCamp/wp-tooling.git` at `release/v1.0.0` and running `npm install --install-links --prefix "$RUNNER_TEMP/wp-tooling"` on the monorepo subpath `node-packages/wp-tooling`. npm can't install a git subdirectory, and the repo root is a private, bin-less workspace, so a plain `npm i -g ` exposes no CLI. The workflow then adds `$RUNNER_TEMP/wp-tooling/node_modules/.bin` to `PATH` via `GITHUB_PATH` (no global install). Interim stopgap until `@rtcamp/wp-tooling` is published (GitHub Packages, `access: restricted`); because the repo may be private the clone needs a token, so detect-changes won't run green in a consumer until publish — verified end-to-end via `act`. +- [2026-05-29] Detection runs with `--output github --include-files`, so the workflow exposes both per-bucket counts (for gating) and per-bucket file lists (`css-files`, `js-files`, `php-files`, `gha-files`). The `--include-files` support is wp-tooling#7, now on `release/v1.0.0`. +- [2026-05-29] The three lint workflows each accept a `changed-files` input: non-empty lints only those paths, empty runs the whole-project `lint-command`. This is what makes the detector's `*-files` outputs useful — addresses @AnuragVasanwala's review asks (lint only updated files for CSS/JS/PHP; include exact file paths). For PHP, `changed-files` scopes PHPCS only; PHPStan always runs whole-project (cross-file analysis). +- [2026-05-29] `ignore-paths` / `base-ref` flags are only passed to the CLI when non-empty. An empty `--ignore` *disables* ignoring in the CLI, so omitting the flag (the default) correctly falls through to the CLI's built-in ignore set. +- [2026-05-29] Orchestrator wiring (`wp-ci.yml`, issue #13) is out of scope — `ci-detect-changes.yml` runs unconditionally and only exposes outputs; the orchestrator does the count-based gating and feeds `*-files` into the lint jobs. + +--- + +## Files changed so far + +- `.github/workflows/ci-detect-changes.yml` — new +- `.github/workflows/ci-lint-css.yml` — new (already on branch) +- `.github/workflows/ci-lint-js.yml` — new (already on branch) +- `.github/workflows/ci-lint-php.yml` — new (already on branch) +- `README.md` — edited (added detect-changes + lint-css/js/php sections) +- `CHANGELOG.md` — edited (four bullets under Unreleased → Added) +- `.claude/issues/1-ci-lint-workflows.md` — new (this file) + +--- + +## Verification run + +```bash +❯ pipx run yamllint . +❯ act workflow_call -W .github/workflows/ci-detect-changes.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Set up job +*DRYRUN* [CI / Detect Changes/Detect changes] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CI / Detect Changes/Detect changes] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CI / Detect Changes/Detect changes] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Detect Changes/Detect changes] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Set up job +*DRYRUN* [CI / Detect Changes/Detect changes] ☁ git clone 'https://github.com/actions/setup-node' # ref=49933ea5288caeca8642d1e84afbd3f7d6820020 +*DRYRUN* [CI / Detect Changes/Detect changes] Non-terminating error while running 'git clone': some refs were not updated +*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Main Checkout repository +*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Main Checkout repository [7.201541ms] +*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Main Set up Node.js +*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Main Set up Node.js [9.009583ms] +*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Main Install wp-tooling +*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Main Install wp-tooling [17.675625ms] +*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Main Detect changed files +*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Main Detect changed files [17.995125ms] +*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Post Set up Node.js +*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Post Set up Node.js [6.890833ms] +*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Complete job +*DRYRUN* [CI / Detect Changes/Detect changes] Cleaning up container for job Detect changes +*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Complete job +*DRYRUN* [CI / Detect Changes/Detect changes] 🏁 Job succeeded +❯ act workflow_call -W .github/workflows/ci-lint-js.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Set up job +*DRYRUN* [CI / Lint JS/ESLint] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CI / Lint JS/ESLint] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CI / Lint JS/ESLint] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Lint JS/ESLint] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Set up job +*DRYRUN* [CI / Lint JS/ESLint] ☁ git clone 'https://github.com/actions/setup-node' # ref=49933ea5288caeca8642d1e84afbd3f7d6820020 +*DRYRUN* [CI / Lint JS/ESLint] Non-terminating error while running 'git clone': some refs were not updated +*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Main Checkout repository +*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Main Checkout repository [6.915708ms] +*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Main Set up Node.js +*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Main Set up Node.js [6.775ms] +*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Main Install npm dependencies +*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Main Install npm dependencies [20.010333ms] +*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Main Run ESLint +*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Main Run ESLint [15.109542ms] +*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Post Set up Node.js +*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Post Set up Node.js [4.765958ms] +*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Complete job +*DRYRUN* [CI / Lint JS/ESLint] Cleaning up container for job ESLint +*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Complete job +*DRYRUN* [CI / Lint JS/ESLint] 🏁 Job succeeded +❯ act workflow_call -W .github/workflows/ci-lint-php.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Set up job +*DRYRUN* [CI / Lint PHP/Lint PHP] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CI / Lint PHP/Lint PHP] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CI / Lint PHP/Lint PHP] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Lint PHP/Lint PHP] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Set up job +*DRYRUN* [CI / Lint PHP/Lint PHP] ☁ git clone 'https://github.com/shivammathur/setup-php' # ref=accd6127cb78bee3e8082180cb391013d204ef9f +*DRYRUN* [CI / Lint PHP/Lint PHP] Non-terminating error while running 'git clone': some refs were not updated +*DRYRUN* [CI / Lint PHP/Lint PHP] ☁ git clone 'https://github.com/actions/cache' # ref=0057852bfaa89a56745cba8c7296529d2fc39830 +*DRYRUN* [CI / Lint PHP/Lint PHP] Non-terminating error while running 'git clone': some refs were not updated +*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Checkout repository +*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Checkout repository [6.769458ms] +*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Set up PHP +*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Set up PHP [6.604291ms] +*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Resolve Composer cache directory +*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Resolve Composer cache directory [14.866541ms] +*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Cache Composer dependencies +*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Cache Composer dependencies [6.350875ms] +*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Install Composer dependencies +*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Install Composer dependencies [16.199916ms] +*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Run PHPCS +*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Run PHPCS [17.39875ms] +*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Post Cache Composer dependencies +*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Post Cache Composer dependencies [4.434375ms] +*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Complete job +*DRYRUN* [CI / Lint PHP/Lint PHP] Cleaning up container for job Lint PHP +*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Complete job +*DRYRUN* [CI / Lint PHP/Lint PHP] 🏁 Job succeeded +❯ act workflow_call -W .github/workflows/ci-lint-css.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Set up job +*DRYRUN* [CI / Lint CSS/Stylelint] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CI / Lint CSS/Stylelint] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CI / Lint CSS/Stylelint] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Lint CSS/Stylelint] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Set up job +*DRYRUN* [CI / Lint CSS/Stylelint] ☁ git clone 'https://github.com/actions/setup-node' # ref=49933ea5288caeca8642d1e84afbd3f7d6820020 +*DRYRUN* [CI / Lint CSS/Stylelint] Non-terminating error while running 'git clone': some refs were not updated +*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Main Checkout repository +*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Main Checkout repository [5.968583ms] +*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Main Set up Node.js +*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Main Set up Node.js [6.16925ms] +*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Main Install npm dependencies +*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Main Install npm dependencies [20.346042ms] +*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Main Run Stylelint +*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Main Run Stylelint [16.111666ms] +*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Post Set up Node.js +*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Post Set up Node.js [4.70925ms] +*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Complete job +*DRYRUN* [CI / Lint CSS/Stylelint] Cleaning up container for job Stylelint +*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Complete job +*DRYRUN* [CI / Lint CSS/Stylelint] 🏁 Job succeeded +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- **Private-repo install auth (deferred, not a blocker):** `git+https://github.com/rtCamp/wp-tooling.git` needs wp-tooling to be public (or a token) to clone in a consumer's CI — the caller's `GITHUB_TOKEN` is not scoped to wp-tooling. Same limitation `version-monitor.yml` already carries; resolves when both repos go public / wp-tooling is published. Carries a `# TODO(wp-tooling publish)` comment. +- **Multi-line `*-files` outputs** are subject to GitHub's `$GITHUB_OUTPUT` size limits on very large PRs — acceptable for normal PRs. +- **`act` cannot fully exercise** the GitHub-event base-ref path or the private `git+https` install; the real proof is a consumer repo referencing `@` that wires `detect` → lint workflows. Note this as deferred end-to-end verification. +- Detection semantics (two-dot `git diff base HEAD`, bucket regexes, ignore defaults) are the CLI's contract, not overridden here. + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/19-ci-build-artifact-gate.md b/.claude/issues/19-ci-build-artifact-gate.md index e5aa32e..fbf7ddd 100644 --- a/.claude/issues/19-ci-build-artifact-gate.md +++ b/.claude/issues/19-ci-build-artifact-gate.md @@ -12,7 +12,7 @@ Every rtCamp WordPress project that produces build output (compiled CSS/JS, Composer `vendor/`, etc.) needs a gate that fails any PR which commits those files. The build is meant to be produced by CI on merge, not committed by hand. Without a gate, stale build trees creep into the repo and silently override what CI produces. -This task lifts the inline `rtcamp-standard.yml` workflow from `rtCamp/theme-elementary` (issue [#642](https://github.com/rtCamp/theme-elementary/issues/642)) into shared-workflows as `ci-build-artifact-gate.yml`, so every rtCamp repo can consume it via `uses:` instead of copy-pasting. Default gated path is `assets/build/`. Consumers can pass a newline-separated list of prefixes and an optional `working-dir` for monorepos. +This task lifts the inline `rtcamp-standard.yml` workflow from `rtCamp/theme-elementary` (issue [#642](https://github.com/rtCamp/theme-elementary/issues/642)) into wp-shared-workflows as `ci-build-artifact-gate.yml`, so every rtCamp repo can consume it via `uses:` instead of copy-pasting. Default gated path is `assets/build/`. Consumers can pass a newline-separated list of prefixes and an optional `working-dir` for monorepos. --- diff --git a/.claude/issues/3-ci-test-js.md b/.claude/issues/3-ci-test-js.md index 0252cd9..30e4228 100644 --- a/.claude/issues/3-ci-test-js.md +++ b/.claude/issues/3-ci-test-js.md @@ -9,7 +9,7 @@ ## Summary -Every rtCamp WordPress project that ships JS runs the same Jest pipeline — `Test and Measure`'s `unit-tests-js` job is copy-pasted across plugins, themes, and Composer packages with minor drift. Centralising this as a reusable workflow lets every consumer adopt one canonical implementation via `uses: rtCamp/shared-workflows/.github/workflows/ci-test-js.yml@v1`, and adds Jest cache support that the legacy job didn't have. +Every rtCamp WordPress project that ships JS runs the same Jest pipeline — `Test and Measure`'s `unit-tests-js` job is copy-pasted across plugins, themes, and Composer packages with minor drift. Centralising this as a reusable workflow lets every consumer adopt one canonical implementation via `uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-js.yml@v1`, and adds Jest cache support that the legacy job didn't have. --- diff --git a/.claude/issues/5-ci-test-php.md b/.claude/issues/5-ci-test-php.md index 924dbc8..750878f 100644 --- a/.claude/issues/5-ci-test-php.md +++ b/.claude/issues/5-ci-test-php.md @@ -9,7 +9,7 @@ ## Summary -Every rtCamp WordPress project that ships PHP currently copy-pastes the same `unit-test-php` job from the legacy `Test and Measure` workflow. Some consumers need a full WordPress integration environment via `@wordpress/env`; Composer-only packages and libraries do not. This task adds `ci-test-php.yml` — a single reusable workflow with a `use-wp-env` toggle that covers both modes so every consumer can adopt one canonical implementation via `uses: rtCamp/shared-workflows/.github/workflows/ci-test-php.yml@v1`. +Every rtCamp WordPress project that ships PHP currently copy-pastes the same `unit-test-php` job from the legacy `Test and Measure` workflow. Some consumers need a full WordPress integration environment via `@wordpress/env`; Composer-only packages and libraries do not. This task adds `ci-test-php.yml` — a single reusable workflow with a `use-wp-env` toggle that covers both modes so every consumer can adopt one canonical implementation via `uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-php.yml@v1`. --- diff --git a/.claude/issues/7-ci-build.md b/.claude/issues/7-ci-build.md index 8d89ac7..088c871 100644 --- a/.claude/issues/7-ci-build.md +++ b/.claude/issues/7-ci-build.md @@ -9,7 +9,7 @@ ## Summary -Every rtCamp WordPress project that ships JS or CSS runs the same production build — `Test and Measure`'s `build-prod` job is copy-pasted across plugins, themes, and packages. Most callers only need to verify the build exits 0; CD callers also need the built files handed to a downstream deploy job. This task adds `ci-build.yml` — a single reusable workflow with an `upload-artifact` toggle (default `false`) that covers both shapes so every consumer can adopt one canonical implementation via `uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1`. +Every rtCamp WordPress project that ships JS or CSS runs the same production build — `Test and Measure`'s `build-prod` job is copy-pasted across plugins, themes, and packages. Most callers only need to verify the build exits 0; CD callers also need the built files handed to a downstream deploy job. This task adds `ci-build.yml` — a single reusable workflow with an `upload-artifact` toggle (default `false`) that covers both shapes so every consumer can adopt one canonical implementation via `uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1`. --- diff --git a/.claude/issues/9-ci-test-a11y.md b/.claude/issues/9-ci-test-a11y.md index a35d9d4..9a81594 100644 --- a/.claude/issues/9-ci-test-a11y.md +++ b/.claude/issues/9-ci-test-a11y.md @@ -9,7 +9,7 @@ ## Summary -Every rtCamp WordPress project that ships UI runs the same accessibility regression check — pa11y-ci against the built site served by `@wordpress/env`. The wiring (build → wp-env start → pa11y → wp-env stop) is tedious to maintain and copy-pasted across consumers; some projects skip a11y entirely as a result. This task adds `ci-test-a11y.yml` — a single reusable workflow that captures that sequence with `if: always()` cleanup, so every consumer can adopt one canonical implementation via `uses: rtCamp/shared-workflows/.github/workflows/ci-test-a11y.yml@v1`. The reusable workflow stays trigger-agnostic; consumers wire the `Run a11y` label gate at the caller level per CLAUDE.md. +Every rtCamp WordPress project that ships UI runs the same accessibility regression check — pa11y-ci against the built site served by `@wordpress/env`. The wiring (build → wp-env start → pa11y → wp-env stop) is tedious to maintain and copy-pasted across consumers; some projects skip a11y entirely as a result. This task adds `ci-test-a11y.yml` — a single reusable workflow that captures that sequence with `if: always()` cleanup, so every consumer can adopt one canonical implementation via `uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-a11y.yml@v1`. The reusable workflow stays trigger-agnostic; consumers wire the `Run a11y` label gate at the caller level per CLAUDE.md. --- diff --git a/.github/workflows/ci-detect-changes.yml b/.github/workflows/ci-detect-changes.yml new file mode 100644 index 0000000..381c525 --- /dev/null +++ b/.github/workflows/ci-detect-changes.yml @@ -0,0 +1,121 @@ +name: CI / Detect Changes + +on: + workflow_call: + inputs: + node-version: + description: "Node.js version used to run the wp-tooling CLI." + type: string + default: "22" + ignore-paths: + description: "Regex of paths to exclude from the counts and file lists. Empty uses the CLI's built-in ignore set." + type: string + default: "" + base-ref: + description: "Explicit git ref to diff HEAD against. Empty lets the CLI resolve it from the PR base or push event." + type: string + default: "" + secrets: + wp-tooling-token: + description: "Token with read access to the private rtCamp/wp-tooling repo, used to clone the interim CLI. Required while that repo is private; omit once @rtcamp/wp-tooling is published or public." + required: false + outputs: + total-count: + description: "Number of changed files after the ignore filter." + value: ${{ jobs.detect.outputs.total-count }} + ignored-count: + description: "Number of changed files dropped by the ignore filter." + value: ${{ jobs.detect.outputs.ignored-count }} + css-count: + description: "Number of changed CSS/SCSS files." + value: ${{ jobs.detect.outputs.css-count }} + js-count: + description: "Number of changed JS files." + value: ${{ jobs.detect.outputs.js-count }} + php-count: + description: "Number of changed PHP files." + value: ${{ jobs.detect.outputs.php-count }} + gha-count: + description: "Number of changed GitHub Actions workflow files." + value: ${{ jobs.detect.outputs.gha-count }} + css-files: + description: "Newline-separated changed CSS/SCSS files. Pass straight into ci-lint-css.yml's changed-files." + value: ${{ jobs.detect.outputs.css-files }} + js-files: + description: "Newline-separated changed JS files. Pass straight into ci-lint-js.yml's changed-files." + value: ${{ jobs.detect.outputs.js-files }} + php-files: + description: "Newline-separated changed PHP files. Pass straight into ci-lint-php.yml's changed-files." + value: ${{ jobs.detect.outputs.php-files }} + gha-files: + description: "Newline-separated changed GitHub Actions workflow files." + value: ${{ jobs.detect.outputs.gha-files }} + +permissions: + contents: read + +jobs: + detect: + name: Detect changes + runs-on: ubuntu-latest + outputs: + total-count: ${{ steps.detect.outputs.total-count }} + ignored-count: ${{ steps.detect.outputs.ignored-count }} + css-count: ${{ steps.detect.outputs.css-count }} + js-count: ${{ steps.detect.outputs.js-count }} + php-count: ${{ steps.detect.outputs.php-count }} + gha-count: ${{ steps.detect.outputs.gha-count }} + css-files: ${{ steps.detect.outputs.css-files }} + js-files: ${{ steps.detect.outputs.js-files }} + php-files: ${{ steps.detect.outputs.php-files }} + gha-files: ${{ steps.detect.outputs.gha-files }} + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + fetch-depth: 2 + + - name: Set up Node.js + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 + with: + node-version: ${{ inputs.node-version }} + + - name: Install wp-tooling + # Interim install until @rtcamp/wp-tooling is published. The CLI lives in the + # rtCamp/wp-tooling monorepo under node-packages/wp-tooling (npm can't install a git + # subdirectory), so clone the branch and install the subpath into a job-local prefix + # on PATH — no global. --install-links copies (vs symlinks) so the temp clone can be + # removed; the repo is private, so authenticate with wp-tooling-token when provided. + # TODO(wp-tooling publish): replace with `npm install --prefix … @rtcamp/wp-tooling`. + shell: bash + env: + WP_TOOLING_TOKEN: ${{ secrets.wp-tooling-token }} + run: | + set -euo pipefail + src="$(mktemp -d)" + trap 'rm -rf "$src"' EXIT + repo="https://github.com/rtCamp/wp-tooling.git" + if [ -n "${WP_TOOLING_TOKEN:-}" ]; then + repo="https://x-access-token:${WP_TOOLING_TOKEN}@github.com/rtCamp/wp-tooling.git" + fi + git clone --depth 1 --branch release/v1.0.0 "$repo" "$src" + prefix="$RUNNER_TEMP/wp-tooling" + npm install --install-links --prefix "$prefix" "$src/node-packages/wp-tooling" + echo "$prefix/node_modules/.bin" >> "$GITHUB_PATH" + + - name: Detect changed files + id: detect + shell: bash + env: + IGNORE_PATHS: ${{ inputs.ignore-paths }} + BASE_REF: ${{ inputs.base-ref }} + run: | + set -euo pipefail + args=(--output github --include-files) + if [ -n "$IGNORE_PATHS" ]; then + args+=(--ignore "$IGNORE_PATHS") + fi + if [ -n "$BASE_REF" ]; then + args+=(--base "$BASE_REF") + fi + wp-tooling detect-changes "${args[@]}" diff --git a/.github/workflows/ci-lint-css.yml b/.github/workflows/ci-lint-css.yml new file mode 100644 index 0000000..0a84c6c --- /dev/null +++ b/.github/workflows/ci-lint-css.yml @@ -0,0 +1,55 @@ +name: CI / Lint CSS + +on: + workflow_call: + inputs: + node-version: + description: "Node.js version." + type: string + default: "22" + lint-command: + description: "Shell command that runs Stylelint over the whole project. Used when changed-files is empty." + type: string + default: "npm run lint:css" + changed-files: + description: "Newline-separated list of CSS files to lint. Empty = run lint-command over the whole project." + type: string + default: "" + working-dir: + description: "Working directory for monorepos." + type: string + default: "." + +permissions: + contents: read + +jobs: + lint-css: + name: Stylelint + runs-on: ubuntu-latest + defaults: + run: + working-directory: ${{ inputs.working-dir }} + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Set up Node.js + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 + with: + node-version: ${{ inputs.node-version }} + cache: npm + + - name: Install npm dependencies + run: npm ci + + - name: Run Stylelint + shell: bash + env: + CHANGED_FILES: ${{ inputs.changed-files }} + run: | + if [ -n "$CHANGED_FILES" ]; then + printf '%s\n' "$CHANGED_FILES" | xargs -d '\n' --no-run-if-empty npx --no-install stylelint -- + else + ${{ inputs.lint-command }} + fi diff --git a/.github/workflows/ci-lint-js.yml b/.github/workflows/ci-lint-js.yml new file mode 100644 index 0000000..6c14539 --- /dev/null +++ b/.github/workflows/ci-lint-js.yml @@ -0,0 +1,63 @@ +name: CI / Lint JS + +on: + workflow_call: + inputs: + node-version: + description: "Node.js version." + type: string + default: "22" + lint-command: + description: "Shell command that runs ESLint over the whole project. Used when changed-files is empty." + type: string + default: "npm run lint:js" + changed-files: + description: "Newline-separated list of JS files to lint. Empty = run lint-command over the whole project." + type: string + default: "" + validate-package-json: + description: "Run `npm run lint:package-json` before ESLint." + type: boolean + default: true + working-dir: + description: "Working directory for monorepos." + type: string + default: "." + +permissions: + contents: read + +jobs: + lint-js: + name: ESLint + runs-on: ubuntu-latest + defaults: + run: + working-directory: ${{ inputs.working-dir }} + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Set up Node.js + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 + with: + node-version: ${{ inputs.node-version }} + cache: npm + + - name: Install npm dependencies + run: npm ci + + - name: Validate package.json + if: ${{ inputs.validate-package-json }} + run: npm run lint:package-json --if-present + + - name: Run ESLint + shell: bash + env: + CHANGED_FILES: ${{ inputs.changed-files }} + run: | + if [ -n "$CHANGED_FILES" ]; then + printf '%s\n' "$CHANGED_FILES" | xargs -d '\n' --no-run-if-empty npx --no-install eslint -- + else + ${{ inputs.lint-command }} + fi diff --git a/.github/workflows/ci-lint-php.yml b/.github/workflows/ci-lint-php.yml new file mode 100644 index 0000000..ced8df7 --- /dev/null +++ b/.github/workflows/ci-lint-php.yml @@ -0,0 +1,107 @@ +name: CI / Lint PHP + +on: + workflow_call: + inputs: + php-version: + description: "PHP version." + type: string + default: "8.3" + enable-phpstan: + description: "Run PHPStan after PHPCS." + type: boolean + default: false + phpcs-command: + description: "PHPCS binary path or custom command." + type: string + default: "vendor/bin/phpcs" + changed-files: + description: "Newline-separated list of PHP files to lint with PHPCS. Empty = lint the whole project. PHPStan always runs whole-project — it analyses cross-file dependencies." + type: string + default: "" + phpstan-command: + description: "Shell command that runs PHPStan." + type: string + default: "vendor/bin/phpstan analyse" + phpstan-level: + description: "Override PHPStan level. Empty uses the level from phpstan.neon.dist." + type: string + default: "" + composer-flags: + description: "Flags passed to `composer install`. Default includes `--no-scripts` for supply-chain hygiene." + type: string + default: "--prefer-dist --optimize-autoloader --no-progress --no-interaction --no-scripts" + validate-composer: + description: "Run `composer validate` before installing. Disable for packages without composer.lock." + type: boolean + default: true + working-dir: + description: "Working directory for monorepos." + type: string + default: "." + +permissions: + contents: read + +jobs: + lint-php: + name: Lint PHP + runs-on: ubuntu-latest + defaults: + run: + working-directory: ${{ inputs.working-dir }} + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Set up PHP + uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # 2.37.0 + with: + php-version: ${{ inputs.php-version }} + tools: composer, cs2pr + coverage: none + + - name: Validate composer.json + if: ${{ inputs.validate-composer }} + run: composer validate --no-check-publish + + - name: Resolve Composer cache directory + id: composer-cache + run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT" + + - name: Cache Composer dependencies + uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0 + with: + path: ${{ steps.composer-cache.outputs.dir }} + key: composer-${{ runner.os }}-php${{ inputs.php-version }}-${{ hashFiles('**/composer.lock') }} + restore-keys: | + composer-${{ runner.os }}-php${{ inputs.php-version }}- + + - name: Install Composer dependencies + run: composer install ${{ inputs.composer-flags }} + + - name: Run PHPCS + shell: bash + env: + CHANGED_FILES: ${{ inputs.changed-files }} + run: | + set -euo pipefail + if [ -n "$CHANGED_FILES" ]; then + tmp_list=$(mktemp) + trap 'rm -f "$tmp_list"' EXIT + printf '%s\n' "$CHANGED_FILES" > "$tmp_list" + ${{ inputs.phpcs-command }} --file-list="$tmp_list" \ + -q --report=checkstyle \ + --runtime-set ignore_warnings_on_exit 1 \ + | cs2pr --graceful-warnings + else + ${{ inputs.phpcs-command }} -q --report=checkstyle \ + --runtime-set ignore_warnings_on_exit 1 \ + | cs2pr --graceful-warnings + fi + + - name: Run PHPStan + if: ${{ inputs.enable-phpstan }} + run: >- + ${{ inputs.phpstan-command }} + ${{ inputs.phpstan-level != '' && format('--level={0}', inputs.phpstan-level) || '' }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 738d53d..ed4e10d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,3 +18,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `cd-github-release.yml`: reusable workflow that publishes a GitHub Release on a `v*.*.*` tag push. Downloads the named build artifact, extracts the release body from the matching `CHANGELOG.md` section (tolerant heading match — `## v1.2.3` or `## [1.2.3]` with an optional trailing date; `## Unreleased` is never matched and a missing/empty section fails the workflow rather than publishing empty notes), then creates the Release via the `gh` CLI (no third-party action) with `--verify-tag` so a non-existent tag errors instead of silently creating one. Attaches the artifact files and honours `draft` / `prerelease`. Requires the caller to grant `contents: write`; the artifact must be produced in the same run. Inputs: `tag`, `artifact-name`, `changelog-path`, `draft`, `prerelease`. - `cd-s3.yml`: reusable workflow that distributes a private/customer plugin to an S3 bucket on a release tag. Downloads the named build artifact and uploads its single `.zip` to a versioned key (`s3:///.zip`) plus an always-overwritten `latest.zip` (fails if the artifact contains zero or more than one `.zip`, so a misconfigured `artifact-path` can never deploy the wrong bundle), then optionally invalidates `/*` on a CloudFront distribution when `cloudfront-distribution-id` is set. Uses the official `aws-actions/configure-aws-credentials` (SHA-pinned to v6.1.3) with static access keys and the preinstalled AWS CLI — no third-party action, no checkout. User inputs pass through step `env:` (injection-safe). Inputs: `tag`, `artifact-name`, `bucket`, `prefix`, `cloudfront-distribution-id`, `region`. Required secrets: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (need `s3:PutObject` on the prefix, plus `cloudfront:CreateInvalidation` when invalidating). - `cd-wp-org.yml`: reusable workflow that deploys a plugin to the WordPress.org directory over SVN on a release tag, wrapping `10up/action-wordpress-plugin-deploy` (SHA-pinned to v2.3.0). Downloads the named build artifact, fails fast unless `readme.txt`'s `Stable tag` matches the tag (leading `v` stripped), then deploys the artifact to `trunk/` + `tags//` via the action's `BUILD_DIR` and syncs `assets-path` (default `.wordpress-org`, read from the checked-out repo) to SVN `/assets/`. The action is configured through environment variables (`SLUG`, `VERSION`, `ASSETS_DIR`, `BUILD_DIR`, `SVN_USERNAME`, `SVN_PASSWORD`); `dry-run` runs everything except the SVN commit; deploying a version that already exists fails (WP.org tags are immutable). Inputs: `slug`, `tag`, `artifact-name`, `assets-path`, `dry-run`. Required secrets: `WP_ORG_USERNAME`, `WP_ORG_PASSWORD`. +- `ci-detect-changes.yml`: reusable pre-run workflow that buckets a PR/push's changed files and exposes per-bucket change counts (`total-count`, `ignored-count`, `css-count`, `js-count`, `php-count`, `gha-count`) and file lists (`css-files`, `js-files`, `php-files`, `gha-files`) as workflow outputs. Wraps the `wp-tooling detect-changes` CLI (`--output github --include-files`); base-ref resolution and bucket rules live in the CLI. wp-tooling is installed by cloning `rtCamp/wp-tooling` at `release/v1.0.0` and running `npm install --install-links --prefix "$RUNNER_TEMP/wp-tooling"` on the `node-packages/wp-tooling` subpath, then adding `$RUNNER_TEMP/wp-tooling/node_modules/.bin` to `PATH` (no global install) until `@rtcamp/wp-tooling` is published. The `*-files` outputs feed straight into the lint workflows' `changed-files` input so the orchestrator can lint only changed files. Runs unconditionally — count-based gating is the caller's job. Inputs: `node-version`, `ignore-paths`, `base-ref`. +- `ci-lint-css.yml`: reusable Stylelint workflow. Runs `lint-command` over the whole project, or only the files in `changed-files` when that input is non-empty (selective linting). Inputs: `node-version`, `lint-command`, `changed-files`, `working-dir`. +- `ci-lint-js.yml`: reusable ESLint workflow with optional `package.json` validation (`validate-package-json`, default `true`). `changed-files` scopes ESLint to just the listed files; empty lints the whole project. Inputs: `node-version`, `lint-command`, `changed-files`, `validate-package-json`, `working-dir`. +- `ci-lint-php.yml`: reusable PHPCS workflow with `cs2pr` annotations and an optional PHPStan pass (`enable-phpstan`, default `false`). `changed-files` scopes PHPCS to the listed files; PHPStan always runs whole-project because it analyses cross-file dependencies. Default `composer-flags` keep `--no-scripts` for supply-chain hygiene. Inputs: `php-version`, `enable-phpstan`, `phpcs-command`, `changed-files`, `phpstan-command`, `phpstan-level`, `composer-flags`, `validate-composer`, `working-dir`. diff --git a/CLAUDE.md b/CLAUDE.md index 409ceb2..041dddb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,4 +1,4 @@ -# CLAUDE.md — `shared-workflows` +# CLAUDE.md — `wp-shared-workflows` Read this file at the start of every session. Topic-specific details live in [.claude/issues/](.claude/issues/) (per-task state) and [.claude/commands/](.claude/commands/) (skills). Read those only when the task requires. @@ -6,7 +6,7 @@ Read this file at the start of every session. Topic-specific details live in [.c ## What this repo is -A pure GitHub Actions workflow repository for rtCamp WordPress projects. Provides reusable CI and CD building blocks consumed by every rtCamp repo via `uses: rtCamp/shared-workflows/.github/workflows/.yml@v1`. Zero JavaScript. Zero `node_modules`. Only YAML. Scripts that need logic live in `@rtcamp/wp-tooling` and are invoked through `npx wp-tooling `. +A pure GitHub Actions workflow repository for rtCamp WordPress projects. Provides reusable CI and CD building blocks consumed by every rtCamp repo via `uses: rtCamp/wp-shared-workflows/.github/workflows/.yml@v1`. Zero JavaScript. Zero `node_modules`. Only YAML. Scripts that need logic live in `@rtcamp/wp-tooling` and are invoked through `npx wp-tooling `. --- @@ -68,7 +68,7 @@ README.md Caller examples — keep accurate Deploy workflows are all optional. Consumers list which deploy targets they want in the CD orchestrator call: ```yaml -uses: rtCamp/shared-workflows/.github/workflows/wp-cd.yml@v1 +uses: rtCamp/wp-shared-workflows/.github/workflows/wp-cd.yml@v1 with: deploy-target: "github,vip" # or "github,wporg" or "github,s3" ``` diff --git a/README.md b/README.md index bbb56a0..3db4dc2 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,114 @@ jobs: ## Individual workflows +### `ci-detect-changes.yml`: changed-file detection + +Buckets the files changed in a PR or push and exposes, per language bucket, both a **count** (for job gating) and the **exact file list** (for selective linting). Wraps the [`wp-tooling detect-changes`](https://github.com/rtCamp/wp-tooling) CLI — base-ref resolution and the bucket rules live there. Run it as a pre-run job, then feed its `*-files` outputs into the lint workflows so each one lints only what the PR touched. + +```yaml +jobs: + detect: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-detect-changes.yml@v1 + secrets: + # Read access to the private rtCamp/wp-tooling repo until it is published. + wp-tooling-token: ${{ secrets.WP_TOOLING_TOKEN }} + + lint-css: + needs: detect + if: ${{ needs.detect.outputs.css-count > 0 }} + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-css.yml@v1 + with: + changed-files: ${{ needs.detect.outputs.css-files }} + + lint-php: + needs: detect + if: ${{ needs.detect.outputs.php-count > 0 }} + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-php.yml@v1 + with: + changed-files: ${{ needs.detect.outputs.php-files }} +``` + +| Input | Type | Default | Description | +| -------------- | ------ | ------- | ------------------------------------------------------------------------------------------ | +| `node-version` | string | `"22"` | Node.js version used to run the wp-tooling CLI. | +| `ignore-paths` | string | `""` | Regex of paths to exclude from counts and file lists. Empty uses the CLI's built-in ignore set. | +| `base-ref` | string | `""` | Explicit ref to diff `HEAD` against. Empty lets the CLI resolve it from the PR base or push event. | + +| Output | Description | +| ------------------------------------------------- | ---------------------------------------------------------------------------------- | +| `total-count` / `ignored-count` | Changed files kept after / dropped by the ignore filter. | +| `css-count` / `js-count` / `php-count` / `gha-count` | Per-bucket change counts. Gate downstream jobs on these. | +| `css-files` / `js-files` / `php-files` / `gha-files` | Newline-separated paths per bucket, ready for the lint workflows' `changed-files`. | + +**Secret:** `wp-tooling-token` (optional) — token with read access to the private `rtCamp/wp-tooling` repo, used to install the interim CLI. Required until `@rtcamp/wp-tooling` is published; omit once it is public. + +wp-tooling is installed from its `release/v1.0.0` branch until it is published to a registry. The workflow runs unconditionally — count-based gating is the caller's (or orchestrator's) job, not the detector's. + +### `ci-lint-css.yml`: Stylelint + +Runs Stylelint over the project, or only over the files in `changed-files` when that input is non-empty. + +```yaml +jobs: + lint-css: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-css.yml@v1 + with: + node-version: "22" +``` + +| Input | Type | Default | Description | +| --------------- | ------ | ------------------ | ---------------------------------------------------------------------------- | +| `node-version` | string | `"22"` | Node.js version. | +| `lint-command` | string | `"npm run lint:css"` | Whole-project Stylelint command. Used when `changed-files` is empty. | +| `changed-files` | string | `""` | Newline-separated CSS files to lint. Empty = run `lint-command` whole-project. | +| `working-dir` | string | `"."` | Working directory for monorepos. | + +### `ci-lint-js.yml`: ESLint + +Runs ESLint, with optional `package.json` validation. `changed-files` scopes ESLint to just the listed files. + +```yaml +jobs: + lint-js: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-js.yml@v1 + with: + node-version: "22" +``` + +| Input | Type | Default | Description | +| ----------------------- | ------- | ----------------- | ---------------------------------------------------------------------------- | +| `node-version` | string | `"22"` | Node.js version. | +| `lint-command` | string | `"npm run lint:js"` | Whole-project ESLint command. Used when `changed-files` is empty. | +| `changed-files` | string | `""` | Newline-separated JS files to lint. Empty = run `lint-command` whole-project. | +| `validate-package-json` | boolean | `true` | Run `npm run lint:package-json` before ESLint. | +| `working-dir` | string | `"."` | Working directory for monorepos. | + +### `ci-lint-php.yml`: PHPCS + optional PHPStan + +Runs PHPCS with `cs2pr` annotations and, when `enable-phpstan` is true, PHPStan. `changed-files` scopes **PHPCS** to the listed files; PHPStan always runs whole-project because it analyses cross-file dependencies. + +```yaml +jobs: + lint-php: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-php.yml@v1 + with: + php-version: "8.3" + enable-phpstan: true +``` + +| Input | Type | Default | Description | +| ------------------ | ------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- | +| `php-version` | string | `"8.3"` | PHP version. | +| `enable-phpstan` | boolean | `false` | Run PHPStan after PHPCS. | +| `phpcs-command` | string | `"vendor/bin/phpcs"` | PHPCS binary path or custom command. | +| `changed-files` | string | `""` | Newline-separated PHP files to lint with PHPCS. Empty = lint the whole project. | +| `phpstan-command` | string | `"vendor/bin/phpstan analyse"` | Shell command that runs PHPStan. | +| `phpstan-level` | string | `""` | Override PHPStan level. Empty uses the level from `phpstan.neon.dist`. | +| `composer-flags` | string | `"--prefer-dist --optimize-autoloader --no-progress --no-interaction --no-scripts"` | Flags passed to `composer install`. Keeps `--no-scripts` for hygiene. | +| `validate-composer`| boolean | `true` | Run `composer validate` before installing. | +| `working-dir` | string | `"."` | Working directory for monorepos. | + + ### `ci-build.yml`: production build Runs the consumer's production build, with an optional artifact upload for downstream CD jobs. Default shape is build-only (no artifact written). @@ -402,7 +510,7 @@ permissions: contents: read jobs: build: - uses: rtCamp/shared-workflows/.github/workflows/ci-build.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 with: upload-artifact: true artifact-name: wp-org-build @@ -413,7 +521,7 @@ jobs: artifact-path: "dist/my-plugin/" deploy: needs: build - uses: rtCamp/shared-workflows/.github/workflows/cd-wp-org.yml@v1 + uses: rtCamp/wp-shared-workflows/.github/workflows/cd-wp-org.yml@v1 with: slug: my-plugin tag: ${{ github.ref_name }} From 07dd7eface7286cacf0c7607e9abcfe90a7e8511 Mon Sep 17 00:00:00 2001 From: Swanand <75439077+Swanand01@users.noreply.github.com> Date: Wed, 17 Jun 2026 19:17:38 +0530 Subject: [PATCH 32/43] feat: version monitor workflow (#22) * feat: add version-monitor workflow and example * chore: docs * fix: write files to RUNNER_TEMP * chore: docs * feat: enhance version-monitor workflow with dynamic node version input and improved error handling * feat: update version-monitor workflow with concurrency settings and enhanced README details * fix: adjust installation method for wp-tooling abd update version-monitor workflow path in README * fix: update wp-tooling installation method to use local prefix instead of global install * feat(version-monitor): add wp-tooling-token secret, rework install step * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Aditya Singh Co-authored-by: Anurag Vasanwala <75766877+AnuragVasanwala@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> --- .claude/issues/18-version-monitor-workflow.md | 72 ++++++++ .github/workflows/version-monitor.yml | 157 ++++++++++++++++++ CHANGELOG.md | 1 + README.md | 38 +++++ 4 files changed, 268 insertions(+) create mode 100644 .claude/issues/18-version-monitor-workflow.md create mode 100644 .github/workflows/version-monitor.yml diff --git a/.claude/issues/18-version-monitor-workflow.md b/.claude/issues/18-version-monitor-workflow.md new file mode 100644 index 0000000..56f2e8c --- /dev/null +++ b/.claude/issues/18-version-monitor-workflow.md @@ -0,0 +1,72 @@ +# Issue #18 — Add Version Monitor reusable workflow + +**Status:** in-review +**Branch:** `v1.0.0/task/version-monitor-workflow` +**PR:** +**Assignee:** @Swanand01 + +--- + +## Summary + +Add a `version-monitor.yml` reusable workflow that runs on a monthly schedule, calls `@rtcamp/wp-tooling version-monitor` to detect version bumps across npm, GitHub Actions, PHP, Node, WP-CLI, and container base images, and opens a draft PR on a `version-monitor/YYYY-MM` branch. Re-runs in the same month update the existing PR rather than opening a duplicate. + +--- + +## Decisions made + +- [2026-05-26] Using `peter-evans/create-pull-request@v8.1.1` (SHA-pinned) for PR creation — handles idempotent open/update on the same monthly branch automatically. +- [2026-05-26] Config check (`.github/version-monitor.yml` present) runs before Node setup for fast failure. +- [2026-05-27] Install step uses branch URL (`git+https://github.com/rtCamp/wp-tooling.git#v1.0.0/task/version-monitor-scripts`) with a `TODO(wp-tooling#10)` comment to switch to the published package once released. +- [2026-05-27] `updates.json` and `pr-body.md` written to `$RUNNER_TEMP` (not the workspace) so `peter-evans/create-pull-request` does not commit them into the consumer repo's dependency-bump PR. +- [2026-06-11] Review fixes: + - Node version is now the `node-version` input (default `22`) instead of being hard-coded in the setup step. + - `--detect`'s exit-1-with-partial-results is captured (`set +e` + `$?`) so `bash -e` no longer aborts the step and discards the month's findings; valid JSON proceeds to a PR, a non-zero exit records `detectors_errored=true`. + - All-major (or all-unmatched) month produces no diff → no PR; a guard step now fails the run with the report printed so the bumps are surfaced, not silently green. A second guard fails the run when a detector errored, honouring wp-tooling's "never green while blind" contract while still letting the partial-results PR open. README/CHANGELOG updated to match. + - Install step left unchanged — `@rtcamp/wp-tooling` is still unpublished (`TODO(wp-tooling#10)`). +- [2026-06-17] **Install reworked for production use.** Clones `release/v1.0.0` and installs the `node-packages/wp-tooling` subpath into a job-local prefix on PATH via `npm install --install-links --prefix` (no global; `--install-links` copies, not symlinks, so the temp clone is removed via an EXIT trap). Added an optional `wp-tooling-token` workflow_call secret to authenticate the clone — `rtCamp/wp-tooling` is private and `GITHUB_TOKEN`/same-org can't read it. Mirrors `ci-detect-changes.yml`. Immutable-ref (SHA/tag) pin deferred until wp-tooling stabilises. + +--- + +## Files changed + +- `.claude/issues/18-version-monitor-workflow.md` — new +- `.github/workflows/version-monitor.yml` — new +- `README.md` — edited (version-monitor section in the standard `### ` format) +- `CHANGELOG.md` — new + +--- + +## Verification run + +Tested locally with `act` v0.2.88 (`~/.local/bin/act`) using `--platform ubuntu-latest=-self-hosted`. + +**No-updates path** — `wp-tooling version-monitor --detect` ran against this repo's `.github/version-monitor.yml`, returned `count=0`, workflow exited cleanly with expected log message. + +**Updates-found path** — detect step patched to emit a single fake update record with the correct schema (`source`, `file`, `package`, `currentValue`, `latestValue`, `reason`). Confirmed: +- `--apply` and `--report` steps executed +- `pr-body.md` generated in `$RUNNER_TEMP` with correct markdown table (`actions/checkout | v3.5.3 | v4.2.2`) +- Workspace clean check passed — neither `updates.json` nor `pr-body.md` present in the repo working tree + +**Config-missing guard** — removed `.github/version-monitor.yml` and confirmed workflow errors with `::error::` annotation and non-zero exit. + +Full PR creation (`peter-evans/create-pull-request`) requires a pushed branch and real CI — local runner cannot complete that step. + +--- + +## Open questions + +_(none)_ + +--- + +## Notes for the reviewer + +- Install clones `release/v1.0.0` + copy-installs the subpath into a job-local prefix, authenticated by the optional `wp-tooling-token` secret (private repo). Consumers must pass that secret until `@rtcamp/wp-tooling` is published; clone is pinned to the branch only (immutable-ref pin deferred). +- End-to-end PR creation (the `peter-evans/create-pull-request` step) is verified structurally but requires real CI for a live smoke test. + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.github/workflows/version-monitor.yml b/.github/workflows/version-monitor.yml new file mode 100644 index 0000000..9f437e1 --- /dev/null +++ b/.github/workflows/version-monitor.yml @@ -0,0 +1,157 @@ +name: Version Monitor + +on: + workflow_call: + inputs: + node-version: + description: "Node.js version used to install and run wp-tooling" + type: string + default: "22" + base-branch: + description: "Branch to open the PR against" + type: string + default: "main" + pr-label: + description: "Label to apply to the draft PR" + type: string + default: "version-monitor" + pr-assignees: + description: "Comma-separated GitHub usernames to assign to the draft PR" + type: string + default: "" + secrets: + wp-tooling-token: + description: "Token with read access to the private rtCamp/wp-tooling repo, used to clone the interim CLI. Required while that repo is private." + required: false + +# Serialise runs per consumer repo so a scheduled run and a manual dispatch can't +# race on the same version-monitor/YYYY-MM branch. +concurrency: + group: version-monitor-${{ github.repository }} + cancel-in-progress: false + +jobs: + version-monitor: + runs-on: ubuntu-latest + timeout-minutes: 20 + permissions: + contents: write + pull-requests: write + steps: + - name: Checkout + uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + with: + fetch-depth: 0 + + - name: Verify version-monitor config present + run: | + if [ ! -f ".github/version-monitor.yml" ]; then + echo "::error::.github/version-monitor.yml not found in caller repo. See README for required config shape." + exit 1 + fi + + - name: Setup Node + uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + with: + node-version: ${{ inputs.node-version }} + + - name: Install wp-tooling + # Interim until @rtcamp/wp-tooling is published: the CLI is a subpath of the private + # rtCamp/wp-tooling monorepo (npm can't install a git subdir), so clone the branch and + # copy-install it (--install-links, not a symlink) into a job-local prefix on PATH. + # Auth the clone with wp-tooling-token when set; a plain clone works only if public. + shell: bash + env: + WP_TOOLING_TOKEN: ${{ secrets.wp-tooling-token }} + run: | + set -euo pipefail + src="$(mktemp -d)" + trap 'rm -rf "$src"' EXIT + repo="https://github.com/rtCamp/wp-tooling.git" + if [ -n "${WP_TOOLING_TOKEN:-}" ]; then + repo="https://x-access-token:${WP_TOOLING_TOKEN}@github.com/rtCamp/wp-tooling.git" + fi + git clone --depth 1 --branch release/v1.0.0 "$repo" "$src" + prefix="$RUNNER_TEMP/wp-tooling" + npm install --install-links --prefix "$prefix" "$src/node-packages/wp-tooling" + echo "$prefix/node_modules/.bin" >> "$GITHUB_PATH" + + - name: Detect version updates + id: detect + # Detectors that hit the GitHub API (actions, etc.) read GITHUB_TOKEN to + # avoid the unauthenticated 60/hour shared-runner rate limit; Actions does + # not export it to run steps automatically, so map it here. + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + # --detect prints valid (maybe partial) JSON, then exits 1 if a detector + # errored. Capture the status so `bash -e` can't abort and drop results. + set +e + wp-tooling version-monitor --detect > "$RUNNER_TEMP/updates.json" + status=$? + set -e + + # `jq -e` (plain jq exits 0 on an empty file) fails when detect emitted no + # JSON at all — a usage/config error or a throw, so there's nothing to do. + if ! count=$(jq -e 'length' "$RUNNER_TEMP/updates.json" 2>/dev/null); then + echo "::error::version-monitor --detect produced no valid JSON (exit ${status}). Cannot continue." + exit 1 + fi + echo "count=${count}" >> "$GITHUB_OUTPUT" + + # Partial results: proceed to a PR, but record it to fail the job at the end. + if [ "${status}" -ne 0 ]; then + echo "detectors_errored=true" >> "$GITHUB_OUTPUT" + echo "::warning::version-monitor: one or more detectors errored (exit ${status}); proceeding with ${count} partial result(s). The run will be marked failed so the blind source is investigated — see this step's log for details." + else + echo "detectors_errored=false" >> "$GITHUB_OUTPUT" + fi + + - name: Skip — no updates this month + if: steps.detect.outputs.count == '0' + run: echo "No updates detected this month. Exiting cleanly." + + - name: Set monthly branch name + if: steps.detect.outputs.count != '0' + id: monthly + run: | + MONTH=$(date +%Y-%m) + echo "branch=version-monitor/$MONTH" >> "$GITHUB_OUTPUT" + echo "month=$MONTH" >> "$GITHUB_OUTPUT" + + - name: Apply updates and generate PR report + if: steps.detect.outputs.count != '0' + run: | + wp-tooling version-monitor --apply < "$RUNNER_TEMP/updates.json" + wp-tooling version-monitor --report < "$RUNNER_TEMP/updates.json" > "$RUNNER_TEMP/pr-body.md" + + - name: Open or update draft PR + id: pr + if: steps.detect.outputs.count != '0' + uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 + with: + token: ${{ secrets.GITHUB_TOKEN }} + branch: ${{ steps.monthly.outputs.branch }} + base: ${{ inputs.base-branch }} + title: "chore(deps): monthly version monitor — ${{ steps.monthly.outputs.month }}" + body-path: ${{ runner.temp }}/pr-body.md + draft: true + labels: ${{ inputs.pr-label }} + assignees: ${{ inputs.pr-assignees }} + commit-message: "chore(deps): monthly version monitor — ${{ steps.monthly.outputs.month }}" + + - name: Flag detected updates that produced no PR + # Updates found but nothing applied (all major, or unmatched) → no diff, no + # PR. Fail with the report so the bumps aren't silently dropped. + if: steps.detect.outputs.count != '0' && steps.pr.outputs.pull-request-number == '' + run: | + echo "::error::version-monitor detected ${{ steps.detect.outputs.count }} update(s) but produced no file changes, so no PR was opened — every bump is a major-version bump (skipped pending manual review) or a value could not be matched in its file. Apply these manually:" + cat "$RUNNER_TEMP/pr-body.md" + exit 1 + + - name: Fail if any detector could not be checked + # A detector was blind this run — fail even if a partial-results PR opened. + if: always() && steps.detect.outputs.detectors_errored == 'true' + run: | + echo "::error::version-monitor: one or more detectors errored this run, so the results are incomplete. Any PR opened above carries only the updates that were found. See the 'Detect version updates' step log for the failing detector(s)." + exit 1 diff --git a/CHANGELOG.md b/CHANGELOG.md index ed4e10d..f161557 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `ci-test-a11y.yml` — reusable pa11y-ci accessibility test workflow. Order: `npm ci` → build → `wp-env start` → pa11y → `wp-env stop` (with `if: always()` so cleanup runs on failure). Inputs: `node-version`, `build-command`, `test-command`, `working-dir`. Trigger-agnostic — consumers wire the `Run a11y` label gate at the caller level. - `ci-build.yml`: reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. The `build-command` default is empty and selects `npm run build:prod` when Node deps install, `composer run-script build` otherwise. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. - `ci-build-artifact-gate.yml`: reusable workflow that fails a PR if it commits files under configured path prefixes (default: `assets/build/`). Pair with `ci-build.yml` so the CI-produced bundle is the only source of truth for build output. Compares `origin/..HEAD` with `--diff-filter=ACMR`, so additions/modifications/renames trip the gate and deletions are ignored (removing a previously-committed artifact is welcome). Runs only on `pull_request` events; on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. Empty `gated-paths` input skips gracefully. Path prefixes are anchored as literal strings, and regex metacharacters in path names (`. + * ( ) [ ] { } | ^ $ ? \`) are escaped automatically. Inputs: `gated-paths`, `working-dir`. +- `version-monitor.yml` — monthly scheduled workflow that detects version bumps and opens a draft PR per repo on a `version-monitor/YYYY-MM` branch. Re-runs in the same month update the existing PR. Node.js version is set via the `node-version` input (default `22`). Major bumps are surfaced for manual review; a month of only major bumps, or a detector that could not be checked, fails the run rather than passing silently. - `cd-split-composer-packages.yml`: reusable "monorepo split" workflow (Symfony pattern) that mirrors each Composer-package subtree to its own standalone repo so Packagist can serve it. A `build-matrix` job parses `splitsh.json` (`organization`, `subtrees` map, `defaults.branch`/`user_name`/`user_email`) with jq — accepting both the shorthand string form and the object/`prefixes` form — and a matrixed `split` job runs `danharrin/monorepo-split-github-action` (pinned to `14e42e2`, v2.4.5) per subtree with `fail-fast: false`. `tag` falls back to the caller's `github.ref_name` when empty; missing or empty config fails loudly. Inputs: `tag`, `config-file`. Secret: `split-token` (PAT/App token with `contents: write` on every mirror repo). - `ci-test-build-artifact.yml`: reusable workflow that boots the packaged build artifact in a real WordPress to prove it installs, not just that the build compiled. Downloads the named artifact (via `actions/download-artifact` pinned to `d3f86a1`, v4.3.0), writes a `.wp-env.override.json` to pin `phpVersion`/`core` and mount only the downloaded artifact (clearing `plugins`/`themes` from the consumer config so the dev source tree never collides with the packaged output), boots `@wordpress/env` with `npx --yes @wordpress/env start --update`, activates the plugin or theme (selected from `install-path`), then runs `wp doctor check --all --format=json` and fails only on `error`-severity checks (warnings allowed). The artifact must be a complete installable plugin/theme directory, so point `ci-build.yml`'s `artifact-path` at a packaged dist directory rather than bare `build/`. An optional `smoke-script` runs inside the container after activation, and `wp-env stop` runs in an `if: always()` step (with its own timeout) so no container leaks into the next job. Production-oriented doctor checks that a dev wp-env always trips (e.g. `constant-wp-debug-falsy`, since wp-env enables `WP_DEBUG`) are excluded from the gate via the `doctor-ignore-checks` input. Inputs: `artifact-name`, `slug`, `node-version`, `php-version`, `wp-version`, `install-path`, `smoke-script`, `doctor-ignore-checks`. - `cd-github-release.yml`: reusable workflow that publishes a GitHub Release on a `v*.*.*` tag push. Downloads the named build artifact, extracts the release body from the matching `CHANGELOG.md` section (tolerant heading match — `## v1.2.3` or `## [1.2.3]` with an optional trailing date; `## Unreleased` is never matched and a missing/empty section fails the workflow rather than publishing empty notes), then creates the Release via the `gh` CLI (no third-party action) with `--verify-tag` so a non-existent tag errors instead of silently creating one. Attaches the artifact files and honours `draft` / `prerelease`. Requires the caller to grant `contents: write`; the artifact must be produced in the same run. Inputs: `tag`, `artifact-name`, `changelog-path`, `draft`, `prerelease`. diff --git a/README.md b/README.md index 3db4dc2..6e3fdd6 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,44 @@ jobs: ## Individual workflows +### `version-monitor.yml`: monthly version monitor + +Runs on a monthly schedule and opens a draft PR with the version bumps detected across npm, GitHub Actions, PHP, Node, WP-CLI, and container base images — the moving versions Dependabot does not cover. Minor and patch bumps are applied automatically; major bumps are listed in the PR body for manual review rather than applied. Re-runs in the same calendar month update the existing PR instead of opening a duplicate. Detection and patching run through `npx wp-tooling version-monitor`; the draft PR is opened and updated with [`peter-evans/create-pull-request`](https://github.com/peter-evans/create-pull-request) (SHA-pinned). + +Requires a `.github/version-monitor.yml` config in the consumer repo listing which sources to watch — see [`@rtcamp/wp-tooling`](https://github.com/rtCamp/wp-tooling) for the full schema. + +```yaml +# .github/workflows/version-monitor.yml in the consumer +name: Version Monitor +on: + schedule: + - cron: "0 6 1 * *" # 06:00 UTC, first of each month + workflow_dispatch: +jobs: + monitor: + permissions: + contents: write + pull-requests: write + uses: rtCamp/wp-shared-workflows/.github/workflows/version-monitor.yml@v1 + with: + base-branch: main + pr-assignees: "Adi-ty" + secrets: + # Read access to the private rtCamp/wp-tooling repo until it is published. + wp-tooling-token: ${{ secrets.WP_TOOLING_TOKEN }} +``` + +| Input | Type | Default | Description | +| -------------- | ------ | ------------------- | ---------------------------------------------------- | +| `node-version` | string | `"22"` | Node.js version used to install and run wp-tooling. | +| `base-branch` | string | `"main"` | Branch the draft PR is opened against. | +| `pr-label` | string | `"version-monitor"` | Label applied to the draft PR. | +| `pr-assignees` | string | `""` | Comma-separated GitHub usernames assigned to the PR. | + +**Secret:** `wp-tooling-token` (optional) — token with read access to the private `rtCamp/wp-tooling` repo, used to install the interim CLI. Required until `@rtcamp/wp-tooling` is published; omit once it is public. + +The calling job must grant `permissions: contents: write` and `pull-requests: write` so the workflow can push the `version-monitor/YYYY-MM` branch and open the PR, and the repo must have **Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"** enabled, or PR creation is blocked. Major bumps are never auto-applied — a bare version-string swap is rarely a safe major upgrade — so a month of only major bumps produces no diff and no PR; the run fails with the bump list in the log so they are surfaced rather than passing silently. The run also fails when a detector could not be checked (a PR may still carry the bumps that were found), so a scheduled run is never green while blind. + ### `ci-detect-changes.yml`: changed-file detection Buckets the files changed in a PR or push and exposes, per language bucket, both a **count** (for job gating) and the **exact file list** (for selective linting). Wraps the [`wp-tooling detect-changes`](https://github.com/rtCamp/wp-tooling) CLI — base-ref resolution and the bucket rules live there. Run it as a pre-run job, then feed its `*-files` outputs into the lint workflows so each one lints only what the PR touched. From 3434fccabc084edd5c3b7afcdbb0068f80a9795c Mon Sep 17 00:00:00 2001 From: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> Date: Mon, 22 Jun 2026 15:41:54 +0530 Subject: [PATCH 33/43] [v1.0.0] Add wp-ci orchestrator workflow (#25) * feat(ci): add wp-ci orchestrator + wp-env matrix for ci-test-php * fix(ci): make a11y opt-in via run-a11y input in wp-ci orchestrator * docs: clarify always-on jobs and act dry-run note in wp-ci --- .claude/issues/13-ci-orchestrator.md | 113 +++++++++++++++ .github/workflows/ci-test-php.yml | 12 +- .github/workflows/wp-ci.yml | 199 +++++++++++++++++++++++++++ CHANGELOG.md | 3 +- README.md | 75 +++++++++- 5 files changed, 397 insertions(+), 5 deletions(-) create mode 100644 .claude/issues/13-ci-orchestrator.md create mode 100644 .github/workflows/wp-ci.yml diff --git a/.claude/issues/13-ci-orchestrator.md b/.claude/issues/13-ci-orchestrator.md new file mode 100644 index 0000000..123518e --- /dev/null +++ b/.claude/issues/13-ci-orchestrator.md @@ -0,0 +1,113 @@ +# Issue #13 — Add CI orchestrator workflow (`wp-ci.yml`) + +**Status:** in-review +**Branch:** `v1.0.0/task/ci-orchestrator` +**PR:** #25 +**Assignee:** @Adi-ty + +--- + +## Summary + +The individual CI workflows each do one thing; a consuming skeleton would otherwise call ~8 of them by hand and keep them in sync. `wp-ci.yml` is the orchestrator a skeleton calls once: it routes to the right subset based on a single `project-type` input (`plugin` | `theme` | `package`), runs `ci-detect-changes` first, and gates every downstream job on the per-bucket change counts so untouched file types are skipped. A `skip` input drops a named job without forking. It is the CI counterpart to the planned CD orchestrator (`wp-cd.yml`, #17). + +--- + +## Decisions made + +- [2026-05-29] **Branched off `v1.0.0/task/ci-lint-workflows` (#2)**, not `release/v1.0.0`. `detect-changes` is the orchestrator's backbone (every job gates on its outputs), so it must exist on the branch for the orchestrator to be written in its real shape. PR is **stacked against the #2 branch** (clean diff = orchestrator + docs + example); rebase onto `release/v1.0.0` once #2 merges. Review-only for now — will not merge. +- [2026-05-29] **Gating uses counts, not the issue's booleans.** The real `ci-detect-changes.yml` outputs `*-count` + `*-files`, not `php-changed == 'true'`. Jobs gate on `needs.detect-changes.outputs.-count > 0` and pass `*-files` into each linter's `changed-files`. (Hardens / corrects the issue's reference snippet.) +- [2026-05-29] **Started from a `project-type` (required) + `skip` contract.** Updated the stale top-level README consumer example that advertised non-existent inputs (CLAUDE.md: README examples must actually work). +- [2026-06-16] **Contract expanded to replace the legacy "Test and Measure" workflow.** Added the `php-versions` × `wp-versions` (+ `test-php-exclude`) matrix for `test-php`, a `use-wp-env` toggle (default true; false = standalone PHPUnit for a pure Composer library), an `enable-phpstan` passthrough to `lint-php`, and a `validate-inputs` job that fails fast on a bad `project-type` or matrix input. Coverage reporting stays a v1.x follow-up. +- [2026-05-29] **`skip` matching is comma-bounded:** `!contains(format(',{0},', inputs.skip), ',,')` so `skip: build` never also drops `build-artifact`. +- [2026-06-16] **`build-artifact` wired; `bc` dropped.** `ci-test-build-artifact.yml` is present and wired into the orchestrator. `ci-test-bc.yml` stays deferred (TS blocker), so no `bc` job is defined. With all `uses:` targets present, `act --dryrun` parses the whole orchestrator. +- [2026-06-16] **No committed example caller.** Dropped `.github/workflows/_examples/caller-wp-ci.yml` for README-only delivery, matching house style (#3/#5/#7/#9/#11/#14). +- [2026-06-17] **a11y is opt-in via `run-a11y` (default false).** It was running for every plugin/theme push/PR — diverging from the documented label-gated convention and failing CI for consumers without pa11y config. Added a `run-a11y` boolean (default false); the caller wires it to the `Run a11y` label. Chose an input over hard-coding the event/label into the orchestrator (Copilot's suggestion) so it stays trigger-agnostic and input-driven; `skip: a11y` remains a second off-switch. +- [2026-05-29] **`build-artifact` install-path derived from `project-type`** (`theme` → `wp-content/themes`, else `wp-content/plugins`) and `slug` defaulted to the repo name — the most the 2-input contract can infer. + +--- + +## Files changed so far + +- `.github/workflows/wp-ci.yml` — new (the orchestrator + `validate-inputs` job) +- `.github/workflows/ci-test-php.yml` — edited (`wp-version` input + WP_ENV pin steps for the matrix) +- `README.md` — edited (new `### wp-ci.yml` section; orchestrator inputs + presets) +- `CHANGELOG.md` — edited (bullets under Unreleased → Added) +- `.claude/issues/13-ci-orchestrator.md` — new (this file) + +--- + +## Verification run + +```bash +❯ act workflow_call -W .github/workflows/wp-ci.yml --dryrun +INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' +WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ +*DRYRUN* [CI / Orchestrator/Validate inputs] ⭐ Run Set up job +*DRYRUN* [CI / Orchestrator/Validate inputs] 🚀 Start image=node:16-buster-slim +*DRYRUN* [CI / Orchestrator/Validate inputs] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [CI / Orchestrator/Validate inputs] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Orchestrator/Validate inputs] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [CI / Orchestrator/Validate inputs] ✅ Success - Set up job +*DRYRUN* [CI / Orchestrator/Validate inputs] ⭐ Run Main Check project-type and test-php matrix inputs +*DRYRUN* [CI / Orchestrator/Validate inputs] ✅ Success - Main Check project-type and test-php matrix inputs [7.807875ms] +*DRYRUN* [CI / Orchestrator/Validate inputs] ⭐ Run Complete job +*DRYRUN* [CI / Orchestrator/Validate inputs] Cleaning up container for job Validate inputs +*DRYRUN* [CI / Orchestrator/Validate inputs] ✅ Success - Complete job +*DRYRUN* [CI / Orchestrator/Validate inputs] 🏁 Job succeeded +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Set up job +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] 🚀 Start image=node:16-buster-slim +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"]cmd=[] network="host" +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Set up job +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ☁ git clone 'https://github.com/actions/setup-node' # ref=49933ea5288caeca8642d1e84afbd3f7d6820020 +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] Non-terminating error while running 'git clone': some refs were not updated +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Main Checkout repository +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Main Checkout repository [3.83375ms] +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Main Set up Node.js +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Main Set up Node.js [3.577917ms] +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Main Install wp-tooling +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Main Install wp-tooling [5.64275ms] +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Main Detect changed files +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Main Detect changed files [5.960959ms] +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Post Set up Node.js +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Post Set up Node.js [1.769208ms] +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Complete job +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] Cleaning up container for job Detect changes +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Complete job +*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] 🏁 Job succeeded +``` + +Succeeded — no schema or terminating errors. (`act --dryrun` emits a benign non-terminating `git clone` "some refs were not updated" warning while pre-fetching the actions — an `act` quirk, not a workflow failure.) + +Gating trace (manual) — expected job set per preset: + +- **plugin** → detect-changes + lint-css/js/php + test-js + test-php + build + build-artifact + a11y +- **theme** → detect-changes + lint-css/js/php + test-js + build + build-artifact + a11y (no test-php) +- **package** → detect-changes + lint-php + test-php (no css/js lint, test-js, build, build-artifact, a11y) + +Each job additionally requires its bucket count `> 0`; `skip: ""` drops exactly that job (comma-bounded — no substring bleed, e.g. `build` vs `build-artifact`). + +--- + +## Open questions + +- _(none yet)_ + +--- + +## Notes for the reviewer + +- **`act` dry-run passes.** All `uses:` targets are present on the branch (`build-artifact` included), so the orchestrator parses and the `test-php` matrix expands under `act --dryrun`. A full green run still needs a real consumer on GitHub Actions; anything touching `wp-env` (Docker-in-Docker) cannot run under local `act`. +- **`build-artifact` is the weakest generic fit.** It needs a *packaged* artifact (`dist//`), but the default `ci-build` build-command emits bare `build/`. Wired with `slug` = repo name + `project-type`-derived install-path for design completeness; a non-standard slug or a packaging step needs a consumer override (candidate v1.x passthrough inputs). Do not assume this job runs green post-#23 without packaging wiring. +- **`bc` removed.** `ci-test-bc.yml` is deferred (TypeScript blocker), so no `bc` job is defined; add it back when that workflow lands. +- **Self-test deferred.** This repo is pure YAML (no PHP/JS to lint/test), so a meaningful self-run of `wp-ci.yml` is not possible. Real e2e proof = a consumer repo calling `wp-ci.yml@` on push/PR. +- **a11y is opt-in (`run-a11y`, default false).** `ci-test-a11y` is trigger-agnostic; the orchestrator now gates it on the `run-a11y` input (default false) so a slow pa11y run never fires — or fails for lack of pa11y config — unless the caller opts in (typically wired to the `Run a11y` label). `skip: a11y` remains a second off-switch. +- **Deps landed.** detect-changes + lint (#2) and build-artifact (#23) are present on the branch; only `bc` (`ci-test-bc.yml`) stays deferred and is intentionally not wired. + +--- + +## Handoff log + +_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.github/workflows/ci-test-php.yml b/.github/workflows/ci-test-php.yml index 85282e1..e050e68 100644 --- a/.github/workflows/ci-test-php.yml +++ b/.github/workflows/ci-test-php.yml @@ -4,13 +4,17 @@ on: workflow_call: inputs: php-version: - description: "PHP version to install." + description: "PHP version. Installed on the host (used directly in standalone mode) and passed to wp-env as WP_ENV_PHP_VERSION so the container runs the same version." type: string default: "8.3" node-version: description: "Node.js version (used only when use-wp-env is true)." type: string default: "22" + wp-version: + description: "WordPress core version for wp-env, e.g. '6.8' (resolved as WordPress/WordPress#). Empty uses the version from the consumer's .wp-env.json. Ignored when use-wp-env is false." + type: string + default: "" use-wp-env: description: "Start @wordpress/env before tests for WordPress integration runs." type: boolean @@ -35,6 +39,12 @@ jobs: test-php: name: PHPUnit runs-on: ubuntu-latest + # Pin the wp-env container's PHP/WordPress core via env: (not $GITHUB_ENV, which is + # newline-injectable) at job scope, so start/run/stop resolve the same environment. + # An empty WP_ENV_CORE is ignored by wp-env (falls back to the consumer's .wp-env.json). + env: + WP_ENV_PHP_VERSION: ${{ inputs.use-wp-env && inputs.php-version || '' }} + WP_ENV_CORE: ${{ (inputs.use-wp-env && inputs.wp-version != '') && format('WordPress/WordPress#{0}', inputs.wp-version) || '' }} defaults: run: working-directory: ${{ inputs.working-dir }} diff --git a/.github/workflows/wp-ci.yml b/.github/workflows/wp-ci.yml new file mode 100644 index 0000000..2dc3b89 --- /dev/null +++ b/.github/workflows/wp-ci.yml @@ -0,0 +1,199 @@ +name: CI / Orchestrator + +on: + workflow_call: + inputs: + project-type: + description: "Project shape that selects the job preset: plugin | theme | package." + type: string + required: true + skip: + description: "Comma-separated job ids to drop, e.g. 'a11y,test-php'. Ids: lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact, a11y." + type: string + default: "" + enable-phpstan: + description: "Run PHPStan (whole-project) after PHPCS in the lint-php job." + type: boolean + default: false + run-a11y: + description: "Run the a11y (pa11y) job. Off by default — it is slow and needs pa11y config. Gate it on the 'Run a11y' label at the caller (see README)." + type: boolean + default: false + use-wp-env: + description: "Run test-php under @wordpress/env (default). Set false for a standalone Composer library that runs PHPUnit without WordPress." + type: boolean + default: true + php-versions: + description: "JSON array of PHP versions for test-php, crossed with wp-versions, e.g. '[\"8.2\",\"8.3\"]'. Must be non-empty — use skip: test-php to disable." + type: string + default: '["8.3"]' + wp-versions: + description: "JSON array of WordPress core versions for wp-env, crossed with php-versions, e.g. '[\"6.8\",\"6.9\"]'. An empty-string entry uses .wp-env.json. Ignored when use-wp-env is false." + type: string + default: '[""]' + test-php-exclude: + description: "JSON array of {php, wp} cells to drop from the php-versions × wp-versions product, e.g. '[{\"php\":\"8.1\",\"wp\":\"6.9\"}]'." + type: string + default: '[]' + build-artifact-path: + description: "Path to the packaged, installable plugin/theme dir the build produces, e.g. 'dist/my-plugin/'. Required to run the build-artifact install test; empty skips it (the default build emits bare build/, which is not installable)." + type: string + default: "" + build-artifact-slug: + description: "Plugin/theme slug to activate in the build-artifact test. Empty uses the repo name." + type: string + default: "" + secrets: + wp-tooling-token: + description: "Token with read access to the private rtCamp/wp-tooling repo, forwarded to detect-changes to install the interim CLI. Required while that repo is private." + required: false + +# Cancel an in-progress run when the same ref is pushed again (e.g. a force-push). +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + # Fail fast on a bad project-type or matrix input — a typo otherwise silently runs nothing. + validate-inputs: + name: Validate inputs + runs-on: ubuntu-latest + steps: + - name: Check project-type and test-php matrix inputs + env: + PROJECT_TYPE: ${{ inputs.project-type }} + PHP_VERSIONS: ${{ inputs.php-versions }} + WP_VERSIONS: ${{ inputs.wp-versions }} + TEST_PHP_EXCLUDE: ${{ inputs.test-php-exclude }} + run: | + case "$PROJECT_TYPE" in + plugin|theme|package) ;; + *) echo "::error::project-type must be one of: plugin, theme, package (got '$PROJECT_TYPE')"; exit 1 ;; + esac + echo "$PHP_VERSIONS" | jq -e 'type == "array" and length > 0' >/dev/null \ + || { echo "::error::php-versions must be a non-empty JSON array (got '$PHP_VERSIONS') — use skip: test-php to disable PHP tests"; exit 1; } + echo "$WP_VERSIONS" | jq -e 'type == "array" and length > 0' >/dev/null \ + || { echo "::error::wp-versions must be a non-empty JSON array (got '$WP_VERSIONS')"; exit 1; } + echo "$TEST_PHP_EXCLUDE" | jq -e 'type == "array"' >/dev/null \ + || { echo "::error::test-php-exclude must be a JSON array (got '$TEST_PHP_EXCLUDE')"; exit 1; } + + # Backbone: never skippable. Emits the per-bucket change counts and file lists the + # jobs below gate on. + detect-changes: + name: Detect changes + needs: [validate-inputs] + uses: ./.github/workflows/ci-detect-changes.yml + secrets: + wp-tooling-token: ${{ secrets.wp-tooling-token }} + + lint-css: + name: Lint CSS + needs: [detect-changes] + if: >- + needs.detect-changes.outputs.css-count > 0 + && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && !contains(format(',{0},', inputs.skip), ',lint-css,') + uses: ./.github/workflows/ci-lint-css.yml + with: + changed-files: ${{ needs.detect-changes.outputs.css-files }} + + lint-js: + name: Lint JS + needs: [detect-changes] + if: >- + needs.detect-changes.outputs.js-count > 0 + && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && !contains(format(',{0},', inputs.skip), ',lint-js,') + uses: ./.github/workflows/ci-lint-js.yml + with: + changed-files: ${{ needs.detect-changes.outputs.js-files }} + + lint-php: + name: Lint PHP + needs: [detect-changes] + if: >- + needs.detect-changes.outputs.php-count > 0 + && (inputs.project-type == 'plugin' || inputs.project-type == 'theme' || inputs.project-type == 'package') + && !contains(format(',{0},', inputs.skip), ',lint-php,') + uses: ./.github/workflows/ci-lint-php.yml + with: + changed-files: ${{ needs.detect-changes.outputs.php-files }} + enable-phpstan: ${{ inputs.enable-phpstan }} + + test-js: + name: Test JS + needs: [detect-changes] + if: >- + needs.detect-changes.outputs.js-count > 0 + && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && !contains(format(',{0},', inputs.skip), ',test-js,') + uses: ./.github/workflows/ci-test-js.yml + + test-php: + name: Test PHP + needs: [detect-changes] + if: >- + needs.detect-changes.outputs.php-count > 0 + && (inputs.project-type == 'plugin' || inputs.project-type == 'package') + && !contains(format(',{0},', inputs.skip), ',test-php,') + # Matrix: php-versions × wp-versions, minus test-php-exclude cells. With use-wp-env + # (default) each cell boots @wordpress/env, pinning PHP + WP core; with use-wp-env + # false it runs standalone PHPUnit and the wp dimension is inert. + strategy: + fail-fast: false + matrix: + php: ${{ fromJSON(inputs.php-versions) }} + wp: ${{ fromJSON(inputs.wp-versions) }} + exclude: ${{ fromJSON(inputs.test-php-exclude) }} + uses: ./.github/workflows/ci-test-php.yml + with: + php-version: ${{ matrix.php }} + wp-version: ${{ matrix.wp }} + use-wp-env: ${{ inputs.use-wp-env }} + + build: + name: Build + needs: [detect-changes] + if: >- + (needs.detect-changes.outputs.css-count > 0 || needs.detect-changes.outputs.js-count > 0 || needs.detect-changes.outputs.php-count > 0) + && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && !contains(format(',{0},', inputs.skip), ',build,') + uses: ./.github/workflows/ci-build.yml + with: + # Only upload when build-artifact runs (it consumes this); otherwise build just compiles. + upload-artifact: ${{ inputs.build-artifact-path != '' }} + artifact-name: wp-ci-build + artifact-path: ${{ inputs.build-artifact-path }} + retention-days: 1 + + # Boots the packaged artifact in real WordPress to prove it installs. Opt-in: runs only + # when build-artifact-path points at an installable dir, since the default build emits + # bare build/. slug defaults to the repo name; install-path follows project-type. + build-artifact: + name: Test build artifact + needs: [detect-changes, build] + if: >- + inputs.build-artifact-path != '' + && (needs.detect-changes.outputs.css-count > 0 || needs.detect-changes.outputs.js-count > 0 || needs.detect-changes.outputs.php-count > 0) + && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && !contains(format(',{0},', inputs.skip), ',build-artifact,') + uses: ./.github/workflows/ci-test-build-artifact.yml + with: + artifact-name: wp-ci-build + slug: ${{ inputs.build-artifact-slug != '' && inputs.build-artifact-slug || github.event.repository.name }} + install-path: ${{ inputs.project-type == 'theme' && 'wp-content/themes' || 'wp-content/plugins' }} + + # Opt-in: a11y is slow and needs pa11y config, so it stays off unless run-a11y is set + # (wire it to the 'Run a11y' label at the caller). Matches the label-gated convention. + a11y: + name: Test accessibility + needs: [detect-changes] + if: >- + inputs.run-a11y + && (needs.detect-changes.outputs.css-count > 0 || needs.detect-changes.outputs.js-count > 0 || needs.detect-changes.outputs.php-count > 0) + && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && !contains(format(',{0},', inputs.skip), ',a11y,') + uses: ./.github/workflows/ci-test-a11y.yml diff --git a/CHANGELOG.md b/CHANGELOG.md index f161557..dd84400 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added -- `ci-test-php.yml`: reusable PHPUnit workflow with a `use-wp-env` toggle (default `true`) for WordPress integration tests via `@wordpress/env`, or standalone PHPUnit for Composer-only packages and libraries. Inputs: `php-version`, `node-version`, `use-wp-env`, `test-command`, `composer-flags`, `working-dir`. The `test-command` default is empty and selects `npm run test:php` in wp-env mode, `vendor/bin/phpunit` standalone. +- `ci-test-php.yml`: reusable PHPUnit workflow with a `use-wp-env` toggle (default `true`) for WordPress integration tests via `@wordpress/env`, or standalone PHPUnit for Composer-only packages and libraries. In wp-env mode, `php-version` is pinned into the container via `WP_ENV_PHP_VERSION` and `wp-version` (when non-empty) sets `WP_ENV_CORE=WordPress/WordPress#` (both set at job scope, not `$GITHUB_ENV`, so a caller's matrix can drive the PHP and WordPress core version per cell without newline-injection risk); an empty `wp-version` uses the consumer's `.wp-env.json`. Inputs: `php-version`, `node-version`, `wp-version`, `use-wp-env`, `test-command`, `composer-flags`, `working-dir`. The `test-command` default is empty and selects `npm run test:php` in wp-env mode, `vendor/bin/phpunit` standalone. - `ci-test-js.yml` — reusable Jest unit-test workflow with optional cross-run cache (`enable-cache`), monorepo support (`working-dir`), and a consumer-overridable command (`test-command`). Replaces the copy-pasted `unit-tests-js` job from the legacy `Test and Measure` workflow. - `ci-test-a11y.yml` — reusable pa11y-ci accessibility test workflow. Order: `npm ci` → build → `wp-env start` → pa11y → `wp-env stop` (with `if: always()` so cleanup runs on failure). Inputs: `node-version`, `build-command`, `test-command`, `working-dir`. Trigger-agnostic — consumers wire the `Run a11y` label gate at the caller level. - `ci-build.yml`: reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. The `build-command` default is empty and selects `npm run build:prod` when Node deps install, `composer run-script build` otherwise. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. @@ -23,3 +23,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `ci-lint-css.yml`: reusable Stylelint workflow. Runs `lint-command` over the whole project, or only the files in `changed-files` when that input is non-empty (selective linting). Inputs: `node-version`, `lint-command`, `changed-files`, `working-dir`. - `ci-lint-js.yml`: reusable ESLint workflow with optional `package.json` validation (`validate-package-json`, default `true`). `changed-files` scopes ESLint to just the listed files; empty lints the whole project. Inputs: `node-version`, `lint-command`, `changed-files`, `validate-package-json`, `working-dir`. - `ci-lint-php.yml`: reusable PHPCS workflow with `cs2pr` annotations and an optional PHPStan pass (`enable-phpstan`, default `false`). `changed-files` scopes PHPCS to the listed files; PHPStan always runs whole-project because it analyses cross-file dependencies. Default `composer-flags` keep `--no-scripts` for supply-chain hygiene. Inputs: `php-version`, `enable-phpstan`, `phpcs-command`, `changed-files`, `phpstan-command`, `phpstan-level`, `composer-flags`, `validate-composer`, `working-dir`. +- `wp-ci.yml`: CI orchestrator that routes to the individual CI workflows from one `project-type` input (`plugin` \| `theme` \| `package`). `detect-changes` runs first as a never-skippable backbone; every other job is gated on its per-bucket change counts (`*-count > 0`) and feeds the `*-files` outputs into the linters' `changed-files`, so a job runs only when its file type changed and only when its preset includes it. A `skip` input drops jobs by id with comma-exact matching (`skip: build` does not also drop `build-artifact`). The `test-php` job fans out over the cross-product of `php-versions` × `wp-versions` (both JSON arrays), with `test-php-exclude` (JSON array of `{php, wp}`) dropping cells; each cell calls `ci-test-php.yml` with that pair. `use-wp-env` (default `true`) boots `@wordpress/env` per cell, pinning the container's `WP_ENV_PHP_VERSION`/`WP_ENV_CORE` — suiting plugins, themes, and packages whose suite tests against WordPress (e.g. via `wp-phpunit`); set it `false` for a pure Composer library to run standalone PHPUnit, where the `wp` dimension is inert. An empty-string `wp-versions` entry uses the consumer's `.wp-env.json` default; defaults run a single PHP 8.3 leg. `enable-phpstan` (default `false`) opts the `lint-php` job into a PHPStan pass. A `validate-inputs` job runs first and fails the run fast on an invalid `project-type` or a non-array matrix input (a typo would otherwise silently run nothing). The `build-artifact` install test is opt-in: it runs only when `build-artifact-path` points at the packaged installable dir the build produces (`build-artifact-slug` overrides the activated slug), so the default pipeline never fails trying to boot the bare `build/` output. Concurrency cancels duplicate runs on the same ref. Inputs: `project-type`, `skip`, `enable-phpstan`, `use-wp-env`, `php-versions`, `wp-versions`, `test-php-exclude`, `build-artifact-path`, `build-artifact-slug`. Covers the lint/test/build pipeline previously hand-wired in the "Test and Measure" workflow; code coverage reporting is not yet included (v1.x follow-up). diff --git a/README.md b/README.md index 6e3fdd6..545ffa2 100644 --- a/README.md +++ b/README.md @@ -22,17 +22,85 @@ Per-issue progress lives in [`.claude/issues/`](./.claude/issues/). Claude skill # .github/workflows/ci.yml in any rtCamp repo name: CI on: [push, pull_request] +permissions: + contents: read jobs: ci: uses: rtCamp/wp-shared-workflows/.github/workflows/wp-ci.yml@v1 with: - php-version: "8.3" - node-version: "22" - project-type: "plugin" + project-type: "plugin" # plugin | theme | package + secrets: + # Read access to the private rtCamp/wp-tooling repo until it is published. + wp-tooling-token: ${{ secrets.WP_TOOLING_TOKEN }} ``` ## Individual workflows +### `wp-ci.yml`: CI orchestrator + +Call this once and it routes to the right subset of the individual CI workflows for your `project-type`. `detect-changes` runs first; every downstream job is gated on its per-bucket counts, so a PR that touched no PHP skips PHP lint and tests, and so on. A consumer adds a ~10-line caller and never wires the underlying workflows by hand. + +```yaml +# .github/workflows/ci.yml in the consumer +name: CI +on: [push, pull_request] +permissions: + contents: read +jobs: + ci: + uses: rtCamp/wp-shared-workflows/.github/workflows/wp-ci.yml@v1 + with: + project-type: plugin # plugin | theme | package + # skip: "a11y" # optional: comma-separated job ids + # enable-phpstan: true # optional: run PHPStan after PHPCS + # use-wp-env: false # optional: standalone PHPUnit for a pure Composer library + # run-a11y: ${{ contains(github.event.pull_request.labels.*.name, 'Run a11y') }} # optional: gate a11y on a label + # Optional: fan PHPUnit across a PHP x WordPress grid. Under the default wp-env + # each cell pins PHP + WordPress core; drop cells via test-php-exclude — each + # {php, wp} must match a cell in the product. Omit all three for a single 8.3 leg. + php-versions: '["8.1","8.2","8.3"]' + wp-versions: '["6.7","6.8","6.9"]' + test-php-exclude: '[{"php":"8.1","wp":"6.9"}]' + secrets: + # Read access to the private rtCamp/wp-tooling repo until it is published. + wp-tooling-token: ${{ secrets.WP_TOOLING_TOKEN }} +``` + +| Input | Type | Default | Description | +| ------------------ | ------- | ------------ | ---------------------------------------------------------------------------------------------------- | +| `project-type` | string | — | **Required.** `plugin` \| `theme` \| `package` — selects the job preset. | +| `skip` | string | `""` | Comma-separated job ids to drop without forking the orchestrator. Disable PHP tests with `test-php` here — not an empty array. | +| `enable-phpstan` | boolean | `false` | Run PHPStan (whole-project) after PHPCS in `lint-php`. | +| `run-a11y` | boolean | `false` | Run the `a11y` job. Off by default — slow and needs pa11y config. Gate it on the `Run a11y` label at the caller. | +| `use-wp-env` | boolean | `true` | Run `test-php` under `@wordpress/env`. Set `false` only for a pure Composer library that runs standalone PHPUnit. | +| `php-versions` | string | `["8.3"]` | Non-empty JSON array of PHP versions; crossed with `wp-versions` to fan out `test-php`. Empty `[]` is a matrix error. | +| `wp-versions` | string | `[""]` | JSON array of WordPress core versions for wp-env; crossed with `php-versions`. Empty string = `.wp-env.json` default; ignored when `use-wp-env: false`. | +| `test-php-exclude` | string | `[]` | JSON array of `{php, wp}` cells to drop from the product; both keys must match a cell. | +| `build-artifact-path` | string | `""` | Packaged installable plugin/theme dir the build produces (e.g. `dist/my-plugin/`). Set this to run the `build-artifact` install test; empty skips it. | +| `build-artifact-slug` | string | `""` | Slug to activate in the `build-artifact` test. Empty uses the repo name. | + +**Secret:** `wp-tooling-token` (optional) — forwarded to `detect-changes` to install the interim CLI from the private `rtCamp/wp-tooling` repo. Required until `@rtcamp/wp-tooling` is published. + +**Project-type presets** (a job also runs only when `detect-changes` reports the relevant bucket changed): + +| Preset | Jobs | +| --------- | ---- | +| `plugin` | detect-changes, lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact†, a11y‡ | +| `theme` | detect-changes, lint-css, lint-js, lint-php, test-js, build, build-artifact†, a11y‡ | +| `package` | detect-changes, lint-php, test-php | + +† `build-artifact` runs only when `build-artifact-path` is set — the default `build` output is not an installable directory. +‡ `a11y` runs only when `run-a11y: true` — it is slow and needs pa11y config, so gate it on the `Run a11y` label at the caller. + +Skippable job ids (for `skip`): `lint-css`, `lint-js`, `lint-php`, `test-js`, `test-php`, `build`, `build-artifact`, `a11y`. `validate-inputs` and `detect-changes` always run and aren't skippable. Matching is comma-exact, so `skip: build` drops `build` but not `build-artifact`. + +Notes: + +- **Concurrency** — duplicate runs on the same ref (e.g. a force-push) are cancelled (`concurrency: ci-${{ github.ref }}`, `cancel-in-progress: true`). +- **PHP / WordPress matrix** — `test-php` fans out over `php-versions` × `wp-versions` minus `test-php-exclude`. With `use-wp-env: true` (the default) each cell boots `@wordpress/env`, pinning `WP_ENV_PHP_VERSION` and `WP_ENV_CORE` — this suits plugins, themes, and packages whose suite tests against WordPress (e.g. via `wp-phpunit`), and the consumer needs a `.wp-env.json` plus `wp-env` and `test:php` npm scripts. A pure Composer library sets `use-wp-env: false` to run **standalone** PHPUnit (`vendor/bin/phpunit`), where the `wp` dimension is inert and no Node/Docker is required. Node defaults to 22; defaults run a single PHP 8.3 leg against the consumer's `.wp-env.json` WordPress version. +- **Static analysis & coverage** — PHPStan is off by default; opt in with `enable-phpstan: true`. The orchestrator does not yet produce a coverage report (a v1.x follow-up), so it does not fully replace a pipeline that gated on coverage. +- **`build-artifact`** — opt-in. Set `build-artifact-path` to the installable dir your build produces (the default `build` output is bare `build/`, not installable); the `build` job then uploads that path and `build-artifact` boots it in WordPress. `build-artifact-slug` overrides the activated slug (defaults to the repo name); install path follows `project-type`. + ### `version-monitor.yml`: monthly version monitor Runs on a monthly schedule and opens a draft PR with the version bumps detected across npm, GitHub Actions, PHP, Node, WP-CLI, and container base images — the moving versions Dependabot does not cover. Minor and patch bumps are applied automatically; major bumps are listed in the PR body for manual review rather than applied. Re-runs in the same calendar month update the existing PR instead of opening a duplicate. Detection and patching run through `npx wp-tooling version-monitor`; the draft PR is opened and updated with [`peter-evans/create-pull-request`](https://github.com/peter-evans/create-pull-request) (SHA-pinned). @@ -273,6 +341,7 @@ jobs: | ---------------- | ------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- | | `php-version` | string | `"8.3"` | PHP version to install. | | `node-version` | string | `"22"` | Node.js version. Consumed only when `use-wp-env: true`. | +| `wp-version` | string | `""` | WordPress core version for wp-env, e.g. `"6.8"` (resolved as `WordPress/WordPress#`). Empty uses the consumer's `.wp-env.json`. Ignored when `use-wp-env: false`. | | `use-wp-env` | boolean | `true` | Start `@wordpress/env` before tests for WordPress integration runs. | | `test-command` | string | `""` | PHPUnit command. Empty means `npm run test:php` in wp-env mode, `vendor/bin/phpunit` standalone. | | `composer-flags` | string | `"--no-interaction --prefer-dist --no-progress --no-scripts"` | Flags passed to `composer install`. Keep `--no-scripts` for supply-chain hygiene. | From 6274f32c5fcb6670b131e7edd15ea5e64691d1ae Mon Sep 17 00:00:00 2001 From: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> Date: Tue, 23 Jun 2026 16:12:41 +0530 Subject: [PATCH 34/43] Add packages-token secret for private Composer VCS deps (#28) * feat(ci): add packages-token secret for private Composer VCS deps Adds optional packages-token secret to ci-lint-php.yml, ci-test-php.yml, and wp-ci.yml to authenticate composer install for private repos like rtCamp/wp-framework. * fix(ci): clarify packages-token docs; guard in-container composer config --- .github/workflows/ci-lint-php.yml | 7 +++++++ .github/workflows/ci-test-php.yml | 24 ++++++++++++++++++++++++ .github/workflows/wp-ci.yml | 7 +++++++ README.md | 14 +++++++++++++- 4 files changed, 51 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci-lint-php.yml b/.github/workflows/ci-lint-php.yml index ced8df7..fea76f3 100644 --- a/.github/workflows/ci-lint-php.yml +++ b/.github/workflows/ci-lint-php.yml @@ -39,6 +39,10 @@ on: description: "Working directory for monorepos." type: string default: "." + secrets: + packages-token: + description: "Optional token with read access to private Composer source repos (e.g. rtCamp/wp-framework). Passed to setup-php so `composer install` can resolve private VCS dependencies. Omit for projects with only public/Packagist deps." + required: false permissions: contents: read @@ -60,6 +64,9 @@ jobs: php-version: ${{ inputs.php-version }} tools: composer, cs2pr coverage: none + # Authenticates `composer install` for private VCS deps. Falls back to the + # default GITHUB_TOKEN (rate-limit help only) when no packages-token is given. + github-token: ${{ secrets.packages-token || github.token }} - name: Validate composer.json if: ${{ inputs.validate-composer }} diff --git a/.github/workflows/ci-test-php.yml b/.github/workflows/ci-test-php.yml index e050e68..47039b1 100644 --- a/.github/workflows/ci-test-php.yml +++ b/.github/workflows/ci-test-php.yml @@ -31,6 +31,10 @@ on: description: "Working directory for monorepos." type: string default: "." + secrets: + packages-token: + description: "Optional token with read access to private Composer source repos (e.g. rtCamp/wp-framework). Authenticates `composer install` on the host (via setup-php) and inside the wp-env container. Omit for projects with only public/Packagist deps." + required: false permissions: contents: read @@ -58,6 +62,9 @@ jobs: php-version: ${{ inputs.php-version }} coverage: none tools: composer + # Authenticates the host `composer install` for private VCS deps. Falls back to + # the default GITHUB_TOKEN (rate-limit help only) when no packages-token is given. + github-token: ${{ secrets.packages-token || github.token }} - name: Set up Node.js if: ${{ inputs.use-wp-env }} @@ -77,6 +84,23 @@ jobs: if: ${{ inputs.use-wp-env }} run: npm run wp-env start + # Configure Composer auth inside the container so the in-container `composer install` + # (e.g. a pretest:php hook) can resolve private VCS deps. Secrets can't be used in + # `if:`, so guard on the env var inside the script — a no-op when no token is set. + - name: Configure Composer auth in wp-env + if: ${{ inputs.use-wp-env }} + env: + PACKAGES_TOKEN: ${{ secrets.packages-token }} + run: | + if [ -n "$PACKAGES_TOKEN" ]; then + # Only configure in-container auth when the container actually has Composer. + # Some consumers run PHPUnit against a host-installed vendor/ with no in-container + # composer, where an unconditional `composer config` would fail the job. + if npx wp-env run tests-cli -- sh -lc 'command -v composer >/dev/null 2>&1'; then + npx wp-env run tests-cli -- composer config --global github-oauth.github.com "$PACKAGES_TOKEN" + fi + fi + - name: Run PHPUnit run: ${{ inputs.test-command != '' && inputs.test-command || (inputs.use-wp-env && 'npm run test:php' || 'vendor/bin/phpunit') }} diff --git a/.github/workflows/wp-ci.yml b/.github/workflows/wp-ci.yml index 2dc3b89..9c2de63 100644 --- a/.github/workflows/wp-ci.yml +++ b/.github/workflows/wp-ci.yml @@ -47,6 +47,9 @@ on: wp-tooling-token: description: "Token with read access to the private rtCamp/wp-tooling repo, forwarded to detect-changes to install the interim CLI. Required while that repo is private." required: false + packages-token: + description: "Token with read access to private Composer source repos (e.g. rtCamp/wp-framework), forwarded to lint-php and test-php to authenticate `composer install`. Omit for projects with only public/Packagist deps. A single token may serve both wp-tooling-token and packages-token." + required: false # Cancel an in-progress run when the same ref is pushed again (e.g. a force-push). concurrency: @@ -122,6 +125,8 @@ jobs: with: changed-files: ${{ needs.detect-changes.outputs.php-files }} enable-phpstan: ${{ inputs.enable-phpstan }} + secrets: + packages-token: ${{ secrets.packages-token }} test-js: name: Test JS @@ -153,6 +158,8 @@ jobs: php-version: ${{ matrix.php }} wp-version: ${{ matrix.wp }} use-wp-env: ${{ inputs.use-wp-env }} + secrets: + packages-token: ${{ secrets.packages-token }} build: name: Build diff --git a/README.md b/README.md index 545ffa2..1b2dbbe 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,10 @@ jobs: secrets: # Read access to the private rtCamp/wp-tooling repo until it is published. wp-tooling-token: ${{ secrets.WP_TOOLING_TOKEN }} + # Read access to private Composer source repos (e.g. rtCamp/wp-framework) so + # composer install can resolve them in lint-php / test-php. One token with access to + # every private repo involved can serve both secrets (wp-tooling-token + packages-token). + packages-token: ${{ secrets.RTCAMP_PACKAGES_TOKEN }} ``` | Input | Type | Default | Description | @@ -79,7 +83,10 @@ jobs: | `build-artifact-path` | string | `""` | Packaged installable plugin/theme dir the build produces (e.g. `dist/my-plugin/`). Set this to run the `build-artifact` install test; empty skips it. | | `build-artifact-slug` | string | `""` | Slug to activate in the `build-artifact` test. Empty uses the repo name. | -**Secret:** `wp-tooling-token` (optional) — forwarded to `detect-changes` to install the interim CLI from the private `rtCamp/wp-tooling` repo. Required until `@rtcamp/wp-tooling` is published. +**Secrets:** + +- `wp-tooling-token` (optional) — forwarded to `detect-changes` to install the interim CLI from the private `rtCamp/wp-tooling` repo. Required until `@rtcamp/wp-tooling` is published. +- `packages-token` (optional) — forwarded to `lint-php` and `test-php` to authenticate `composer install` for private Composer source repos (e.g. `rtCamp/wp-framework`). Omit for projects with only public/Packagist deps. A single token with read access to all the required private repos can serve both `wp-tooling-token` and `packages-token`. **Project-type presets** (a job also runs only when `detect-changes` reports the relevant bucket changed): @@ -246,6 +253,8 @@ jobs: | `validate-composer`| boolean | `true` | Run `composer validate` before installing. | | `working-dir` | string | `"."` | Working directory for monorepos. | +**Secret:** `packages-token` (optional) — passed to setup-php to authenticate `composer install` for private Composer source repos (e.g. `rtCamp/wp-framework`). Omit for projects with only public/Packagist deps. + ### `ci-build.yml`: production build @@ -346,6 +355,9 @@ jobs: | `test-command` | string | `""` | PHPUnit command. Empty means `npm run test:php` in wp-env mode, `vendor/bin/phpunit` standalone. | | `composer-flags` | string | `"--no-interaction --prefer-dist --no-progress --no-scripts"` | Flags passed to `composer install`. Keep `--no-scripts` for supply-chain hygiene. | | `working-dir` | string | `"."` | Working directory for monorepos. | + +**Secret:** `packages-token` (optional) — authenticates `composer install` for private Composer source repos (e.g. `rtCamp/wp-framework`) on the host (via setup-php) and inside the wp-env container. Omit for projects with only public/Packagist deps. + Each workflow can be called independently, so you can wire them into your own job graph if the orchestrator preset does not fit your setup. ### `ci-test-js.yml` — Jest tests From f483c5b21d19ad590883ee50209b6c6bb401cb31 Mon Sep 17 00:00:00 2001 From: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> Date: Tue, 23 Jun 2026 22:24:49 +0530 Subject: [PATCH 35/43] fix: update test-php condition to include 'theme' project type (#29) --- .github/workflows/wp-ci.yml | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/wp-ci.yml b/.github/workflows/wp-ci.yml index 9c2de63..be90877 100644 --- a/.github/workflows/wp-ci.yml +++ b/.github/workflows/wp-ci.yml @@ -142,7 +142,7 @@ jobs: needs: [detect-changes] if: >- needs.detect-changes.outputs.php-count > 0 - && (inputs.project-type == 'plugin' || inputs.project-type == 'package') + && (inputs.project-type == 'plugin' || inputs.project-type == 'theme' || inputs.project-type == 'package') && !contains(format(',{0},', inputs.skip), ',test-php,') # Matrix: php-versions × wp-versions, minus test-php-exclude cells. With use-wp-env # (default) each cell boots @wordpress/env, pinning PHP + WP core; with use-wp-env diff --git a/README.md b/README.md index 1b2dbbe..6467df0 100644 --- a/README.md +++ b/README.md @@ -93,7 +93,7 @@ jobs: | Preset | Jobs | | --------- | ---- | | `plugin` | detect-changes, lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact†, a11y‡ | -| `theme` | detect-changes, lint-css, lint-js, lint-php, test-js, build, build-artifact†, a11y‡ | +| `theme` | detect-changes, lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact†, a11y‡ | | `package` | detect-changes, lint-php, test-php | † `build-artifact` runs only when `build-artifact-path` is set — the default `build` output is not an installable directory. From c08a4504b299ef3794852d20c89c35c610d756a3 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Fri, 31 Jul 2026 11:13:20 +0530 Subject: [PATCH 36/43] feat(ci): add working-dir support, remove wp-tooling/packages tokens, add cd-built-branch workflow --- .github/workflows/cd-built-branch.yml | 630 +++++++++++++++++++ .github/workflows/cd-github-release.yml | 21 + .github/workflows/cd-wp-org.yml | 20 + .github/workflows/ci-build-artifact-gate.yml | 12 +- .github/workflows/ci-build.yml | 2 + .github/workflows/ci-detect-changes.yml | 169 +++-- .github/workflows/ci-lint-css.yml | 2 + .github/workflows/ci-lint-js.yml | 2 + .github/workflows/ci-lint-php.yml | 13 +- .github/workflows/ci-test-a11y.yml | 2 + .github/workflows/ci-test-build-artifact.yml | 13 +- .github/workflows/ci-test-js.yml | 2 + .github/workflows/ci-test-php.yml | 32 +- .github/workflows/version-monitor.yml | 43 +- .github/workflows/wp-ci.yml | 191 ++++-- CHANGELOG.md | 12 +- CLAUDE.md | 39 +- README.md | 179 ++++-- 18 files changed, 1158 insertions(+), 226 deletions(-) create mode 100644 .github/workflows/cd-built-branch.yml diff --git a/.github/workflows/cd-built-branch.yml b/.github/workflows/cd-built-branch.yml new file mode 100644 index 0000000..6219f79 --- /dev/null +++ b/.github/workflows/cd-built-branch.yml @@ -0,0 +1,630 @@ +name: CD / Built Branch + +# Builds a project and force-pushes source + generated output to a deploy branch, for platforms +# that deploy from a branch rather than an artifact. See the README. +# +# Two invariants constrain any edit here: +# * the target branch is ONE commit whose parent is the source commit, so +# `git diff ..` is exactly the generated files; +# * every run republishes EVERY target, so the branch is always a complete tree. + +on: + workflow_call: + inputs: + targets: + description: >- + JSON array of build target objects. Each needs "dir" (repo-relative; "." for a flat repo) + and may override name, php-version, node-version, composer-flags, build-command, + publish-paths, verify-paths, composer, node, optional. A target whose "dir" does not + exist fails the run unless "optional": true is set — that keeps a typo'd or removed + directory from silently shrinking what gets published, while still allowing a target + that has not been scaffolded yet to be listed in advance. + type: string + default: '[{"dir": "."}]' + target-branch: + description: "Branch the built tree is force-pushed to. Must allow force-pushes. Never commit to it by hand — every run rewrites it." + type: string + default: "main-built" + source-ref: + description: "Commit, tag or branch to build and publish. Empty uses the commit that triggered the caller. Pass a full 40-character SHA to rebuild an older commit (rollback)." + type: string + default: "" + publish-paths: + description: >- + Newline-separated generated paths to publish, relative to each target's dir. Empty + auto-resolves to 'vendor/' for Composer targets plus 'assets/build/' for Node ones. Keep + identical to the gate's gated-paths. + type: string + default: "" + verify-paths: + description: >- + Newline-separated paths that must exist after the build, relative to each target's dir. + Directories must be non-empty. Empty auto-resolves to 'vendor/autoload.php' for Composer + targets. + type: string + default: "" + node-version: + description: "Default Node.js version for every target, overridable per target." + type: string + default: "22" + php-version: + description: "Default PHP version for every target, overridable per target." + type: string + default: "8.3" + composer-flags: + description: "Flags passed to composer install." + type: string + default: "--no-dev --prefer-dist --optimize-autoloader --no-progress --no-interaction --no-scripts" + build-command: + description: "Shell command that produces the production build, run in each target's dir. Empty defaults to 'npm run build:prod'. Only run for targets that have a package-lock.json." + type: string + default: "" + commit-subject: + description: "Subject line of the published commit. Empty uses 'build: publish built tree for '. The body always records the source ref, source commit and run URL." + type: string + default: "" + allow-rewind: + description: "Allow publishing a commit older than what the branch already publishes — a deliberate rollback. Off by default so an older tree cannot overwrite a newer one." + type: boolean + default: false + dry-run: + description: "Build, verify and create the commit, but do not push. Prints what would be published." + type: boolean + default: false + retention-days: + description: "Days to keep the intermediate build tarballs. Short by default — they are only a hand-off between jobs in the same run." + type: number + default: 3 + secrets: + push-token: + description: >- + Optional token with 'contents: write' used for the push. Defaults to GITHUB_TOKEN. Supply + one when the push must trigger further workflow runs (GITHUB_TOKEN pushes never do) or a + ruleset needs a bypass actor. + required: false + outputs: + published: + description: "'true' when a commit was pushed to the target branch, 'false' on a dry run." + value: ${{ jobs.publish.outputs.published }} + published-sha: + description: "SHA of the commit created on the target branch. Empty on a dry run." + value: ${{ jobs.publish.outputs.published-sha }} + source-sha: + description: "Resolved source commit that was built. This is the published commit's parent." + value: ${{ jobs.discover.outputs.source-sha }} + targets: + description: "Resolved build matrix as compact JSON — the targets that were actually built." + value: ${{ jobs.discover.outputs.targets }} + +# No workflow-level permissions: each job declares its own. The CALLER must grant +# `permissions: contents: write` — a called workflow can only reduce that grant. + +jobs: + discover: + name: Resolve build targets + runs-on: ubuntu-latest + permissions: + contents: read + outputs: + targets: ${{ steps.resolve.outputs.targets }} + count: ${{ steps.resolve.outputs.count }} + publish-paths: ${{ steps.resolve.outputs.publish-paths }} + source-sha: ${{ steps.resolve.outputs.source-sha }} + source-ref: ${{ steps.resolve.outputs.source-ref }} + skipped: ${{ steps.resolve.outputs.skipped }} + steps: + - name: Checkout source commit + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + ref: ${{ inputs.source-ref != '' && inputs.source-ref || github.sha }} + + - name: Resolve targets into a build matrix + id: resolve + shell: bash + env: + INPUT_TARGETS: ${{ inputs.targets }} + INPUT_PUBLISH_PATHS: ${{ inputs.publish-paths }} + INPUT_VERIFY_PATHS: ${{ inputs.verify-paths }} + INPUT_PHP_VERSION: ${{ inputs.php-version }} + INPUT_NODE_VERSION: ${{ inputs.node-version }} + INPUT_COMPOSER_FLAGS: ${{ inputs.composer-flags }} + INPUT_BUILD_COMMAND: ${{ inputs.build-command }} + SOURCE_REF: ${{ inputs.source-ref != '' && inputs.source-ref || github.ref_name }} + run: | + set -euo pipefail + source_sha="$(git rev-parse HEAD)" + + jq -e 'type == "array" and length > 0 and all(type == "object")' >/dev/null 2>&1 <<<"$INPUT_TARGETS" \ + || { echo "::error::'targets' must be a non-empty JSON array of objects (got: $INPUT_TARGETS)"; exit 1; } + + prefix_paths() { + local list="$1" label="$2" dir="$3" name="$4" out="" p + while IFS= read -r p; do + p="${p#./}"; p="${p%/}" + [ -n "$p" ] || continue + case "$p" in + /*) echo "::error::${label} '$p' (target '$name') must be relative to the target dir" >&2; return 1 ;; + *..*) echo "::error::${label} '$p' (target '$name') must not contain '..'" >&2; return 1 ;; + esac + case "/$p/" in + */node_modules/*) echo "::error::${label} '$p' (target '$name') includes node_modules, which is never published" >&2; return 1 ;; + esac + if [ "$dir" = "." ]; then out="${out}${p}"$'\n'; else out="${out}${dir}/${p}"$'\n'; fi + done <<< "$list" + printf '%s' "${out%$'\n'}" + } + + items='[]' + seen="" + skipped="" + while IFS= read -r item; do + dir="$(jq -r '.dir // ""' <<<"$item")" + [ -n "$dir" ] || { echo "::error::every 'targets' entry needs a \"dir\" key (offending entry: $item)"; exit 1; } + dir="${dir#./}"; dir="${dir%/}"; [ -n "$dir" ] || dir="." + case "$dir" in + /*) echo "::error::target dir '$dir' must be repo-relative, not absolute"; exit 1 ;; + *..*) echo "::error::target dir '$dir' must not contain '..'"; exit 1 ;; + esac + + optional="$(jq -r 'if has("optional") then (.optional | tostring) else "false" end' <<<"$item")" + if [ ! -d "$dir" ]; then + if [ "$optional" = "true" ]; then + echo "::warning::Skipping optional target '$dir' — it does not exist at ${source_sha}, so the published branch will NOT contain its build output." + skipped="${skipped}${dir}"$'\n' + continue + fi + echo "::error::target dir '$dir' does not exist at ${source_sha}. Add \"optional\": true if it is expected to appear later." + exit 1 + fi + + name="$(jq -r '.name // ""' <<<"$item")" + if [ -z "$name" ]; then + if [ "$dir" = "." ]; then name="root"; else name="${dir//\//-}"; fi + fi + case "$name" in + *[:/\\\"\<\>\|\*\?]*) echo "::error::target name '$name' contains a character an artifact name cannot hold (: / \\ \" < > | * ?)"; exit 1 ;; + esac + case "$seen" in + *"|${name}|"*) echo "::error::duplicate target name '$name' — give one of the entries an explicit \"name\"."; exit 1 ;; + esac + seen="${seen}|${name}|" + + # npm ci requires a lockfile, so its presence is the predicate for "needs Node". + composer=false; [ -f "$dir/composer.json" ] && composer=true + ov="$(jq -r 'if has("composer") then (.composer | tostring) else "" end' <<<"$item")" + [ -n "$ov" ] && composer="$ov" + + node=false; [ -f "$dir/package-lock.json" ] && node=true + ov="$(jq -r 'if has("node") then (.node | tostring) else "" end' <<<"$item")" + [ -n "$ov" ] && node="$ov" + + if [ "$node" = "true" ] && [ ! -f "$dir/package-lock.json" ]; then + echo "::error::target '$name' needs Node but '$dir/package-lock.json' is missing — npm ci requires a lockfile." + exit 1 + fi + if [ "$composer" != "true" ] && [ "$node" != "true" ]; then + echo "::error::target '$name' ($dir) has neither composer.json nor package-lock.json — nothing to build." + exit 1 + fi + + php_version="$(jq -r --arg d "$INPUT_PHP_VERSION" '.["php-version"] // $d' <<<"$item")" + node_version="$(jq -r --arg d "$INPUT_NODE_VERSION" '.["node-version"] // $d' <<<"$item")" + composer_flags="$(jq -r --arg d "$INPUT_COMPOSER_FLAGS" '.["composer-flags"] // $d' <<<"$item")" + build_command="$(jq -r --arg d "$INPUT_BUILD_COMMAND" '.["build-command"] // $d' <<<"$item")" + [ -n "$build_command" ] || build_command="npm run build:prod" + + publish="$(jq -r 'if has("publish-paths") then (.["publish-paths"] | if type == "array" then join("\n") else tostring end) else "" end' <<<"$item")" + [ -n "$publish" ] || publish="$INPUT_PUBLISH_PATHS" + if [ -z "$publish" ]; then + [ "$composer" = "true" ] && publish="vendor/" + [ "$node" = "true" ] && publish="${publish:+${publish}$'\n'}assets/build/" + fi + + verify="$(jq -r 'if has("verify-paths") then (.["verify-paths"] | if type == "array" then join("\n") else tostring end) else "" end' <<<"$item")" + [ -n "$verify" ] || verify="$INPUT_VERIFY_PATHS" + if [ -z "$verify" ] && [ "$composer" = "true" ]; then verify="vendor/autoload.php"; fi + + publish_abs="$(prefix_paths "$publish" "publish path" "$dir" "$name")" + verify_abs="$(prefix_paths "$verify" "verify path" "$dir" "$name")" + [ -n "$publish_abs" ] || { echo "::error::target '$name' resolved to zero publish paths."; exit 1; } + + echo "::notice::target '${name}' (${dir}) composer=${composer} node=${node} publishes: $(printf '%s' "$publish_abs" | paste -sd ' ' -)" + + entry="$(jq -nc \ + --arg name "$name" --arg dir "$dir" \ + --arg composer "$composer" --arg node "$node" \ + --arg php "$php_version" --arg nodever "$node_version" \ + --arg cflags "$composer_flags" --arg bcmd "$build_command" \ + --arg lock "${dir%/}/package-lock.json" \ + --arg pp "$publish_abs" --arg vp "$verify_abs" \ + '{name:$name, dir:$dir, composer:$composer, node:$node, + "php-version":$php, "node-version":$nodever, + "composer-flags":$cflags, "build-command":$bcmd, + lockfile:$lock, "publish-paths":$pp, "verify-paths":$vp}')" + items="$(jq -c --argjson e "$entry" '. + [$e]' <<<"$items")" + done < <(jq -c '.[]' <<<"$INPUT_TARGETS") + + count="$(jq 'length' <<<"$items")" + if [ "$count" -eq 0 ]; then + echo "::error::No build targets resolved. Publishing an incomplete tree is never safe, so this is a hard failure rather than a no-op." + exit 1 + fi + + all_publish="$(jq -r '[.[] | .["publish-paths"]] | join("\n")' <<<"$items")" + { + echo "targets=$(jq -c '{include: .}' <<<"$items")" + echo "count=${count}" + echo "source-sha=${source_sha}" + echo "source-ref=${SOURCE_REF}" + echo "skipped<<__WP_SHARED_SKIPPED__" + printf '%s\n' "${skipped%$'\n'}" + echo "__WP_SHARED_SKIPPED__" + echo "publish-paths<<__WP_SHARED_PATHS__" + printf '%s\n' "$all_publish" + echo "__WP_SHARED_PATHS__" + } >> "$GITHUB_OUTPUT" + + - name: Show resolved matrix + shell: bash + # Via env, never interpolated: the JSON is caller-controlled, so one apostrophe inside + # single quotes would end the quote and run the rest as shell. + env: + TARGETS: ${{ steps.resolve.outputs.targets }} + run: printf '%s' "$TARGETS" | jq . + + build: + name: Build ${{ matrix.name }} + needs: [discover] + runs-on: ubuntu-latest + timeout-minutes: 30 + # Read-only on purpose: this job runs third-party dependency code, so it must never hold a + # writable token. Only publish does, and it runs no dependency code. + permissions: + contents: read + # No `if:` guard: discover already fails on zero targets, and a guard here would turn that + # into a green run that publishes nothing. + strategy: + # Not fail-fast: surface every broken target in one run. + fail-fast: false + matrix: ${{ fromJSON(needs.discover.outputs.targets) }} + defaults: + run: + working-directory: ${{ matrix.dir }} + steps: + - name: Checkout source commit + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + ref: ${{ needs.discover.outputs.source-sha }} + + - name: Set up PHP + if: ${{ matrix.composer == 'true' }} + uses: shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f # 2.37.0 + with: + php-version: ${{ matrix.php-version }} + coverage: none + tools: composer + # Raises the GitHub API rate limit when composer install resolves a VCS repo. + github-token: ${{ github.token }} + + - name: Set up Node.js + if: ${{ matrix.node == 'true' }} + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 + with: + node-version: ${{ matrix.node-version }} + cache: npm + # setup-node is a JS action and ignores defaults.run.working-directory, so without + # this it looks for the lockfile at the repo root. + cache-dependency-path: ${{ matrix.lockfile }} + + - name: Install Composer dependencies + if: ${{ matrix.composer == 'true' }} + run: composer install ${{ matrix.composer-flags }} + + - name: Install npm dependencies + if: ${{ matrix.node == 'true' }} + run: npm ci + + - name: Build production assets + if: ${{ matrix.node == 'true' }} + run: ${{ matrix.build-command }} + + - name: Verify build output + working-directory: ${{ github.workspace }} + shell: bash + env: + TARGET_NAME: ${{ matrix.name }} + PUBLISH_PATHS: ${{ matrix.publish-paths }} + VERIFY_PATHS: ${{ matrix.verify-paths }} + run: | + set -euo pipefail + failed=0 + check() { + if [ ! -e "$1" ]; then + echo "::error::${2} '$1' does not exist after building '${TARGET_NAME}'." + failed=1 + elif [ -d "$1" ] && [ -z "$(find "$1" -mindepth 1 -print -quit)" ]; then + echo "::error::${2} '$1' is an empty directory after building '${TARGET_NAME}'." + failed=1 + fi + } + while IFS= read -r p; do [ -n "$p" ] && check "$p" "Publish path" || true; done <<< "$PUBLISH_PATHS" + while IFS= read -r p; do [ -n "$p" ] && check "$p" "Verify path" || true; done <<< "$VERIFY_PATHS" + [ "$failed" -eq 0 ] || exit 1 + echo "Build output for '${TARGET_NAME}' verified." + + - name: Archive build output + working-directory: ${{ github.workspace }} + shell: bash + env: + TARGET_NAME: ${{ matrix.name }} + TARBALL: ${{ runner.temp }}/${{ matrix.name }}.tgz + PUBLISH_PATHS: ${{ matrix.publish-paths }} + run: | + set -euo pipefail + # tar FROM THE REPO ROOT so member paths stay repo-relative. Do NOT pass these + # directories to upload-artifact instead: it re-roots at their common ancestor, so + # themes/foo/vendor arrives as vendor/ and two targets' trees silently merge. + paths=() + while IFS= read -r p; do + [ -n "$p" ] || continue + paths+=("$p") + done <<< "$PUBLISH_PATHS" + [ "${#paths[@]}" -gt 0 ] || { echo "::error::no publish paths to archive for '${TARGET_NAME}'"; exit 1; } + tar -czf "$TARBALL" --owner=0 --group=0 --numeric-owner -- "${paths[@]}" + ls -lh "$TARBALL" + + - name: Upload build output + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: cd-built-branch-${{ matrix.name }} + path: ${{ runner.temp }}/${{ matrix.name }}.tgz + retention-days: ${{ inputs.retention-days }} + if-no-files-found: error + + publish: + name: Publish to ${{ inputs.target-branch }} + needs: [discover, build] + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: write + # Serialise publishes per target branch. Not cancel-in-progress: a cancelled run tells us + # nothing about whether its push landed. + concurrency: + group: cd-built-branch-${{ github.repository }}-${{ inputs.target-branch }} + cancel-in-progress: false + outputs: + published: ${{ steps.publish.outputs.published }} + published-sha: ${{ steps.publish.outputs.published-sha }} + steps: + - name: Checkout source commit + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + ref: ${{ needs.discover.outputs.source-sha }} + # Full history: merge-base needs it, and the server rejects a push from a shallow clone. + fetch-depth: 0 + token: ${{ secrets.push-token || github.token }} + + - name: Download build tarballs + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + path: ${{ runner.temp }}/built + pattern: cd-built-branch-* + merge-multiple: true + + - name: Extract build tarballs + shell: bash + env: + DOWNLOAD_DIR: ${{ runner.temp }}/built + EXPECTED: ${{ needs.discover.outputs.count }} + run: | + set -euo pipefail + shopt -s nullglob + tarballs=("$DOWNLOAD_DIR"/*.tgz) + if [ "${#tarballs[@]}" -ne "$EXPECTED" ]; then + echo "::error::Downloaded ${#tarballs[@]} build tarball(s) but ${EXPECTED} target(s) were resolved. Refusing to publish a partial tree." + printf ' - %s\n' "${tarballs[@]}" + exit 1 + fi + for t in "${tarballs[@]}"; do + echo "Extracting $(basename "$t")" + # Member paths are repo-relative, so extracting at the workspace root restores them. + tar -xzf "$t" -C "$GITHUB_WORKSPACE" --no-same-owner + done + + - name: Publish built tree + id: publish + shell: bash + env: + TARGET_BRANCH: ${{ inputs.target-branch }} + SOURCE_SHA: ${{ needs.discover.outputs.source-sha }} + SOURCE_REF: ${{ needs.discover.outputs.source-ref }} + # Set only when the caller named a ref: tells a deliberate rollback from a lost race. + EXPLICIT_SOURCE_REF: ${{ inputs.source-ref }} + PUBLISH_PATHS: ${{ needs.discover.outputs.publish-paths }} + COMMIT_SUBJECT: ${{ inputs.commit-subject }} + ALLOW_REWIND: ${{ inputs.allow-rewind }} + DRY_RUN: ${{ inputs.dry-run }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + run: | + set -euo pipefail + + git config user.name 'github-actions[bot]' + git config user.email '41898282+github-actions[bot]@users.noreply.github.com' + + # ls-remote exit 2 means "no such branch"; a bare `git fetch` cannot tell that apart. + set +e + git ls-remote --exit-code --heads origin "$TARGET_BRANCH" >/dev/null 2>&1 + ls_status=$? + set -e + case "$ls_status" in + 0) branch_exists=true ;; + 2) branch_exists=false ;; + *) echo "::error::Could not query origin for '${TARGET_BRANCH}' (git ls-remote exit ${ls_status})."; exit 1 ;; + esac + + remote_tip="" + if [ "$branch_exists" = "true" ]; then + git fetch --no-tags origin "+refs/heads/${TARGET_BRANCH}:refs/remotes/origin/${TARGET_BRANCH}" + remote_tip="$(git rev-parse "refs/remotes/origin/${TARGET_BRANCH}")" + + # Something newer is already live, so publishing would move the branch backwards. + # No source-ref means a run that lost a push race: skip green, the live tree is + # correct. An explicit ref means a deliberate rollback, which needs allow-rewind. + published_parent="$(git rev-parse --verify --quiet "refs/remotes/origin/${TARGET_BRANCH}^" || true)" + if [ -n "$published_parent" ] && [ "$published_parent" != "$SOURCE_SHA" ] \ + && git merge-base --is-ancestor "$SOURCE_SHA" "$published_parent"; then + if [ "$ALLOW_REWIND" = "true" ]; then + echo "::warning::Rewinding '${TARGET_BRANCH}' from ${published_parent} to ${SOURCE_SHA} (allow-rewind is true)." + elif [ -z "$EXPLICIT_SOURCE_REF" ]; then + echo "::notice::Superseded — '${TARGET_BRANCH}' already publishes ${published_parent}," \ + "a descendant of this run's ${SOURCE_SHA}. A newer run got there first, so the live" \ + "tree is already ahead of this one. Nothing to do." + { + echo "published=false" + echo "published-sha=" + } >> "$GITHUB_OUTPUT" + exit 0 + else + echo "::error::'${TARGET_BRANCH}' already publishes ${published_parent}, which is newer" \ + "than the requested ${SOURCE_SHA}. Refusing to move the deploy branch backwards." \ + "Re-run with allow-rewind: true to publish an older commit on purpose." + exit 1 + fi + fi + else + echo "::notice::'${TARGET_BRANCH}' does not exist yet — this run creates it." + fi + + git checkout -B "$TARGET_BRANCH" "$SOURCE_SHA" + + # A dependency installed from source leaves a nested .git, which `git add` records as a + # gitlink — publishing an empty directory in place of the package. + while IFS= read -r path; do + [ -n "$path" ] && [ -e "$path" ] || continue + while IFS= read -r nested; do + echo "::warning::Removing nested git directory '${nested}' before staging (a gitlink would publish an empty directory)." + rm -rf "$nested" + done < <(find "$path" -name .git -prune -print) + done <<< "$PUBLISH_PATHS" + + # --force because publish paths are gitignored. Only these paths are staged. + missing=() + while IFS= read -r path; do + [ -n "$path" ] || continue + if [ -e "$path" ]; then + git add --force -- "$path" + else + missing+=("$path") + fi + done <<< "$PUBLISH_PATHS" + if [ "${#missing[@]}" -gt 0 ]; then + echo "::error::Expected build output is missing after extracting the tarballs:" + printf ' - %s\n' "${missing[@]}" + exit 1 + fi + + if git diff --cached --quiet; then + echo "::error::Nothing was staged for '${TARGET_BRANCH}'. Either the tarballs were empty," \ + "or the source branch already commits the generated output — it must be gitignored and" \ + "blocked by ci-build-artifact-gate.yml." + exit 1 + fi + + short="$(git rev-parse --short "$SOURCE_SHA")" + subject="$COMMIT_SUBJECT" + [ -n "$subject" ] || subject="build: publish built tree for ${short}" + + body="Generated by ${GITHUB_WORKFLOW} — ${RUN_URL} + + Source ref: ${SOURCE_REF} + Source commit: ${SOURCE_SHA} + + Do not commit to '${TARGET_BRANCH}' directly. Every run of this workflow force-pushes a + single commit whose parent is the source commit, so any manual work here is lost without + warning. Change the source branch instead." + + git commit --quiet -m "$subject" -m "$body" + git --no-pager show --stat --oneline HEAD | head -n 30 + + if [ "$DRY_RUN" = "true" ]; then + echo "::notice::dry-run: the commit above was NOT pushed to '${TARGET_BRANCH}'." + { + echo "published=false" + echo "published-sha=" + } >> "$GITHUB_OUTPUT" + exit 0 + fi + + # --force-with-lease so a concurrent push fails loudly rather than being clobbered. + # Plain --force when creating the branch, where there is no tip to lease against. + if [ "$branch_exists" = "true" ]; then + push_args=(--force-with-lease="refs/heads/${TARGET_BRANCH}:${remote_tip}") + else + push_args=(--force) + fi + if ! git push "${push_args[@]}" origin "HEAD:refs/heads/${TARGET_BRANCH}"; then + echo "::error::Push to '${TARGET_BRANCH}' was rejected. Check that the caller granted" \ + "'permissions: contents: write', that the branch allows force-pushes (no protection rule" \ + "or ruleset blocking them), and that another run did not publish concurrently." + exit 1 + fi + { + echo "published=true" + echo "published-sha=$(git rev-parse HEAD)" + } >> "$GITHUB_OUTPUT" + + - name: Write run summary + if: ${{ always() && steps.publish.conclusion != 'skipped' }} + shell: bash + env: + TARGET_BRANCH: ${{ inputs.target-branch }} + SOURCE_SHA: ${{ needs.discover.outputs.source-sha }} + SOURCE_REF: ${{ needs.discover.outputs.source-ref }} + COUNT: ${{ needs.discover.outputs.count }} + SKIPPED: ${{ needs.discover.outputs.skipped }} + PUBLISH_PATHS: ${{ needs.discover.outputs.publish-paths }} + PUBLISHED: ${{ steps.publish.outputs.published }} + PUBLISHED_SHA: ${{ steps.publish.outputs.published-sha }} + DRY_RUN: ${{ inputs.dry-run }} + run: | + set -euo pipefail + { + echo "## Built branch" + echo + if [ "${PUBLISHED:-}" = "true" ]; then + echo "Force-pushed \`${TARGET_BRANCH}\` at \`${PUBLISHED_SHA}\`." + elif [ "$DRY_RUN" = "true" ]; then + echo "**Dry run** — the commit was created but not pushed." + else + echo "Publish did not complete. See the job log above." + fi + echo + echo "| | |" + echo "|---|---|" + echo "| Source ref | \`${SOURCE_REF}\` |" + echo "| Source commit | \`${SOURCE_SHA}\` |" + echo "| Target branch | \`${TARGET_BRANCH}\` |" + echo "| Targets built | ${COUNT} |" + echo + if printf '%s' "${SKIPPED:-}" | grep -q '[^[:space:]]'; then + echo "> **Optional targets skipped — their output is NOT on \`${TARGET_BRANCH}\`:**" + echo + printf '%s\n' "$SKIPPED" | sed '/^[[:space:]]*$/d; s/^/> - `/; s/$/`/' + echo + fi + echo "
Published paths" + echo + echo '```' + printf '%s\n' "$PUBLISH_PATHS" + echo '```' + echo + echo "
" + echo + echo "Review exactly what was generated:" + echo + echo '```bash' + echo "git fetch origin ${TARGET_BRANCH}" + echo "git diff --stat ${SOURCE_SHA}..origin/${TARGET_BRANCH}" + echo '```' + } >> "$GITHUB_STEP_SUMMARY" diff --git a/.github/workflows/cd-github-release.yml b/.github/workflows/cd-github-release.yml index e22cf1c..37415ae 100644 --- a/.github/workflows/cd-github-release.yml +++ b/.github/workflows/cd-github-release.yml @@ -23,6 +23,13 @@ on: description: "Mark the GitHub Release as a prerelease." type: boolean default: false + working-dir: + description: >- + Directory the project lives in, relative to the repo root. A path prefix, not a working + directory: it prefixes changelog-path only. The attached files come from the artifact, + already scoped by its build. + type: string + default: "." permissions: contents: write @@ -47,8 +54,22 @@ jobs: env: TAG: ${{ inputs.tag }} CHANGELOG_PATH: ${{ inputs.changelog-path }} + WORKING_DIR: ${{ inputs.working-dir }} run: | set -euo pipefail + + # working-dir is a path prefix, not a cwd: only the changelog is read from the source. + # Without it a monorepo silently picks up the ROOT changelog, which still parses. + dir="${WORKING_DIR:-.}"; dir="${dir#./}"; dir="${dir%/}"; [ -n "$dir" ] || dir="." + # Reject traversal — this file's contents become the public Release body. + case "$dir" in + /*) echo "::error::working-dir must be relative to the repo root (got '$WORKING_DIR')"; exit 1 ;; + *..*) echo "::error::working-dir must not contain '..' (got '$WORKING_DIR')"; exit 1 ;; + esac + if [ "$dir" != "." ]; then + CHANGELOG_PATH="${dir}/${CHANGELOG_PATH#./}" + fi + if [ ! -f "$CHANGELOG_PATH" ]; then echo "::error::Changelog not found at '$CHANGELOG_PATH'" exit 1 diff --git a/.github/workflows/cd-wp-org.yml b/.github/workflows/cd-wp-org.yml index 4fcf85a..8e586f6 100644 --- a/.github/workflows/cd-wp-org.yml +++ b/.github/workflows/cd-wp-org.yml @@ -23,6 +23,13 @@ on: description: "Run the full deploy except the final SVN commit." type: boolean default: false + working-dir: + description: >- + Directory the project lives in, relative to the repo root. A path prefix, not a working + directory: it prefixes assets-path only. The deployed files come from the artifact, + already scoped by its build. + type: string + default: "." secrets: WP_ORG_USERNAME: description: "WordPress.org account username with commit access to the plugin." @@ -82,8 +89,21 @@ jobs: shell: bash env: ASSETS_PATH: ${{ inputs.assets-path }} + WORKING_DIR: ${{ inputs.working-dir }} run: | set -euo pipefail + + # working-dir is a path prefix, not a cwd: only assets-path is read from the source. + dir="${WORKING_DIR:-.}"; dir="${dir#./}"; dir="${dir%/}"; [ -n "$dir" ] || dir="." + # Reject traversal — this is synced to the plugin's PUBLIC wordpress.org /assets/. + case "$dir" in + /*) echo "::error::working-dir must be relative to the repo root (got '$WORKING_DIR')"; exit 1 ;; + *..*) echo "::error::working-dir must not contain '..' (got '$WORKING_DIR')"; exit 1 ;; + esac + if [ -n "$ASSETS_PATH" ] && [ "$dir" != "." ]; then + ASSETS_PATH="${dir}/${ASSETS_PATH#./}" + fi + if [ -n "$ASSETS_PATH" ] && [ -d "$ASSETS_PATH" ]; then echo "assets_dir=$ASSETS_PATH" >> "$GITHUB_OUTPUT" else diff --git a/.github/workflows/ci-build-artifact-gate.yml b/.github/workflows/ci-build-artifact-gate.yml index b0fe05b..0df7fff 100644 --- a/.github/workflows/ci-build-artifact-gate.yml +++ b/.github/workflows/ci-build-artifact-gate.yml @@ -49,9 +49,15 @@ jobs: exit 0 fi - WORKING_DIR="${WORKING_DIR%/}" - if [[ -n "$WORKING_DIR" && "$WORKING_DIR" != "." ]]; then - ANCHORED="^${WORKING_DIR}/(${PATTERN})" + # Normalise AND regex-escape: an unescaped "." matches any character, and a leading + # "./" yields "^./themes/foo/" which matches nothing — silently passing the gate. + DIR="${WORKING_DIR:-.}" + DIR="${DIR#./}" + DIR="${DIR%/}" + [[ -n "$DIR" ]] || DIR="." + if [[ "$DIR" != "." ]]; then + DIR_RE=$(printf '%s' "$DIR" | sed 's/[][\\.|^$()*+?{}]/\\&/g') + ANCHORED="^${DIR_RE}/(${PATTERN})" else ANCHORED="^(${PATTERN})" fi diff --git a/.github/workflows/ci-build.yml b/.github/workflows/ci-build.yml index c67a5bd..7caf6b2 100644 --- a/.github/workflows/ci-build.yml +++ b/.github/workflows/ci-build.yml @@ -68,6 +68,8 @@ jobs: with: node-version: ${{ inputs.node-version }} cache: npm + # setup-node is a JS action: without this it looks for the lockfile at the repo root. + cache-dependency-path: ${{ inputs.working-dir != '.' && format('{0}/package-lock.json', inputs.working-dir) || '' }} - name: Set up PHP if: ${{ inputs.install-composer-deps }} diff --git a/.github/workflows/ci-detect-changes.yml b/.github/workflows/ci-detect-changes.yml index 381c525..a113db6 100644 --- a/.github/workflows/ci-detect-changes.yml +++ b/.github/workflows/ci-detect-changes.yml @@ -15,40 +15,51 @@ on: description: "Explicit git ref to diff HEAD against. Empty lets the CLI resolve it from the PR base or push event." type: string default: "" - secrets: - wp-tooling-token: - description: "Token with read access to the private rtCamp/wp-tooling repo, used to clone the interim CLI. Required while that repo is private; omit once @rtcamp/wp-tooling is published or public." - required: false + working-dir: + description: >- + Directory the project lives in, relative to the repo root. A path scope, not a working + directory: the diff is always taken from the repo root. Restricts the css/js/php outputs + to it and makes those file lists relative to it; total/ignored/gha stay repo-wide. + type: string + default: "." + wp-tooling-ref: + description: "Git ref of rtCamp/wp-tooling's npm/wp-tooling branch to install the CLI from. Defaults to a pinned commit; override to track the branch tip. Obsolete once the package is on npm." + type: string + # npm/wp-tooling @ 2026-07-30. Pinned so that branch moving cannot change what CI runs. + default: "324e3a2ee59134de8dfddf36ba04ff2ca38e9afe" outputs: total-count: - description: "Number of changed files after the ignore filter." + description: >- + Number of changed files after the ignore filter. Always repo-wide, never restricted by + working-dir: the CLI buckets only CSS/JS/PHP/GHA, so a scoped total would drop every other + file type. value: ${{ jobs.detect.outputs.total-count }} ignored-count: - description: "Number of changed files dropped by the ignore filter." + description: "Number of changed files dropped by the ignore filter. Always repo-wide — NOT restricted by working-dir." value: ${{ jobs.detect.outputs.ignored-count }} css-count: - description: "Number of changed CSS/SCSS files." + description: "Number of changed CSS/SCSS files under working-dir." value: ${{ jobs.detect.outputs.css-count }} js-count: - description: "Number of changed JS files." + description: "Number of changed JS files under working-dir." value: ${{ jobs.detect.outputs.js-count }} php-count: - description: "Number of changed PHP files." + description: "Number of changed PHP files under working-dir." value: ${{ jobs.detect.outputs.php-count }} gha-count: - description: "Number of changed GitHub Actions workflow files." + description: "Number of changed GitHub Actions workflow files. Always repo-wide: workflow files only exist at .github/workflows/ in the repo root." value: ${{ jobs.detect.outputs.gha-count }} css-files: - description: "Newline-separated changed CSS/SCSS files. Pass straight into ci-lint-css.yml's changed-files." + description: "Newline-separated changed CSS/SCSS files, relative to working-dir. Pass straight into ci-lint-css.yml's changed-files, provided that workflow is given the same working-dir." value: ${{ jobs.detect.outputs.css-files }} js-files: - description: "Newline-separated changed JS files. Pass straight into ci-lint-js.yml's changed-files." + description: "Newline-separated changed JS files, relative to working-dir. Pass straight into ci-lint-js.yml's changed-files, provided that workflow is given the same working-dir." value: ${{ jobs.detect.outputs.js-files }} php-files: - description: "Newline-separated changed PHP files. Pass straight into ci-lint-php.yml's changed-files." + description: "Newline-separated changed PHP files, relative to working-dir. Pass straight into ci-lint-php.yml's changed-files, provided that workflow is given the same working-dir." value: ${{ jobs.detect.outputs.php-files }} gha-files: - description: "Newline-separated changed GitHub Actions workflow files." + description: "Newline-separated changed GitHub Actions workflow files, repo-root-relative. Always repo-wide — NOT restricted by working-dir." value: ${{ jobs.detect.outputs.gha-files }} permissions: @@ -59,15 +70,17 @@ jobs: name: Detect changes runs-on: ubuntu-latest outputs: + # css/js/php come from the scope step; total/ignored/gha stay repo-wide on detect. total-count: ${{ steps.detect.outputs.total-count }} ignored-count: ${{ steps.detect.outputs.ignored-count }} - css-count: ${{ steps.detect.outputs.css-count }} - js-count: ${{ steps.detect.outputs.js-count }} - php-count: ${{ steps.detect.outputs.php-count }} + css-count: ${{ steps.scope.outputs.css-count }} + js-count: ${{ steps.scope.outputs.js-count }} + php-count: ${{ steps.scope.outputs.php-count }} + # Workflow files only exist at the repo root, so scoping gha would always yield 0. gha-count: ${{ steps.detect.outputs.gha-count }} - css-files: ${{ steps.detect.outputs.css-files }} - js-files: ${{ steps.detect.outputs.js-files }} - php-files: ${{ steps.detect.outputs.php-files }} + css-files: ${{ steps.scope.outputs.css-files }} + js-files: ${{ steps.scope.outputs.js-files }} + php-files: ${{ steps.scope.outputs.php-files }} gha-files: ${{ steps.detect.outputs.gha-files }} steps: - name: Checkout repository @@ -81,26 +94,18 @@ jobs: node-version: ${{ inputs.node-version }} - name: Install wp-tooling - # Interim install until @rtcamp/wp-tooling is published. The CLI lives in the - # rtCamp/wp-tooling monorepo under node-packages/wp-tooling (npm can't install a git - # subdirectory), so clone the branch and install the subpath into a job-local prefix - # on PATH — no global. --install-links copies (vs symlinks) so the temp clone can be - # removed; the repo is private, so authenticate with wp-tooling-token when provided. - # TODO(wp-tooling publish): replace with `npm install --prefix … @rtcamp/wp-tooling`. + # @rtcamp/wp-tooling is not on the npm registry yet, so it is installed from the + # npm/wp-tooling branch, which carries the package at its root. Installed into a + # job-local prefix put on PATH rather than globally. + # TODO(wp-tooling publish): swap the git ref for a semver range and drop wp-tooling-ref. shell: bash env: - WP_TOOLING_TOKEN: ${{ secrets.wp-tooling-token }} + WP_TOOLING_REF: ${{ inputs.wp-tooling-ref }} run: | set -euo pipefail - src="$(mktemp -d)" - trap 'rm -rf "$src"' EXIT - repo="https://github.com/rtCamp/wp-tooling.git" - if [ -n "${WP_TOOLING_TOKEN:-}" ]; then - repo="https://x-access-token:${WP_TOOLING_TOKEN}@github.com/rtCamp/wp-tooling.git" - fi - git clone --depth 1 --branch release/v1.0.0 "$repo" "$src" prefix="$RUNNER_TEMP/wp-tooling" - npm install --install-links --prefix "$prefix" "$src/node-packages/wp-tooling" + npm install --ignore-scripts --no-audit --no-fund --prefix "$prefix" \ + "github:rtCamp/wp-tooling#${WP_TOOLING_REF}" echo "$prefix/node_modules/.bin" >> "$GITHUB_PATH" - name: Detect changed files @@ -119,3 +124,97 @@ jobs: args+=(--base "$BASE_REF") fi wp-tooling detect-changes "${args[@]}" + + # The detector emits repo-root-relative paths but the linters run with cwd = working-dir, + # so an unscoped list resolves to //. At working-dir '.' this is a pure + # pass-through, counts included. + - name: Scope results to working-dir + id: scope + shell: bash + env: + WORKING_DIR: ${{ inputs.working-dir }} + TOTAL_COUNT: ${{ steps.detect.outputs.total-count }} + CSS_FILES: ${{ steps.detect.outputs.css-files }} + JS_FILES: ${{ steps.detect.outputs.js-files }} + PHP_FILES: ${{ steps.detect.outputs.php-files }} + CSS_COUNT: ${{ steps.detect.outputs.css-count }} + JS_COUNT: ${{ steps.detect.outputs.js-count }} + PHP_COUNT: ${{ steps.detect.outputs.php-count }} + run: | + set -euo pipefail + + dir="${WORKING_DIR:-.}" + dir="${dir#./}" + dir="${dir%/}" + [ -n "$dir" ] || dir="." + + if [ "$dir" != "." ] && [ ! -d "$dir" ]; then + echo "::error::working-dir '${WORKING_DIR}' does not exist in this repository." + exit 1 + fi + + # Non-empty lines only, so an empty list counts 0 rather than 1. + count() { printf '%s' "${1-}" | awk 'NF{n++} END{print n+0}'; } + + # Random delimiter so a crafted filename cannot forge a step output. + emit() { + local name="$1" val="${2-}" delim + delim="ghadelim_$(head -c 16 /dev/urandom | od -An -tx1 | tr -d ' \n')" + { + printf '%s<<%s\n' "$name" "$delim" + if [ -n "$val" ]; then + printf '%s\n' "$val" + fi + printf '%s\n' "$delim" + } >> "$GITHUB_OUTPUT" + } + + # Prefix stripped so a consumer with cwd=$dir can open them. String matching, not + # regex, so metacharacters in a path need no escaping. + scope() { + local p out="" + while IFS= read -r p; do + [ -n "$p" ] || continue + case "$p" in + "$dir"/*) out="${out}${p#"$dir"/}"$'\n' ;; + esac + done <<< "${1-}" + # No trailing newline: the lint workflows xargs this, so one would pass an extra + # empty path to the linter. + printf '%s' "${out%$'\n'}" + } + + if [ "$dir" = "." ]; then + # Pure pass-through — the CLI's own counts are authoritative, so do not recount. + emit css-files "$CSS_FILES" + emit js-files "$JS_FILES" + emit php-files "$PHP_FILES" + { + echo "css-count=${CSS_COUNT}" + echo "js-count=${JS_COUNT}" + echo "php-count=${PHP_COUNT}" + } >> "$GITHUB_OUTPUT" + exit 0 + fi + + css="$(scope "$CSS_FILES")" + js="$(scope "$JS_FILES")" + php="$(scope "$PHP_FILES")" + + css_n="$(count "$css")"; js_n="$(count "$js")"; php_n="$(count "$php")" + echo "::notice::Scoped to '${dir}/': css=${css_n} js=${js_n} php=${php_n}." + + if [ "${TOTAL_COUNT:-0}" -gt 0 ] && [ "$css_n" -eq 0 ] && [ "$js_n" -eq 0 ] && [ "$php_n" -eq 0 ]; then + echo "::warning::${TOTAL_COUNT} file(s) changed in this repository but none are in scope" \ + "for '${dir}', so no lint, test or build job ran for it. If this unit depends on code" \ + "outside '${dir}', that dependency is not covered by this call." + fi + + emit css-files "$css" + emit js-files "$js" + emit php-files "$php" + { + echo "css-count=${css_n}" + echo "js-count=${js_n}" + echo "php-count=${php_n}" + } >> "$GITHUB_OUTPUT" diff --git a/.github/workflows/ci-lint-css.yml b/.github/workflows/ci-lint-css.yml index 0a84c6c..6080071 100644 --- a/.github/workflows/ci-lint-css.yml +++ b/.github/workflows/ci-lint-css.yml @@ -39,6 +39,8 @@ jobs: with: node-version: ${{ inputs.node-version }} cache: npm + # setup-node is a JS action: without this it looks for the lockfile at the repo root. + cache-dependency-path: ${{ inputs.working-dir != '.' && format('{0}/package-lock.json', inputs.working-dir) || '' }} - name: Install npm dependencies run: npm ci diff --git a/.github/workflows/ci-lint-js.yml b/.github/workflows/ci-lint-js.yml index 6c14539..475841b 100644 --- a/.github/workflows/ci-lint-js.yml +++ b/.github/workflows/ci-lint-js.yml @@ -43,6 +43,8 @@ jobs: with: node-version: ${{ inputs.node-version }} cache: npm + # setup-node is a JS action: without this it looks for the lockfile at the repo root. + cache-dependency-path: ${{ inputs.working-dir != '.' && format('{0}/package-lock.json', inputs.working-dir) || '' }} - name: Install npm dependencies run: npm ci diff --git a/.github/workflows/ci-lint-php.yml b/.github/workflows/ci-lint-php.yml index fea76f3..300a37c 100644 --- a/.github/workflows/ci-lint-php.yml +++ b/.github/workflows/ci-lint-php.yml @@ -39,10 +39,6 @@ on: description: "Working directory for monorepos." type: string default: "." - secrets: - packages-token: - description: "Optional token with read access to private Composer source repos (e.g. rtCamp/wp-framework). Passed to setup-php so `composer install` can resolve private VCS dependencies. Omit for projects with only public/Packagist deps." - required: false permissions: contents: read @@ -64,9 +60,8 @@ jobs: php-version: ${{ inputs.php-version }} tools: composer, cs2pr coverage: none - # Authenticates `composer install` for private VCS deps. Falls back to the - # default GITHUB_TOKEN (rate-limit help only) when no packages-token is given. - github-token: ${{ secrets.packages-token || github.token }} + # Raises the GitHub API rate limit when composer install resolves a VCS repo. + github-token: ${{ github.token }} - name: Validate composer.json if: ${{ inputs.validate-composer }} @@ -80,7 +75,9 @@ jobs: uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0 with: path: ${{ steps.composer-cache.outputs.dir }} - key: composer-${{ runner.os }}-php${{ inputs.php-version }}-${{ hashFiles('**/composer.lock') }} + # Scoped to working-dir: a repo-wide '**/composer.lock' glob keys every target in + # a monorepo off the same hash, so they share (and clobber) one cache entry. + key: composer-${{ runner.os }}-php${{ inputs.php-version }}-${{ hashFiles(format('{0}/composer.lock', inputs.working-dir)) }} restore-keys: | composer-${{ runner.os }}-php${{ inputs.php-version }}- diff --git a/.github/workflows/ci-test-a11y.yml b/.github/workflows/ci-test-a11y.yml index 2cfa760..71ea290 100644 --- a/.github/workflows/ci-test-a11y.yml +++ b/.github/workflows/ci-test-a11y.yml @@ -39,6 +39,8 @@ jobs: with: node-version: ${{ inputs.node-version }} cache: npm + # setup-node is a JS action: without this it looks for the lockfile at the repo root. + cache-dependency-path: ${{ inputs.working-dir != '.' && format('{0}/package-lock.json', inputs.working-dir) || '' }} - name: Install npm dependencies run: npm ci diff --git a/.github/workflows/ci-test-build-artifact.yml b/.github/workflows/ci-test-build-artifact.yml index 853b3b4..d007921 100644 --- a/.github/workflows/ci-test-build-artifact.yml +++ b/.github/workflows/ci-test-build-artifact.yml @@ -35,6 +35,12 @@ on: description: "Comma-separated wp doctor check names excluded from the error gate. Defaults to production-oriented checks that wp-env's dev defaults always trip (e.g. WP_DEBUG being on)." type: string default: "constant-wp-debug-falsy" + working-dir: + description: >- + Working directory for monorepos. wp-env runs here and the artifact is downloaded into it. + Note: a .wp-env.override.json is written here, overwriting any existing file of that name. + type: string + default: "." permissions: contents: read @@ -44,6 +50,9 @@ jobs: name: Boot artifact in wp-env runs-on: ubuntu-latest timeout-minutes: 10 + defaults: + run: + working-directory: ${{ inputs.working-dir }} steps: - name: Checkout repository uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 @@ -57,7 +66,9 @@ jobs: uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 with: name: ${{ inputs.artifact-name }} - path: artifact + # download-artifact is a JS action: its path is workspace-relative, so it has to + # carry working-dir itself. + path: ${{ inputs.working-dir }}/artifact - name: Write wp-env override shell: bash diff --git a/.github/workflows/ci-test-js.yml b/.github/workflows/ci-test-js.yml index 45b22c7..14fb4e5 100644 --- a/.github/workflows/ci-test-js.yml +++ b/.github/workflows/ci-test-js.yml @@ -39,6 +39,8 @@ jobs: with: node-version: ${{ inputs.node-version }} cache: npm + # setup-node is a JS action: without this it looks for the lockfile at the repo root. + cache-dependency-path: ${{ inputs.working-dir != '.' && format('{0}/package-lock.json', inputs.working-dir) || '' }} - name: Resolve Jest cache directory id: jest-cache diff --git a/.github/workflows/ci-test-php.yml b/.github/workflows/ci-test-php.yml index 47039b1..510559f 100644 --- a/.github/workflows/ci-test-php.yml +++ b/.github/workflows/ci-test-php.yml @@ -12,7 +12,9 @@ on: type: string default: "22" wp-version: - description: "WordPress core version for wp-env, e.g. '6.8' (resolved as WordPress/WordPress#). Empty uses the version from the consumer's .wp-env.json. Ignored when use-wp-env is false." + description: >- + WordPress core version for wp-env, e.g. '6.8' (resolved as WordPress/WordPress#). + Empty uses the version from the consumer's .wp-env.json. Ignored when use-wp-env is false. type: string default: "" use-wp-env: @@ -31,10 +33,6 @@ on: description: "Working directory for monorepos." type: string default: "." - secrets: - packages-token: - description: "Optional token with read access to private Composer source repos (e.g. rtCamp/wp-framework). Authenticates `composer install` on the host (via setup-php) and inside the wp-env container. Omit for projects with only public/Packagist deps." - required: false permissions: contents: read @@ -62,9 +60,8 @@ jobs: php-version: ${{ inputs.php-version }} coverage: none tools: composer - # Authenticates the host `composer install` for private VCS deps. Falls back to - # the default GITHUB_TOKEN (rate-limit help only) when no packages-token is given. - github-token: ${{ secrets.packages-token || github.token }} + # Raises the GitHub API rate limit when composer install resolves a VCS repo. + github-token: ${{ github.token }} - name: Set up Node.js if: ${{ inputs.use-wp-env }} @@ -72,6 +69,8 @@ jobs: with: node-version: ${{ inputs.node-version }} cache: npm + # setup-node is a JS action: without this it looks for the lockfile at the repo root. + cache-dependency-path: ${{ inputs.working-dir != '.' && format('{0}/package-lock.json', inputs.working-dir) || '' }} - name: Install Composer dependencies run: composer install ${{ inputs.composer-flags }} @@ -84,23 +83,6 @@ jobs: if: ${{ inputs.use-wp-env }} run: npm run wp-env start - # Configure Composer auth inside the container so the in-container `composer install` - # (e.g. a pretest:php hook) can resolve private VCS deps. Secrets can't be used in - # `if:`, so guard on the env var inside the script — a no-op when no token is set. - - name: Configure Composer auth in wp-env - if: ${{ inputs.use-wp-env }} - env: - PACKAGES_TOKEN: ${{ secrets.packages-token }} - run: | - if [ -n "$PACKAGES_TOKEN" ]; then - # Only configure in-container auth when the container actually has Composer. - # Some consumers run PHPUnit against a host-installed vendor/ with no in-container - # composer, where an unconditional `composer config` would fail the job. - if npx wp-env run tests-cli -- sh -lc 'command -v composer >/dev/null 2>&1'; then - npx wp-env run tests-cli -- composer config --global github-oauth.github.com "$PACKAGES_TOKEN" - fi - fi - - name: Run PHPUnit run: ${{ inputs.test-command != '' && inputs.test-command || (inputs.use-wp-env && 'npm run test:php' || 'vendor/bin/phpunit') }} diff --git a/.github/workflows/version-monitor.yml b/.github/workflows/version-monitor.yml index 9f437e1..59dda01 100644 --- a/.github/workflows/version-monitor.yml +++ b/.github/workflows/version-monitor.yml @@ -19,10 +19,12 @@ on: description: "Comma-separated GitHub usernames to assign to the draft PR" type: string default: "" - secrets: - wp-tooling-token: - description: "Token with read access to the private rtCamp/wp-tooling repo, used to clone the interim CLI. Required while that repo is private." - required: false + wp-tooling-ref: + description: "Git ref of rtCamp/wp-tooling's npm/wp-tooling branch to install the CLI from. Defaults to a pinned commit; override to track the branch tip. Obsolete once the package is on npm." + type: string + # npm/wp-tooling @ 2026-07-30. Pinned rather than tracking the branch tip so a change + # in that repo cannot alter what every consumer's CI executes with no change here. + default: "324e3a2ee59134de8dfddf36ba04ff2ca38e9afe" # Serialise runs per consumer repo so a scheduled run and a manual dispatch can't # race on the same version-monitor/YYYY-MM branch. @@ -56,24 +58,18 @@ jobs: node-version: ${{ inputs.node-version }} - name: Install wp-tooling - # Interim until @rtcamp/wp-tooling is published: the CLI is a subpath of the private - # rtCamp/wp-tooling monorepo (npm can't install a git subdir), so clone the branch and - # copy-install it (--install-links, not a symlink) into a job-local prefix on PATH. - # Auth the clone with wp-tooling-token when set; a plain clone works only if public. + # @rtcamp/wp-tooling is not on the npm registry yet, so it is installed from the + # npm/wp-tooling branch, which carries the package at its root. Installed into a + # job-local prefix put on PATH rather than globally. + # TODO(wp-tooling publish): swap the git ref for a semver range and drop wp-tooling-ref. shell: bash env: - WP_TOOLING_TOKEN: ${{ secrets.wp-tooling-token }} + WP_TOOLING_REF: ${{ inputs.wp-tooling-ref }} run: | set -euo pipefail - src="$(mktemp -d)" - trap 'rm -rf "$src"' EXIT - repo="https://github.com/rtCamp/wp-tooling.git" - if [ -n "${WP_TOOLING_TOKEN:-}" ]; then - repo="https://x-access-token:${WP_TOOLING_TOKEN}@github.com/rtCamp/wp-tooling.git" - fi - git clone --depth 1 --branch release/v1.0.0 "$repo" "$src" prefix="$RUNNER_TEMP/wp-tooling" - npm install --install-links --prefix "$prefix" "$src/node-packages/wp-tooling" + npm install --ignore-scripts --no-audit --no-fund --prefix "$prefix" \ + "github:rtCamp/wp-tooling#${WP_TOOLING_REF}" echo "$prefix/node_modules/.bin" >> "$GITHUB_PATH" - name: Detect version updates @@ -102,7 +98,9 @@ jobs: # Partial results: proceed to a PR, but record it to fail the job at the end. if [ "${status}" -ne 0 ]; then echo "detectors_errored=true" >> "$GITHUB_OUTPUT" - echo "::warning::version-monitor: one or more detectors errored (exit ${status}); proceeding with ${count} partial result(s). The run will be marked failed so the blind source is investigated — see this step's log for details." + echo "::warning::version-monitor: one or more detectors errored (exit ${status});" \ + "proceeding with ${count} partial result(s). The run will be marked failed so the blind" \ + "source is investigated — see this step's log for details." else echo "detectors_errored=false" >> "$GITHUB_OUTPUT" fi @@ -145,7 +143,10 @@ jobs: # PR. Fail with the report so the bumps aren't silently dropped. if: steps.detect.outputs.count != '0' && steps.pr.outputs.pull-request-number == '' run: | - echo "::error::version-monitor detected ${{ steps.detect.outputs.count }} update(s) but produced no file changes, so no PR was opened — every bump is a major-version bump (skipped pending manual review) or a value could not be matched in its file. Apply these manually:" + echo "::error::version-monitor detected ${{ steps.detect.outputs.count }} update(s) but" \ + "produced no file changes, so no PR was opened — every bump is a major-version bump" \ + "(skipped pending manual review) or a value could not be matched in its file." \ + "Apply these manually:" cat "$RUNNER_TEMP/pr-body.md" exit 1 @@ -153,5 +154,7 @@ jobs: # A detector was blind this run — fail even if a partial-results PR opened. if: always() && steps.detect.outputs.detectors_errored == 'true' run: | - echo "::error::version-monitor: one or more detectors errored this run, so the results are incomplete. Any PR opened above carries only the updates that were found. See the 'Detect version updates' step log for the failing detector(s)." + echo "::error::version-monitor: one or more detectors errored this run, so the results are" \ + "incomplete. Any PR opened above carries only the updates that were found. See the" \ + "'Detect version updates' step log for the failing detector(s)." exit 1 diff --git a/.github/workflows/wp-ci.yml b/.github/workflows/wp-ci.yml index be90877..2ccdd44 100644 --- a/.github/workflows/wp-ci.yml +++ b/.github/workflows/wp-ci.yml @@ -4,11 +4,18 @@ on: workflow_call: inputs: project-type: - description: "Project shape that selects the job preset: plugin | theme | package." + description: "Shape of the project at working-dir, selecting the job preset: plugin | theme | package. Describes the one unit this call targets, not the repository." type: string required: true + working-dir: + description: >- + Directory holding the unit this run targets, relative to the repo root. '.' (default) is a + single-project repo; in a monorepo call this workflow once per unit. See the monorepo + recipes in the README. + type: string + default: "." skip: - description: "Comma-separated job ids to drop, e.g. 'a11y,test-php'. Ids: lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact, a11y." + description: "Comma-separated job ids to drop, e.g. 'a11y,test-php'. Ids: lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact, a11y, artifact-gate." type: string default: "" enable-phpstan: @@ -36,46 +43,87 @@ on: type: string default: '[]' build-artifact-path: - description: "Path to the packaged, installable plugin/theme dir the build produces, e.g. 'dist/my-plugin/'. Required to run the build-artifact install test; empty skips it (the default build emits bare build/, which is not installable)." + description: >- + Path to the packaged, installable plugin/theme dir the build produces, e.g. + 'dist/my-plugin/'. Required to run the build-artifact install test; empty skips it (the + default build emits bare build/, which is not installable). type: string default: "" build-artifact-slug: - description: "Plugin/theme slug to activate in the build-artifact test. Empty uses the repo name." + description: "Plugin/theme slug to activate in the build-artifact test. Empty uses working-dir's basename in a monorepo, or the repo name at the root." + type: string + default: "" + ignore-paths: + description: "Regex of paths detect-changes excludes from its counts and file lists. Empty uses the CLI's built-in ignore set." type: string default: "" - secrets: - wp-tooling-token: - description: "Token with read access to the private rtCamp/wp-tooling repo, forwarded to detect-changes to install the interim CLI. Required while that repo is private." - required: false - packages-token: - description: "Token with read access to private Composer source repos (e.g. rtCamp/wp-framework), forwarded to lint-php and test-php to authenticate `composer install`. Omit for projects with only public/Packagist deps. A single token may serve both wp-tooling-token and packages-token." - required: false - -# Cancel an in-progress run when the same ref is pushed again (e.g. a force-push). + base-ref: + description: "Explicit git ref detect-changes diffs HEAD against. Empty lets the CLI resolve it from the PR base or push event." + type: string + default: "" + wp-tooling-ref: + description: "Git ref of rtCamp/wp-tooling's npm/wp-tooling branch that detect-changes installs the CLI from. Defaults to a pinned commit; override to track the branch tip." + type: string + # Keep in step with ci-detect-changes.yml's default. + default: "324e3a2ee59134de8dfddf36ba04ff2ca38e9afe" + gated-paths: + description: >- + Newline-separated path prefixes, relative to working-dir, whose contents must not be + committed in a PR (e.g. 'assets/build/'). Empty skips the artifact-gate job; set it only + where CI generates the build output. + type: string + default: "" + +# project-type and working-dir are in the group so a monorepo caller invoking this workflow +# once per unit does not have one call cancel its siblings. Uses the RAW input because +# workflow-level concurrency cannot see job outputs. concurrency: - group: ci-${{ github.ref }} + group: ci-${{ github.ref }}-${{ inputs.project-type }}-${{ inputs.working-dir }} cancel-in-progress: true permissions: contents: read jobs: - # Fail fast on a bad project-type or matrix input — a typo otherwise silently runs nothing. validate-inputs: name: Validate inputs runs-on: ubuntu-latest + outputs: + # Children must consume this, NOT inputs.working-dir: an unnormalised "" or + # "./themes/foo" breaks cache-dependency-path and defeats artifact-gate's anchor. + working-dir: ${{ steps.check.outputs.working-dir }} + preset: ${{ steps.check.outputs.preset }} + artifact-name: ${{ steps.check.outputs.artifact-name }} + artifact-slug: ${{ steps.check.outputs.artifact-slug }} + install-path: ${{ steps.check.outputs.install-path }} steps: - - name: Check project-type and test-php matrix inputs + - name: Check inputs and resolve derived values + id: check + shell: bash env: PROJECT_TYPE: ${{ inputs.project-type }} + WORKING_DIR: ${{ inputs.working-dir }} PHP_VERSIONS: ${{ inputs.php-versions }} WP_VERSIONS: ${{ inputs.wp-versions }} TEST_PHP_EXCLUDE: ${{ inputs.test-php-exclude }} + ARTIFACT_SLUG: ${{ inputs.build-artifact-slug }} + REPO_NAME: ${{ github.event.repository.name }} run: | + set -euo pipefail + + # The preset as data, in one place, rather than a disjunction repeated in eight `if:`s. case "$PROJECT_TYPE" in - plugin|theme|package) ;; + plugin|theme) preset="lint-css,lint-js,lint-php,test-js,test-php,build,build-artifact,a11y,artifact-gate" ;; + package) preset="lint-php,test-php,artifact-gate" ;; *) echo "::error::project-type must be one of: plugin, theme, package (got '$PROJECT_TYPE')"; exit 1 ;; esac + + dir="${WORKING_DIR:-.}"; dir="${dir#./}"; dir="${dir%/}"; [ -n "$dir" ] || dir="." + case "$dir" in + /*) echo "::error::working-dir must be relative to the repo root (got '$WORKING_DIR')"; exit 1 ;; + *..*) echo "::error::working-dir must not contain '..' (got '$WORKING_DIR')"; exit 1 ;; + esac + echo "$PHP_VERSIONS" | jq -e 'type == "array" and length > 0' >/dev/null \ || { echo "::error::php-versions must be a non-empty JSON array (got '$PHP_VERSIONS') — use skip: test-php to disable PHP tests"; exit 1; } echo "$WP_VERSIONS" | jq -e 'type == "array" and length > 0' >/dev/null \ @@ -83,66 +131,97 @@ jobs: echo "$TEST_PHP_EXCLUDE" | jq -e 'type == "array"' >/dev/null \ || { echo "::error::test-php-exclude must be a JSON array (got '$TEST_PHP_EXCLUDE')"; exit 1; } - # Backbone: never skippable. Emits the per-bucket change counts and file lists the - # jobs below gate on. + # upload-artifact rejects '/' in a name and 409s on a duplicate within a run, which + # two units sharing one name would hit. + if [ "$dir" = "." ]; then + artifact_name="wp-ci-build" + else + artifact_name="wp-ci-build-$(printf '%s' "$dir" | tr -c 'a-zA-Z0-9._-' '-')" + fi + + # A monorepo's repo name is rarely the slug, so prefer the target directory's basename. + if [ -n "$ARTIFACT_SLUG" ]; then slug="$ARTIFACT_SLUG" + elif [ "$dir" != "." ]; then slug="$(basename "$dir")" + else slug="$REPO_NAME" + fi + + if [ "$PROJECT_TYPE" = "theme" ]; then install_path="wp-content/themes"; else install_path="wp-content/plugins"; fi + + { + echo "working-dir=${dir}" + echo "preset=,${preset}," + echo "artifact-name=${artifact_name}" + echo "artifact-slug=${slug}" + echo "install-path=${install_path}" + } >> "$GITHUB_OUTPUT" + + echo "::notice::Target '${dir}' (${PROJECT_TYPE}) — artifact '${artifact_name}', slug '${slug}'." + detect-changes: name: Detect changes needs: [validate-inputs] uses: ./.github/workflows/ci-detect-changes.yml - secrets: - wp-tooling-token: ${{ secrets.wp-tooling-token }} + with: + # A path scope, not a cwd — the detector still diffs from the repo root. + working-dir: ${{ needs.validate-inputs.outputs.working-dir }} + ignore-paths: ${{ inputs.ignore-paths }} + base-ref: ${{ inputs.base-ref }} + wp-tooling-ref: ${{ inputs.wp-tooling-ref }} lint-css: name: Lint CSS - needs: [detect-changes] + needs: [validate-inputs, detect-changes] if: >- needs.detect-changes.outputs.css-count > 0 - && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && contains(needs.validate-inputs.outputs.preset, ',lint-css,') && !contains(format(',{0},', inputs.skip), ',lint-css,') uses: ./.github/workflows/ci-lint-css.yml with: changed-files: ${{ needs.detect-changes.outputs.css-files }} + working-dir: ${{ needs.validate-inputs.outputs.working-dir }} lint-js: name: Lint JS - needs: [detect-changes] + needs: [validate-inputs, detect-changes] if: >- needs.detect-changes.outputs.js-count > 0 - && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && contains(needs.validate-inputs.outputs.preset, ',lint-js,') && !contains(format(',{0},', inputs.skip), ',lint-js,') uses: ./.github/workflows/ci-lint-js.yml with: changed-files: ${{ needs.detect-changes.outputs.js-files }} + working-dir: ${{ needs.validate-inputs.outputs.working-dir }} lint-php: name: Lint PHP - needs: [detect-changes] + needs: [validate-inputs, detect-changes] if: >- needs.detect-changes.outputs.php-count > 0 - && (inputs.project-type == 'plugin' || inputs.project-type == 'theme' || inputs.project-type == 'package') + && contains(needs.validate-inputs.outputs.preset, ',lint-php,') && !contains(format(',{0},', inputs.skip), ',lint-php,') uses: ./.github/workflows/ci-lint-php.yml with: changed-files: ${{ needs.detect-changes.outputs.php-files }} enable-phpstan: ${{ inputs.enable-phpstan }} - secrets: - packages-token: ${{ secrets.packages-token }} + working-dir: ${{ needs.validate-inputs.outputs.working-dir }} test-js: name: Test JS - needs: [detect-changes] + needs: [validate-inputs, detect-changes] if: >- needs.detect-changes.outputs.js-count > 0 - && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && contains(needs.validate-inputs.outputs.preset, ',test-js,') && !contains(format(',{0},', inputs.skip), ',test-js,') uses: ./.github/workflows/ci-test-js.yml + with: + working-dir: ${{ needs.validate-inputs.outputs.working-dir }} test-php: name: Test PHP - needs: [detect-changes] + needs: [validate-inputs, detect-changes] if: >- needs.detect-changes.outputs.php-count > 0 - && (inputs.project-type == 'plugin' || inputs.project-type == 'theme' || inputs.project-type == 'package') + && contains(needs.validate-inputs.outputs.preset, ',test-php,') && !contains(format(',{0},', inputs.skip), ',test-php,') # Matrix: php-versions × wp-versions, minus test-php-exclude cells. With use-wp-env # (default) each cell boots @wordpress/env, pinning PHP + WP core; with use-wp-env @@ -158,49 +237,65 @@ jobs: php-version: ${{ matrix.php }} wp-version: ${{ matrix.wp }} use-wp-env: ${{ inputs.use-wp-env }} - secrets: - packages-token: ${{ secrets.packages-token }} + working-dir: ${{ needs.validate-inputs.outputs.working-dir }} build: name: Build - needs: [detect-changes] + needs: [validate-inputs, detect-changes] if: >- (needs.detect-changes.outputs.css-count > 0 || needs.detect-changes.outputs.js-count > 0 || needs.detect-changes.outputs.php-count > 0) - && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && contains(needs.validate-inputs.outputs.preset, ',build,') && !contains(format(',{0},', inputs.skip), ',build,') uses: ./.github/workflows/ci-build.yml with: # Only upload when build-artifact runs (it consumes this); otherwise build just compiles. upload-artifact: ${{ inputs.build-artifact-path != '' }} - artifact-name: wp-ci-build + artifact-name: ${{ needs.validate-inputs.outputs.artifact-name }} artifact-path: ${{ inputs.build-artifact-path }} retention-days: 1 + working-dir: ${{ needs.validate-inputs.outputs.working-dir }} - # Boots the packaged artifact in real WordPress to prove it installs. Opt-in: runs only - # when build-artifact-path points at an installable dir, since the default build emits - # bare build/. slug defaults to the repo name; install-path follows project-type. + # Opt-in: runs only when build-artifact-path points at an installable dir, since the default + # build emits bare build/. build-artifact: name: Test build artifact - needs: [detect-changes, build] + needs: [validate-inputs, detect-changes, build] if: >- inputs.build-artifact-path != '' && (needs.detect-changes.outputs.css-count > 0 || needs.detect-changes.outputs.js-count > 0 || needs.detect-changes.outputs.php-count > 0) - && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && contains(needs.validate-inputs.outputs.preset, ',build-artifact,') && !contains(format(',{0},', inputs.skip), ',build-artifact,') uses: ./.github/workflows/ci-test-build-artifact.yml with: - artifact-name: wp-ci-build - slug: ${{ inputs.build-artifact-slug != '' && inputs.build-artifact-slug || github.event.repository.name }} - install-path: ${{ inputs.project-type == 'theme' && 'wp-content/themes' || 'wp-content/plugins' }} + artifact-name: ${{ needs.validate-inputs.outputs.artifact-name }} + slug: ${{ needs.validate-inputs.outputs.artifact-slug }} + install-path: ${{ needs.validate-inputs.outputs.install-path }} + working-dir: ${{ needs.validate-inputs.outputs.working-dir }} # Opt-in: a11y is slow and needs pa11y config, so it stays off unless run-a11y is set # (wire it to the 'Run a11y' label at the caller). Matches the label-gated convention. a11y: name: Test accessibility - needs: [detect-changes] + needs: [validate-inputs, detect-changes] if: >- inputs.run-a11y && (needs.detect-changes.outputs.css-count > 0 || needs.detect-changes.outputs.js-count > 0 || needs.detect-changes.outputs.php-count > 0) - && (inputs.project-type == 'plugin' || inputs.project-type == 'theme') + && contains(needs.validate-inputs.outputs.preset, ',a11y,') && !contains(format(',{0},', inputs.skip), ',a11y,') uses: ./.github/workflows/ci-test-a11y.yml + with: + working-dir: ${{ needs.validate-inputs.outputs.working-dir }} + + # Opt-in via gated-paths: fails a PR that commits build output, which is only correct where + # CI produces it. Needs only validate-inputs, so it runs alongside detect-changes. + artifact-gate: + name: Block committed build artifacts + needs: [validate-inputs] + if: >- + inputs.gated-paths != '' + && contains(needs.validate-inputs.outputs.preset, ',artifact-gate,') + && !contains(format(',{0},', inputs.skip), ',artifact-gate,') + uses: ./.github/workflows/ci-build-artifact-gate.yml + with: + gated-paths: ${{ inputs.gated-paths }} + working-dir: ${{ needs.validate-inputs.outputs.working-dir }} diff --git a/CHANGELOG.md b/CHANGELOG.md index dd84400..bc0e5bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,8 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## Unreleased +### Changed + +- **Breaking for callers that pass it:** the `wp-tooling-token` secret is removed from `ci-detect-changes.yml`, `version-monitor.yml` and `wp-ci.yml`. `rtCamp/wp-tooling` is public, so the CLI now installs straight from its `npm/wp-tooling` branch with no token. A caller still passing `wp-tooling-token:` fails with `Invalid input, wp-tooling-token is not defined in the referenced workflow` — delete the line. A new `wp-tooling-ref` input (forwarded through `wp-ci.yml`) pins the install to a commit SHA and installs with `--ignore-scripts`, so a change on that branch cannot alter what your CI runs; override it to track the tip. The package is still not on the npm registry, so the install remains a git ref. +- **Breaking for callers that pass it:** the `packages-token` secret is removed from `ci-lint-php.yml`, `ci-test-php.yml` and `wp-ci.yml`. `rtCamp/wp-framework` is public, so no known private Composer dependency is left to authenticate. A caller still passing `packages-token:` fails with `Invalid input, packages-token is not defined in the referenced workflow` — delete the line. `setup-php` still receives `github-token: ${{ github.token }}` for the API rate limit, which never depended on the secret, and `ci-test-php.yml` drops the wp-env Composer-auth step that existed only to forward it into the container. +- Monorepo fixes across the CI leaves. All six `setup-node` steps that use `cache: npm` now pass `cache-dependency-path`, and `ci-lint-php.yml`'s Composer cache key is scoped to `/composer.lock`. `ci-build-artifact-gate.yml` normalises **and** regex-escapes `working-dir` before anchoring its pattern — previously a `./`-prefixed or metacharacter-containing value matched nothing, so the gate passed green on a PR that committed build output. `ci-test-build-artifact.yml` gains `working-dir`. +- `cd-github-release.yml` and `cd-wp-org.yml` gain `working-dir` as a **path prefix, not a working directory**: it scopes only the source-tree paths they read (`changelog-path`, `assets-path`), since the deployed files come from an already unit-scoped artifact. Both previously fell back to the repo root in a monorepo and failed silently — another unit's `CHANGELOG.md` still parses, and a missing `.wordpress-org` only emits a notice. Both now reject absolute and `..` paths. `cd-s3.yml` and `cd-split-composer-packages.yml` are unchanged. + ### Added +- `cd-built-branch.yml`: reusable workflow that builds a project and force-pushes **source plus generated output** (Composer `vendor/`, compiled `assets/build/`) to a dedicated branch, for platforms that deploy from a git branch rather than an artifact. Three jobs: `discover` resolves the `targets` JSON into a build matrix, `build` builds each target in parallel, and `publish` force-pushes a single commit whose parent is the source commit — so `git diff ..` is exactly the generated files, and rollback is a re-run from an older SHA. Every run republishes every target, so the branch is always a complete tree; a target whose `dir` is missing fails the run unless marked `"optional": true`. A push-triggered run that loses a race ends **green** with a `::notice::` because the newer tree is already live, while an explicit `source-ref` pointing backwards errors unless `allow-rewind: true`. Only `publish` holds `contents: write`, so the job that executes third-party dependency code never has a writable token; the caller must grant `permissions: contents: write`. See the README for the full contract and caveats. Inputs: `targets`, `target-branch`, `source-ref`, `publish-paths`, `verify-paths`, `node-version`, `php-version`, `composer-flags`, `build-command`, `commit-subject`, `allow-rewind`, `dry-run`, `retention-days`. Optional secret: `push-token`, for when a push must trigger further workflow runs, which the default `GITHUB_TOKEN` never does. Outputs: `published`, `published-sha`, `source-sha`, `targets`. - `ci-test-php.yml`: reusable PHPUnit workflow with a `use-wp-env` toggle (default `true`) for WordPress integration tests via `@wordpress/env`, or standalone PHPUnit for Composer-only packages and libraries. In wp-env mode, `php-version` is pinned into the container via `WP_ENV_PHP_VERSION` and `wp-version` (when non-empty) sets `WP_ENV_CORE=WordPress/WordPress#` (both set at job scope, not `$GITHUB_ENV`, so a caller's matrix can drive the PHP and WordPress core version per cell without newline-injection risk); an empty `wp-version` uses the consumer's `.wp-env.json`. Inputs: `php-version`, `node-version`, `wp-version`, `use-wp-env`, `test-command`, `composer-flags`, `working-dir`. The `test-command` default is empty and selects `npm run test:php` in wp-env mode, `vendor/bin/phpunit` standalone. - `ci-test-js.yml` — reusable Jest unit-test workflow with optional cross-run cache (`enable-cache`), monorepo support (`working-dir`), and a consumer-overridable command (`test-command`). Replaces the copy-pasted `unit-tests-js` job from the legacy `Test and Measure` workflow. - `ci-test-a11y.yml` — reusable pa11y-ci accessibility test workflow. Order: `npm ci` → build → `wp-env start` → pa11y → `wp-env stop` (with `if: always()` so cleanup runs on failure). Inputs: `node-version`, `build-command`, `test-command`, `working-dir`. Trigger-agnostic — consumers wire the `Run a11y` label gate at the caller level. @@ -19,8 +27,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `cd-github-release.yml`: reusable workflow that publishes a GitHub Release on a `v*.*.*` tag push. Downloads the named build artifact, extracts the release body from the matching `CHANGELOG.md` section (tolerant heading match — `## v1.2.3` or `## [1.2.3]` with an optional trailing date; `## Unreleased` is never matched and a missing/empty section fails the workflow rather than publishing empty notes), then creates the Release via the `gh` CLI (no third-party action) with `--verify-tag` so a non-existent tag errors instead of silently creating one. Attaches the artifact files and honours `draft` / `prerelease`. Requires the caller to grant `contents: write`; the artifact must be produced in the same run. Inputs: `tag`, `artifact-name`, `changelog-path`, `draft`, `prerelease`. - `cd-s3.yml`: reusable workflow that distributes a private/customer plugin to an S3 bucket on a release tag. Downloads the named build artifact and uploads its single `.zip` to a versioned key (`s3:///.zip`) plus an always-overwritten `latest.zip` (fails if the artifact contains zero or more than one `.zip`, so a misconfigured `artifact-path` can never deploy the wrong bundle), then optionally invalidates `/*` on a CloudFront distribution when `cloudfront-distribution-id` is set. Uses the official `aws-actions/configure-aws-credentials` (SHA-pinned to v6.1.3) with static access keys and the preinstalled AWS CLI — no third-party action, no checkout. User inputs pass through step `env:` (injection-safe). Inputs: `tag`, `artifact-name`, `bucket`, `prefix`, `cloudfront-distribution-id`, `region`. Required secrets: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (need `s3:PutObject` on the prefix, plus `cloudfront:CreateInvalidation` when invalidating). - `cd-wp-org.yml`: reusable workflow that deploys a plugin to the WordPress.org directory over SVN on a release tag, wrapping `10up/action-wordpress-plugin-deploy` (SHA-pinned to v2.3.0). Downloads the named build artifact, fails fast unless `readme.txt`'s `Stable tag` matches the tag (leading `v` stripped), then deploys the artifact to `trunk/` + `tags//` via the action's `BUILD_DIR` and syncs `assets-path` (default `.wordpress-org`, read from the checked-out repo) to SVN `/assets/`. The action is configured through environment variables (`SLUG`, `VERSION`, `ASSETS_DIR`, `BUILD_DIR`, `SVN_USERNAME`, `SVN_PASSWORD`); `dry-run` runs everything except the SVN commit; deploying a version that already exists fails (WP.org tags are immutable). Inputs: `slug`, `tag`, `artifact-name`, `assets-path`, `dry-run`. Required secrets: `WP_ORG_USERNAME`, `WP_ORG_PASSWORD`. -- `ci-detect-changes.yml`: reusable pre-run workflow that buckets a PR/push's changed files and exposes per-bucket change counts (`total-count`, `ignored-count`, `css-count`, `js-count`, `php-count`, `gha-count`) and file lists (`css-files`, `js-files`, `php-files`, `gha-files`) as workflow outputs. Wraps the `wp-tooling detect-changes` CLI (`--output github --include-files`); base-ref resolution and bucket rules live in the CLI. wp-tooling is installed by cloning `rtCamp/wp-tooling` at `release/v1.0.0` and running `npm install --install-links --prefix "$RUNNER_TEMP/wp-tooling"` on the `node-packages/wp-tooling` subpath, then adding `$RUNNER_TEMP/wp-tooling/node_modules/.bin` to `PATH` (no global install) until `@rtcamp/wp-tooling` is published. The `*-files` outputs feed straight into the lint workflows' `changed-files` input so the orchestrator can lint only changed files. Runs unconditionally — count-based gating is the caller's job. Inputs: `node-version`, `ignore-paths`, `base-ref`. +- `ci-detect-changes.yml`: reusable pre-run workflow that buckets a PR/push's changed files and exposes per-bucket change counts (`total-count`, `ignored-count`, `css-count`, `js-count`, `php-count`, `gha-count`) and file lists (`css-files`, `js-files`, `php-files`, `gha-files`) as workflow outputs. Wraps the `wp-tooling detect-changes` CLI; base-ref resolution and bucket rules live there. The `*-files` outputs feed straight into the lint workflows' `changed-files` input so the orchestrator can lint only changed files. A `working-dir` input restricts the css/js/php counts and file lists to one directory and re-roots those lists against it — a **path scope, not a working directory**, since the diff is always taken from the repo root while the linters run *inside* that directory. At `working-dir: "."` it is a pure pass-through, counts included, so single-project consumers keep the CLI's own numbers. `total-count`/`ignored-count` and `gha-count`/`gha-files` stay repo-wide: the CLI buckets only CSS/JS/PHP/GHA, and workflow files only exist at `.github/workflows/` in the repo root. A `::warning::` fires when the repository changed but nothing is in scope for the unit, so a green run that verified nothing is at least visible. Runs unconditionally — count-based gating is the caller's job. Inputs: `node-version`, `ignore-paths`, `base-ref`, `working-dir`, `wp-tooling-ref`. - `ci-lint-css.yml`: reusable Stylelint workflow. Runs `lint-command` over the whole project, or only the files in `changed-files` when that input is non-empty (selective linting). Inputs: `node-version`, `lint-command`, `changed-files`, `working-dir`. - `ci-lint-js.yml`: reusable ESLint workflow with optional `package.json` validation (`validate-package-json`, default `true`). `changed-files` scopes ESLint to just the listed files; empty lints the whole project. Inputs: `node-version`, `lint-command`, `changed-files`, `validate-package-json`, `working-dir`. - `ci-lint-php.yml`: reusable PHPCS workflow with `cs2pr` annotations and an optional PHPStan pass (`enable-phpstan`, default `false`). `changed-files` scopes PHPCS to the listed files; PHPStan always runs whole-project because it analyses cross-file dependencies. Default `composer-flags` keep `--no-scripts` for supply-chain hygiene. Inputs: `php-version`, `enable-phpstan`, `phpcs-command`, `changed-files`, `phpstan-command`, `phpstan-level`, `composer-flags`, `validate-composer`, `working-dir`. -- `wp-ci.yml`: CI orchestrator that routes to the individual CI workflows from one `project-type` input (`plugin` \| `theme` \| `package`). `detect-changes` runs first as a never-skippable backbone; every other job is gated on its per-bucket change counts (`*-count > 0`) and feeds the `*-files` outputs into the linters' `changed-files`, so a job runs only when its file type changed and only when its preset includes it. A `skip` input drops jobs by id with comma-exact matching (`skip: build` does not also drop `build-artifact`). The `test-php` job fans out over the cross-product of `php-versions` × `wp-versions` (both JSON arrays), with `test-php-exclude` (JSON array of `{php, wp}`) dropping cells; each cell calls `ci-test-php.yml` with that pair. `use-wp-env` (default `true`) boots `@wordpress/env` per cell, pinning the container's `WP_ENV_PHP_VERSION`/`WP_ENV_CORE` — suiting plugins, themes, and packages whose suite tests against WordPress (e.g. via `wp-phpunit`); set it `false` for a pure Composer library to run standalone PHPUnit, where the `wp` dimension is inert. An empty-string `wp-versions` entry uses the consumer's `.wp-env.json` default; defaults run a single PHP 8.3 leg. `enable-phpstan` (default `false`) opts the `lint-php` job into a PHPStan pass. A `validate-inputs` job runs first and fails the run fast on an invalid `project-type` or a non-array matrix input (a typo would otherwise silently run nothing). The `build-artifact` install test is opt-in: it runs only when `build-artifact-path` points at the packaged installable dir the build produces (`build-artifact-slug` overrides the activated slug), so the default pipeline never fails trying to boot the bare `build/` output. Concurrency cancels duplicate runs on the same ref. Inputs: `project-type`, `skip`, `enable-phpstan`, `use-wp-env`, `php-versions`, `wp-versions`, `test-php-exclude`, `build-artifact-path`, `build-artifact-slug`. Covers the lint/test/build pipeline previously hand-wired in the "Test and Measure" workflow; code coverage reporting is not yet included (v1.x follow-up). +- `wp-ci.yml`: CI orchestrator that routes to the individual CI workflows from one `project-type` input (`plugin` \| `theme` \| `package`). `detect-changes` runs first as a never-skippable backbone; every other job is gated on its per-bucket change counts and fed the matching `*-files` list, so a job runs only when its file type changed and its preset includes it. `skip` drops jobs by id with comma-exact matching (`skip: build` does not also drop `build-artifact`). `test-php` fans out over `php-versions` × `wp-versions` minus `test-php-exclude` cells; `use-wp-env` (default `true`) boots `@wordpress/env` per cell, pinning `WP_ENV_PHP_VERSION`/`WP_ENV_CORE`, while `false` runs standalone PHPUnit for a pure Composer library and leaves the `wp` dimension inert. `enable-phpstan` (default `false`) opts `lint-php` into a PHPStan pass. A `validate-inputs` job fails the run fast on an invalid `project-type` or a non-array matrix input, resolves the job preset from a single table, and derives a per-unit `artifact-name` (two units uploading the same name in one run is a `409 Conflict`) and a `build-artifact-slug` defaulting to `basename(working-dir)`. The `build-artifact` install test is opt-in via `build-artifact-path`; `artifact-gate` is opt-in via `gated-paths`, since failing a PR for committed build output is only correct where CI produces it. A `working-dir` input targets one unit in a monorepo and is forwarded to every child job, so `project-type` describes the unit at `working-dir` rather than the repository — a repo with a theme and two plugins calls this workflow three times, or matrixes over the units in one caller job. Concurrency includes `project-type` and `working-dir` so sibling calls do not cancel each other. Inputs: `project-type`, `working-dir`, `skip`, `enable-phpstan`, `use-wp-env`, `php-versions`, `wp-versions`, `test-php-exclude`, `build-artifact-path`, `build-artifact-slug`, `ignore-paths`, `base-ref`, `gated-paths`, `wp-tooling-ref`. Code coverage reporting is not yet included (v1.x follow-up). diff --git a/CLAUDE.md b/CLAUDE.md index 041dddb..6d6defe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -47,30 +47,33 @@ Before adding any new action or step: check if an official option already exists ``` .github/workflows/ - ci-detect-changes.yml Pre-run: changed file detection - ci-lint-css.yml Stylelint - ci-lint-js.yml ESLint + package.json validation - ci-lint-php.yml PHPCS + optional PHPStan - ci-test-js.yml Jest - ci-test-php.yml PHPUnit (wp-env or standalone) - ci-test-a11y.yml pa11y-ci WCAG2AA (label-triggered by default) - ci-build.yml Build + optional artifact - wp-ci.yml CI orchestrator (project-type presets) - cd-release.yml GitHub Release + dist zip - cd-deploy-wporg.yml WordPress.org SVN deploy (optional) - cd-deploy-vip.yml WPVIP deploy (optional; via VIP-CLI) - cd-deploy-s3.yml S3 artifact upload (optional; deferred to v1.1.0) - wp-cd.yml CD orchestrator — caller picks deploy target(s) via `deploy-target` input - version-monitor.yml Monthly version check -README.md Caller examples — keep accurate + ci-detect-changes.yml Pre-run: changed file detection (wraps the wp-tooling CLI) + ci-lint-css.yml Stylelint + ci-lint-js.yml ESLint + package.json validation + ci-lint-php.yml PHPCS + optional PHPStan + ci-test-js.yml Jest + ci-test-php.yml PHPUnit (wp-env or standalone) + ci-test-a11y.yml pa11y-ci WCAG2AA (opt-in via run-a11y) + ci-build.yml Build + optional artifact + ci-build-artifact-gate.yml Fails a PR that commits build output + ci-test-build-artifact.yml Boots the packaged artifact in real WordPress + wp-ci.yml CI orchestrator (project-type presets, one unit per call) + cd-github-release.yml GitHub Release from a tag + artifact + cd-wp-org.yml WordPress.org SVN deploy + cd-s3.yml S3 artifact upload (+ optional CloudFront invalidation) + cd-built-branch.yml Builds and force-pushes the built tree to a deploy branch + cd-split-composer-packages.yml Mirrors Composer subtrees to standalone repos + wp-cd.yml CD orchestrator — deploy-target: github, wporg, s3 + version-monitor.yml Monthly version check +README.md Caller examples — keep accurate ``` -Deploy workflows are all optional. Consumers list which deploy targets they want in the CD orchestrator call: +Deploy workflows are all optional. For tag-driven releases, consumers list which targets they want in the CD orchestrator call: ```yaml uses: rtCamp/wp-shared-workflows/.github/workflows/wp-cd.yml@v1 with: - deploy-target: "github,vip" # or "github,wporg" or "github,s3" + deploy-target: "github,wporg" # or "github,s3" ``` --- diff --git a/README.md b/README.md index 6467df0..43d3c82 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Reusable GitHub Actions workflows for rtCamp WordPress projects. Pure YAML — z - CI workflows — lint (PHP / JS / CSS), test (PHPUnit / Jest / pa11y), build, detect-changes - CI orchestrator — `wp-ci.yml` composes individual workflows based on `project-type` preset (plugin / theme / package) -- CD workflows — GitHub Release, WordPress.org SVN deploy, S3 artifact upload +- CD workflows — GitHub Release, WordPress.org SVN deploy, S3 artifact upload, built-branch publish - CD orchestrator — `wp-cd.yml` - Version monitor — `version-monitor.yml` runs monthly and opens draft PRs for version bumps @@ -29,9 +29,6 @@ jobs: uses: rtCamp/wp-shared-workflows/.github/workflows/wp-ci.yml@v1 with: project-type: "plugin" # plugin | theme | package - secrets: - # Read access to the private rtCamp/wp-tooling repo until it is published. - wp-tooling-token: ${{ secrets.WP_TOOLING_TOKEN }} ``` ## Individual workflows @@ -61,18 +58,12 @@ jobs: php-versions: '["8.1","8.2","8.3"]' wp-versions: '["6.7","6.8","6.9"]' test-php-exclude: '[{"php":"8.1","wp":"6.9"}]' - secrets: - # Read access to the private rtCamp/wp-tooling repo until it is published. - wp-tooling-token: ${{ secrets.WP_TOOLING_TOKEN }} - # Read access to private Composer source repos (e.g. rtCamp/wp-framework) so - # composer install can resolve them in lint-php / test-php. One token with access to - # every private repo involved can serve both secrets (wp-tooling-token + packages-token). - packages-token: ${{ secrets.RTCAMP_PACKAGES_TOKEN }} ``` | Input | Type | Default | Description | | ------------------ | ------- | ------------ | ---------------------------------------------------------------------------------------------------- | -| `project-type` | string | — | **Required.** `plugin` \| `theme` \| `package` — selects the job preset. | +| `project-type` | string | — | **Required.** `plugin` \| `theme` \| `package` — selects the job preset. Describes the unit at `working-dir`, not the repository. | +| `working-dir` | string | `"."` | Directory holding the unit this call targets, relative to the repo root. `"."` is the repo root itself. | | `skip` | string | `""` | Comma-separated job ids to drop without forking the orchestrator. Disable PHP tests with `test-php` here — not an empty array. | | `enable-phpstan` | boolean | `false` | Run PHPStan (whole-project) after PHPCS in `lint-php`. | | `run-a11y` | boolean | `false` | Run the `a11y` job. Off by default — slow and needs pa11y config. Gate it on the `Run a11y` label at the caller. | @@ -81,32 +72,32 @@ jobs: | `wp-versions` | string | `[""]` | JSON array of WordPress core versions for wp-env; crossed with `php-versions`. Empty string = `.wp-env.json` default; ignored when `use-wp-env: false`. | | `test-php-exclude` | string | `[]` | JSON array of `{php, wp}` cells to drop from the product; both keys must match a cell. | | `build-artifact-path` | string | `""` | Packaged installable plugin/theme dir the build produces (e.g. `dist/my-plugin/`). Set this to run the `build-artifact` install test; empty skips it. | -| `build-artifact-slug` | string | `""` | Slug to activate in the `build-artifact` test. Empty uses the repo name. | - -**Secrets:** - -- `wp-tooling-token` (optional) — forwarded to `detect-changes` to install the interim CLI from the private `rtCamp/wp-tooling` repo. Required until `@rtcamp/wp-tooling` is published. -- `packages-token` (optional) — forwarded to `lint-php` and `test-php` to authenticate `composer install` for private Composer source repos (e.g. `rtCamp/wp-framework`). Omit for projects with only public/Packagist deps. A single token with read access to all the required private repos can serve both `wp-tooling-token` and `packages-token`. +| `build-artifact-slug` | string | `""` | Slug to activate in the `build-artifact` test. Empty uses `working-dir`'s basename, or the repo name when `working-dir` is `"."`. | +| `ignore-paths` | string | `""` | Regex of paths `detect-changes` excludes from its counts and file lists. Empty uses the CLI's built-in ignore set. | +| `base-ref` | string | `""` | Explicit git ref `detect-changes` diffs `HEAD` against. Empty lets the CLI resolve it from the PR base or push event. | +| `gated-paths` | string | `""` | Newline-separated path prefixes (relative to `working-dir`) that must not be committed in a PR, e.g. `assets/build/`. Empty skips the `artifact-gate` job entirely. | +| `wp-tooling-ref` | string | pinned SHA | Git ref of `rtCamp/wp-tooling`'s `npm/wp-tooling` branch that `detect-changes` installs the CLI from. Defaults to a pinned commit; override to track the branch tip. | **Project-type presets** (a job also runs only when `detect-changes` reports the relevant bucket changed): | Preset | Jobs | | --------- | ---- | -| `plugin` | detect-changes, lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact†, a11y‡ | -| `theme` | detect-changes, lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact†, a11y‡ | -| `package` | detect-changes, lint-php, test-php | +| `plugin` | detect-changes, lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact†, a11y‡, artifact-gate§ | +| `theme` | detect-changes, lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact†, a11y‡, artifact-gate§ | +| `package` | detect-changes, lint-php, test-php, artifact-gate§ | † `build-artifact` runs only when `build-artifact-path` is set — the default `build` output is not an installable directory. ‡ `a11y` runs only when `run-a11y: true` — it is slow and needs pa11y config, so gate it on the `Run a11y` label at the caller. +§ `artifact-gate` runs only when `gated-paths` is set. It fails a PR that commits generated output, so it is opt-in — set it only where CI produces that output rather than the repo committing it. -Skippable job ids (for `skip`): `lint-css`, `lint-js`, `lint-php`, `test-js`, `test-php`, `build`, `build-artifact`, `a11y`. `validate-inputs` and `detect-changes` always run and aren't skippable. Matching is comma-exact, so `skip: build` drops `build` but not `build-artifact`. +Skippable job ids (for `skip`): `lint-css`, `lint-js`, `lint-php`, `test-js`, `test-php`, `build`, `build-artifact`, `a11y`, `artifact-gate`. `validate-inputs` and `detect-changes` always run and aren't skippable. Matching is comma-exact, so `skip: build` drops `build` but not `build-artifact`. Notes: -- **Concurrency** — duplicate runs on the same ref (e.g. a force-push) are cancelled (`concurrency: ci-${{ github.ref }}`, `cancel-in-progress: true`). +- **Concurrency** — duplicate runs on the same ref (e.g. a force-push) are cancelled. The group includes `project-type` and `working-dir` (`ci-${{ github.ref }}--`) so that sibling calls do not cancel each other. - **PHP / WordPress matrix** — `test-php` fans out over `php-versions` × `wp-versions` minus `test-php-exclude`. With `use-wp-env: true` (the default) each cell boots `@wordpress/env`, pinning `WP_ENV_PHP_VERSION` and `WP_ENV_CORE` — this suits plugins, themes, and packages whose suite tests against WordPress (e.g. via `wp-phpunit`), and the consumer needs a `.wp-env.json` plus `wp-env` and `test:php` npm scripts. A pure Composer library sets `use-wp-env: false` to run **standalone** PHPUnit (`vendor/bin/phpunit`), where the `wp` dimension is inert and no Node/Docker is required. Node defaults to 22; defaults run a single PHP 8.3 leg against the consumer's `.wp-env.json` WordPress version. - **Static analysis & coverage** — PHPStan is off by default; opt in with `enable-phpstan: true`. The orchestrator does not yet produce a coverage report (a v1.x follow-up), so it does not fully replace a pipeline that gated on coverage. -- **`build-artifact`** — opt-in. Set `build-artifact-path` to the installable dir your build produces (the default `build` output is bare `build/`, not installable); the `build` job then uploads that path and `build-artifact` boots it in WordPress. `build-artifact-slug` overrides the activated slug (defaults to the repo name); install path follows `project-type`. +- **`build-artifact`** — opt-in. Set `build-artifact-path` to the installable dir your build produces (the default `build` output is bare `build/`, not installable); the `build` job then uploads that path and `build-artifact` boots it in WordPress. `build-artifact-slug` overrides the activated slug (it defaults to `basename(working-dir)`, or the repo name when `working-dir` is `"."`); install path follows `project-type`. ### `version-monitor.yml`: monthly version monitor @@ -130,9 +121,6 @@ jobs: with: base-branch: main pr-assignees: "Adi-ty" - secrets: - # Read access to the private rtCamp/wp-tooling repo until it is published. - wp-tooling-token: ${{ secrets.WP_TOOLING_TOKEN }} ``` | Input | Type | Default | Description | @@ -141,8 +129,7 @@ jobs: | `base-branch` | string | `"main"` | Branch the draft PR is opened against. | | `pr-label` | string | `"version-monitor"` | Label applied to the draft PR. | | `pr-assignees` | string | `""` | Comma-separated GitHub usernames assigned to the PR. | - -**Secret:** `wp-tooling-token` (optional) — token with read access to the private `rtCamp/wp-tooling` repo, used to install the interim CLI. Required until `@rtcamp/wp-tooling` is published; omit once it is public. +| `wp-tooling-ref` | string | pinned SHA | Git ref of `rtCamp/wp-tooling`'s `npm/wp-tooling` branch the CLI is installed from. Defaults to a pinned commit; override to track the branch tip. | The calling job must grant `permissions: contents: write` and `pull-requests: write` so the workflow can push the `version-monitor/YYYY-MM` branch and open the PR, and the repo must have **Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"** enabled, or PR creation is blocked. Major bumps are never auto-applied — a bare version-string swap is rarely a safe major upgrade — so a month of only major bumps produces no diff and no PR; the run fails with the bump list in the log so they are surfaced rather than passing silently. The run also fails when a detector could not be checked (a PR may still carry the bumps that were found), so a scheduled run is never green while blind. @@ -154,9 +141,6 @@ Buckets the files changed in a PR or push and exposes, per language bucket, both jobs: detect: uses: rtCamp/wp-shared-workflows/.github/workflows/ci-detect-changes.yml@v1 - secrets: - # Read access to the private rtCamp/wp-tooling repo until it is published. - wp-tooling-token: ${{ secrets.WP_TOOLING_TOKEN }} lint-css: needs: detect @@ -178,16 +162,19 @@ jobs: | `node-version` | string | `"22"` | Node.js version used to run the wp-tooling CLI. | | `ignore-paths` | string | `""` | Regex of paths to exclude from counts and file lists. Empty uses the CLI's built-in ignore set. | | `base-ref` | string | `""` | Explicit ref to diff `HEAD` against. Empty lets the CLI resolve it from the PR base or push event. | +| `wp-tooling-ref` | string | pinned SHA | Git ref of `rtCamp/wp-tooling`'s `npm/wp-tooling` branch the CLI is installed from. Defaults to a pinned commit; override to track the branch tip. | +| `working-dir` | string | `"."` | Restricts the css/js/php counts and file lists to this directory, and makes those file lists relative to it. A **path scope, not a working directory** — the diff is always taken from the repo root. | | Output | Description | | ------------------------------------------------- | ---------------------------------------------------------------------------------- | -| `total-count` / `ignored-count` | Changed files kept after / dropped by the ignore filter. | -| `css-count` / `js-count` / `php-count` / `gha-count` | Per-bucket change counts. Gate downstream jobs on these. | -| `css-files` / `js-files` / `php-files` / `gha-files` | Newline-separated paths per bucket, ready for the lint workflows' `changed-files`. | +| `total-count` / `ignored-count` | Changed files kept after / dropped by the ignore filter. **Always repo-wide** — not restricted by `working-dir`. | +| `css-count` / `js-count` / `php-count` | Per-bucket change counts under `working-dir`. Gate downstream jobs on these. | +| `gha-count` / `gha-files` | Changed workflow files. **Always repo-wide** — workflow files only exist at `.github/workflows/` in the repo root, so scoping them would always yield nothing. | +| `css-files` / `js-files` / `php-files` | Newline-separated paths per bucket, **relative to `working-dir`**, ready for the lint workflows' `changed-files`. | -**Secret:** `wp-tooling-token` (optional) — token with read access to the private `rtCamp/wp-tooling` repo, used to install the interim CLI. Required until `@rtcamp/wp-tooling` is published; omit once it is public. +`@rtcamp/wp-tooling` is not on the npm registry yet, so the CLI is installed from the public `rtCamp/wp-tooling` repo's `npm/wp-tooling` branch, which carries the package at its root — no token needed. The install uses `--ignore-scripts`, and `wp-tooling-ref` defaults to a **pinned commit SHA** so a change on that branch cannot alter what your CI executes; override it to track the tip. The workflow runs unconditionally — count-based gating is the caller's (or orchestrator's) job, not the detector's. -wp-tooling is installed from its `release/v1.0.0` branch until it is published to a registry. The workflow runs unconditionally — count-based gating is the caller's (or orchestrator's) job, not the detector's. +> **Gate on the count, always.** An empty `changed-files` makes every lint workflow fall back to a whole-project run. Without the `if: … > 0` guard, a PR that touched no CSS would start the linter with nothing to do and it would silently lint the entire project instead of skipping. ### `ci-lint-css.yml`: Stylelint @@ -206,7 +193,7 @@ jobs: | `node-version` | string | `"22"` | Node.js version. | | `lint-command` | string | `"npm run lint:css"` | Whole-project Stylelint command. Used when `changed-files` is empty. | | `changed-files` | string | `""` | Newline-separated CSS files to lint. Empty = run `lint-command` whole-project. | -| `working-dir` | string | `"."` | Working directory for monorepos. | +| `working-dir` | string | `"."` | Directory the job runs in. | ### `ci-lint-js.yml`: ESLint @@ -226,7 +213,7 @@ jobs: | `lint-command` | string | `"npm run lint:js"` | Whole-project ESLint command. Used when `changed-files` is empty. | | `changed-files` | string | `""` | Newline-separated JS files to lint. Empty = run `lint-command` whole-project. | | `validate-package-json` | boolean | `true` | Run `npm run lint:package-json` before ESLint. | -| `working-dir` | string | `"."` | Working directory for monorepos. | +| `working-dir` | string | `"."` | Directory the job runs in. | ### `ci-lint-php.yml`: PHPCS + optional PHPStan @@ -251,10 +238,7 @@ jobs: | `phpstan-level` | string | `""` | Override PHPStan level. Empty uses the level from `phpstan.neon.dist`. | | `composer-flags` | string | `"--prefer-dist --optimize-autoloader --no-progress --no-interaction --no-scripts"` | Flags passed to `composer install`. Keeps `--no-scripts` for hygiene. | | `validate-composer`| boolean | `true` | Run `composer validate` before installing. | -| `working-dir` | string | `"."` | Working directory for monorepos. | - -**Secret:** `packages-token` (optional) — passed to setup-php to authenticate `composer install` for private Composer source repos (e.g. `rtCamp/wp-framework`). Omit for projects with only public/Packagist deps. - +| `working-dir` | string | `"."` | Directory the job runs in. | ### `ci-build.yml`: production build @@ -318,7 +302,7 @@ jobs: | `artifact-name` | string | `"build"` | Artifact name. Must match the name in the downstream `actions/download-artifact` step. | | `artifact-path` | string | `"build/"` | Path to upload. Resolved as `working-dir/artifact-path`. | | `retention-days` | number | `7` | Days to keep the artifact before GitHub deletes it. | -| `working-dir` | string | `"."` | Working directory for monorepos. | +| `working-dir` | string | `"."` | Directory the job runs in. | A misconfigured `artifact-path` fails loudly via `if-no-files-found: error`. No silent empty artifacts. ### `ci-test-php.yml`: PHPUnit @@ -354,9 +338,7 @@ jobs: | `use-wp-env` | boolean | `true` | Start `@wordpress/env` before tests for WordPress integration runs. | | `test-command` | string | `""` | PHPUnit command. Empty means `npm run test:php` in wp-env mode, `vendor/bin/phpunit` standalone. | | `composer-flags` | string | `"--no-interaction --prefer-dist --no-progress --no-scripts"` | Flags passed to `composer install`. Keep `--no-scripts` for supply-chain hygiene. | -| `working-dir` | string | `"."` | Working directory for monorepos. | - -**Secret:** `packages-token` (optional) — authenticates `composer install` for private Composer source repos (e.g. `rtCamp/wp-framework`) on the host (via setup-php) and inside the wp-env container. Omit for projects with only public/Packagist deps. +| `working-dir` | string | `"."` | Directory the job runs in. | Each workflow can be called independently, so you can wire them into your own job graph if the orchestrator preset does not fit your setup. @@ -380,7 +362,7 @@ jobs: | `node-version` | string | `"22"` | Node.js version to install. | | `test-command` | string | `"npm run test:js -- --ci"`| Shell command that runs Jest. | | `enable-cache` | boolean | `true` | Cache Jest transform/result data across runs. | -| `working-dir` | string | `"."` | Working directory for monorepos. | +| `working-dir` | string | `"."` | Directory the job runs in. | ### `ci-test-a11y.yml` — accessibility tests @@ -405,7 +387,7 @@ jobs: | `node-version` | string | `"22"` | Node.js version to install. | | `build-command` | string | `"npm run build:prod"` | Shell command that produces the production build pa11y will test against. | | `test-command` | string | `"npm run test:a11y"` | Shell command that runs pa11y-ci. | -| `working-dir` | string | `"."` | Working directory for monorepos. | +| `working-dir` | string | `"."` | Directory the job runs in. | Step order is load-bearing: build runs **before** `wp-env start` so pa11y sees compiled CSS/JS. `wp-env stop` uses `if: always()` so a failing pa11y run does not leak a Docker stack into the next job. @@ -436,29 +418,18 @@ jobs: public/build/ ``` -**Monorepo:** scope the gate to one sub-package. - -```yaml -jobs: - artifact-gate: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 - with: - gated-paths: "assets/build/" - working-dir: "packages/admin-ui" -``` - | Input | Type | Default | Description | | ------------- | ------ | ----------------- | --------------------------------------------------------------------------------- | | `gated-paths` | string | `"assets/build/"` | Newline-separated path prefixes whose contents must not be committed in a PR. | -| `working-dir` | string | `"."` | Working directory for monorepos. Path prefixes are anchored under this directory. | +| `working-dir` | string | `"."` | Directory the gated path prefixes are anchored under. | Only meaningful on `pull_request` events. On other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. The check compares `origin/..HEAD` with `--diff-filter=ACMR`, so deletions are ignored: removing a previously-committed artifact in the PR does not trip the gate. ### `cd-split-composer-packages.yml`: split Composer packages to mirror repos -Splits Composer-package subtrees out of a monorepo into standalone mirror repos (the Symfony "monorepo split" pattern), so Packagist can serve each package from its own repository. A `splitsh.json` (by default at the repo root) is the single source of truth — to add or remove a package, edit that file, never the workflow. +Splits Composer-package subtrees out of one repository into standalone mirror repos, so Packagist can serve each package from its own repository. A `splitsh.json` (by default at the repo root) is the single source of truth — to add or remove a package, edit that file, never the workflow. -`splitsh.json` lives in the **calling** monorepo (e.g. `wp-tooling`), not in this repo. As a reusable workflow, `actions/checkout` pulls the caller's repository by default, so the config is read from the caller's checkout — `config-file` is a path relative to that checkout, never the file's contents. +`splitsh.json` lives in the **calling** repository (e.g. `wp-tooling`), not in this repo. As a reusable workflow, `actions/checkout` pulls the caller's repository by default, so the config is read from the caller's checkout — `config-file` is a path relative to that checkout, never the file's contents. `splitsh.json`: @@ -480,7 +451,7 @@ Splits Composer-package subtrees out of a monorepo into standalone mirror repos Caller — split on every `v*` tag push: ```yaml -# .github/workflows/split.yml in the monorepo +# .github/workflows/split.yml in the source repository name: Split Composer Packages on: push: @@ -497,7 +468,7 @@ jobs: The reusable workflow owns no trigger of its own — the caller decides when it runs. To also allow a manual smoke-test run (the `workflow_dispatch` path the standalone version had), add the trigger and pass the tag through. On a manual run `github.ref_name` is a **branch**, not a tag, so the dispatch input must win: ```yaml -# .github/workflows/split.yml in the monorepo +# .github/workflows/split.yml in the source repository name: Split Composer Packages on: push: @@ -527,7 +498,78 @@ jobs: | ------------- | -------- | ------------------------------------------------------------------------------------------------------ | | `split-token` | yes | Token (fine-grained PAT or GitHub App token) with `contents: write` on every mirror repo in the config. | -The `subtrees` map accepts both the shorthand string form (`"mirror": "path/in/monorepo"`) and the object form (`"mirror": { "prefixes": [{ "from": "path" }] }`). Each subtree is force-pushed to its mirror in parallel with `fail-fast: false`, so one failing package does not abort the rest. A missing or empty config fails the run loudly. +The `subtrees` map accepts both the shorthand string form (`"mirror": "path/in/repo" `) and the object form (`"mirror": { "prefixes": [{ "from": "path" }] }`). Each subtree is force-pushed to its mirror in parallel with `fail-fast: false`, so one failing package does not abort the rest. A missing or empty config fails the run loudly. + +### `cd-built-branch.yml`: publish the built tree to a deploy branch + +Builds the project and force-pushes **source plus generated output** (Composer `vendor/`, compiled `assets/build/`) to a dedicated branch, for platforms that deploy from a git branch rather than an artifact. + +Two invariants make this safe to point a production environment at: + +- **The source branch never contains generated output.** Pair this workflow with `ci-build-artifact-gate.yml` on the *same* path list — whatever you gate, you publish. +- **The target branch is always one commit whose parent is the source commit.** So `git diff main..main-built` shows exactly the generated files and nothing else, and rollback is just "re-run from an older commit". + +> **Requirements.** The caller must grant `permissions: contents: write` — a called workflow can only reduce the caller's grant, never raise it. The target branch must allow force-pushes. And note that **pushes made with the default `GITHUB_TOKEN` do not trigger further workflow runs**; if something must fire on a push to the deploy branch, supply `push-token`. + +```yaml +# .github/workflows/publish-built-branch.yml in the consumer +name: Publish built branch +on: + push: + branches: [main] + workflow_dispatch: +permissions: + contents: write +jobs: + publish: + uses: rtCamp/wp-shared-workflows/.github/workflows/cd-built-branch.yml@v1 +``` + +That 12-line caller covers a single-plugin or single-theme repo: `targets` defaults to `[{"dir": "."}]`, and `vendor/` / `assets/build/` are inferred from the presence of `composer.json` and `package-lock.json`. + +| Input | Type | Default | Description | +| ----------------- | ------- | -------------------- | ---------------------------------------------------------------------------------------------- | +| `targets` | string | `[{"dir": "."}]` | JSON array of build **objects**. Each needs `dir`; may override `name`, `php-version`, `node-version`, `composer-flags`, `build-command`, `publish-paths`, `verify-paths`, `composer`, `node`, `optional`. Per-target `publish-paths`/`verify-paths` accept either a JSON array (`["vendor","dist"]`) or a newline string. | +| `target-branch` | string | `"main-built"` | Branch the built tree is force-pushed to. Must allow force-pushes. | +| `source-ref` | string | `""` | Commit/tag/branch to build. Empty uses the triggering commit. A full SHA rebuilds an older commit. | +| `publish-paths` | string | `""` | Newline-separated generated paths to publish, relative to each target's `dir`. Empty auto-resolves to `vendor/` (Composer targets) plus `assets/build/` (Node targets). | +| `verify-paths` | string | `""` | Newline-separated paths that must exist after the build. Files must exist; directories must be non-empty. Empty auto-resolves to `vendor/autoload.php` for Composer targets. | +| `node-version` | string | `"22"` | Default Node.js version, overridable per target. | +| `php-version` | string | `"8.3"` | Default PHP version, overridable per target. | +| `composer-flags` | string | `--no-dev …` | Flags passed to `composer install`. | +| `build-command` | string | `""` | Empty defaults to `npm run build:prod`. Only run for targets with a `package-lock.json`. | +| `commit-subject` | string | `""` | Subject of the published commit. Empty uses `build: publish built tree for `. | +| `allow-rewind` | boolean | `false` | Allow publishing a commit older than what the branch already publishes (deliberate rollback). | +| `dry-run` | boolean | `false` | Build, verify and commit, but do not push. | +| `retention-days` | number | `3` | Days to keep the intermediate build tarballs. | + +| Secret | Required | Description | +| ---------------- | -------- | ---------------------------------------------------------------------------------------------- | +| `push-token` | no | Token with `contents: write` used for the push. Supply one when the push must trigger further workflows, or when a ruleset needs a bypass actor. | + +| Output | Description | +| --------------- | ---------------------------------------------------------------------- | +| `published` | `'true'` when a commit was pushed; `'false'` on a dry run. | +| `published-sha` | SHA of the commit created on the target branch. Empty on a dry run. | +| `source-sha` | Resolved source commit that was built — the published commit's parent. | +| `targets` | The resolved build matrix as compact JSON. | + +**Rollback**, two ways. Re-run an older successful run from the Actions UI and it republishes that run's commit. Or dispatch with `source-ref: ` **and** `allow-rewind: true`; without the flag that dispatch is refused, since moving the deploy branch backwards should be deliberate. + +**Losing a push race is not a failure.** If two pushes land close together and the newer run publishes first, the older run finds the branch already ahead of it, logs a `::notice::` and ends **green** without pushing — the correct tree is already live. Only an explicit `source-ref` rollback errors without `allow-rewind`. + +Notes: + +- **Every run rebuilds and republishes every target.** The branch must always be a complete deployable tree, and each run resets it to the source commit — so a skipped target would simply be absent, not stale. Consequently: **do not put a `paths:` filter on the push trigger.** A filtered-out commit leaves the branch's parent behind, and those changes never reach the deploy branch. +- **A target's `dir` must exist, or the run fails** — a typo'd or removed path never silently shrinks the published tree. To list a plugin or theme that has not been scaffolded yet, mark it `"optional": true`; an absent optional target is skipped with a `::warning::` and listed in the run summary instead of failing the run. +- **`node_modules/` is never published**, and listing it in `publish-paths` is a hard error. Only the declared paths are staged, so anything an npm lifecycle script wrote elsewhere stays out of the branch. +- **Nested `.git` directories inside published paths are removed** before staging. A dependency installed from source leaves one, and `git add` would record it as a gitlink — publishing an empty directory instead of the package's files. +- If the repo uses `* text=auto` in `.gitattributes`, add `vendor/** -text`. Line-ending normalisation is applied at `git add` time and can corrupt binary assets that lack a `binary` attribute. +- The branch's history is rewritten on every run, so old trees are orphaned until GitHub's GC runs; server-side repo size grows over time. That is inherent to build-to-branch. +- Not part of `wp-cd.yml`. That orchestrator is tag-and-artifact driven; this is push-and-self-building, and combining them would build the project twice. + +**Setup:** point your branch-deploy platform at `main-built`, keep PR CI on `main`, and never commit to `main-built` by hand. + ### `ci-test-build-artifact.yml`: boot the built artifact A green `ci-build.yml` run only proves the build did not crash — not that the packaged output installs and boots. This workflow downloads the artifact, boots a real WordPress in [`@wordpress/env`](https://github.com/WordPress/gutenberg/tree/trunk/packages/env), activates the plugin/theme, and runs `wp doctor`. It catches PHP files referenced but never copied into the bundle, an over-eager `.distignore`, and path-cased files that break on Linux. Pair it with `ci-build.yml`. @@ -573,9 +615,12 @@ jobs: | `install-path` | string | `"wp-content/plugins"`| Destination under the WordPress root. A path ending in `themes` activates a theme, else a plugin. | | `smoke-script` | string | `""` | Optional path inside the artifact to a shell script, run in the container after activation. | | `doctor-ignore-checks` | string | `"constant-wp-debug-falsy"` | Comma-separated `wp doctor` check names excluded from the error gate (production-oriented checks that wp-env's dev defaults always trip). | +| `working-dir` | string | `"."` | Directory the job runs in. wp-env runs here (so a `.wp-env.json` in this directory is picked up) and the artifact is downloaded into it. | `wp doctor check --all` includes production-oriented checks that a dev wp-env always trips — notably `constant-wp-debug-falsy`, because wp-env enables `WP_DEBUG` by default. Those are excluded from the gate via `doctor-ignore-checks` (extend the comma-separated list if your wp-env config trips others); every other `error`-severity check still fails the build. +The run writes a `.wp-env.override.json` into `working-dir`, **overwriting any existing file of that name**. The override clears `plugins` and `themes` and mounts only the downloaded artifact, so the boot tests the packaged output rather than the working tree that a consumer's own `.wp-env.json` would map. + The artifact must be a **complete installable plugin/theme directory** (main PHP file plus assets), so point `ci-build.yml`'s `artifact-path` at a packaged dist directory, not bare `build/`. `actions/download-artifact` restores the uploaded directory contents uncompressed, so there is no unzip step. The workflow writes a `.wp-env.override.json` that pins `phpVersion`/`core` and mounts **only** the downloaded artifact — it clears `plugins`/`themes` from the consumer's `.wp-env.json` so the test reflects the packaged output in isolation, not the dev source tree. It then runs `wp activate ` and `wp doctor check --all` (failing only on `error` severity), and always runs `wp-env stop` so no container leaks into the next job. ### `cd-github-release.yml`: GitHub Release @@ -612,6 +657,7 @@ jobs: | `changelog-path` | string | `"CHANGELOG.md"` | Changelog whose matching section becomes the release body. | | `draft` | boolean | `false` | Create the Release as a draft. | | `prerelease` | boolean | `false` | Mark the Release as a prerelease. | +| `working-dir` | string | `"."` | Prefixes `changelog-path`. A **path prefix, not a working directory** — the attached files come from the artifact, which the build already scoped. | The calling job must grant `permissions: contents: write`. The artifact must be produced **in the same workflow run** — `download-artifact` only sees the current run's artifacts. The changelog heading must contain the tag's version (`## v1.2.3` or `## [1.2.3]`, with an optional trailing date); `## Unreleased` is never matched. A missing or empty section fails the workflow rather than publishing a Release with no notes. @@ -657,6 +703,7 @@ jobs: | `artifact-name` | string | _(required)_ | **Required.** Build artifact to download and deploy (must match the producer). | | `assets-path` | string | `".wordpress-org"` | Local directory mapped to SVN `/assets/`. Skipped if absent. | | `dry-run` | boolean | `false` | Run the full deploy except the final SVN commit. | +| `working-dir` | string | `"."` | Prefixes `assets-path`. A **path prefix, not a working directory** — the deployed files come from the artifact, which the build already scoped. | | Secret | Required | Description | | ----------------- | -------- | -------------------------------------------------------------------- | From 7fff4c9b0825924c4dd42ffaea09eedb0dd3bd3a Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Tue, 4 Aug 2026 09:25:24 +0530 Subject: [PATCH 37/43] fix(ci): harden rewinds, path guards, and artifact naming in the cd/ci workflows --- .github/workflows/cd-built-branch.yml | 30 ++++++++++++++----------- .github/workflows/cd-github-release.yml | 4 ++++ .github/workflows/cd-wp-org.yml | 4 ++++ .github/workflows/ci-detect-changes.yml | 4 ++++ .github/workflows/wp-ci.yml | 6 ++--- CHANGELOG.md | 6 ++--- README.md | 6 ++--- 7 files changed, 38 insertions(+), 22 deletions(-) diff --git a/.github/workflows/cd-built-branch.yml b/.github/workflows/cd-built-branch.yml index 6219f79..e033666 100644 --- a/.github/workflows/cd-built-branch.yml +++ b/.github/workflows/cd-built-branch.yml @@ -26,7 +26,10 @@ on: type: string default: "main-built" source-ref: - description: "Commit, tag or branch to build and publish. Empty uses the commit that triggered the caller. Pass a full 40-character SHA to rebuild an older commit (rollback)." + description: >- + Commit, tag or branch to build and publish. Empty uses the commit that triggered the + caller. Pass a full 40-character SHA to rebuild an older commit; rolling back also needs + allow-rewind: true. type: string default: "" publish-paths: @@ -64,7 +67,10 @@ on: type: string default: "" allow-rewind: - description: "Allow publishing a commit older than what the branch already publishes — a deliberate rollback. Off by default so an older tree cannot overwrite a newer one." + description: >- + Allow publishing a commit that is not a descendant of what the branch already publishes — + a deliberate rollback, or a rebuild after the source branch was force-pushed. Off by + default so an older or diverged tree cannot overwrite a newer one. type: boolean default: false dry-run: @@ -468,15 +474,14 @@ jobs: git fetch --no-tags origin "+refs/heads/${TARGET_BRANCH}:refs/remotes/origin/${TARGET_BRANCH}" remote_tip="$(git rev-parse "refs/remotes/origin/${TARGET_BRANCH}")" - # Something newer is already live, so publishing would move the branch backwards. - # No source-ref means a run that lost a push race: skip green, the live tree is - # correct. An explicit ref means a deliberate rollback, which needs allow-rewind. + # Only ever move the branch forward: a lost push race skips green, an explicit ref is a + # rollback needing allow-rewind, and a force-pushed source branch is refused outright. published_parent="$(git rev-parse --verify --quiet "refs/remotes/origin/${TARGET_BRANCH}^" || true)" if [ -n "$published_parent" ] && [ "$published_parent" != "$SOURCE_SHA" ] \ - && git merge-base --is-ancestor "$SOURCE_SHA" "$published_parent"; then + && ! git merge-base --is-ancestor "$published_parent" "$SOURCE_SHA"; then if [ "$ALLOW_REWIND" = "true" ]; then echo "::warning::Rewinding '${TARGET_BRANCH}' from ${published_parent} to ${SOURCE_SHA} (allow-rewind is true)." - elif [ -z "$EXPLICIT_SOURCE_REF" ]; then + elif [ -z "$EXPLICIT_SOURCE_REF" ] && git merge-base --is-ancestor "$SOURCE_SHA" "$published_parent"; then echo "::notice::Superseded — '${TARGET_BRANCH}' already publishes ${published_parent}," \ "a descendant of this run's ${SOURCE_SHA}. A newer run got there first, so the live" \ "tree is already ahead of this one. Nothing to do." @@ -486,9 +491,9 @@ jobs: } >> "$GITHUB_OUTPUT" exit 0 else - echo "::error::'${TARGET_BRANCH}' already publishes ${published_parent}, which is newer" \ - "than the requested ${SOURCE_SHA}. Refusing to move the deploy branch backwards." \ - "Re-run with allow-rewind: true to publish an older commit on purpose." + echo "::error::'${TARGET_BRANCH}' already publishes ${published_parent}, which is not an" \ + "ancestor of ${SOURCE_SHA} — a rollback, or the source branch was force-pushed." \ + "Re-run with allow-rewind: true to publish ${SOURCE_SHA} on purpose." exit 1 fi fi @@ -545,7 +550,7 @@ jobs: warning. Change the source branch instead." git commit --quiet -m "$subject" -m "$body" - git --no-pager show --stat --oneline HEAD | head -n 30 + git --no-pager show --stat --oneline HEAD | sed -n '1,30p' if [ "$DRY_RUN" = "true" ]; then echo "::notice::dry-run: the commit above was NOT pushed to '${TARGET_BRANCH}'." @@ -557,11 +562,10 @@ jobs: fi # --force-with-lease so a concurrent push fails loudly rather than being clobbered. - # Plain --force when creating the branch, where there is no tip to lease against. if [ "$branch_exists" = "true" ]; then push_args=(--force-with-lease="refs/heads/${TARGET_BRANCH}:${remote_tip}") else - push_args=(--force) + push_args=(--force-with-lease="refs/heads/${TARGET_BRANCH}:") fi if ! git push "${push_args[@]}" origin "HEAD:refs/heads/${TARGET_BRANCH}"; then echo "::error::Push to '${TARGET_BRANCH}' was rejected. Check that the caller granted" \ diff --git a/.github/workflows/cd-github-release.yml b/.github/workflows/cd-github-release.yml index 37415ae..dee63d9 100644 --- a/.github/workflows/cd-github-release.yml +++ b/.github/workflows/cd-github-release.yml @@ -66,6 +66,10 @@ jobs: /*) echo "::error::working-dir must be relative to the repo root (got '$WORKING_DIR')"; exit 1 ;; *..*) echo "::error::working-dir must not contain '..' (got '$WORKING_DIR')"; exit 1 ;; esac + case "$CHANGELOG_PATH" in + /*) echo "::error::changelog-path must be relative to working-dir (got '$CHANGELOG_PATH')"; exit 1 ;; + *..*) echo "::error::changelog-path must not contain '..' (got '$CHANGELOG_PATH')"; exit 1 ;; + esac if [ "$dir" != "." ]; then CHANGELOG_PATH="${dir}/${CHANGELOG_PATH#./}" fi diff --git a/.github/workflows/cd-wp-org.yml b/.github/workflows/cd-wp-org.yml index 8e586f6..1939ce1 100644 --- a/.github/workflows/cd-wp-org.yml +++ b/.github/workflows/cd-wp-org.yml @@ -100,6 +100,10 @@ jobs: /*) echo "::error::working-dir must be relative to the repo root (got '$WORKING_DIR')"; exit 1 ;; *..*) echo "::error::working-dir must not contain '..' (got '$WORKING_DIR')"; exit 1 ;; esac + case "$ASSETS_PATH" in + /*) echo "::error::assets-path must be relative to working-dir (got '$ASSETS_PATH')"; exit 1 ;; + *..*) echo "::error::assets-path must not contain '..' (got '$ASSETS_PATH')"; exit 1 ;; + esac if [ -n "$ASSETS_PATH" ] && [ "$dir" != "." ]; then ASSETS_PATH="${dir}/${ASSETS_PATH#./}" fi diff --git a/.github/workflows/ci-detect-changes.yml b/.github/workflows/ci-detect-changes.yml index a113db6..add39e0 100644 --- a/.github/workflows/ci-detect-changes.yml +++ b/.github/workflows/ci-detect-changes.yml @@ -147,6 +147,10 @@ jobs: dir="${dir#./}" dir="${dir%/}" [ -n "$dir" ] || dir="." + case "$dir" in + /*) echo "::error::working-dir must be relative to the repo root (got '$WORKING_DIR')"; exit 1 ;; + *..*) echo "::error::working-dir must not contain '..' (got '$WORKING_DIR')"; exit 1 ;; + esac if [ "$dir" != "." ] && [ ! -d "$dir" ]; then echo "::error::working-dir '${WORKING_DIR}' does not exist in this repository." diff --git a/.github/workflows/wp-ci.yml b/.github/workflows/wp-ci.yml index 2ccdd44..682c199 100644 --- a/.github/workflows/wp-ci.yml +++ b/.github/workflows/wp-ci.yml @@ -10,8 +10,8 @@ on: working-dir: description: >- Directory holding the unit this run targets, relative to the repo root. '.' (default) is a - single-project repo; in a monorepo call this workflow once per unit. See the monorepo - recipes in the README. + single-project repo; where one repo holds several projects, call this workflow once per + unit. type: string default: "." skip: @@ -136,7 +136,7 @@ jobs: if [ "$dir" = "." ]; then artifact_name="wp-ci-build" else - artifact_name="wp-ci-build-$(printf '%s' "$dir" | tr -c 'a-zA-Z0-9._-' '-')" + artifact_name="wp-ci-build-$(printf '%s' "$dir" | sed 's/-/--/g; s|/|-|g' | tr -c 'a-zA-Z0-9._-' '-')" fi # A monorepo's repo name is rarely the slug, so prefer the target directory's basename. diff --git a/CHANGELOG.md b/CHANGELOG.md index bc0e5bb..6820259 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,14 +8,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Changed -- **Breaking for callers that pass it:** the `wp-tooling-token` secret is removed from `ci-detect-changes.yml`, `version-monitor.yml` and `wp-ci.yml`. `rtCamp/wp-tooling` is public, so the CLI now installs straight from its `npm/wp-tooling` branch with no token. A caller still passing `wp-tooling-token:` fails with `Invalid input, wp-tooling-token is not defined in the referenced workflow` — delete the line. A new `wp-tooling-ref` input (forwarded through `wp-ci.yml`) pins the install to a commit SHA and installs with `--ignore-scripts`, so a change on that branch cannot alter what your CI runs; override it to track the tip. The package is still not on the npm registry, so the install remains a git ref. -- **Breaking for callers that pass it:** the `packages-token` secret is removed from `ci-lint-php.yml`, `ci-test-php.yml` and `wp-ci.yml`. `rtCamp/wp-framework` is public, so no known private Composer dependency is left to authenticate. A caller still passing `packages-token:` fails with `Invalid input, packages-token is not defined in the referenced workflow` — delete the line. `setup-php` still receives `github-token: ${{ github.token }}` for the API rate limit, which never depended on the secret, and `ci-test-php.yml` drops the wp-env Composer-auth step that existed only to forward it into the container. +- The `wp-tooling-token` secret is removed from `ci-detect-changes.yml`, `version-monitor.yml` and `wp-ci.yml`. `rtCamp/wp-tooling` is public, so the CLI now installs straight from its `npm/wp-tooling` branch with no token. This secret never appeared in a tagged release, so v1.0.0 simply ships without it — no major bump is owed. Anyone pinned to a branch ref for pre-release smoke testing must still delete the line, or the call fails with `Invalid input, wp-tooling-token is not defined in the referenced workflow`. A new `wp-tooling-ref` input (forwarded through `wp-ci.yml`) pins the install to a commit SHA and installs with `--ignore-scripts`, so a change on that branch cannot alter what your CI runs; override it to track the tip. The package is still not on the npm registry, so the install remains a git ref. +- The `packages-token` secret is removed from `ci-lint-php.yml`, `ci-test-php.yml` and `wp-ci.yml`. `rtCamp/wp-framework` is public, so no known private Composer dependency is left to authenticate. It was added in `6274f32` and removed here, both within the unreleased v1.0.0 cycle, so no tagged release ever accepted it. Anyone pinned to a branch ref must delete the line, or the call fails with `Invalid input, packages-token is not defined in the referenced workflow`. `setup-php` still receives `github-token: ${{ github.token }}` for the API rate limit, which never depended on the secret, and `ci-test-php.yml` drops the wp-env Composer-auth step that existed only to forward it into the container. - Monorepo fixes across the CI leaves. All six `setup-node` steps that use `cache: npm` now pass `cache-dependency-path`, and `ci-lint-php.yml`'s Composer cache key is scoped to `/composer.lock`. `ci-build-artifact-gate.yml` normalises **and** regex-escapes `working-dir` before anchoring its pattern — previously a `./`-prefixed or metacharacter-containing value matched nothing, so the gate passed green on a PR that committed build output. `ci-test-build-artifact.yml` gains `working-dir`. - `cd-github-release.yml` and `cd-wp-org.yml` gain `working-dir` as a **path prefix, not a working directory**: it scopes only the source-tree paths they read (`changelog-path`, `assets-path`), since the deployed files come from an already unit-scoped artifact. Both previously fell back to the repo root in a monorepo and failed silently — another unit's `CHANGELOG.md` still parses, and a missing `.wordpress-org` only emits a notice. Both now reject absolute and `..` paths. `cd-s3.yml` and `cd-split-composer-packages.yml` are unchanged. ### Added -- `cd-built-branch.yml`: reusable workflow that builds a project and force-pushes **source plus generated output** (Composer `vendor/`, compiled `assets/build/`) to a dedicated branch, for platforms that deploy from a git branch rather than an artifact. Three jobs: `discover` resolves the `targets` JSON into a build matrix, `build` builds each target in parallel, and `publish` force-pushes a single commit whose parent is the source commit — so `git diff ..` is exactly the generated files, and rollback is a re-run from an older SHA. Every run republishes every target, so the branch is always a complete tree; a target whose `dir` is missing fails the run unless marked `"optional": true`. A push-triggered run that loses a race ends **green** with a `::notice::` because the newer tree is already live, while an explicit `source-ref` pointing backwards errors unless `allow-rewind: true`. Only `publish` holds `contents: write`, so the job that executes third-party dependency code never has a writable token; the caller must grant `permissions: contents: write`. See the README for the full contract and caveats. Inputs: `targets`, `target-branch`, `source-ref`, `publish-paths`, `verify-paths`, `node-version`, `php-version`, `composer-flags`, `build-command`, `commit-subject`, `allow-rewind`, `dry-run`, `retention-days`. Optional secret: `push-token`, for when a push must trigger further workflow runs, which the default `GITHUB_TOKEN` never does. Outputs: `published`, `published-sha`, `source-sha`, `targets`. +- `cd-built-branch.yml`: reusable workflow that builds a project and force-pushes **source plus generated output** (Composer `vendor/`, compiled `assets/build/`) to a dedicated branch, for platforms that deploy from a git branch rather than an artifact. Three jobs: `discover` resolves the `targets` JSON into a build matrix, `build` builds each target in parallel, and `publish` force-pushes a single commit whose parent is the source commit — so `git diff ..` is exactly the generated files, and rollback is a dispatch with `source-ref` plus `allow-rewind: true`. Every run republishes every target, so the branch is always a complete tree; a target whose `dir` is missing fails the run unless marked `"optional": true`. A push-triggered run that loses a race ends **green** with a `::notice::` because the newer tree is already live, while an explicit `source-ref` pointing backwards errors unless `allow-rewind: true`. Only `publish` holds `contents: write`, so the job that executes third-party dependency code never has a writable token; the caller must grant `permissions: contents: write`. See the README for the full contract and caveats. Inputs: `targets`, `target-branch`, `source-ref`, `publish-paths`, `verify-paths`, `node-version`, `php-version`, `composer-flags`, `build-command`, `commit-subject`, `allow-rewind`, `dry-run`, `retention-days`. Optional secret: `push-token`, for when a push must trigger further workflow runs, which the default `GITHUB_TOKEN` never does. Outputs: `published`, `published-sha`, `source-sha`, `targets`. - `ci-test-php.yml`: reusable PHPUnit workflow with a `use-wp-env` toggle (default `true`) for WordPress integration tests via `@wordpress/env`, or standalone PHPUnit for Composer-only packages and libraries. In wp-env mode, `php-version` is pinned into the container via `WP_ENV_PHP_VERSION` and `wp-version` (when non-empty) sets `WP_ENV_CORE=WordPress/WordPress#` (both set at job scope, not `$GITHUB_ENV`, so a caller's matrix can drive the PHP and WordPress core version per cell without newline-injection risk); an empty `wp-version` uses the consumer's `.wp-env.json`. Inputs: `php-version`, `node-version`, `wp-version`, `use-wp-env`, `test-command`, `composer-flags`, `working-dir`. The `test-command` default is empty and selects `npm run test:php` in wp-env mode, `vendor/bin/phpunit` standalone. - `ci-test-js.yml` — reusable Jest unit-test workflow with optional cross-run cache (`enable-cache`), monorepo support (`working-dir`), and a consumer-overridable command (`test-command`). Replaces the copy-pasted `unit-tests-js` job from the legacy `Test and Measure` workflow. - `ci-test-a11y.yml` — reusable pa11y-ci accessibility test workflow. Order: `npm ci` → build → `wp-env start` → pa11y → `wp-env stop` (with `if: always()` so cleanup runs on failure). Inputs: `node-version`, `build-command`, `test-command`, `working-dir`. Trigger-agnostic — consumers wire the `Run a11y` label gate at the caller level. diff --git a/README.md b/README.md index 43d3c82..2567959 100644 --- a/README.md +++ b/README.md @@ -507,7 +507,7 @@ Builds the project and force-pushes **source plus generated output** (Composer ` Two invariants make this safe to point a production environment at: - **The source branch never contains generated output.** Pair this workflow with `ci-build-artifact-gate.yml` on the *same* path list — whatever you gate, you publish. -- **The target branch is always one commit whose parent is the source commit.** So `git diff main..main-built` shows exactly the generated files and nothing else, and rollback is just "re-run from an older commit". +- **The target branch is always one commit whose parent is the source commit.** So `git diff main..main-built` shows exactly the generated files and nothing else. > **Requirements.** The caller must grant `permissions: contents: write` — a called workflow can only reduce the caller's grant, never raise it. The target branch must allow force-pushes. And note that **pushes made with the default `GITHUB_TOKEN` do not trigger further workflow runs**; if something must fire on a push to the deploy branch, supply `push-token`. @@ -539,7 +539,7 @@ That 12-line caller covers a single-plugin or single-theme repo: `targets` defau | `composer-flags` | string | `--no-dev …` | Flags passed to `composer install`. | | `build-command` | string | `""` | Empty defaults to `npm run build:prod`. Only run for targets with a `package-lock.json`. | | `commit-subject` | string | `""` | Subject of the published commit. Empty uses `build: publish built tree for `. | -| `allow-rewind` | boolean | `false` | Allow publishing a commit older than what the branch already publishes (deliberate rollback). | +| `allow-rewind` | boolean | `false` | Allow publishing a commit that is not a descendant of what the branch already publishes — a rollback, or a rebuild after the source branch was force-pushed. | | `dry-run` | boolean | `false` | Build, verify and commit, but do not push. | | `retention-days` | number | `3` | Days to keep the intermediate build tarballs. | @@ -554,7 +554,7 @@ That 12-line caller covers a single-plugin or single-theme repo: `targets` defau | `source-sha` | Resolved source commit that was built — the published commit's parent. | | `targets` | The resolved build matrix as compact JSON. | -**Rollback**, two ways. Re-run an older successful run from the Actions UI and it republishes that run's commit. Or dispatch with `source-ref: ` **and** `allow-rewind: true`; without the flag that dispatch is refused, since moving the deploy branch backwards should be deliberate. +**Rollback** is a `workflow_dispatch` with `source-ref: ` **and** `allow-rewind: true`. Without the flag the dispatch is refused, since moving the deploy branch off a newer tree should be deliberate. Re-running an older run from the Actions UI does *not* roll back — a re-run cannot change these inputs, so it is indistinguishable from a run that lost a push race and it ends green without publishing. **Losing a push race is not a failure.** If two pushes land close together and the newer run publishes first, the older run finds the branch already ahead of it, logs a `::notice::` and ends **green** without pushing — the correct tree is already live. Only an explicit `source-ref` rollback errors without `allow-rewind`. From 04df887b6ffbc25c924c48dfdceed3611d4df5c6 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Tue, 4 Aug 2026 09:47:24 +0530 Subject: [PATCH 38/43] fix(ci): refuse to publish the target root or .git in cd-built-branch --- .github/workflows/cd-built-branch.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/cd-built-branch.yml b/.github/workflows/cd-built-branch.yml index e033666..b4bc333 100644 --- a/.github/workflows/cd-built-branch.yml +++ b/.github/workflows/cd-built-branch.yml @@ -151,9 +151,12 @@ jobs: case "$p" in /*) echo "::error::${label} '$p' (target '$name') must be relative to the target dir" >&2; return 1 ;; *..*) echo "::error::${label} '$p' (target '$name') must not contain '..'" >&2; return 1 ;; + .) echo "::error::${label} '.' (target '$name') would archive the whole tree, .git included — name the generated directories" >&2; return 1 ;; esac case "/$p/" in */node_modules/*) echo "::error::${label} '$p' (target '$name') includes node_modules, which is never published" >&2; return 1 ;; + # A published .git overwrites the publish job's own, handing build-time dependency code its push credential. + */.git/*) echo "::error::${label} '$p' (target '$name') includes .git, which is never published" >&2; return 1 ;; esac if [ "$dir" = "." ]; then out="${out}${p}"$'\n'; else out="${out}${dir}/${p}"$'\n'; fi done <<< "$list" From 02f367cdc2297b8a80cc1587d75e5ff056a52a27 Mon Sep 17 00:00:00 2001 From: Aditya Singh Date: Tue, 4 Aug 2026 10:05:38 +0530 Subject: [PATCH 39/43] fix(ci): reject target-branch == source ref to prevent overwriting the source branch --- .github/workflows/cd-built-branch.yml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/.github/workflows/cd-built-branch.yml b/.github/workflows/cd-built-branch.yml index b4bc333..53ebf04 100644 --- a/.github/workflows/cd-built-branch.yml +++ b/.github/workflows/cd-built-branch.yml @@ -135,11 +135,17 @@ jobs: INPUT_NODE_VERSION: ${{ inputs.node-version }} INPUT_COMPOSER_FLAGS: ${{ inputs.composer-flags }} INPUT_BUILD_COMMAND: ${{ inputs.build-command }} + TARGET_BRANCH: ${{ inputs.target-branch }} SOURCE_REF: ${{ inputs.source-ref != '' && inputs.source-ref || github.ref_name }} run: | set -euo pipefail source_sha="$(git rev-parse HEAD)" + if [ "$TARGET_BRANCH" = "$SOURCE_REF" ]; then + echo "::error::target-branch '${TARGET_BRANCH}' is the ref being built. Publishing would commit generated output onto the source branch — use a dedicated branch." + exit 1 + fi + jq -e 'type == "array" and length > 0 and all(type == "object")' >/dev/null 2>&1 <<<"$INPUT_TARGETS" \ || { echo "::error::'targets' must be a non-empty JSON array of objects (got: $INPUT_TARGETS)"; exit 1; } @@ -477,6 +483,14 @@ jobs: git fetch --no-tags origin "+refs/heads/${TARGET_BRANCH}:refs/remotes/origin/${TARGET_BRANCH}" remote_tip="$(git rev-parse "refs/remotes/origin/${TARGET_BRANCH}")" + # A dedicated deploy branch is never in the source history — its tip is a generated commit. + if git merge-base --is-ancestor "$remote_tip" "$SOURCE_SHA"; then + echo "::error::'${TARGET_BRANCH}' is part of the history being built (its tip ${remote_tip}" \ + "is an ancestor of ${SOURCE_SHA}), so publishing would commit generated output onto the" \ + "source branch. Point target-branch at a dedicated branch only this workflow writes to." + exit 1 + fi + # Only ever move the branch forward: a lost push race skips green, an explicit ref is a # rollback needing allow-rewind, and a force-pushed source branch is refused outright. published_parent="$(git rev-parse --verify --quiet "refs/remotes/origin/${TARGET_BRANCH}^" || true)" From b7722188549dfcd4b8d8f4a90d42086097b9226c Mon Sep 17 00:00:00 2001 From: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> Date: Mon, 10 Aug 2026 17:51:18 +0530 Subject: [PATCH 40/43] [v1.0.0] Prepare release for public main (#33) * docs(release): prepare v1.0.0 for public main - README: drop from 800 lines to a workflow index; remove references to the never-implemented wp-cd.yml orchestrator. - CHANGELOG: add "v1.0.0 - 2026-08-10" section, removing the Unreleased heading - Split caller examples out of README into examples/ (one per workflow) - Add LICENSE (GPL-2.0-or-later) and CONTRIBUTING.md - Replace CLAUDE.md doc content with a pointer to tool-agnostic AGENTS.md - Add ci-self-check.yml (yamllint + actionlint + bin/check-workflows.sh) and bin/check-workflows.sh examples contract checker - Add .github/actionlint.yaml (ignore SC2016) - Drop .claude/ working directory and cd-split-composer-packages.yml from the release - version-monitor.yml: pin checkout/setup-node SHAs, add job name * fix(ci): drop &&/|| short-circuits flagged by SC2015 in cd-built-branch * fix: address Copilot review on examples, README and concurrency --- .claude/commands/handoff.md | 184 ---- .claude/issues/1-ci-lint-workflows.md | 168 ---- .claude/issues/11-ci-test-build-artifact.md | 119 --- .claude/issues/13-ci-orchestrator.md | 113 --- .claude/issues/14-cd-github-release.md | 87 -- .claude/issues/15-cd-wp-org.md | 99 --- .claude/issues/16-cd-s3.md | 95 -- .claude/issues/18-version-monitor-workflow.md | 72 -- .claude/issues/19-ci-build-artifact-gate.md | 97 --- .../issues/20-cd-split-composer-packages.md | 103 --- .claude/issues/3-ci-test-js.md | 86 -- .claude/issues/5-ci-test-php.md | 92 -- .claude/issues/7-ci-build.md | 121 --- .claude/issues/9-ci-test-a11y.md | 97 --- .claude/issues/_TEMPLATE.md | 98 --- .gitattributes | 3 - .github/ISSUE_TEMPLATE/task.md | 4 +- .github/actionlint.yaml | 7 + .github/pull_request_template.md | 7 +- .github/workflows/cd-built-branch.yml | 14 +- .../workflows/cd-split-composer-packages.yml | 154 ---- .github/workflows/ci-self-check.yml | 47 + .github/workflows/version-monitor.yml | 5 +- .yamllint.yml | 1 - AGENTS.md | 93 ++ CHANGELOG.md | 12 +- CLAUDE.md | 191 +--- CONTRIBUTING.md | 62 ++ LICENSE | 339 ++++++++ README.md | 820 ++---------------- bin/check-workflows.sh | 159 ++++ examples/cd-built-branch.yml | 37 + examples/cd-github-release.yml | 31 + examples/cd-s3.yml | 34 + examples/cd-wp-org.yml | 34 + examples/ci-build-artifact-gate.yml | 16 + examples/ci-build.yml | 25 + examples/ci-detect-changes.yml | 30 + examples/ci-lint-css.yml | 15 + examples/ci-lint-js.yml | 16 + examples/ci-lint-php.yml | 17 + examples/ci-test-a11y.yml | 20 + examples/ci-test-build-artifact.yml | 29 + examples/ci-test-js.yml | 16 + examples/ci-test-php.yml | 22 + examples/version-monitor.yml | 20 + examples/wp-ci.yml | 42 + 47 files changed, 1195 insertions(+), 2758 deletions(-) delete mode 100644 .claude/commands/handoff.md delete mode 100644 .claude/issues/1-ci-lint-workflows.md delete mode 100644 .claude/issues/11-ci-test-build-artifact.md delete mode 100644 .claude/issues/13-ci-orchestrator.md delete mode 100644 .claude/issues/14-cd-github-release.md delete mode 100644 .claude/issues/15-cd-wp-org.md delete mode 100644 .claude/issues/16-cd-s3.md delete mode 100644 .claude/issues/18-version-monitor-workflow.md delete mode 100644 .claude/issues/19-ci-build-artifact-gate.md delete mode 100644 .claude/issues/20-cd-split-composer-packages.md delete mode 100644 .claude/issues/3-ci-test-js.md delete mode 100644 .claude/issues/5-ci-test-php.md delete mode 100644 .claude/issues/7-ci-build.md delete mode 100644 .claude/issues/9-ci-test-a11y.md delete mode 100644 .claude/issues/_TEMPLATE.md create mode 100644 .github/actionlint.yaml delete mode 100644 .github/workflows/cd-split-composer-packages.yml create mode 100644 .github/workflows/ci-self-check.yml create mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100755 bin/check-workflows.sh create mode 100644 examples/cd-built-branch.yml create mode 100644 examples/cd-github-release.yml create mode 100644 examples/cd-s3.yml create mode 100644 examples/cd-wp-org.yml create mode 100644 examples/ci-build-artifact-gate.yml create mode 100644 examples/ci-build.yml create mode 100644 examples/ci-detect-changes.yml create mode 100644 examples/ci-lint-css.yml create mode 100644 examples/ci-lint-js.yml create mode 100644 examples/ci-lint-php.yml create mode 100644 examples/ci-test-a11y.yml create mode 100644 examples/ci-test-build-artifact.yml create mode 100644 examples/ci-test-js.yml create mode 100644 examples/ci-test-php.yml create mode 100644 examples/version-monitor.yml create mode 100644 examples/wp-ci.yml diff --git a/.claude/commands/handoff.md b/.claude/commands/handoff.md deleted file mode 100644 index ac04bd2..0000000 --- a/.claude/commands/handoff.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -name: handoff -description: Generate a Handoff log entry for rotating out of, or into, the current issue. Produces both the log entry for `.claude/issues/-.md` and a matching GitHub issue comment. ---- - -# /handoff — log rotation to or from this issue - -## What this skill does - -Generates a correctly-formatted **Handoff log** entry for `.claude/issues/-.md` plus a matching **GitHub issue comment** the engineer can post directly on the issue. - -Automatically detects which issue is active from the current branch name, and produces the right direction of entry based on the user's input. - -## How to invoke - -- `/handoff out` — before you step away from the issue (planned or unplanned rotation) -- `/handoff in` — after you pull the branch and confirm you can reproduce state -- `/handoff` — Claude asks which direction - ---- - -## Instructions for Claude - -### Step 1 — confirm direction - -If the user passed `out` or `in` as an argument, use that. Otherwise ask once: - -> Are you handing off **OUT** (leaving the issue) or **IN** (taking over)? - -Do not proceed until direction is confirmed. - -### Step 2 — locate the issue progress file - -1. Run `git branch --show-current` to get the active branch. -2. Parse the pattern `/task/` (e.g. `v1.0.0/task/singleton-trait` → slug is `singleton-trait`). -3. Search `.claude/issues/` for a file matching `*-.md`. -4. If exactly one match, that's the file. -5. If no match, ask the user: "Couldn't find a progress file for this branch. What's the issue number and slug?" -6. If multiple matches, list them and ask which one. - -Read the file — it provides context for what's been done. - -### Step 3a — for `out` direction, gather context - -Collect these before drafting the entry. Do the investigation first, then ask only the questions you can't answer from the repo state. - -1. **Branch state:** - ```bash - git log -8 --oneline - git status - git rev-parse --short HEAD - ``` - Flag any uncommitted or untracked changes — they must be either committed (`wip:` prefix OK), stashed, or pushed to a WIP branch before handoff. - -2. **What's done / in progress / next:** - - Read the issue file's `Files changed so far` and `Decisions made` sections — done work is there. - - Compare against the GitHub issue body's `What you're building → In scope` list — figure out what's still outstanding. - - Look at `git diff HEAD~1` for the most recent work — that's likely "in progress". - -3. **Verification state:** - - Read the issue file's `Verification run` section — last known-green state. - - Confirm with the user whether it's still accurate ("Have you run the verification commands since this log?"). - -4. **Gotchas worth flagging:** - - Grep for `TODO` / `FIXME` / `XXX` in the diff since the last commit on the base branch: - ```bash - git diff release/...HEAD | grep -E '(TODO|FIXME|XXX)' - ``` - - Check for suppression directives added to `phpstan.neon.dist`, `phpcs.xml.dist`, or `.eslintrc.js` — those are non-obvious state the incoming engineer needs to know about. - - Check if any config files changed (`composer.json`, `package.json`, `phpcs.xml.dist`, etc.). - -5. **Blockers / open questions:** - - Read the issue file's `Open questions` section. - - If entries are stale (resolved but not cleaned up), flag to the user before generating the log. - -### Step 3b — for `in` direction, verify reproducibility first - -Before drafting an incoming entry, make sure the engineer can actually reproduce state. Ask: - -> Have you run the repo's verification commands on this branch? (`composer check` for PHP repos, `npm run check` for JS repos.) - -If not, tell them to run: - -```bash -git fetch origin -git checkout /task/ -git pull -composer check # or: npm run check -``` - -Only proceed with the log entry after they confirm exit code `0`. If the commands fail, help them triage what's changed between the outgoing-handoff commit and HEAD before continuing. - -### Step 4 — ask the minimum needed questions - -For `out` direction, ask one at a time (don't dump everything at once): - -1. **Reason for rotation** — e.g. "Client X escalation", "End of sprint rotation", "Permanent rotation" -2. **Expected return date** — an estimate is fine; "fully off" is fine too -3. **Anything a reviewer or the next engineer needs to know that isn't already in git history or the issue file?** -4. **Contact availability during the rotation** — "Slack DM OK", "Fully off", "Emergency only" - -For `in` direction, ask only: - -1. **Any deviations from the outgoing plan?** (If they agree with the outgoing engineer's next steps, answer is "none") - -### Step 5 — produce two artifacts - -Output BOTH clearly separated. Do not combine them. - -#### Artifact 1 — Handoff log entry (paste into `.claude/issues/-.md`) - -Use the **exact** template below. Keep bullets tight — this is a log, not a narrative. - -**OUT entry template:** - -```markdown -### → Handoff OUT · · @ - -- **Reason for rotation:** -- **Expected return:** -- **Branch state:** `` pushed to remote, HEAD at commit `` -- **What's done:** - - - - -- **What's in progress:** - - -- **What's next:** - - -- **Blockers / open questions:** - - -- **Gotchas for the incoming engineer:** - - -- **Contact:** -``` - -**IN entry template:** - -```markdown -### ← Handoff IN · · @ - -- **Confirmed reproducibility:** -- **Starting point:** -- **Deviations from plan above:** -``` - -#### Artifact 2 — GitHub issue comment (paste into the issue) - -Short, 3–5 lines. Links back to the log entry. @mentions whoever matters. - -```markdown -### 🔄 Handoff — @ <→|←> @ - -<1–2 sentence plain-language summary> - -Full details in `.claude/issues/-.md` → Handoff log. - -cc @ -``` - -### Step 6 — hand back to the user without taking further action - -Do **not** commit, push, or post the comment yourself. Print both artifacts with clear instructions: - -**For OUT direction, remind the user to:** - -1. Append Artifact 1 to `.claude/issues/-.md` → `Handoff log` section -2. Commit + push the log update (small commit — just the log is fine: `chore(handoff): log rotation out of #`) -3. Apply `Status: Blocked` label on the GitHub issue with a short note -4. Post Artifact 2 as a GitHub issue comment - -**For IN direction, remind the user to:** - -1. Append Artifact 1 to `.claude/issues/-.md` → `Handoff log` section -2. Commit + push the log update (`chore(handoff): log rotation into #`) -3. Remove `Status: Blocked` label from the GitHub issue (if they're actively resuming) -4. Post Artifact 2 as a GitHub issue comment - ---- - -## Why this matters - -With 4-hour-per-day senior availability, engineers will rotate in and out of issues regularly. A clean handoff turns a 4-hour window into 4 productive hours. A messy handoff turns it into 2 productive hours plus 2 hours of archaeology. Across a sprint that's the difference between shipping and slipping. - -The handoff log is the single source of truth for rotation state — not Slack threads, not DMs, not the PR description. It lives with the code, in the issue file, under git. diff --git a/.claude/issues/1-ci-lint-workflows.md b/.claude/issues/1-ci-lint-workflows.md deleted file mode 100644 index 7c5d5f4..0000000 --- a/.claude/issues/1-ci-lint-workflows.md +++ /dev/null @@ -1,168 +0,0 @@ -# Issue #1 — Add detect-changes + lint-css/js/php reusable workflows - -**Status:** in-review -**Branch:** `v1.0.0/task/ci-lint-workflows` -**PR:** #2 -**Assignee:** @Adi-ty - ---- - -## Summary - -Every rtCamp WordPress project duplicates the same lint pipeline (the copy-pasted `Test and Measure` workflow, with drift). This issue centralises the four pre-CI lint stages — changed-file detection plus CSS / JS / PHP linting — into individually callable reusable workflows so every consumer adopts one canonical implementation via `uses: rtCamp/wp-shared-workflows/.github/workflows/ci-*.yml@v1`. - ---- - -## Decisions made - -- [2026-05-29] `ci-detect-changes.yml` wraps the `wp-tooling detect-changes` CLI rather than re-implementing the legacy git-diff bash dance. Base-ref resolution (PR via `GITHUB_BASE_REF`, push via the event `before` SHA / `HEAD~1`), bucket regexes, and the ignore default all live in the CLI — the workflow only passes flags and promotes outputs. -- [2026-05-29] wp-tooling is installed by cloning `https://github.com/rtCamp/wp-tooling.git` at `release/v1.0.0` and running `npm install --install-links --prefix "$RUNNER_TEMP/wp-tooling"` on the monorepo subpath `node-packages/wp-tooling`. npm can't install a git subdirectory, and the repo root is a private, bin-less workspace, so a plain `npm i -g ` exposes no CLI. The workflow then adds `$RUNNER_TEMP/wp-tooling/node_modules/.bin` to `PATH` via `GITHUB_PATH` (no global install). Interim stopgap until `@rtcamp/wp-tooling` is published (GitHub Packages, `access: restricted`); because the repo may be private the clone needs a token, so detect-changes won't run green in a consumer until publish — verified end-to-end via `act`. -- [2026-05-29] Detection runs with `--output github --include-files`, so the workflow exposes both per-bucket counts (for gating) and per-bucket file lists (`css-files`, `js-files`, `php-files`, `gha-files`). The `--include-files` support is wp-tooling#7, now on `release/v1.0.0`. -- [2026-05-29] The three lint workflows each accept a `changed-files` input: non-empty lints only those paths, empty runs the whole-project `lint-command`. This is what makes the detector's `*-files` outputs useful — addresses @AnuragVasanwala's review asks (lint only updated files for CSS/JS/PHP; include exact file paths). For PHP, `changed-files` scopes PHPCS only; PHPStan always runs whole-project (cross-file analysis). -- [2026-05-29] `ignore-paths` / `base-ref` flags are only passed to the CLI when non-empty. An empty `--ignore` *disables* ignoring in the CLI, so omitting the flag (the default) correctly falls through to the CLI's built-in ignore set. -- [2026-05-29] Orchestrator wiring (`wp-ci.yml`, issue #13) is out of scope — `ci-detect-changes.yml` runs unconditionally and only exposes outputs; the orchestrator does the count-based gating and feeds `*-files` into the lint jobs. - ---- - -## Files changed so far - -- `.github/workflows/ci-detect-changes.yml` — new -- `.github/workflows/ci-lint-css.yml` — new (already on branch) -- `.github/workflows/ci-lint-js.yml` — new (already on branch) -- `.github/workflows/ci-lint-php.yml` — new (already on branch) -- `README.md` — edited (added detect-changes + lint-css/js/php sections) -- `CHANGELOG.md` — edited (four bullets under Unreleased → Added) -- `.claude/issues/1-ci-lint-workflows.md` — new (this file) - ---- - -## Verification run - -```bash -❯ pipx run yamllint . -❯ act workflow_call -W .github/workflows/ci-detect-changes.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Set up job -*DRYRUN* [CI / Detect Changes/Detect changes] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CI / Detect Changes/Detect changes] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CI / Detect Changes/Detect changes] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Detect Changes/Detect changes] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Set up job -*DRYRUN* [CI / Detect Changes/Detect changes] ☁ git clone 'https://github.com/actions/setup-node' # ref=49933ea5288caeca8642d1e84afbd3f7d6820020 -*DRYRUN* [CI / Detect Changes/Detect changes] Non-terminating error while running 'git clone': some refs were not updated -*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Main Checkout repository [7.201541ms] -*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Main Set up Node.js -*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Main Set up Node.js [9.009583ms] -*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Main Install wp-tooling -*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Main Install wp-tooling [17.675625ms] -*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Main Detect changed files -*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Main Detect changed files [17.995125ms] -*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Post Set up Node.js -*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Post Set up Node.js [6.890833ms] -*DRYRUN* [CI / Detect Changes/Detect changes] ⭐ Run Complete job -*DRYRUN* [CI / Detect Changes/Detect changes] Cleaning up container for job Detect changes -*DRYRUN* [CI / Detect Changes/Detect changes] ✅ Success - Complete job -*DRYRUN* [CI / Detect Changes/Detect changes] 🏁 Job succeeded -❯ act workflow_call -W .github/workflows/ci-lint-js.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Set up job -*DRYRUN* [CI / Lint JS/ESLint] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CI / Lint JS/ESLint] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CI / Lint JS/ESLint] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Lint JS/ESLint] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Set up job -*DRYRUN* [CI / Lint JS/ESLint] ☁ git clone 'https://github.com/actions/setup-node' # ref=49933ea5288caeca8642d1e84afbd3f7d6820020 -*DRYRUN* [CI / Lint JS/ESLint] Non-terminating error while running 'git clone': some refs were not updated -*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Main Checkout repository [6.915708ms] -*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Main Set up Node.js -*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Main Set up Node.js [6.775ms] -*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Main Install npm dependencies -*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Main Install npm dependencies [20.010333ms] -*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Main Run ESLint -*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Main Run ESLint [15.109542ms] -*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Post Set up Node.js -*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Post Set up Node.js [4.765958ms] -*DRYRUN* [CI / Lint JS/ESLint] ⭐ Run Complete job -*DRYRUN* [CI / Lint JS/ESLint] Cleaning up container for job ESLint -*DRYRUN* [CI / Lint JS/ESLint] ✅ Success - Complete job -*DRYRUN* [CI / Lint JS/ESLint] 🏁 Job succeeded -❯ act workflow_call -W .github/workflows/ci-lint-php.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Set up job -*DRYRUN* [CI / Lint PHP/Lint PHP] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CI / Lint PHP/Lint PHP] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CI / Lint PHP/Lint PHP] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Lint PHP/Lint PHP] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Set up job -*DRYRUN* [CI / Lint PHP/Lint PHP] ☁ git clone 'https://github.com/shivammathur/setup-php' # ref=accd6127cb78bee3e8082180cb391013d204ef9f -*DRYRUN* [CI / Lint PHP/Lint PHP] Non-terminating error while running 'git clone': some refs were not updated -*DRYRUN* [CI / Lint PHP/Lint PHP] ☁ git clone 'https://github.com/actions/cache' # ref=0057852bfaa89a56745cba8c7296529d2fc39830 -*DRYRUN* [CI / Lint PHP/Lint PHP] Non-terminating error while running 'git clone': some refs were not updated -*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Checkout repository [6.769458ms] -*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Set up PHP -*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Set up PHP [6.604291ms] -*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Resolve Composer cache directory -*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Resolve Composer cache directory [14.866541ms] -*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Cache Composer dependencies -*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Cache Composer dependencies [6.350875ms] -*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Install Composer dependencies -*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Install Composer dependencies [16.199916ms] -*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Main Run PHPCS -*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Main Run PHPCS [17.39875ms] -*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Post Cache Composer dependencies -*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Post Cache Composer dependencies [4.434375ms] -*DRYRUN* [CI / Lint PHP/Lint PHP] ⭐ Run Complete job -*DRYRUN* [CI / Lint PHP/Lint PHP] Cleaning up container for job Lint PHP -*DRYRUN* [CI / Lint PHP/Lint PHP] ✅ Success - Complete job -*DRYRUN* [CI / Lint PHP/Lint PHP] 🏁 Job succeeded -❯ act workflow_call -W .github/workflows/ci-lint-css.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Set up job -*DRYRUN* [CI / Lint CSS/Stylelint] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CI / Lint CSS/Stylelint] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CI / Lint CSS/Stylelint] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Lint CSS/Stylelint] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Set up job -*DRYRUN* [CI / Lint CSS/Stylelint] ☁ git clone 'https://github.com/actions/setup-node' # ref=49933ea5288caeca8642d1e84afbd3f7d6820020 -*DRYRUN* [CI / Lint CSS/Stylelint] Non-terminating error while running 'git clone': some refs were not updated -*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Main Checkout repository [5.968583ms] -*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Main Set up Node.js -*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Main Set up Node.js [6.16925ms] -*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Main Install npm dependencies -*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Main Install npm dependencies [20.346042ms] -*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Main Run Stylelint -*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Main Run Stylelint [16.111666ms] -*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Post Set up Node.js -*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Post Set up Node.js [4.70925ms] -*DRYRUN* [CI / Lint CSS/Stylelint] ⭐ Run Complete job -*DRYRUN* [CI / Lint CSS/Stylelint] Cleaning up container for job Stylelint -*DRYRUN* [CI / Lint CSS/Stylelint] ✅ Success - Complete job -*DRYRUN* [CI / Lint CSS/Stylelint] 🏁 Job succeeded ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- **Private-repo install auth (deferred, not a blocker):** `git+https://github.com/rtCamp/wp-tooling.git` needs wp-tooling to be public (or a token) to clone in a consumer's CI — the caller's `GITHUB_TOKEN` is not scoped to wp-tooling. Same limitation `version-monitor.yml` already carries; resolves when both repos go public / wp-tooling is published. Carries a `# TODO(wp-tooling publish)` comment. -- **Multi-line `*-files` outputs** are subject to GitHub's `$GITHUB_OUTPUT` size limits on very large PRs — acceptable for normal PRs. -- **`act` cannot fully exercise** the GitHub-event base-ref path or the private `git+https` install; the real proof is a consumer repo referencing `@` that wires `detect` → lint workflows. Note this as deferred end-to-end verification. -- Detection semantics (two-dot `git diff base HEAD`, bucket regexes, ignore defaults) are the CLI's contract, not overridden here. - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/11-ci-test-build-artifact.md b/.claude/issues/11-ci-test-build-artifact.md deleted file mode 100644 index 024c388..0000000 --- a/.claude/issues/11-ci-test-build-artifact.md +++ /dev/null @@ -1,119 +0,0 @@ -# Issue #11 — ci-test-build-artifact reusable workflow - -**Status:** in-progress -**Branch:** `v1.0.0/task/ci-test-build-artifact` -**PR:** # -**Assignee:** @Adi-ty - ---- - -## Summary - -A green `ci-build.yml` run only proves the build did not crash — not that the packaged output installs and boots in WordPress. This workflow downloads the build artifact, boots a real WordPress in `@wordpress/env`, activates the plugin/theme, and runs `wp doctor`, so failures like a PHP file referenced but never copied into the bundle, an over-eager `.distignore`, or a path-cased file that breaks on Linux fail CI loudly. It lives here because every consuming skeleton needs the same flow against its own artifact. - ---- - -## Decisions made - -- [2026-05-28] README-only delivery (repo house style): reusable workflow + README caller examples + CHANGELOG entry. No committed fixture, no `_examples/` file, no in-PR self-test wrapper — matches how #3/#5/#7/#9/#19 shipped. Verify via `act` dry-run and a real consumer repo's CI. -- [2026-05-28] Workflow-owned wp-env: the workflow runs `npx --yes @wordpress/env` itself and writes a `.wp-env.override.json` to pin `phpVersion`/`core` and mount the artifact, rather than reusing the consumer's `npm run wp-env` (which `ci-test-a11y.yml` does). Keeps version pinning self-contained. -- [2026-05-28] Override mounts the artifact **in isolation** — it sets `plugins: []` and `themes: []` so the consumer's `.wp-env.json` (standard rtCamp config mounts the dev source `"."`) does not collide with the artifact mapping at the same destination. Discovered during smoke testing (a standard rtCamp `.wp-env.json` mounts the dev source as `plugins: ["."]`). -- [2026-05-28] Explicit `slug` input (the directory to activate) instead of deriving it from plugin headers / composer.json — deterministic across project shapes. Added `node-version` too (needed to drive `npx`, parity with sibling workflows). Both go beyond the issue's literal four-input contract. -- [2026-05-28] Used `wp doctor check --all --format=json` (runs the checks, returns per-check `status`) — the issue's reference used `wp doctor list`, which only lists available checks. Fail only on `error` severity; warnings allowed. Verified against the doctor-command docs: `check` runs, `--all` = every registered check, results are `{name, status, message}` with `status` ∈ `success|warning|error`. -- [2026-05-28] Artifact contract documented: the artifact must be a complete installable plugin/theme directory, so consumers point `ci-build.yml`'s `artifact-path` at a packaged dist dir, not bare `build/`. `actions/download-artifact` restores contents uncompressed — no unzip step. -- [2026-05-28] `wp doctor check --all` flagged `constant-wp-debug-falsy` as `error` during smoke testing (a real CI run, after the visibility fix). Cause: wp-env enables `WP_DEBUG` by default (dev environment), and that check is production-oriented — so it errors for every consumer regardless of the artifact (`core-verify-checksums` passed; my earlier guess was wrong). Fix: added a `doctor-ignore-checks` input (default `constant-wp-debug-falsy`) and filter those names out of the error gate in jq; all other error-severity checks still fail the build. -- [2026-05-28] Theme-path + pinned-version were exercised during smoke testing (`install-path: wp-content/themes`, `wp-version: 6.9.4`). Pinned `6.9.4` (latest in its 6.9.x line) so only a *major* (7.0) update is offered → doctor `core-update` returns `warning`, not `error`. Verified via the doctor-command source: `core-update` sets `error` for an available *minor* update, `warning` for a major. Also passed `doctor-ignore-checks: "constant-wp-debug-falsy,core-update"` so the test stays durable as releases advance (core updates are about WordPress core, not the artifact). -- [2026-05-28] `permissions: contents: read` is sufficient — the artifact is downloaded from the same run (consumer calls `ci-build` then this), so no `actions: read` / cross-run id needed. `wp-env stop` runs in an `if: always()` step with its own `timeout-minutes: 2` so no container leaks. - ---- - -## Files changed so far - -- `.github/workflows/ci-test-build-artifact.yml` — new -- `README.md` — edited (new `### ci-test-build-artifact.yml` section under Individual workflows) -- `CHANGELOG.md` — edited (Unreleased → Added bullet) -- `.claude/issues/11-ci-test-build-artifact.md` — new (this file) - -Consumer-side verification was done separately via smoke testing (external, not tracked here). - ---- - -## Verification run - -```bash -❯ act workflow_call -W .github/workflows/ci-test-build-artifact.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Set up job -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Set up job -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] Non-terminating error while running 'git clone': some refs were not updated -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ☁ git clone 'https://github.com/actions/download-artifact' # ref=d3f86a106a0bac45b974a628896c90dbdf5c8093 -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Checkout repository [6.879458ms] -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Set up Node.js -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Set up Node.js [6.783ms] -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Download build artifact -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Download build artifact [6.240375ms] -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Write wp-env override -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Write wp-env override [15.153375ms] -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Start wp-env -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Start wp-env [17.473208ms] -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Activate plugin or theme -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Activate plugin or theme [19.252875ms] -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Run wp doctor -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Run wp doctor [14.417958ms] -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Main Stop wp-env -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Main Stop wp-env [13.550458ms] -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Post Set up Node.js -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Post Set up Node.js [4.557333ms] -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ⭐ Run Complete job -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] Cleaning up container for job Boot artifact in wp-env -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] ✅ Success - Complete job -*DRYRUN* [CI / Test Build Artifact/Boot artifact in wp-env] 🏁 Job succeeded - -WP_VERSION=latest PHP_VERSION=8.3 INSTALL_PATH=wp-content/plugins SLUG=my-plugin \ - jq -n --arg wp "$WP_VERSION" --arg php "$PHP_VERSION" --arg dest "${INSTALL_PATH%/}/${SLUG}" \ - '{ - core: (if $wp == "latest" then null else "WordPress/WordPress#\($wp)" end), - phpVersion: $php, - plugins: [], - themes: [], - mappings: { ($dest): "./artifact" } - }' -{ - "core": "WordPress/WordPress#", - "phpVersion": "", - "plugins": [], - "themes": [], - "mappings": { - "/": "./artifact" - } -} -``` - -Binding test (boots wp-env + Docker, which `act` cannot do reliably) is done via smoke testing: a real CI run boots `ci-build` → `ci-test-build-artifact` against a packaged plugin/theme, confirming activate + `wp doctor` pass and `wp-env stop` runs on failure. - ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- Doctor output parsing is safe without stderr suppression: wp-env spawns the cli command with `stdio: 'inherit'` (`node_modules/@wordpress/env/lib/runtime/docker/index.js`), so the WP-CLI JSON is alone on stdout while wp-env's ora spinner writes status to stderr. `result=$(…)` captures only stdout. Earlier `2>/dev/null` was removed (it only hid useful diagnostics). `wp doctor check` exits 1 on an error-severity check, so the capture uses `|| true` to always print the report; the explicit `jq` is the gate (and fails the step under `set -e` on empty/garbage output). -- `npx --yes @wordpress/env` first-run install counts against the ~6 min target; `--update` + runner Docker cache should keep it under budget. -- Isolation override clears `plugins`/`themes`; a consumer that needs companion plugins active during the smoke test is not covered yet (would be a future `companion-plugins` input). - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/13-ci-orchestrator.md b/.claude/issues/13-ci-orchestrator.md deleted file mode 100644 index 123518e..0000000 --- a/.claude/issues/13-ci-orchestrator.md +++ /dev/null @@ -1,113 +0,0 @@ -# Issue #13 — Add CI orchestrator workflow (`wp-ci.yml`) - -**Status:** in-review -**Branch:** `v1.0.0/task/ci-orchestrator` -**PR:** #25 -**Assignee:** @Adi-ty - ---- - -## Summary - -The individual CI workflows each do one thing; a consuming skeleton would otherwise call ~8 of them by hand and keep them in sync. `wp-ci.yml` is the orchestrator a skeleton calls once: it routes to the right subset based on a single `project-type` input (`plugin` | `theme` | `package`), runs `ci-detect-changes` first, and gates every downstream job on the per-bucket change counts so untouched file types are skipped. A `skip` input drops a named job without forking. It is the CI counterpart to the planned CD orchestrator (`wp-cd.yml`, #17). - ---- - -## Decisions made - -- [2026-05-29] **Branched off `v1.0.0/task/ci-lint-workflows` (#2)**, not `release/v1.0.0`. `detect-changes` is the orchestrator's backbone (every job gates on its outputs), so it must exist on the branch for the orchestrator to be written in its real shape. PR is **stacked against the #2 branch** (clean diff = orchestrator + docs + example); rebase onto `release/v1.0.0` once #2 merges. Review-only for now — will not merge. -- [2026-05-29] **Gating uses counts, not the issue's booleans.** The real `ci-detect-changes.yml` outputs `*-count` + `*-files`, not `php-changed == 'true'`. Jobs gate on `needs.detect-changes.outputs.-count > 0` and pass `*-files` into each linter's `changed-files`. (Hardens / corrects the issue's reference snippet.) -- [2026-05-29] **Started from a `project-type` (required) + `skip` contract.** Updated the stale top-level README consumer example that advertised non-existent inputs (CLAUDE.md: README examples must actually work). -- [2026-06-16] **Contract expanded to replace the legacy "Test and Measure" workflow.** Added the `php-versions` × `wp-versions` (+ `test-php-exclude`) matrix for `test-php`, a `use-wp-env` toggle (default true; false = standalone PHPUnit for a pure Composer library), an `enable-phpstan` passthrough to `lint-php`, and a `validate-inputs` job that fails fast on a bad `project-type` or matrix input. Coverage reporting stays a v1.x follow-up. -- [2026-05-29] **`skip` matching is comma-bounded:** `!contains(format(',{0},', inputs.skip), ',,')` so `skip: build` never also drops `build-artifact`. -- [2026-06-16] **`build-artifact` wired; `bc` dropped.** `ci-test-build-artifact.yml` is present and wired into the orchestrator. `ci-test-bc.yml` stays deferred (TS blocker), so no `bc` job is defined. With all `uses:` targets present, `act --dryrun` parses the whole orchestrator. -- [2026-06-16] **No committed example caller.** Dropped `.github/workflows/_examples/caller-wp-ci.yml` for README-only delivery, matching house style (#3/#5/#7/#9/#11/#14). -- [2026-06-17] **a11y is opt-in via `run-a11y` (default false).** It was running for every plugin/theme push/PR — diverging from the documented label-gated convention and failing CI for consumers without pa11y config. Added a `run-a11y` boolean (default false); the caller wires it to the `Run a11y` label. Chose an input over hard-coding the event/label into the orchestrator (Copilot's suggestion) so it stays trigger-agnostic and input-driven; `skip: a11y` remains a second off-switch. -- [2026-05-29] **`build-artifact` install-path derived from `project-type`** (`theme` → `wp-content/themes`, else `wp-content/plugins`) and `slug` defaulted to the repo name — the most the 2-input contract can infer. - ---- - -## Files changed so far - -- `.github/workflows/wp-ci.yml` — new (the orchestrator + `validate-inputs` job) -- `.github/workflows/ci-test-php.yml` — edited (`wp-version` input + WP_ENV pin steps for the matrix) -- `README.md` — edited (new `### wp-ci.yml` section; orchestrator inputs + presets) -- `CHANGELOG.md` — edited (bullets under Unreleased → Added) -- `.claude/issues/13-ci-orchestrator.md` — new (this file) - ---- - -## Verification run - -```bash -❯ act workflow_call -W .github/workflows/wp-ci.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CI / Orchestrator/Validate inputs] ⭐ Run Set up job -*DRYRUN* [CI / Orchestrator/Validate inputs] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CI / Orchestrator/Validate inputs] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CI / Orchestrator/Validate inputs] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Orchestrator/Validate inputs] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Orchestrator/Validate inputs] ✅ Success - Set up job -*DRYRUN* [CI / Orchestrator/Validate inputs] ⭐ Run Main Check project-type and test-php matrix inputs -*DRYRUN* [CI / Orchestrator/Validate inputs] ✅ Success - Main Check project-type and test-php matrix inputs [7.807875ms] -*DRYRUN* [CI / Orchestrator/Validate inputs] ⭐ Run Complete job -*DRYRUN* [CI / Orchestrator/Validate inputs] Cleaning up container for job Validate inputs -*DRYRUN* [CI / Orchestrator/Validate inputs] ✅ Success - Complete job -*DRYRUN* [CI / Orchestrator/Validate inputs] 🏁 Job succeeded -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Set up job -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] 🚀 Start image=node:16-buster-slim -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"]cmd=[] network="host" -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Set up job -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ☁ git clone 'https://github.com/actions/setup-node' # ref=49933ea5288caeca8642d1e84afbd3f7d6820020 -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] Non-terminating error while running 'git clone': some refs were not updated -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Main Checkout repository -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Main Checkout repository [3.83375ms] -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Main Set up Node.js -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Main Set up Node.js [3.577917ms] -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Main Install wp-tooling -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Main Install wp-tooling [5.64275ms] -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Main Detect changed files -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Main Detect changed files [5.960959ms] -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Post Set up Node.js -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Post Set up Node.js [1.769208ms] -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ⭐ Run Complete job -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] Cleaning up container for job Detect changes -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] ✅ Success - Complete job -*DRYRUN* [Detect changes/CI / Detect Changes/Detect changes] 🏁 Job succeeded -``` - -Succeeded — no schema or terminating errors. (`act --dryrun` emits a benign non-terminating `git clone` "some refs were not updated" warning while pre-fetching the actions — an `act` quirk, not a workflow failure.) - -Gating trace (manual) — expected job set per preset: - -- **plugin** → detect-changes + lint-css/js/php + test-js + test-php + build + build-artifact + a11y -- **theme** → detect-changes + lint-css/js/php + test-js + build + build-artifact + a11y (no test-php) -- **package** → detect-changes + lint-php + test-php (no css/js lint, test-js, build, build-artifact, a11y) - -Each job additionally requires its bucket count `> 0`; `skip: ""` drops exactly that job (comma-bounded — no substring bleed, e.g. `build` vs `build-artifact`). - ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- **`act` dry-run passes.** All `uses:` targets are present on the branch (`build-artifact` included), so the orchestrator parses and the `test-php` matrix expands under `act --dryrun`. A full green run still needs a real consumer on GitHub Actions; anything touching `wp-env` (Docker-in-Docker) cannot run under local `act`. -- **`build-artifact` is the weakest generic fit.** It needs a *packaged* artifact (`dist//`), but the default `ci-build` build-command emits bare `build/`. Wired with `slug` = repo name + `project-type`-derived install-path for design completeness; a non-standard slug or a packaging step needs a consumer override (candidate v1.x passthrough inputs). Do not assume this job runs green post-#23 without packaging wiring. -- **`bc` removed.** `ci-test-bc.yml` is deferred (TypeScript blocker), so no `bc` job is defined; add it back when that workflow lands. -- **Self-test deferred.** This repo is pure YAML (no PHP/JS to lint/test), so a meaningful self-run of `wp-ci.yml` is not possible. Real e2e proof = a consumer repo calling `wp-ci.yml@` on push/PR. -- **a11y is opt-in (`run-a11y`, default false).** `ci-test-a11y` is trigger-agnostic; the orchestrator now gates it on the `run-a11y` input (default false) so a slow pa11y run never fires — or fails for lack of pa11y config — unless the caller opts in (typically wired to the `Run a11y` label). `skip: a11y` remains a second off-switch. -- **Deps landed.** detect-changes + lint (#2) and build-artifact (#23) are present on the branch; only `bc` (`ci-test-bc.yml`) stays deferred and is intentionally not wired. - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/14-cd-github-release.md b/.claude/issues/14-cd-github-release.md deleted file mode 100644 index e014ed6..0000000 --- a/.claude/issues/14-cd-github-release.md +++ /dev/null @@ -1,87 +0,0 @@ -# Issue #14 — Add CD GitHub Releases workflow (`cd-github-release.yml`) - -**Status:** in-review -**Branch:** `v1.0.0/task/cd-github-release` -**PR:** #24 -**Assignee:** @Adi-ty - ---- - -## Summary - -Tagging a release should produce a Git tag, a GitHub Release carrying the changelog notes, and the build artifact attached to that Release — without every skeleton wiring it by hand. `cd-github-release.yml` does exactly that on a `v*.*.*` tag push: download the named artifact, extract the matching `CHANGELOG.md` section as the body, and create the Release. It is the first CD workflow in the repo and the GitHub-target option the CD orchestrator (`wp-cd.yml`, #17) will call. - ---- - -## Decisions made - -- [2026-05-29] Create the Release with the **`gh` CLI** (`gh release create`), not `softprops/action-gh-release`. gh is preinstalled on runners, needs no third-party SHA to pin/track, and matches the repo's "prefer official/built-in tooling" rule. Overrides the issue's softprops suggestion. -- [2026-05-29] **README-only** delivery — no `.github/workflows/_examples/` file. The dir does not exist and every prior workflow shipped README-only. Overrides the issue's literal `_examples/` acceptance criterion for consistency. -- [2026-05-29] **Tolerant changelog heading match.** The awk does a literal first-token compare after stripping `## `, surrounding brackets, and a leading `v` — so `## v1.2.3`, `## 1.2.3`, `## [1.2.3]`, `## [v1.2.3]`, and `## v1.2.3 - ` all match `v1.2.3`, while `## Unreleased` and `## v1.2.30` do not. Avoids dynamic-regex escaping entirely. -- [2026-05-29] **Injection-safe:** `tag` / paths / booleans pass through step-level `env:` and are referenced as `$VARS`; nothing is interpolated as `${{ inputs.* }}` inside a shell/awk script (hardens the issue's reference snippet). -- [2026-05-29] **Fail closed:** missing changelog file, empty/absent section, or an empty downloaded artifact each `::error::` + `exit 1` — never publish a Release with no notes or no asset. `gh release create` runs with `--verify-tag` so a wrong/absent tag errors rather than silently creating a tag off the default branch. -- [2026-05-29] Inputs are exactly the five from the contract: `tag` (required), `artifact-name` (required), `changelog-path` (`CHANGELOG.md`), `draft` (`false`), `prerelease` (`false`). No extra knobs added. - ---- - -## Files changed so far - -- `.github/workflows/cd-github-release.yml` — new -- `README.md` — edited (new `### cd-github-release.yml` section) -- `CHANGELOG.md` — edited (bullet under Unreleased → Added) -- `.claude/issues/14-cd-github-release.md` — new (this file) - ---- - -## Verification run - -```bash -❯ pipx run yamllint . -❯ act workflow_call -W .github/workflows/cd-github-release.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Set up job -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Set up job -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ☁ git clone 'https://github.com/actions/download-artifact' # ref=d3f86a106a0bac45b974a628896c90dbdf5c8093 -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Main Checkout repository -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Main Checkout repository [8.740416ms] -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Main Download release artifact -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Main Download release artifact [7.706667ms] -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Main Extract changelog section -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Main Extract changelog section [19.298167ms] -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Main Create GitHub Release -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Main Create GitHub Release [19.135125ms] -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ⭐ Run Complete job -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] Cleaning up container for job Publish GitHub Release -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] ✅ Success - Complete job -*DRYRUN* [CD / GitHub Release/Publish GitHub Release] 🏁 Job succeeded -``` - -All pass. `## v1.2.3` and `## [1.2.3]` extract the right body; `## Unreleased` and `## v1.2.30` are not matched for tag `v1.2.3`; a tag with no section returns empty → exit 1. (A degenerate `tag: vUnreleased` would match `## Unreleased`, but a `v*.*.*` trigger can never produce that, so no special-casing.) - ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- **Same-run artifact:** `actions/download-artifact@v4` only sees the current run's artifacts. The intended model is orchestrator-driven (build → release in one run); a standalone tag-push call with no in-run build finds nothing. -- **Re-runs:** `gh release create` fails if the Release already exists. Acceptable for "create a Release" — no idempotency was requested. Flag if reviewers want upsert behaviour. -- **Asset shape:** attaches each file under `artifact/` as a Release asset (mirrors the issue's `files: artifact/*`). A single zipped asset would be a follow-up. -- **End-to-end is deferred:** `act` cannot create a real Release. Real proof is a `v*.*.*` tag push in a throwaway consumer (or via the orchestrator) with `contents: write`. -- **Soft deps:** #11 (artifact contract) and #17 (orchestrator) are open but non-blocking — the upload contract already lives in `ci-build.yml`, and the orchestrator is downstream. -- **Action pins:** `actions/checkout@…v4.2.2` (reused), `actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0` (matches the v4 `upload-artifact` producer). - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/15-cd-wp-org.md b/.claude/issues/15-cd-wp-org.md deleted file mode 100644 index b57faec..0000000 --- a/.claude/issues/15-cd-wp-org.md +++ /dev/null @@ -1,99 +0,0 @@ -# Issue #15 — Add CD WP.org deploy workflow (`cd-wp-org.yml`) - -**Status:** in-review -**Branch:** `v1.0.0/task/cd-wp-org` -**PR:** #26 -**Assignee:** @Adi-ty - ---- - -## Summary - -Plugins on the WordPress.org directory deploy over SVN to `https://plugins.svn.wordpress.org//` — a fiddly flow (trunk vs `tags/`, the `/assets/` dir, `readme.txt` `Stable tag` validation). `cd-wp-org.yml` wraps the proven `10up/action-wordpress-plugin-deploy` so a consuming plugin skeleton deploys with one tag-triggered caller: it downloads the build artifact, fails fast unless `readme.txt`'s `Stable tag` matches the tag, then deploys to `trunk/` + `tags//` and syncs assets to SVN `/assets/`. It is the second CD workflow (with `cd-github-release.yml`) and the WP.org target the CD orchestrator (`wp-cd.yml`, #17) will call. - ---- - -## Decisions made - -- [2026-05-29] **No blocker — proceeded.** Runs entirely in the caller's repo with its own WP.org credentials. The issue's "depends on #11" is a *logical/runtime* dependency: the workflow only downloads an artifact by name (like `cd-github-release.yml`), with no code-level `uses:` on `ci-test-build-artifact`. The producer `ci-build.yml` is already merged. No private cross-repo dependency, no impossible-input blocker (unlike the deferred BC workflow). -- [2026-05-29] **Branched off `release/v1.0.0`** (needs nothing from detect-changes/lint); PR targets `release/v1.0.0`. No stacking. -- [2026-05-29] **Use `10up/action-wordpress-plugin-deploy@54bd289b8525fd23a5c365ec369185f2966529c2 # v2.3.0`, SHA-pinned.** Third-party, but no official WordPress/Automattic WP.org deploy action exists, so this is the de-facto standard — justified under CLAUDE.md's "build custom only when there's a real gap." Mandated by the issue. -- [2026-05-29] **Corrected the issue's reference snippet.** Verified against the action's `action.yml` + `deploy.sh` at 2.3.0: the only `with:` inputs are `generate-zip` and `dry-run`. Everything else is **environment variables** — `SVN_USERNAME`, `SVN_PASSWORD`, `SLUG`, `VERSION`, `ASSETS_DIR`, `BUILD_DIR`. The issue's `with: slug / assets-dir` would silently do nothing. -- [2026-05-29] **`VERSION` computed by us, not the action.** The action only strips a leading `v` when it *derives* `VERSION` from the git ref; a passed `VERSION` is used as-is. So the readme-verify step strips `v`, emits the bare version as a step output, and the deploy step passes it as `VERSION` — keeping it equal to the readme `Stable tag` and the SVN `tags/`. -- [2026-05-29] **Artifact → `BUILD_DIR`.** The action rsyncs `$BUILD_DIR/` into `trunk/`; we download the artifact to `artifact/` and set `BUILD_DIR: artifact`. Assets are read from the *workspace* (`$GITHUB_WORKSPACE/$ASSETS_DIR/`), so the job also checks out the repo. -- [2026-05-29] **Injection-safe + fail-fast:** `tag` / `artifact-name` pass via step `env:` and are referenced as `$VARS`; nothing interpolated as `${{ inputs.* }}` inside a script. Missing `readme.txt`, missing `Stable tag:` header, or a mismatch each `::error::` + `exit 1` before the action runs (matches `cd-github-release.yml`). -- [2026-05-29] **`permissions: contents: read`** — only `checkout` reads the repo; the SVN deploy authenticates with the secrets, not the GitHub token. - ---- - -## Files changed so far - -- `.github/workflows/cd-wp-org.yml` — new (the workflow) -- `README.md` — edited (new `### cd-wp-org.yml` section under Individual workflows) -- `CHANGELOG.md` — edited (bullet under Unreleased → Added) -- `.claude/issues/15-cd-wp-org.md` — new (this file) - ---- - -## Verification run - -```bash -❯ pipx run yamllint .github/workflows/cd-wp-org.yml -❯ act workflow_call -W .github/workflows/cd-wp-org.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Set up job -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Set up job -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ☁ git clone 'https://github.com/actions/download-artifact' # ref=d3f86a106a0bac45b974a628896c90dbdf5c8093 -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ☁ git clone 'https://github.com/10up/action-wordpress-plugin-deploy' # ref=54bd289b8525fd23a5c365ec369185f2966529c2 -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Pre Deploy to WordPress.org -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Pre Deploy to WordPress.org [22.511292ms] -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Main Checkout repository -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Main Checkout repository [6.783791ms] -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Main Download build artifact -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Main Download build artifact [9.202ms] -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Main Verify readme.txt stable tag matches the release tag -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Main Verify readme.txt stable tag matches the release tag [21.101542ms] -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Main Deploy to WordPress.org -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Main /var/run/act/actions/10up-action-wordpress-plugin-deploy@54bd289b8525fd23a5c365ec369185f2966529c2/deploy.sh -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Main /var/run/act/actions/10up-action-wordpress-plugin-deploy@54bd289b8525fd23a5c365ec369185f2966529c2/deploy.sh [15.179166ms] -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⚙ ::set-output:: zip-path= -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Main Deploy to WordPress.org [52.698916ms] -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Post Deploy to WordPress.org -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Post Deploy to WordPress.org [30.75µs] -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ⭐ Run Complete job -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] Cleaning up container for job Deploy to WordPress.org -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] ✅ Success - Complete job -*DRYRUN* [CD / WordPress.org Deploy/Deploy to WordPress.org] 🏁 Job succeeded -``` - -yamllint clean; `act` resolves the full step graph (checkout → download-artifact → verify → 10up composite deploy). - -readme `Stable tag` check (local awk unit-test, all pass): `Stable tag: 1.2.3` matches `tag: v1.2.3`; a mismatched tag, a `Stable tag: trunk`, and a missing `Stable tag:` header each exit 1; case-insensitive and CRLF/space-tolerant. - ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- **`Stable tag: trunk` plugins are rejected** by the strict match. -- **Same-run artifact** — `download-artifact@v4` only sees the current run's artifacts; the model is build → deploy in one run (mirrors `cd-github-release.yml`). -- **Immutable tags** — the action errors (non-zero) if `tags/` already exists on WP.org; it will not overwrite an existing tag, so re-deploying the same version fails. -- **Third-party action** — not WordPress/Automattic org, but no official option exists; SHA-pinned to v2.3.0 and tracked. -- **README merge order** — `cd-github-release.yml` (PR #24) also adds a section before `## License`; whichever merges second may need a trivial conflict resolution. -- **Action pins:** `actions/checkout@…v4.2.2`, `actions/download-artifact@…v4.3.0` (reuse the CD sibling's pins), `10up/action-wordpress-plugin-deploy@54bd289… # v2.3.0`. - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/16-cd-s3.md b/.claude/issues/16-cd-s3.md deleted file mode 100644 index a02cc24..0000000 --- a/.claude/issues/16-cd-s3.md +++ /dev/null @@ -1,95 +0,0 @@ -# Issue #16 — Add CD S3 deploy workflow (`cd-s3.yml`) - -**Status:** in-review -**Branch:** `v1.0.0/task/cd-s3` -**PR:** #27 -**Assignee:** @Adi-ty - ---- - -## Summary - -Private / customer plugins not published on WP.org are distributed via an S3 bucket the customer can read. `cd-s3.yml` uploads the release artifact to a configured S3 path — a versioned object (`.zip`) plus a rolling `latest.zip` — and optionally invalidates a CloudFront distribution so the new `latest.zip` is served immediately. It is the third CD workflow (with `cd-github-release.yml` and `cd-wp-org.yml`) and the S3 target the CD orchestrator (`wp-cd.yml`, #17) will call. - ---- - -## Decisions made - -- [2026-05-29] **No blocker — proceeded.** `aws-actions/configure-aws-credentials@v6.1.3` is official and SHA-pinnable; the AWS CLI is preinstalled on `ubuntu-latest`. The issue's "depends on #11" is a *logical/runtime* dependency: the workflow only downloads an artifact by name (the producer `ci-build.yml` is merged), with no code-level `uses:` on `ci-test-build-artifact`. Secrets declare via `workflow_call`; no checkout needed; no private cross-repo dependency. -- [2026-05-29] **Versioned object keyed by `tag`** (chosen with the user): `s3:///.zip` + an always-overwritten `latest.zip`. Predictable URL; uses the required `tag` input. Supersedes the issue's `` key, which left `tag` unused. -- [2026-05-29] **`aws-actions/configure-aws-credentials@99214aa6889fcddfa57764031d71add364327e59 # v6.1.3`, SHA-pinned** (latest stable; static access keys via inputs still supported). The issue's "v4.x" was illustrative. -- [2026-05-29] **Static access-key auth** via the two required secrets (per the issue), not OIDC. -- [2026-05-29] **Injection-safe:** `tag` / `bucket` / `prefix` / `cloudfront-distribution-id` pass through step `env:` and are referenced as `$VARS`; nothing interpolated as `${{ inputs.* }}` inside a shell script (the issue's reference inlined them — a shell-injection risk). Matches `cd-github-release` / `cd-wp-org`. -- [2026-05-29] **No checkout; `permissions: contents: read`.** The job only downloads an artifact and talks to AWS; `download-artifact@v4` is same-run and independent of `GITHUB_TOKEN` scopes. -- [2026-05-29] **Single `.zip` enforced:** fail with `::error::` if the artifact contains zero or more than one `.zip`, so a misconfigured `artifact-path` can never deploy the wrong bundle. -- [2026-05-29] **Branched off `release/v1.0.0`**; PR targets `release/v1.0.0`. - ---- - -## Files changed so far - -- `.github/workflows/cd-s3.yml` — new (the workflow) -- `README.md` — edited (new `### cd-s3.yml` section with inline caller + required IAM permissions block) -- `CHANGELOG.md` — edited (bullet under Unreleased → Added) -- `.claude/issues/16-cd-s3.md` — new (this file) - ---- - -## Verification run - -```bash -❯ pipx run yamllint .github/workflows/cd-s3.yml -❯ act workflow_call -W .github/workflows/cd-s3.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Set up job -*DRYRUN* [CD / S3 Deploy/Upload to S3] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CD / S3 Deploy/Upload to S3] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CD / S3 Deploy/Upload to S3] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CD / S3 Deploy/Upload to S3] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Set up job -*DRYRUN* [CD / S3 Deploy/Upload to S3] ☁ git clone 'https://github.com/actions/download-artifact' # ref=d3f86a106a0bac45b974a628896c90dbdf5c8093 -*DRYRUN* [CD / S3 Deploy/Upload to S3] ☁ git clone 'https://github.com/aws-actions/configure-aws-credentials' # ref=99214aa6889fcddfa57764031d71add364327e59 -*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Main Download build artifact -*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Main Download build artifact [7.01175ms] -*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Main Configure AWS credentials -*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Main Configure AWS credentials [8.5785ms] -*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Main Upload to S3 -*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Main Upload to S3 [16.170417ms] -*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Post Configure AWS credentials -*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Post Configure AWS credentials [4.981459ms] -*DRYRUN* [CD / S3 Deploy/Upload to S3] ⭐ Run Complete job -*DRYRUN* [CD / S3 Deploy/Upload to S3] Cleaning up container for job Upload to S3 -*DRYRUN* [CD / S3 Deploy/Upload to S3] ✅ Success - Complete job -*DRYRUN* [CD / S3 Deploy/Upload to S3] 🏁 Job succeeded -``` - -yamllint clean; `act` resolves the full graph (download-artifact + configure-aws-credentials). The CloudFront step is correctly skipped when no distribution id is passed. - -Local logic test (aws stubbed on PATH, run under bash, all pass): -- single zip, `prefix=plugins/acme/`, `tag=v1.2.3` → `aws s3 cp ... s3://my-bucket/plugins/acme/v1.2.3.zip` and `.../latest.zip`. -- no zip → `::error::` + exit 1. -- multiple zips, empty prefix → `::error::` + exit 1 (lists the matched `.zip` files) so a misconfigured `artifact-path` can't deploy the wrong bundle. -- CloudFront path: `/plugins/acme/*` (prefix set) and `/*` (empty prefix). - ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- **CLAUDE.md deferral note.** The directory-layout section lists the S3 deploy as "optional; deferred to v1.1.0", conflicting with this PR's v1.0.0 target. That section's names are already stale (`cd-release`/`cd-deploy-wporg`/`cd-deploy-s3` vs the actual `cd-github-release`/`cd-wp-org`/`cd-s3`), so the note is treated as outdated. Updating that line is suggested but not done here. -- **Real S3 upload deferred.** `act` validates the graph and the zip-discovery / key construction is unit-testable locally (stub `aws`), but a true upload needs a real bucket + credentials (or localstack). Out of scope for this PR. -- **Bucket region** should match `region` or `aws s3 cp` redirects (slower); the bucket + distribution must pre-exist. -- **README merge order** — `cd-github-release` (#24) and `cd-wp-org` also add a section before `## License`; whichever merges later may need a trivial conflict resolution. -- **Action pins:** `actions/download-artifact@…v4.3.0`, `aws-actions/configure-aws-credentials@99214aa… # v6.1.3`. - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/18-version-monitor-workflow.md b/.claude/issues/18-version-monitor-workflow.md deleted file mode 100644 index 56f2e8c..0000000 --- a/.claude/issues/18-version-monitor-workflow.md +++ /dev/null @@ -1,72 +0,0 @@ -# Issue #18 — Add Version Monitor reusable workflow - -**Status:** in-review -**Branch:** `v1.0.0/task/version-monitor-workflow` -**PR:** -**Assignee:** @Swanand01 - ---- - -## Summary - -Add a `version-monitor.yml` reusable workflow that runs on a monthly schedule, calls `@rtcamp/wp-tooling version-monitor` to detect version bumps across npm, GitHub Actions, PHP, Node, WP-CLI, and container base images, and opens a draft PR on a `version-monitor/YYYY-MM` branch. Re-runs in the same month update the existing PR rather than opening a duplicate. - ---- - -## Decisions made - -- [2026-05-26] Using `peter-evans/create-pull-request@v8.1.1` (SHA-pinned) for PR creation — handles idempotent open/update on the same monthly branch automatically. -- [2026-05-26] Config check (`.github/version-monitor.yml` present) runs before Node setup for fast failure. -- [2026-05-27] Install step uses branch URL (`git+https://github.com/rtCamp/wp-tooling.git#v1.0.0/task/version-monitor-scripts`) with a `TODO(wp-tooling#10)` comment to switch to the published package once released. -- [2026-05-27] `updates.json` and `pr-body.md` written to `$RUNNER_TEMP` (not the workspace) so `peter-evans/create-pull-request` does not commit them into the consumer repo's dependency-bump PR. -- [2026-06-11] Review fixes: - - Node version is now the `node-version` input (default `22`) instead of being hard-coded in the setup step. - - `--detect`'s exit-1-with-partial-results is captured (`set +e` + `$?`) so `bash -e` no longer aborts the step and discards the month's findings; valid JSON proceeds to a PR, a non-zero exit records `detectors_errored=true`. - - All-major (or all-unmatched) month produces no diff → no PR; a guard step now fails the run with the report printed so the bumps are surfaced, not silently green. A second guard fails the run when a detector errored, honouring wp-tooling's "never green while blind" contract while still letting the partial-results PR open. README/CHANGELOG updated to match. - - Install step left unchanged — `@rtcamp/wp-tooling` is still unpublished (`TODO(wp-tooling#10)`). -- [2026-06-17] **Install reworked for production use.** Clones `release/v1.0.0` and installs the `node-packages/wp-tooling` subpath into a job-local prefix on PATH via `npm install --install-links --prefix` (no global; `--install-links` copies, not symlinks, so the temp clone is removed via an EXIT trap). Added an optional `wp-tooling-token` workflow_call secret to authenticate the clone — `rtCamp/wp-tooling` is private and `GITHUB_TOKEN`/same-org can't read it. Mirrors `ci-detect-changes.yml`. Immutable-ref (SHA/tag) pin deferred until wp-tooling stabilises. - ---- - -## Files changed - -- `.claude/issues/18-version-monitor-workflow.md` — new -- `.github/workflows/version-monitor.yml` — new -- `README.md` — edited (version-monitor section in the standard `### ` format) -- `CHANGELOG.md` — new - ---- - -## Verification run - -Tested locally with `act` v0.2.88 (`~/.local/bin/act`) using `--platform ubuntu-latest=-self-hosted`. - -**No-updates path** — `wp-tooling version-monitor --detect` ran against this repo's `.github/version-monitor.yml`, returned `count=0`, workflow exited cleanly with expected log message. - -**Updates-found path** — detect step patched to emit a single fake update record with the correct schema (`source`, `file`, `package`, `currentValue`, `latestValue`, `reason`). Confirmed: -- `--apply` and `--report` steps executed -- `pr-body.md` generated in `$RUNNER_TEMP` with correct markdown table (`actions/checkout | v3.5.3 | v4.2.2`) -- Workspace clean check passed — neither `updates.json` nor `pr-body.md` present in the repo working tree - -**Config-missing guard** — removed `.github/version-monitor.yml` and confirmed workflow errors with `::error::` annotation and non-zero exit. - -Full PR creation (`peter-evans/create-pull-request`) requires a pushed branch and real CI — local runner cannot complete that step. - ---- - -## Open questions - -_(none)_ - ---- - -## Notes for the reviewer - -- Install clones `release/v1.0.0` + copy-installs the subpath into a job-local prefix, authenticated by the optional `wp-tooling-token` secret (private repo). Consumers must pass that secret until `@rtcamp/wp-tooling` is published; clone is pinned to the branch only (immutable-ref pin deferred). -- End-to-end PR creation (the `peter-evans/create-pull-request` step) is verified structurally but requires real CI for a live smoke test. - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/19-ci-build-artifact-gate.md b/.claude/issues/19-ci-build-artifact-gate.md deleted file mode 100644 index fbf7ddd..0000000 --- a/.claude/issues/19-ci-build-artifact-gate.md +++ /dev/null @@ -1,97 +0,0 @@ -# Issue #19: Add ci-build-artifact-gate reusable workflow - -**Status:** done -**Branch:** `v1.0.0/task/ci-build-artifact-gate` -**PR:** #19 -**Closes:** `rtCamp/theme-elementary#642` (external) -**Assignee:** @Adi-ty - ---- - -## Summary - -Every rtCamp WordPress project that produces build output (compiled CSS/JS, Composer `vendor/`, etc.) needs a gate that fails any PR which commits those files. The build is meant to be produced by CI on merge, not committed by hand. Without a gate, stale build trees creep into the repo and silently override what CI produces. - -This task lifts the inline `rtcamp-standard.yml` workflow from `rtCamp/theme-elementary` (issue [#642](https://github.com/rtCamp/theme-elementary/issues/642)) into wp-shared-workflows as `ci-build-artifact-gate.yml`, so every rtCamp repo can consume it via `uses:` instead of copy-pasting. Default gated path is `assets/build/`. Consumers can pass a newline-separated list of prefixes and an optional `working-dir` for monorepos. - ---- - -## Decisions made - -- [2026-05-21] Implementation lifted from `theme-elementary`'s inline `.github/workflows/rtcamp-standard.yml`. Same diff-based detection, but reworked to take inputs (`gated-paths`, `working-dir`) so consumers can configure rather than fork. -- [2026-05-21] Inputs passed to bash via `env:` rather than direct GHA expression interpolation. Prevents expression injection if a consumer ever passes a value with backticks or `$(...)` in it. `set -euo pipefail` guards against silent failures in the script body. -- [2026-05-21] `--diff-filter=ACMR` chosen so deletions of previously-committed artifacts are explicitly allowed. Cleaning up an old committed `assets/build/` is a welcome change, not something the gate should block. -- [2026-05-21] Non-PR triggers (missing `github.base_ref`) skip gracefully with a `::notice::`. Lets a consumer wire this into a generic `on: [push, pull_request]` workflow without it firing on direct pushes to main. -- [2026-05-21] `permissions: contents: read`. Least-privilege; the workflow only reads the diff, never writes anywhere. -- [2026-05-21] Drive-by fix to `.yamllint.yml` line 14 (bracket spacing). Same starter-kit bug other PRs in this milestone also touched. Whichever lands first wins. -- [2026-05-21] In response to PR review (PR #19): switched empty-line removal from `grep -v '^$'` to `sed -e '/^$/d'`. `grep -v` returns exit 1 when no matches are found, which under `set -e` + `pipefail` would crash the script before the empty-`PATTERN` check could fire. `sed` exits 0 even on empty input, so the graceful-skip branch is now actually reachable. Verified by reproduction. -- [2026-05-21] In response to PR review (PR #19): broadened the regex escape from `sed 's/\./\\./g'` to `sed 's/[][\\.|^$()*+?{}]/\\&/g'` so all regex metacharacters in path names are neutralised. A directory like `c++build/` or `dist[v2]/` now matches as a literal path, not as a regex pattern. - -### Action SHA pins recorded - -- `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683`: v4.2.2. - ---- - -## Files changed so far - -- `.github/workflows/ci-build-artifact-gate.yml`: new -- `.claude/issues/19-ci-build-artifact-gate.md`: new (this file) -- `README.md`: edited (caller examples + inputs table) -- `CHANGELOG.md`: edited (new entry under `## Unreleased`) -- `.yamllint.yml`: edited (drive-by bracket-spacing fix on line 14) - ---- - -## Verification run - -```bash -$ python3 -m yamllint . -# exit 0 - -$ act workflow_call -W .github/workflows/ci-build-artifact-gate.yml --dryrun --container-architecture linux/amd64 -*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ⭐ Run Set up job -*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ✅ Success - Set up job -*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ✅ Success - Main Checkout repository -*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ⭐ Run Main Detect committed build artifacts -*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ✅ Success - Main Detect committed build artifacts -*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] ✅ Success - Complete job -*DRYRUN* [CI / Build Artifact Gate/Block committed build artifacts] 🏁 Job succeeded -``` - -Standalone reproduction of the PATTERN pipeline against the post-review code (commit `c1ad9e4`): - -``` -case=empty PATTERN=[] - -> graceful-skip-reached -case=whitespace-only PATTERN=[] - -> graceful-skip-reached -case=single-path PATTERN=[assets/build/] - -> continues to diff phase -case=multi-path-with-regex-chars PATTERN=[assets/build/|c\+\+build/|dist\[v2\]/] - -> continues to diff phase -overall-exit=0 -``` - -Confirms: empty and whitespace-only `gated-paths` reach the graceful-skip branch (acceptance criterion), and paths with regex metacharacters (`c++build/`, `dist[v2]/`) are escaped as literal strings. - ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- A full end-to-end smoke test against a real `pull_request` payload is still outstanding. `act --dryrun` cannot exercise the actual GitHub event context, so the "detects a committed `assets/build/` file, surfaces a clear error, exits 1" path is unverified locally. Recommend running once against a throwaway consumer repo before tagging. -- This PR closes an external issue (`rtCamp/theme-elementary#642`), so there was no internal GitHub issue in this repo. This file was created retroactively to keep the decision log alongside the other v1.0.0 task issues. -- `.yamllint.yml` line 14 conflicts with PRs #6 and #8. PR #6 already merged, so this branch was rebased and the conflict resolved before final review. - ---- - -## Handoff log - -_(no rotations yet; delete this line when the first entry is added)_ diff --git a/.claude/issues/20-cd-split-composer-packages.md b/.claude/issues/20-cd-split-composer-packages.md deleted file mode 100644 index 494033e..0000000 --- a/.claude/issues/20-cd-split-composer-packages.md +++ /dev/null @@ -1,103 +0,0 @@ -# Issue #20 — Add cd-split-composer-packages reusable workflow (monorepo → mirror repos) - -**Status:** in-review -**Branch:** `v1.0.0/task/cd-split-composer-packages` -**PR:** #21 -**Assignee:** @Adi-ty - ---- - -## Summary - -rtCamp's tooling lives in a monorepo, but Packagist serves each Composer package from its own repository with its own tags. This adds a reusable `workflow_call` workflow that splits each package subtree out into a standalone mirror repo (the Symfony "monorepo split" pattern) on a release tag, so every rtCamp monorepo shares one copy instead of copy-pasting the split logic. Derived from the working standalone `release-php.yml` in the tooling monorepo. - ---- - -## Decisions made - -- [2026-05-25] Modelled on the standalone `release-php.yml` (two-job `build-matrix` → matrixed `split`), converted to `on: workflow_call`. Core split logic (jq matrix, danharrin action, `fetch-depth: 0`) is byte-for-byte equivalent in behaviour. -- [2026-05-25] Inputs kept minimal: `tag` (default `""`) and `config-file` (default `"splitsh.json"`). `organization`/`branch`/`user_name`/`user_email` stay sourced from `splitsh.json` so it remains the single source of truth (Symfony pattern) — no redundant inputs. -- [2026-05-25] Secret `split-token` (required) reaches the danharrin action only via `env.GITHUB_TOKEN`; never echoed. -- [2026-05-25] `permissions: contents: read` at top level — the mirror push uses `split-token`, not the workflow's `GITHUB_TOKEN`, so read-only is sufficient and correct. -- [2026-05-25] Triggers move to the caller (a reusable workflow owns none). Tag resolution: explicit `tag` input wins, else `github.ref_name`. The `ref_name` fallback only covers the tag-push case — on `workflow_dispatch` `ref_name` is a branch, so the caller must pass the tag from its own dispatch input. Documented both caller shapes in the README. -- [2026-05-25] Hardening beyond the reference: fail loudly on missing config file / invalid JSON / empty `subtrees` (jq `// {}` guard avoids a null-deref on missing `subtrees`). -- [2026-05-25] Every action pinned to a commit SHA with a version comment: `actions/checkout@11bd719` (v4.2.2, matching the rest of the repo), `danharrin/monorepo-split-github-action@14e42e2` (v2.4.5, resolved from the tag). -- [2026-05-25] Named `cd-split-composer-packages.yml` to sit in the CD family. - ---- - -## Files changed so far - -- `.github/workflows/cd-split-composer-packages.yml` — new -- `README.md` — edited (new `cd-split-composer-packages.yml` section: config shape, tag-push + dispatch caller examples, inputs + secret tables) -- `CHANGELOG.md` — edited (Unreleased entry) - ---- - -## Verification run - -```bash -❯ act workflow_call -W .github/workflows/cd-split-composer-packages.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ⭐ Run Set up job -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ✅ Success - Set up job -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ⭐ Run Main Checkout repository -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ✅ Success - Main Checkout repository [6.708375ms] -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ⭐ Run Main Parse config into a matrix -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ✅ Success - Main Parse config into a matrix [21.030167ms] -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ⭐ Run Main Echo resolved matrix -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ✅ Success - Main Echo resolved matrix [17.754917ms] -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ⭐ Run Complete job -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] Cleaning up container for job Build split matrix from config -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] ✅ Success - Complete job -*DRYRUN* [CD / Split Composer Packages/Build split matrix from config] 🏁 Job succeeded -ERRO[0000] Error while evaluating matrix: Invalid JSON: unexpected end of JSON input -*DRYRUN* [CD / Split Composer Packages/Split ] ⭐ Run Set up job -*DRYRUN* [CD / Split Composer Packages/Split ] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CD / Split Composer Packages/Split ] ✅ Success - Set up job -*DRYRUN* [CD / Split Composer Packages/Split ] ☁ git clone 'https://github.com/danharrin/monorepo-split-github-action' # ref=14e42e2437f674b8987c1f50ca3689116aea1893 -*DRYRUN* [CD / Split Composer Packages/Split ] ⭐ Run Main Checkout monorepo (full history) -*DRYRUN* [CD / Split Composer Packages/Split ] ✅ Success - Main Checkout monorepo (full history) [9.643417ms] -*DRYRUN* [CD / Split Composer Packages/Split ] ⭐ Run Main Split and push subtree to mirror -*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker build -t act-danharrin-monorepo-split-github-action-14e42e2437f674b8987c1f50ca3689116aea1893-dockeraction:latest /Users/adi/.cache/act/danharrin-monorepo-split-github-action@14e42e2437f674b8987c1f50ca3689116aea1893 -*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker pull image=act-danharrin-monorepo-split-github-action-14e42e2437f674b8987c1f50ca3689116aea1893-dockeraction:latest platform= username= forcePull=false -*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker create image=act-danharrin-monorepo-split-github-action-14e42e2437f674b8987c1f50ca3689116aea1893-dockeraction:latest platform= entrypoint=[] cmd=["" "github.com" "" "" "" "" "" ""] network="container:act-CD--Split-Composer-Packages-Split-dc5f2bbaabb4c8d86f0a7386db3ec2a110255f2a742a58f5a5007f0ea266e004" -*DRYRUN* [CD / Split Composer Packages/Split ] 🐳 docker run image=act-danharrin-monorepo-split-github-action-14e42e2437f674b8987c1f50ca3689116aea1893-dockeraction:latest platform= entrypoint=[] cmd=["" "github.com" "" "" "" "" "" ""] network="container:act-CD--Split-Composer-Packages-Split-dc5f2bbaabb4c8d86f0a7386db3ec2a110255f2a742a58f5a5007f0ea266e004" -*DRYRUN* [CD / Split Composer Packages/Split ] ✅ Success - Main Split and push subtree to mirror [41.679417ms] -*DRYRUN* [CD / Split Composer Packages/Split ] ⭐ Run Complete job -*DRYRUN* [CD / Split Composer Packages/Split ] Cleaning up container for job Split -*DRYRUN* [CD / Split Composer Packages/Split ] ✅ Success - Complete job -*DRYRUN* [CD / Split Composer Packages/Split ] 🏁 Job succeeded - -# jq matrix confirmed on both value forms (shorthand + prefixes): -jq -c '{ include: [ .subtrees | to_entries[] | { mirror_repo: .key, package_directory: (if (.value|type)=="string" then .value else .value.prefixes[0].from end) } ] }' splitsh.json -{"include":[{"mirror_repo":"wp-phpcs","package_directory":"composer-packages/phpcs"},{"mirror_repo":"wp-phpstan","package_directory":"composer-packages/phpstan"}]} - -``` - ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- **Optional hardening, not yet added (awaiting steer):** a guard in `build-matrix` that fails when the tag came from the `ref_name` fallback while `github.ref_type != 'tag'` — turns a silent "pushed a branch-named tag" (dispatch without an explicit tag) into a clear error. -- Mirror repos must already exist and `split-token` must hold `contents: write` on each for a real run to succeed. - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/3-ci-test-js.md b/.claude/issues/3-ci-test-js.md deleted file mode 100644 index 30e4228..0000000 --- a/.claude/issues/3-ci-test-js.md +++ /dev/null @@ -1,86 +0,0 @@ -# Issue #3 — ci-test-js.yml reusable workflow - -**Status:** done -**Branch:** `v1.0.0/task/ci-test-js` -**PR:** #4 -**Assignee:** @Adi-ty - ---- - -## Summary - -Every rtCamp WordPress project that ships JS runs the same Jest pipeline — `Test and Measure`'s `unit-tests-js` job is copy-pasted across plugins, themes, and Composer packages with minor drift. Centralising this as a reusable workflow lets every consumer adopt one canonical implementation via `uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-js.yml@v1`, and adds Jest cache support that the legacy job didn't have. - ---- - -## Decisions made - -- [2026-05-12] `node-version` ships with `default: "22"`, not `required: true`. CLAUDE.md says "Node 22 (overridable per call)"; required-with-no-default would be boilerplate tax for a workflow library where every consumer wants the org default anyway. Major bumps go to `@v2` per tag strategy, so silent drift is already prevented. -- [2026-05-12] Jest cache path resolved at runtime via `$HOME/.jest-cache` in a step output, not literal `~/.jest-cache` in the env. Reason: Node doesn't expand `~` from `process.env.JEST_CACHE_DIRECTORY`, but `actions/cache` *does* expand `~` for its `path:` field — mixing both forms silently breaks caching. Computing once with `$HOME` keeps both ends pointing at the same directory. -- [2026-05-12] When `enable-cache: false`, the resolve step is skipped, `steps.jest-cache.outputs.dir` is empty, and `JEST_CACHE_DIRECTORY` becomes `""`. Jest treats empty as falsy and falls back to its OS-temp default — same end-state as not setting the var at all. -- [2026-05-12] `--ci` baked into the default `test-command`. Legacy used `env: CI: true` (still set by the runner automatically); the explicit flag in the default communicates intent at the call site. -- [2026-05-12] Cache key keyed by OS only (`jest-${{ runner.os }}`) per spec. Jest manages its own internal invalidation; no need to mix `node-version` or content hashes into the key. -- [2026-05-12] Job display name `Jest` — matches the tool-name pattern from the lint-trio PR (`Stylelint`, `ESLint`). - ---- - -## Files changed so far - -- `.github/workflows/ci-test-js.yml` — new -- `.claude/issues/3-ci-test-js.md` — new -- `CHANGELOG.md` — new -- `README.md` — edited -- `.yamllint.yml` — edited (drive-by: removed stray spaces in `truthy.allowed-values` flow sequence so the starter-kit config passes its own linter; same fix also lives on the lint PR — merge order produces a trivial no-op conflict) - ---- - -## Verification run - -```bash -❯ pipx run yamllint . -❯ act workflow_call -W .github/workflows/ci-test-js.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CI / Test JS/Jest] ⭐ Run Set up job -*DRYRUN* [CI / Test JS/Jest] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CI / Test JS/Jest] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CI / Test JS/Jest] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Test JS/Jest] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Test JS/Jest] ✅ Success - Set up job -*DRYRUN* [CI / Test JS/Jest] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af -*DRYRUN* [CI / Test JS/Jest] ☁ git clone 'https://github.com/actions/cache' # ref=1bd1e32a3bdc45362d1e726936510720a7c30a57 -*DRYRUN* [CI / Test JS/Jest] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Test JS/Jest] ✅ Success - Main Checkout repository [5.413291ms] -*DRYRUN* [CI / Test JS/Jest] ⭐ Run Main Set up Node.js -*DRYRUN* [CI / Test JS/Jest] ✅ Success - Main Set up Node.js [5.880042ms] -*DRYRUN* [CI / Test JS/Jest] ⭐ Run Main Install npm dependencies -*DRYRUN* [CI / Test JS/Jest] ✅ Success - Main Install npm dependencies [16.523709ms] -*DRYRUN* [CI / Test JS/Jest] ⭐ Run Main Run Jest -*DRYRUN* [CI / Test JS/Jest] ✅ Success - Main Run Jest [17.757417ms] -*DRYRUN* [CI / Test JS/Jest] ⭐ Run Post Set up Node.js -*DRYRUN* [CI / Test JS/Jest] ✅ Success - Post Set up Node.js [4.301542ms] -*DRYRUN* [CI / Test JS/Jest] ⭐ Run Complete job -*DRYRUN* [CI / Test JS/Jest] Cleaning up container for job Jest -*DRYRUN* [CI / Test JS/Jest] ✅ Success - Complete job -*DRYRUN* [CI / Test JS/Jest] 🏁 Job succeeded -``` - ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- SHA pins resolved: `actions/checkout@v4.2.2` → `11bd71901bbe5b1630ceea73d27597364c9af683`, `actions/setup-node@v4.1.0` → `39370e3970a6d050c480ffad4ff0ed4d3fdee5af`, `actions/cache@v4.2.0` → `1bd1e32a3bdc45362d1e726936510720a7c30a57`. All three are direct commit refs (not annotated tag objects — verified via `gh api .../git/refs/tags/...`). -- README's "Individual workflows" section is new in this PR. -- Smoke test deferred to consumer-side run — call this branch from a Jest-configured throwaway repo and confirm: clean exit on green tests, non-zero on a failing test, cache restore visible in `actions/cache` step logs on the second run. - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/5-ci-test-php.md b/.claude/issues/5-ci-test-php.md deleted file mode 100644 index 750878f..0000000 --- a/.claude/issues/5-ci-test-php.md +++ /dev/null @@ -1,92 +0,0 @@ -# Issue #5 — Add PHP unit tests reusable workflow - -**Status:** done -**Branch:** `v1.0.0/task/ci-test-php` -**PR:** #6 -**Assignee:** @Adi-ty - ---- - -## Summary - -Every rtCamp WordPress project that ships PHP currently copy-pastes the same `unit-test-php` job from the legacy `Test and Measure` workflow. Some consumers need a full WordPress integration environment via `@wordpress/env`; Composer-only packages and libraries do not. This task adds `ci-test-php.yml` — a single reusable workflow with a `use-wp-env` toggle that covers both modes so every consumer can adopt one canonical implementation via `uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-php.yml@v1`. - ---- - -## Decisions made - -- [2026-05-12] `php-version` gets a default of `"8.3"` rather than `required: true` — matches CLAUDE.md ("PHP in workflows: 8.3, overridable per call") and the input-design convention adopted in the lint-trio PR. `required: true` is reserved for unguessable identity (deploy slugs, bucket names) on future CD workflows. -- [2026-05-12] `composer-flags` default carries `--no-scripts` — supply-chain hygiene, mirrors `ci-lint-php.yml`. Consumers that need post-install scripts must opt in explicitly by overriding the input. -- [2026-05-12] `npm ci` is split into its own step gated on `use-wp-env`. The planning doc combined `npm ci && composer install`; that breaks standalone mode because there is no Node setup. Composer install always runs; npm install only when wp-env is enabled. -- [2026-05-12] `coverage: none` on `shivammathur/setup-php` — skips the Xdebug install cost. Coverage is a follow-up concern (will become a `coverage` input flipping Xdebug/PCOV on, plus Codecov / artifact upload). -- [2026-05-12] `tools: composer` on `shivammathur/setup-php` — pins Composer explicitly so we do not rely on whatever `ubuntu-latest` happens to ship. -- [2026-05-12] `wp-version` input deferred. `WP_ENV_CORE` works but needs a format transform (`6.7` → `WordPress/WordPress#tags/6.7`); writing `.wp-env.override.json` clobbers consumer overrides. Both are sharp edges and the legacy workflow did not expose this — defer to a clean follow-up issue. -- [2026-05-12] No Composer or wp-env caching in v1.0.0. Composer install is fast relative to wp-env Docker pulls; wp-env caching is genuinely tricky (Docker layer cache vs `~/.wp-env`). Both can be added later without breaking the input schema. -- [2026-05-12] Drive-by fix to `.yamllint.yml` line 14 (bracket spacing) — same starter-kit bug surfaces here as it did on the ci-test-js branch. yamllint would otherwise fail on the very file that defines its own rules. - -### Action SHA pins recorded - -- `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683` — v4.2.2. -- `actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af` — v4.1.0. -- `shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f` — 2.37.0 (annotated tag dereferenced via `gh api repos/.../git/tags/`). - ---- - -## Files changed so far - -- `.github/workflows/ci-test-php.yml` — new -- `.claude/issues/5-ci-test-php.md` — new -- `CHANGELOG.md` — new (first entry under `## Unreleased`) -- `README.md` — edited (caller example + inputs row) -- `.yamllint.yml` — edited (drive-by bracket-spacing fix on line 14) - ---- - -## Verification run - -```bash - pipx run yamllint . -❯ act workflow_call -W .github/workflows/ci-test-php.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Set up job -*DRYRUN* [CI / Test PHP/PHPUnit] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CI / Test PHP/PHPUnit] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CI / Test PHP/PHPUnit] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Test PHP/PHPUnit] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Set up job -*DRYRUN* [CI / Test PHP/PHPUnit] ☁ git clone 'https://github.com/shivammathur/setup-php' # ref=accd6127cb78bee3e8082180cb391013d204ef9f -*DRYRUN* [CI / Test PHP/PHPUnit] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af -*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Main Checkout repository [5.999542ms] -*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Main Set up PHP -*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Main Set up PHP [5.649958ms] -*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Main Install Composer dependencies -*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Main Install Composer dependencies [13.607667ms] -*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Main Run PHPUnit -*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Main Run PHPUnit [12.081917ms] -*DRYRUN* [CI / Test PHP/PHPUnit] ⭐ Run Complete job -*DRYRUN* [CI / Test PHP/PHPUnit] Cleaning up container for job PHPUnit -*DRYRUN* [CI / Test PHP/PHPUnit] ✅ Success - Complete job -*DRYRUN* [CI / Test PHP/PHPUnit] 🏁 Job succeeded -``` - ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- The biggest deviation from the planning doc is the **split `npm ci` / `composer install` steps**. The doc's combined step would fail in standalone mode (no Node = `npm ci` cannot run). Splitting is cheap and keeps the dependency graph honest. -- `wp-version` is intentionally absent from v1.0.0. If reviewers want it shipped now, the cleanest wire is `env: WP_ENV_CORE: WordPress/WordPress#tags/${{ inputs.wp-version }}` on the wp-env start step, gated on the input being non-empty. Happy to fold that in if requested — flagging here so it is a conscious decision rather than an oversight. -- Same `.yamllint.yml` bracket-spacing fix lives in the other open PR. Whichever PR merges second will conflict on that single line. - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/7-ci-build.md b/.claude/issues/7-ci-build.md deleted file mode 100644 index 088c871..0000000 --- a/.claude/issues/7-ci-build.md +++ /dev/null @@ -1,121 +0,0 @@ -# Issue #7 — Add ci-build reusable workflow - -**Status:** done -**Branch:** `v1.0.0/task/ci-build` -**PR:** #8 -**Assignee:** @Adi-ty - ---- - -## Summary - -Every rtCamp WordPress project that ships JS or CSS runs the same production build — `Test and Measure`'s `build-prod` job is copy-pasted across plugins, themes, and packages. Most callers only need to verify the build exits 0; CD callers also need the built files handed to a downstream deploy job. This task adds `ci-build.yml` — a single reusable workflow with an `upload-artifact` toggle (default `false`) that covers both shapes so every consumer can adopt one canonical implementation via `uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1`. - ---- - -## Decisions made - -- [2026-05-12] `node-version` defaults to `"22"` rather than `required: true` — matches CLAUDE.md ("Node in workflows: 22, overridable per call") and the input-design convention adopted in the lint-trio / test-js / test-php PRs. `required: true` is reserved for unguessable identity (deploy slugs, bucket names) on future CD workflows. -- [2026-05-12] `if-no-files-found: error` set on `actions/upload-artifact`. The action's default is `warn`, which silently produces an empty artifact and breaks any downstream CD job that tries to `actions/download-artifact` it. Failing loudly is the right shape for a reusable workflow — a misconfigured `artifact-path` should surface at the upload step, not three jobs later. -- [2026-05-12] Artifact `path` is composed as `${{ inputs.working-dir }}/${{ inputs.artifact-path }}`. `actions/upload-artifact`'s `path` is repo-root-relative, not working-directory-relative, so monorepo callers would otherwise have to double-prefix. Composing here means `working-dir: "plugins/foo"` + `artifact-path: "build/"` does what a consumer expects. -- [2026-05-12] No `env: CI: true` on the build step. GitHub Actions sets `CI=true` automatically on hosted runners. The legacy workflow set it explicitly — that was redundant. Mirrors the convention from `ci-test-js` / `ci-test-php`. -- [2026-05-12] No build-output caching in v1.0.0. `actions/setup-node`'s `cache: npm` already covers the slow part (dependency install); build outputs are reproducible from `package-lock.json` + source and rarely benefit from caching. Can be added later without breaking the input schema. -- [2026-05-12] `actions/upload-artifact` pinned to `v4.6.2`, not `v5`/`v6`/`v7`. v4 is the stable major referenced in the planning doc; v5+ introduced breaking changes around upload behaviour that aren't needed here. We can move forward on a future minor when consumers ask for it. -- [2026-05-12] `upload-artifact` defaults to `false`. The CI-verification path (no upload) is the common case; defaulting to `true` would burn artifact storage on every CI run for callers that don't need it. -- [2026-05-12] Drive-by fix to `.yamllint.yml` line 14 (bracket spacing) — same starter-kit bug that the lint-trio, ci-test-js, and ci-test-php PRs all touch. Whichever PR merges first wins; later ones hit a one-line conflict. -- [2026-05-13] Added `install-composer-deps` / `install-node-deps` toggles (+ `php-version`, `composer-flags`) in response to PR review. Both stacks are individually optional — three consumer shapes: Node-only (default), Composer-only, both. `composer-flags` defaults to `--no-dev` (production build, not dev). Node defaults on; Composer defaults off. Backwards-compatible. - -### Action SHA pins recorded - -- `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683` — v4.2.2. -- `actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af` — v4.1.0. -- `actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02` — v4.6.2. -- `shivammathur/setup-php@accd6127cb78bee3e8082180cb391013d204ef9f` — 2.37.0. - ---- - -## Files changed so far - -- `.github/workflows/ci-build.yml` — new -- `.claude/issues/7-ci-build.md` — new -- `CHANGELOG.md` — new (first entry under `## Unreleased`) -- `README.md` — edited (caller example + inputs row) -- `.yamllint.yml` — edited (drive-by bracket-spacing fix on line 14) - ---- - -## Verification run - -```bash -❯ pipx run yamllint . -❯ act workflow_call -W .github/workflows/ci-build.yml --dryrun -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CI / Build/Build] ⭐ Run Set up job -*DRYRUN* [CI / Build/Build] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CI / Build/Build] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CI / Build/Build] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Build/Build] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Build/Build] ✅ Success - Set up job -*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af -*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/shivammathur/setup-php' # ref=accd6127cb78bee3e8082180cb391013d204ef9f -*DRYRUN* [CI / Build/Build] Non-terminating error while running 'git clone': some refs were not updated -*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/actions/upload-artifact' # ref=ea165f8d65b6e75b540449e92b4886f43607fa02 -*DRYRUN* [CI / Build/Build] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Build/Build] ✅ Success - Main Checkout repository [6.2005ms] -*DRYRUN* [CI / Build/Build] ⭐ Run Main Build production assets -*DRYRUN* [CI / Build/Build] ✅ Success - Main Build production assets [13.612625ms] -*DRYRUN* [CI / Build/Build] ⭐ Run Complete job -*DRYRUN* [CI / Build/Build] Cleaning up container for job Build -*DRYRUN* [CI / Build/Build] ✅ Success - Complete job -*DRYRUN* [CI / Build/Build] 🏁 Job succeeded -❯ act workflow_call -W .github/workflows/ci-build.yml --dryrun \ - --input install-node-deps=false --input install-composer-deps=true -INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' -WARN ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠ -*DRYRUN* [CI / Build/Build] ⭐ Run Set up job -*DRYRUN* [CI / Build/Build] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CI / Build/Build] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CI / Build/Build] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Build/Build] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Build/Build] ✅ Success - Set up job -*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af -*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/shivammathur/setup-php' # ref=accd6127cb78bee3e8082180cb391013d204ef9f -*DRYRUN* [CI / Build/Build] Non-terminating error while running 'git clone': some refs were not updated -*DRYRUN* [CI / Build/Build] ☁ git clone 'https://github.com/actions/upload-artifact' # ref=ea165f8d65b6e75b540449e92b4886f43607fa02 -*DRYRUN* [CI / Build/Build] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Build/Build] ✅ Success - Main Checkout repository [5.398708ms] -*DRYRUN* [CI / Build/Build] ⭐ Run Main Set up PHP -*DRYRUN* [CI / Build/Build] ✅ Success - Main Set up PHP [5.585334ms] -*DRYRUN* [CI / Build/Build] ⭐ Run Main Install Composer dependencies -*DRYRUN* [CI / Build/Build] ✅ Success - Main Install Composer dependencies [26.049167ms] -*DRYRUN* [CI / Build/Build] ⭐ Run Main Build production assets -*DRYRUN* [CI / Build/Build] ✅ Success - Main Build production assets [13.907375ms] -*DRYRUN* [CI / Build/Build] ⭐ Run Complete job -*DRYRUN* [CI / Build/Build] Cleaning up container for job Build -*DRYRUN* [CI / Build/Build] ✅ Success - Complete job -*DRYRUN* [CI / Build/Build] 🏁 Job succeeded -``` - ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- The `path: ${{ inputs.working-dir }}/${{ inputs.artifact-path }}` composition is the only non-obvious bit. `defaults.run.working-directory` only affects `run:` steps; action inputs (`uses:` blocks) still resolve relative to the repo root. Composing the two inputs here is the cheapest way to keep monorepo callers ergonomic without exposing the GitHub Actions quirk. -- `if-no-files-found: error` is a deliberate hardening over the planning doc, which didn't mention it. Worth a sanity-check during smoke testing — confirm that misconfiguring `artifact-path` produces a clear failure rather than a silent empty artifact. -- `actions/upload-artifact` v7.0.1 exists but pins live at v4.6.2. Happy to bump if reviewers prefer staying on the latest major; v4 was chosen for stability and alignment with the planning doc. -- Default `composer-flags` use `--no-dev` because this is a production-build workflow — different from `ci-lint-php` / `ci-test-php`, which need dev deps (PHPCS, PHPUnit). The inconsistency is deliberate, not a copy-paste oversight. -- Both stacks are individually toggleable (`install-node-deps`, `install-composer-deps`) because rtCamp consumes this workflow from plugins, themes, AND pure-PHP packages. Defaults reflect the most common case (Node-only). Setting both to `false` runs `build-command` on a bare checkout — degenerate but not broken. -- `.yamllint.yml` fix is duplicated across the PRs. Whichever merges first wins; later ones hit a one-line conflict. - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/9-ci-test-a11y.md b/.claude/issues/9-ci-test-a11y.md deleted file mode 100644 index 9a81594..0000000 --- a/.claude/issues/9-ci-test-a11y.md +++ /dev/null @@ -1,97 +0,0 @@ -# Issue #9 — Add ci-test-a11y reusable workflow - -**Status:** done -**Branch:** `v1.0.0/task/ci-test-a11y` -**PR:** #10 -**Assignee:** @Adi-ty - ---- - -## Summary - -Every rtCamp WordPress project that ships UI runs the same accessibility regression check — pa11y-ci against the built site served by `@wordpress/env`. The wiring (build → wp-env start → pa11y → wp-env stop) is tedious to maintain and copy-pasted across consumers; some projects skip a11y entirely as a result. This task adds `ci-test-a11y.yml` — a single reusable workflow that captures that sequence with `if: always()` cleanup, so every consumer can adopt one canonical implementation via `uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-a11y.yml@v1`. The reusable workflow stays trigger-agnostic; consumers wire the `Run a11y` label gate at the caller level per CLAUDE.md. - ---- - -## Decisions made - -- [2026-05-12] `node-version` defaults to `"22"` rather than `required: true` — matches CLAUDE.md ("Node in workflows: 22, overridable per call") and the input-design convention adopted in the lint-trio / test-js / test-php / build PRs. `required: true` is reserved for unguessable identity (deploy slugs, bucket names) on future CD workflows. -- [2026-05-12] Build runs before `wp-env start`, not after. pa11y crawls user-facing pages served by WordPress; those pages need compiled CSS/JS. Swapping the order would silently let pa11y inspect un-built markup and might still pass — a false-green. Order is load-bearing and called out in "Things to avoid". -- [2026-05-12] `wp-env stop` carries `if: always()` so a failing pa11y run does not leak a Docker stack into the next job. Without it, repeat runs on the same runner hit port-in-use flakes. -- [2026-05-12] No `setup-php` / `composer install` step in v1.0.0. pa11y serves pages from inside the wp-env Docker containers which carry their own PHP; the consumer's plugin/theme code is mounted in. Plugins with Composer autoloaders that fatal without `vendor/` are a real edge case but uncommon enough to defer behind a follow-up `install-composer-deps` opt-in input rather than baking host-side composer setup into every a11y run. -- [2026-05-12] Reusable workflow stays trigger-agnostic. CLAUDE.md notes a11y is "label-triggered by default", but that wiring (`if: contains(github.event.pull_request.labels.*.name, 'Run a11y')`) belongs at the caller — embedding it here would force the gate on every consumer. -- [2026-05-12] No `env: CI: true` on any step. GitHub Actions sets `CI=true` automatically on hosted runners. The legacy workflow set it explicitly — that was redundant. -- [2026-05-12] No HTML report artifact upload in v1.0.0. pa11y can emit HTML reports and uploading them as a GitHub artifact is genuinely useful for debugging failing runs, but it adds an `actions/upload-artifact` step and a path-resolution decision. Defer to a follow-up. -- [2026-05-12] No browser / wp-env Docker / build-output caching in v1.0.0. `setup-node` `cache: npm` covers the slow part (dependency install). wp-env Docker image caching is genuinely tricky and rarely worth the complexity for the first cut. -- [2026-05-12] Drive-by fix to `.yamllint.yml` line 14 (bracket spacing) — same starter-kit bug that the lint-trio, ci-test-js, ci-test-php, and ci-build PRs all touch. Whichever PR merges first wins; later ones hit a one-line conflict. - -### Action SHA pins recorded - -- `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683` — v4.2.2. -- `actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af` — v4.1.0. - ---- - -## Files changed so far - -- `.github/workflows/ci-test-a11y.yml` — new -- `.claude/issues/9-ci-test-a11y.md` — new (rename to match the issue number once filed) -- `CHANGELOG.md` — new (first entry under `## Unreleased`) -- `README.md` — edited (Individual workflows section + caller example with label gate + inputs row) -- `.yamllint.yml` — edited (drive-by bracket-spacing fix on line 14) - ---- - -## Verification run - -```bash -❯ pipx run yamllint . -❯ act workflow_call -W .github/workflows/ci-test-a11y.yml --dryrun -*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Set up job -*DRYRUN* [CI / Test a11y/pa11y-ci] 🚀 Start image=node:16-buster-slim -*DRYRUN* [CI / Test a11y/pa11y-ci] 🐳 docker pull image=node:16-buster-slim platform= username= forcePull=true -*DRYRUN* [CI / Test a11y/pa11y-ci] 🐳 docker create image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Test a11y/pa11y-ci] 🐳 docker run image=node:16-buster-slim platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" -*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Set up job -*DRYRUN* [CI / Test a11y/pa11y-ci] ☁ git clone 'https://github.com/actions/setup-node' # ref=39370e3970a6d050c480ffad4ff0ed4d3fdee5af -*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Checkout repository -*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Checkout repository [7.135916ms] -*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Set up Node.js -*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Set up Node.js [11.4295ms] -*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Install npm dependencies -*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Install npm dependencies [16.7305ms] -*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Build production assets -*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Build production assets [16.109583ms] -*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Start wp-env -*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Start wp-env [16.489ms] -*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Run pa11y-ci -*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Run pa11y-ci [16.027583ms] -*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Main Stop wp-env -*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Main Stop wp-env [13.088125ms] -*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Post Set up Node.js -*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Post Set up Node.js [4.724833ms] -*DRYRUN* [CI / Test a11y/pa11y-ci] ⭐ Run Complete job -*DRYRUN* [CI / Test a11y/pa11y-ci] Cleaning up container for job pa11y-ci -*DRYRUN* [CI / Test a11y/pa11y-ci] ✅ Success - Complete job -*DRYRUN* [CI / Test a11y/pa11y-ci] 🏁 Job succeeded -``` - ---- - -## Open questions - -- _(none yet)_ - ---- - -## Notes for the reviewer - -- The `if: always()` on `wp-env stop` is non-negotiable — without it, a failing pa11y leaves containers running and the next CI run on the same runner hits port-in-use errors. -- Composer install is deliberately absent. If reviewers want it for v1.0.0, the cleanest shape is an `install-composer-deps` boolean (default `false`) that conditionally sets up PHP and runs `composer install --no-scripts` before the build step. Happy to fold that in if requested — flagging here so it is a conscious decision rather than an oversight. -- `.yamllint.yml` fix is duplicated across the PRs. Whichever merges first wins; later ones hit a one-line conflict. - ---- - -## Handoff log - -_(no rotations yet — delete this line when the first entry is added)_ diff --git a/.claude/issues/_TEMPLATE.md b/.claude/issues/_TEMPLATE.md deleted file mode 100644 index 34f38c4..0000000 --- a/.claude/issues/_TEMPLATE.md +++ /dev/null @@ -1,98 +0,0 @@ -# Issue # — - -**Status:** in-progress -**Branch:** `/task/` -**PR:** # -**Assignee:** @ - ---- - -## Summary - - - ---- - -## Decisions made - - - -- [YYYY-MM-DD] Example: chose X over Y because Z - ---- - -## Files changed so far - - - -- `src/...` — new - ---- - -## Verification run - - - -```bash -$ ... -``` - ---- - -## Open questions - - - -- _(none yet)_ - ---- - -## Notes for the reviewer - - - -- _(none yet)_ - ---- - -## Handoff log - - - -_(no rotations yet — delete this line when the first entry is added)_ - - - diff --git a/.gitattributes b/.gitattributes index c633223..9ec165a 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,6 +1,3 @@ -# Per-issue Claude progress files — mostly additive; auto-resolve conflicts -.claude/issues/*.md merge=union - # Line endings * text=auto eol=lf *.bat text eol=crlf diff --git a/.github/ISSUE_TEMPLATE/task.md b/.github/ISSUE_TEMPLATE/task.md index 3ea01e5..92f0582 100644 --- a/.github/ISSUE_TEMPLATE/task.md +++ b/.github/ISSUE_TEMPLATE/task.md @@ -103,8 +103,8 @@ $ ... - [ ] ### Housekeeping -- [ ] `CHANGELOG.md` entry under `## Unreleased` -- [ ] `.claude/issues/-.md` created and maintained +- [ ] `CHANGELOG.md` entry under the current version heading +- [ ] `examples/.yml` added or updated to match --- diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml new file mode 100644 index 0000000..1993563 --- /dev/null +++ b/.github/actionlint.yaml @@ -0,0 +1,7 @@ +# SC2016 fires on every sed script that anchors with a literal '$'. These workflows are +# full of them and the rule is informational, so it is excluded repo-wide. Keeping it here +# rather than in a SHELLCHECK_OPTS env var means `actionlint ` just works. +paths: + "**/*.yml": + ignore: + - 'shellcheck reported issue in this script: SC2016' diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9b62c7a..d405f28 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -33,8 +33,9 @@ $ ... - [ ] Tests pass ### Housekeeping -- [ ] `CHANGELOG.md` entry under `## Unreleased` -- [ ] `.claude/issues/-.md` updated with final state +- [ ] `CHANGELOG.md` entry under the current version heading +- [ ] `examples/.yml` added or updated to match any input change +- [ ] `yamllint`, `actionlint` and `bin/check-workflows.sh` pass locally ## Reviewer notes @@ -48,4 +49,4 @@ $ ... --- -Full decision log and verification history for this work lives in `.claude/issues/-.md` on this branch. +Conventions: [AGENTS.md](../AGENTS.md) · PR process: [CONTRIBUTING.md](../CONTRIBUTING.md) diff --git a/.github/workflows/cd-built-branch.yml b/.github/workflows/cd-built-branch.yml index 53ebf04..f69eb58 100644 --- a/.github/workflows/cd-built-branch.yml +++ b/.github/workflows/cd-built-branch.yml @@ -362,8 +362,14 @@ jobs: failed=1 fi } - while IFS= read -r p; do [ -n "$p" ] && check "$p" "Publish path" || true; done <<< "$PUBLISH_PATHS" - while IFS= read -r p; do [ -n "$p" ] && check "$p" "Verify path" || true; done <<< "$VERIFY_PATHS" + while IFS= read -r p; do + [ -n "$p" ] || continue + check "$p" "Publish path" + done <<< "$PUBLISH_PATHS" + while IFS= read -r p; do + [ -n "$p" ] || continue + check "$p" "Verify path" + done <<< "$VERIFY_PATHS" [ "$failed" -eq 0 ] || exit 1 echo "Build output for '${TARGET_NAME}' verified." @@ -523,7 +529,9 @@ jobs: # A dependency installed from source leaves a nested .git, which `git add` records as a # gitlink — publishing an empty directory in place of the package. while IFS= read -r path; do - [ -n "$path" ] && [ -e "$path" ] || continue + if [ -z "$path" ] || [ ! -e "$path" ]; then + continue + fi while IFS= read -r nested; do echo "::warning::Removing nested git directory '${nested}' before staging (a gitlink would publish an empty directory)." rm -rf "$nested" diff --git a/.github/workflows/cd-split-composer-packages.yml b/.github/workflows/cd-split-composer-packages.yml deleted file mode 100644 index 62470b0..0000000 --- a/.github/workflows/cd-split-composer-packages.yml +++ /dev/null @@ -1,154 +0,0 @@ -name: CD / Split Composer Packages - -# Splits Composer-package subtrees out of a monorepo into standalone mirror -# repos (the Symfony "monorepo split" pattern), so Packagist can serve each -# package from its own repository. -# -# * (default splitsh.json) is the single source of truth for -# mirror-repo name -> monorepo subdirectory. It lives in the CALLING -# monorepo (e.g. wp-tooling), NOT in this repo: as a reusable workflow, -# actions/checkout here pulls the caller's repository by default, so the -# config is read from the caller's checkout at the triggering ref. -# * build-matrix reads it once and emits a matrix. -# * split runs splitsh-lite (via the danharrin action) per subtree, in -# parallel, force-pushing each subtree to its mirror. -# -# To add/remove a package: edit the config file. No workflow change needed. - -on: - workflow_call: - inputs: - tag: - description: "Tag to push to the mirror repos. When empty, falls back to the ref that triggered the caller (github.ref_name)." - type: string - default: "" - config-file: - description: "Path to the splitsh config file, relative to the repo root." - type: string - default: "splitsh.json" - secrets: - split-token: - description: "Token (fine-grained PAT or GitHub App token) with 'contents: write' on every mirror repo listed in the config file." - required: true - -permissions: - contents: read - -jobs: - build-matrix: - name: Build split matrix from config - runs-on: ubuntu-latest - outputs: - matrix: ${{ steps.parse.outputs.matrix }} - organization: ${{ steps.parse.outputs.organization }} - branch: ${{ steps.parse.outputs.branch }} - user_name: ${{ steps.parse.outputs.user_name }} - user_email: ${{ steps.parse.outputs.user_email }} - tag: ${{ steps.parse.outputs.tag }} - steps: - - name: Checkout repository - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - - name: Parse config into a matrix - id: parse - shell: bash - env: - CONFIG_FILE: ${{ inputs.config-file }} - INPUT_TAG: ${{ inputs.tag }} - run: | - set -euo pipefail - - if [[ ! -f "$CONFIG_FILE" ]]; then - echo "::error::Config file '$CONFIG_FILE' not found (path is relative to the repo root)." - exit 1 - fi - - if ! jq empty "$CONFIG_FILE" 2>/dev/null; then - echo "::error::Config file '$CONFIG_FILE' is not valid JSON." - exit 1 - fi - - # Normalise both the shorthand string form ("composer-packages/foo") - # and the object form ({ "prefixes": [{ "from": "..." }] }). - if ! matrix=$(jq -c '{ - include: [ - (.subtrees // {}) | to_entries[] | { - mirror_repo: .key, - package_directory: ( - if (.value | type) == "string" then .value - elif ((.value | type) == "object") - and ((.value.prefixes | type) == "array") - and ((.value.prefixes | length) > 0) - and ((.value.prefixes[0].from | type) == "string") then .value.prefixes[0].from - else error("invalid subtrees entry for \"" + .key + "\": expected a string path or { prefixes: [{ from: \"...\" }] }") - end - ) - } - ] - }' "$CONFIG_FILE"); then - echo "::error::Invalid 'subtrees' entry in '$CONFIG_FILE' — each value must be a string path or { prefixes: [{ from: \"...\" }] } (see jq error above)." - exit 1 - fi - - count=$(jq -r '.include | length' <<<"$matrix") - if [[ "$count" -eq 0 ]]; then - echo "::error::No subtrees defined in '$CONFIG_FILE'. Nothing to split." - exit 1 - fi - - # Resolve the tag: explicit input wins, else the caller's ref name. - tag="$INPUT_TAG" - if [[ -z "$tag" ]]; then - tag="${{ github.ref_name }}" - fi - - # `// empty` turns a missing/null key into an empty string instead - # of the literal "null", so the presence check below actually works. - organization=$(jq -r '.organization // empty' "$CONFIG_FILE") - branch=$(jq -r '.defaults.branch // empty' "$CONFIG_FILE") - user_name=$(jq -r '.defaults.user_name // empty' "$CONFIG_FILE") - user_email=$(jq -r '.defaults.user_email // empty' "$CONFIG_FILE") - - if [[ -z "$organization" || -z "$branch" || -z "$user_name" || -z "$user_email" ]]; then - echo "::error::Missing required keys in '$CONFIG_FILE' — organization, defaults.branch, defaults.user_name and defaults.user_email must all be set." - exit 1 - fi - - { - echo "matrix=$matrix" - echo "organization=$organization" - echo "branch=$branch" - echo "user_name=$user_name" - echo "user_email=$user_email" - echo "tag=$tag" - } >> "$GITHUB_OUTPUT" - - - name: Echo resolved matrix - run: echo '${{ steps.parse.outputs.matrix }}' | jq . - - split: - name: Split ${{ matrix.mirror_repo }} - needs: build-matrix - runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: ${{ fromJson(needs.build-matrix.outputs.matrix) }} - steps: - - name: Checkout monorepo (full history) - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - with: - # splitsh-lite needs every commit that ever touched the subtree. - fetch-depth: 0 - - - name: Split and push subtree to mirror - uses: danharrin/monorepo-split-github-action@14e42e2437f674b8987c1f50ca3689116aea1893 # v2.4.5 - with: - package_directory: ${{ matrix.package_directory }} - repository_organization: ${{ needs.build-matrix.outputs.organization }} - repository_name: ${{ matrix.mirror_repo }} - branch: ${{ needs.build-matrix.outputs.branch }} - tag: ${{ needs.build-matrix.outputs.tag }} - user_name: ${{ needs.build-matrix.outputs.user_name }} - user_email: ${{ needs.build-matrix.outputs.user_email }} - env: - GITHUB_TOKEN: ${{ secrets.split-token }} diff --git a/.github/workflows/ci-self-check.yml b/.github/workflows/ci-self-check.yml new file mode 100644 index 0000000..28adae0 --- /dev/null +++ b/.github/workflows/ci-self-check.yml @@ -0,0 +1,47 @@ +name: Self Check + +on: + push: + branches: + - main + - "release/**" + pull_request: + +permissions: + contents: read + +concurrency: + group: self-check-${{ github.ref }} + cancel-in-progress: true + +jobs: + self-check: + name: Lint workflows and verify examples + runs-on: ubuntu-latest + env: + ACTIONLINT_VERSION: "1.7.12" + ACTIONLINT_SHA256: "8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8" + steps: + - name: Checkout + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Install yamllint + run: pipx install yamllint + + - name: Run yamllint + run: yamllint -c .yamllint.yml .github/workflows/ examples/ + + - name: Install actionlint + run: | + set -euo pipefail + curl -sSfL -o actionlint.tar.gz \ + "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz" + echo "${ACTIONLINT_SHA256} actionlint.tar.gz" | sha256sum -c - + tar -xzf actionlint.tar.gz actionlint + install -m 0755 actionlint /usr/local/bin/actionlint + + - name: Run actionlint + run: actionlint -color .github/workflows/*.yml examples/*.yml + + - name: Verify examples match the workflows they call + run: bin/check-workflows.sh diff --git a/.github/workflows/version-monitor.yml b/.github/workflows/version-monitor.yml index 59dda01..d042331 100644 --- a/.github/workflows/version-monitor.yml +++ b/.github/workflows/version-monitor.yml @@ -34,6 +34,7 @@ concurrency: jobs: version-monitor: + name: Check for version bumps runs-on: ubuntu-latest timeout-minutes: 20 permissions: @@ -41,7 +42,7 @@ jobs: pull-requests: write steps: - name: Checkout - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: fetch-depth: 0 @@ -53,7 +54,7 @@ jobs: fi - name: Setup Node - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0 with: node-version: ${{ inputs.node-version }} diff --git a/.yamllint.yml b/.yamllint.yml index 9d33a61..e902d61 100644 --- a/.yamllint.yml +++ b/.yamllint.yml @@ -22,5 +22,4 @@ rules: document-start: disable ignore: | - .claude/ node_modules/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ed12b4a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,93 @@ +## Dev environment tips + +```bash +brew install actionlint yq jq # the only tooling this repo needs +``` + +Nothing to build, no `package.json`, no `node_modules`. Every file here is YAML or POSIX shell. + +### Key Directories + +- `.github/workflows/ci-*.yml` — CI leaves: `detect-changes`, `lint-{css,js,php}`, `test-{js,php,a11y}`, `build`, `build-artifact-gate`, `test-build-artifact` +- `.github/workflows/wp-ci.yml` — CI orchestrator; composes the leaves and routes by `project-type` +- `.github/workflows/cd-*.yml` — opt-in deploy leaves: `github-release`, `wp-org`, `s3`, `built-branch` +- `.github/workflows/version-monitor.yml` — monthly version-bump check that opens a draft PR +- `.github/workflows/ci-self-check.yml` — this repo's own CI; the only workflow not `on: workflow_call` +- `examples/.yml` — exactly one caller example per workflow, matched by filename +- `bin/check-workflows.sh` — enforces the examples contract and the conventions below + +## Progressive discovery + +Read only what your task needs, when it needs it: + +- **Input contracts**: a workflow's own `on.workflow_call` block is the source of truth for its inputs, secrets and outputs. Nothing duplicates it — GitHub renders those `description:` fields when a consumer wires up a caller. +- **Consumer view**: `README.md` carries the workflow index and the tag a consumer should pin. +- **Contributor docs**: `CONTRIBUTING.md` for the PR checklist. + +## Code quality + +```bash +pipx run yamllint . # style +actionlint .github/workflows/*.yml examples/*.yml # workflow correctness +bin/check-workflows.sh # examples match the workflows +act workflow_call -W .github/workflows/.yml --dryrun # plan one workflow locally (Docker) +``` + +The first three run in CI via `ci-self-check.yml`. Every workflow follows this shape: + +```yaml +name: CI / Lint PHP +on: + workflow_call: + inputs: + php-version: + description: "PHP version to install" + type: string + default: "8.3" +jobs: + lint-php: + name: Lint PHP + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 +``` + +- 2-space indent, `kebab-case` input names, a `description:` on every input, a `name:` on every job and step. `bin/check-workflows.sh` enforces all four. +- Third-party actions pinned to a commit SHA with a trailing `# vX.Y.Z` comment. +- User-controlled values reach a `run:` body through step `env:`, never through `${{ }}` interpolation: + +```yaml + - name: Resolve targets + env: + INPUT_TARGETS: ${{ inputs.targets }} + run: jq -e 'type == "array"' <<<"$INPUT_TARGETS" +``` + +## Architectural decisions + +- **A tagged workflow is public API**: inputs, secrets and outputs are consumed by every rtCamp repo pinned at `@v1`. A renamed input breaks them at workflow-validation time, before a single job starts. Additive changes only within a major; removals, renames and newly-required inputs ship as a new major. +- **Orchestrator plus leaves**: `wp-ci.yml` composes the CI leaves via `jobs..uses`, so a consumer wires up one job instead of ten. The `cd-*` workflows have no orchestrator by design — a consumer calls the ones it needs from its own release trigger, and each stays independently useful. +- **One unit per call**: `project-type` describes the unit at `working-dir`, not the repository. A repo with two plugins and a theme calls `wp-ci.yml` three times, usually via a matrix in the caller. Sibling calls don't cancel each other, and each derives its own artifact name. +- **Everything gated on what changed**: `ci-detect-changes.yml` buckets the diff and every downstream job keys off it, so a docs-only PR runs almost nothing. +- **Logic that needs a real language lives elsewhere**: `@rtcamp/wp-tooling`, invoked as `npx wp-tooling `. Repo-local automation is POSIX shell under `bin/`. +- **Examples are executable documentation**: one per workflow, verified in CI, comment-free, pinned `@v1`. They target a `wp-content`-shaped monorepo because that is the shape people get wrong. Anything consuming a build artifact shows the producing `ci-build` job and the `needs:` edge in the same file. +- **Prefer official tooling**: `actions/checkout`, `actions/setup-node`, `shivammathur/setup-php`, and WordPress/Automattic-maintained actions over third-party ones. + +## Common pitfalls + +- `working-dir` carries three different meanings. On the CI leaves it is a real working directory — tools install and run inside it. On `ci-detect-changes.yml` it is a **path scope**: the diff is always taken from the repository root, then the CSS/JS/PHP lists are filtered and re-rooted, while `total-count`, `ignored-count` and the `gha-*` outputs stay repo-wide. On `cd-github-release.yml` and `cd-wp-org.yml` it is a **path prefix** for source files they read (`changelog-path`, `assets-path`); the deployed files come from the artifact. `cd-built-branch.yml` scopes per entry in its `targets` JSON array, and `cd-s3.yml` by the artifact it downloads. +- `actions/download-artifact` only sees the current run. Anything consuming a build artifact must run in the same workflow as the `ci-build` job that produced it, wired with `needs:`. +- The default `wp-tooling-ref` SHA is duplicated in `ci-detect-changes.yml`, `wp-ci.yml` and `version-monitor.yml`. Changing one without the others silently splits behaviour across jobs. +- `actionlint` shells out to whatever `shellcheck` is on `PATH`, and rule behaviour differs between shellcheck releases — a local pass does not guarantee a CI pass. Write shell that is clean on older versions too: prefer `guard || continue` and explicit `if` blocks over `A && B || C`, which SC2015 flags on shellcheck 0.10 and earlier. +- A green `bin/check-workflows.sh` proves input *names* are right, not input *values*. A wrong `build-command` or `artifact-path` only surfaces in a real consumer run. +- `cd-github-release.yml` extracts release notes by matching a version heading in `CHANGELOG.md`, and deliberately fails rather than publishing empty notes. Cut `## Unreleased` to `## vX.Y.Z - YYYY-MM-DD` before tagging. +- Consumers pin `@v1`, never a branch such as `@release/v1.0.0`. A moving ref has already broken real consumer runs mid-change. + +## PR instructions + +- Task branches `/task/` off the active release branch. Never commit to `main`. +- [Conventional Commits](https://www.conventionalcommits.org/): `feat(ci): add lint-css workflow`. +- PR title `[] `, targeting the release branch. Squash merge; release branch → `main` is a merge commit. +- Ensure the Code quality commands pass, the caller example is updated alongside the workflow, and a `CHANGELOG.md` entry is added — see `CONTRIBUTING.md` for the full checklist. +- Ask first before removing or renaming an input, adding a deploy target, or granting a job `contents: write` it does not already need. diff --git a/CHANGELOG.md b/CHANGELOG.md index 6820259..5ad7df3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,14 +4,19 @@ All notable changes to `@rtcamp/wp-shared-workflows` are documented in this file The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). -## Unreleased +## v1.0.0 - 2026-08-10 + +First tagged release. Consumers pin `@v1`. ### Changed +- Documentation restructured for a public `main`. Caller examples move out of `README.md` into [`examples/`](examples/), one runnable file per workflow, verified in CI by `bin/check-workflows.sh`. `README.md` is now a workflow index plus a versioning guide, and no longer duplicates the input tables — each workflow's `workflow_call` block is the single source of truth, and GitHub renders those descriptions when a caller is configured. Repo conventions move to a tool-agnostic [`AGENTS.md`](AGENTS.md), which `CLAUDE.md` imports. Adds `LICENSE` (GPL-2.0-or-later, previously declared but absent) and `CONTRIBUTING.md`. +- `version-monitor.yml` now pins `actions/checkout` and `actions/setup-node` to the same SHAs as the other fifteen workflows, and its job carries an explicit `name:`. + - The `wp-tooling-token` secret is removed from `ci-detect-changes.yml`, `version-monitor.yml` and `wp-ci.yml`. `rtCamp/wp-tooling` is public, so the CLI now installs straight from its `npm/wp-tooling` branch with no token. This secret never appeared in a tagged release, so v1.0.0 simply ships without it — no major bump is owed. Anyone pinned to a branch ref for pre-release smoke testing must still delete the line, or the call fails with `Invalid input, wp-tooling-token is not defined in the referenced workflow`. A new `wp-tooling-ref` input (forwarded through `wp-ci.yml`) pins the install to a commit SHA and installs with `--ignore-scripts`, so a change on that branch cannot alter what your CI runs; override it to track the tip. The package is still not on the npm registry, so the install remains a git ref. - The `packages-token` secret is removed from `ci-lint-php.yml`, `ci-test-php.yml` and `wp-ci.yml`. `rtCamp/wp-framework` is public, so no known private Composer dependency is left to authenticate. It was added in `6274f32` and removed here, both within the unreleased v1.0.0 cycle, so no tagged release ever accepted it. Anyone pinned to a branch ref must delete the line, or the call fails with `Invalid input, packages-token is not defined in the referenced workflow`. `setup-php` still receives `github-token: ${{ github.token }}` for the API rate limit, which never depended on the secret, and `ci-test-php.yml` drops the wp-env Composer-auth step that existed only to forward it into the container. - Monorepo fixes across the CI leaves. All six `setup-node` steps that use `cache: npm` now pass `cache-dependency-path`, and `ci-lint-php.yml`'s Composer cache key is scoped to `/composer.lock`. `ci-build-artifact-gate.yml` normalises **and** regex-escapes `working-dir` before anchoring its pattern — previously a `./`-prefixed or metacharacter-containing value matched nothing, so the gate passed green on a PR that committed build output. `ci-test-build-artifact.yml` gains `working-dir`. -- `cd-github-release.yml` and `cd-wp-org.yml` gain `working-dir` as a **path prefix, not a working directory**: it scopes only the source-tree paths they read (`changelog-path`, `assets-path`), since the deployed files come from an already unit-scoped artifact. Both previously fell back to the repo root in a monorepo and failed silently — another unit's `CHANGELOG.md` still parses, and a missing `.wordpress-org` only emits a notice. Both now reject absolute and `..` paths. `cd-s3.yml` and `cd-split-composer-packages.yml` are unchanged. +- `cd-github-release.yml` and `cd-wp-org.yml` gain `working-dir` as a **path prefix, not a working directory**: it scopes only the source-tree paths they read (`changelog-path`, `assets-path`), since the deployed files come from an already unit-scoped artifact. Both previously fell back to the repo root in a monorepo and failed silently — another unit's `CHANGELOG.md` still parses, and a missing `.wordpress-org` only emits a notice. Both now reject absolute and `..` paths. `cd-s3.yml` is unchanged. ### Added @@ -22,7 +27,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `ci-build.yml`: reusable production-build workflow that covers the three rtCamp project shapes (Node-only, Composer-only, both). Each stack is gated on its own toggle: `install-node-deps` (default `true`) and `install-composer-deps` (default `false`). Default `composer-flags` use `--no-dev` (production build) and keep `--no-scripts` for supply-chain hygiene. The `build-command` default is empty and selects `npm run build:prod` when Node deps install, `composer run-script build` otherwise. Optional `upload-artifact` (default `false`) hands the build output to a downstream CD job; uses `if-no-files-found: error` so a misconfigured artifact path fails loudly at the upload step. Inputs: `install-node-deps`, `node-version`, `install-composer-deps`, `php-version`, `composer-flags`, `build-command`, `upload-artifact`, `artifact-name`, `artifact-path`, `retention-days`, `working-dir`. - `ci-build-artifact-gate.yml`: reusable workflow that fails a PR if it commits files under configured path prefixes (default: `assets/build/`). Pair with `ci-build.yml` so the CI-produced bundle is the only source of truth for build output. Compares `origin/..HEAD` with `--diff-filter=ACMR`, so additions/modifications/renames trip the gate and deletions are ignored (removing a previously-committed artifact is welcome). Runs only on `pull_request` events; on other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. Empty `gated-paths` input skips gracefully. Path prefixes are anchored as literal strings, and regex metacharacters in path names (`. + * ( ) [ ] { } | ^ $ ? \`) are escaped automatically. Inputs: `gated-paths`, `working-dir`. - `version-monitor.yml` — monthly scheduled workflow that detects version bumps and opens a draft PR per repo on a `version-monitor/YYYY-MM` branch. Re-runs in the same month update the existing PR. Node.js version is set via the `node-version` input (default `22`). Major bumps are surfaced for manual review; a month of only major bumps, or a detector that could not be checked, fails the run rather than passing silently. -- `cd-split-composer-packages.yml`: reusable "monorepo split" workflow (Symfony pattern) that mirrors each Composer-package subtree to its own standalone repo so Packagist can serve it. A `build-matrix` job parses `splitsh.json` (`organization`, `subtrees` map, `defaults.branch`/`user_name`/`user_email`) with jq — accepting both the shorthand string form and the object/`prefixes` form — and a matrixed `split` job runs `danharrin/monorepo-split-github-action` (pinned to `14e42e2`, v2.4.5) per subtree with `fail-fast: false`. `tag` falls back to the caller's `github.ref_name` when empty; missing or empty config fails loudly. Inputs: `tag`, `config-file`. Secret: `split-token` (PAT/App token with `contents: write` on every mirror repo). - `ci-test-build-artifact.yml`: reusable workflow that boots the packaged build artifact in a real WordPress to prove it installs, not just that the build compiled. Downloads the named artifact (via `actions/download-artifact` pinned to `d3f86a1`, v4.3.0), writes a `.wp-env.override.json` to pin `phpVersion`/`core` and mount only the downloaded artifact (clearing `plugins`/`themes` from the consumer config so the dev source tree never collides with the packaged output), boots `@wordpress/env` with `npx --yes @wordpress/env start --update`, activates the plugin or theme (selected from `install-path`), then runs `wp doctor check --all --format=json` and fails only on `error`-severity checks (warnings allowed). The artifact must be a complete installable plugin/theme directory, so point `ci-build.yml`'s `artifact-path` at a packaged dist directory rather than bare `build/`. An optional `smoke-script` runs inside the container after activation, and `wp-env stop` runs in an `if: always()` step (with its own timeout) so no container leaks into the next job. Production-oriented doctor checks that a dev wp-env always trips (e.g. `constant-wp-debug-falsy`, since wp-env enables `WP_DEBUG`) are excluded from the gate via the `doctor-ignore-checks` input. Inputs: `artifact-name`, `slug`, `node-version`, `php-version`, `wp-version`, `install-path`, `smoke-script`, `doctor-ignore-checks`. - `cd-github-release.yml`: reusable workflow that publishes a GitHub Release on a `v*.*.*` tag push. Downloads the named build artifact, extracts the release body from the matching `CHANGELOG.md` section (tolerant heading match — `## v1.2.3` or `## [1.2.3]` with an optional trailing date; `## Unreleased` is never matched and a missing/empty section fails the workflow rather than publishing empty notes), then creates the Release via the `gh` CLI (no third-party action) with `--verify-tag` so a non-existent tag errors instead of silently creating one. Attaches the artifact files and honours `draft` / `prerelease`. Requires the caller to grant `contents: write`; the artifact must be produced in the same run. Inputs: `tag`, `artifact-name`, `changelog-path`, `draft`, `prerelease`. - `cd-s3.yml`: reusable workflow that distributes a private/customer plugin to an S3 bucket on a release tag. Downloads the named build artifact and uploads its single `.zip` to a versioned key (`s3:///.zip`) plus an always-overwritten `latest.zip` (fails if the artifact contains zero or more than one `.zip`, so a misconfigured `artifact-path` can never deploy the wrong bundle), then optionally invalidates `/*` on a CloudFront distribution when `cloudfront-distribution-id` is set. Uses the official `aws-actions/configure-aws-credentials` (SHA-pinned to v6.1.3) with static access keys and the preinstalled AWS CLI — no third-party action, no checkout. User inputs pass through step `env:` (injection-safe). Inputs: `tag`, `artifact-name`, `bucket`, `prefix`, `cloudfront-distribution-id`, `region`. Required secrets: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` (need `s3:PutObject` on the prefix, plus `cloudfront:CreateInvalidation` when invalidating). @@ -31,4 +35,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). - `ci-lint-css.yml`: reusable Stylelint workflow. Runs `lint-command` over the whole project, or only the files in `changed-files` when that input is non-empty (selective linting). Inputs: `node-version`, `lint-command`, `changed-files`, `working-dir`. - `ci-lint-js.yml`: reusable ESLint workflow with optional `package.json` validation (`validate-package-json`, default `true`). `changed-files` scopes ESLint to just the listed files; empty lints the whole project. Inputs: `node-version`, `lint-command`, `changed-files`, `validate-package-json`, `working-dir`. - `ci-lint-php.yml`: reusable PHPCS workflow with `cs2pr` annotations and an optional PHPStan pass (`enable-phpstan`, default `false`). `changed-files` scopes PHPCS to the listed files; PHPStan always runs whole-project because it analyses cross-file dependencies. Default `composer-flags` keep `--no-scripts` for supply-chain hygiene. Inputs: `php-version`, `enable-phpstan`, `phpcs-command`, `changed-files`, `phpstan-command`, `phpstan-level`, `composer-flags`, `validate-composer`, `working-dir`. -- `wp-ci.yml`: CI orchestrator that routes to the individual CI workflows from one `project-type` input (`plugin` \| `theme` \| `package`). `detect-changes` runs first as a never-skippable backbone; every other job is gated on its per-bucket change counts and fed the matching `*-files` list, so a job runs only when its file type changed and its preset includes it. `skip` drops jobs by id with comma-exact matching (`skip: build` does not also drop `build-artifact`). `test-php` fans out over `php-versions` × `wp-versions` minus `test-php-exclude` cells; `use-wp-env` (default `true`) boots `@wordpress/env` per cell, pinning `WP_ENV_PHP_VERSION`/`WP_ENV_CORE`, while `false` runs standalone PHPUnit for a pure Composer library and leaves the `wp` dimension inert. `enable-phpstan` (default `false`) opts `lint-php` into a PHPStan pass. A `validate-inputs` job fails the run fast on an invalid `project-type` or a non-array matrix input, resolves the job preset from a single table, and derives a per-unit `artifact-name` (two units uploading the same name in one run is a `409 Conflict`) and a `build-artifact-slug` defaulting to `basename(working-dir)`. The `build-artifact` install test is opt-in via `build-artifact-path`; `artifact-gate` is opt-in via `gated-paths`, since failing a PR for committed build output is only correct where CI produces it. A `working-dir` input targets one unit in a monorepo and is forwarded to every child job, so `project-type` describes the unit at `working-dir` rather than the repository — a repo with a theme and two plugins calls this workflow three times, or matrixes over the units in one caller job. Concurrency includes `project-type` and `working-dir` so sibling calls do not cancel each other. Inputs: `project-type`, `working-dir`, `skip`, `enable-phpstan`, `use-wp-env`, `php-versions`, `wp-versions`, `test-php-exclude`, `build-artifact-path`, `build-artifact-slug`, `ignore-paths`, `base-ref`, `gated-paths`, `wp-tooling-ref`. Code coverage reporting is not yet included (v1.x follow-up). +- `wp-ci.yml`: CI orchestrator that routes to the individual CI workflows from one `project-type` input (`plugin` \| `theme` \| `package`). `detect-changes` runs first as a never-skippable backbone; every other job is gated on its per-bucket change counts and fed the matching `*-files` list, so a job runs only when its file type changed and its preset includes it. `skip` drops jobs by id with comma-exact matching (`skip: build` does not also drop `build-artifact`). `test-php` fans out over `php-versions` × `wp-versions` minus `test-php-exclude` cells; `use-wp-env` (default `true`) boots `@wordpress/env` per cell, pinning `WP_ENV_PHP_VERSION`/`WP_ENV_CORE`, while `false` runs standalone PHPUnit for a pure Composer library and leaves the `wp` dimension inert. `enable-phpstan` (default `false`) opts `lint-php` into a PHPStan pass. A `validate-inputs` job fails the run fast on an invalid `project-type` or a non-array matrix input, resolves the job preset from a single table, and derives a per-unit `artifact-name` (two units uploading the same name in one run is a `409 Conflict`) and a `build-artifact-slug` defaulting to `basename(working-dir)`. The `build-artifact` install test is opt-in via `build-artifact-path`; `artifact-gate` is opt-in via `gated-paths`, since failing a PR for committed build output is only correct where CI produces it. A `working-dir` input targets one unit in a monorepo and is forwarded to every child job, so `project-type` describes the unit at `working-dir` rather than the repository — a repo with a theme and two plugins calls this workflow three times, or matrixes over the units in one caller job. Concurrency includes `project-type` and `working-dir` so sibling calls do not cancel each other. Inputs: `project-type`, `working-dir`, `skip`, `enable-phpstan`, `run-a11y`, `use-wp-env`, `php-versions`, `wp-versions`, `test-php-exclude`, `build-artifact-path`, `build-artifact-slug`, `ignore-paths`, `base-ref`, `gated-paths`, `wp-tooling-ref`. Code coverage reporting is not yet included (v1.x follow-up). diff --git a/CLAUDE.md b/CLAUDE.md index 6d6defe..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,190 +1 @@ -# CLAUDE.md — `wp-shared-workflows` - -Read this file at the start of every session. Topic-specific details live in [.claude/issues/](.claude/issues/) (per-task state) and [.claude/commands/](.claude/commands/) (skills). Read those only when the task requires. - ---- - -## What this repo is - -A pure GitHub Actions workflow repository for rtCamp WordPress projects. Provides reusable CI and CD building blocks consumed by every rtCamp repo via `uses: rtCamp/wp-shared-workflows/.github/workflows/.yml@v1`. Zero JavaScript. Zero `node_modules`. Only YAML. Scripts that need logic live in `@rtcamp/wp-tooling` and are invoked through `npx wp-tooling `. - ---- - -## Non-negotiables - -- No JavaScript files in this repo — not even one. -- No `package.json` — this is not a Node project. -- Every workflow uses `on: workflow_call` with typed inputs and outputs. -- Input names use `kebab-case` (`php-version`, not `phpVersion`). -- Every breaking change produces a new major version tag. -- Caller examples in `README.md` must actually work — tested against a consumer repo before merge. -- Deploy targets (WordPress.org, VIP, S3, custom) are separate workflows. The CD orchestrator picks based on caller input. No deploy path is hard-coded; consumers opt into each explicitly. - ---- - -## Principle — prefer official WordPress tooling - -When WordPress or `@wordpress/*` ships something that covers our need, we use it. Build custom only when there's a real gap — no official option, or the official option blocks a hard constraint (pinned input schema, project-type presets, etc.). - -Use `actions/checkout`, `actions/setup-node`, `shivammathur/setup-php` (the community standard PHP action) over hand-rolled steps. For WordPress-specific tasks, prefer actions maintained by the WordPress or Automattic org over third-party ones. - -Before adding any new action or step: check if an official option already exists. If it does, use that and layer rtCamp-specific overrides via inputs. - ---- - -## Language & versions - -| | | -|---|---| -| GitHub Actions | latest stable runners (`ubuntu-latest`) | -| Versioning | `@v1` / `@v1.2` / `@v1.2.3` tags | -| PHP in workflows | 8.3 (overridable per call) | -| Node in workflows | 22 (overridable per call) | - ---- - -## Directory layout - -``` -.github/workflows/ - ci-detect-changes.yml Pre-run: changed file detection (wraps the wp-tooling CLI) - ci-lint-css.yml Stylelint - ci-lint-js.yml ESLint + package.json validation - ci-lint-php.yml PHPCS + optional PHPStan - ci-test-js.yml Jest - ci-test-php.yml PHPUnit (wp-env or standalone) - ci-test-a11y.yml pa11y-ci WCAG2AA (opt-in via run-a11y) - ci-build.yml Build + optional artifact - ci-build-artifact-gate.yml Fails a PR that commits build output - ci-test-build-artifact.yml Boots the packaged artifact in real WordPress - wp-ci.yml CI orchestrator (project-type presets, one unit per call) - cd-github-release.yml GitHub Release from a tag + artifact - cd-wp-org.yml WordPress.org SVN deploy - cd-s3.yml S3 artifact upload (+ optional CloudFront invalidation) - cd-built-branch.yml Builds and force-pushes the built tree to a deploy branch - cd-split-composer-packages.yml Mirrors Composer subtrees to standalone repos - wp-cd.yml CD orchestrator — deploy-target: github, wporg, s3 - version-monitor.yml Monthly version check -README.md Caller examples — keep accurate -``` - -Deploy workflows are all optional. For tag-driven releases, consumers list which targets they want in the CD orchestrator call: - -```yaml -uses: rtCamp/wp-shared-workflows/.github/workflows/wp-cd.yml@v1 -with: - deploy-target: "github,wporg" # or "github,s3" -``` - ---- - -## Architecture patterns - -Every reusable workflow follows this shape: - -```yaml -name: -on: - workflow_call: - inputs: - php-version: - description: "PHP version to install" - type: string - default: "8.3" - enable-phpstan: - description: "Run PHPStan after PHPCS" - type: boolean - default: false -jobs: - : - runs-on: ubuntu-latest - steps: - - name: - ... -``` - -Orchestrators (`wp-ci.yml`, `wp-cd.yml`) compose individual workflows via `jobs..uses: ./.github/workflows/.yml`. They never duplicate logic — if you find yourself copying from an individual workflow into an orchestrator, stop and refactor. - ---- - -## Coding standards - -- YAML indented 2 spaces, no tabs. -- Every input has a `description:` string — shown in GitHub UI when a caller configures. -- Every `step` has an explicit `name:` — never anonymous. -- Third-party actions pinned to a commit SHA, not a tag (supply-chain hygiene). -- Prefer built-in actions (`actions/checkout@v4`, `actions/setup-node@v4`) over third-party where possible. - ---- - -## Testing - -- Local dry-run: [`act`](https://github.com/nektos/act). -- Full integration test: push to a test branch in a throwaway consumer repo that references `@`. -- Every workflow merge is followed by a smoke test in at least one real consumer before tagging. - ---- - -## Git workflow - -- Every milestone has a long-lived release branch (`release/v1.0.0`). Never merge directly into `main`. -- Task branches: `v1.0.0/task/`, based on `release/v1.0.0`. -- Commit style: [Conventional Commits](https://www.conventionalcommits.org/) — `feat(ci): add lint-css workflow`. -- PR title: `[v1.0.0] `. PR target: `release/v1.0.0`. -- Squash merge. Never `--no-verify`. - -### Version tag strategy - -When `release/v1.0.0` merges to `main`: - -| Change type | Action | -|---|---| -| Bug fix, no API change | move `@v1.2` + add `@v1.2.3` | -| New input with a default | add `@v1.3` + move `@v1` | -| Breaking change (input removed, renamed, required-now) | add `@v2` — do NOT move `@v1` | - ---- - -## Working on an issue - -When the user references a GitHub issue (`#13`, "the CI lint task"): - -1. Check `.claude/issues/-.md`. -2. **File exists** → the issue is in progress or complete. Read it for current state. Continue from there. -3. **File missing** → the issue has not been started. Copy `.claude/issues/_TEMPLATE.md` to `.claude/issues/-.md`, fill `Summary` from the GitHub issue, set `status: in-progress`. Commit it as part of the first commit on the task branch. - -Update this file as work progresses. - -### Rotation protocol (seniors at 4h/day may rotate mid-issue) - -- **Leaving an issue:** run `/handoff out` — Claude generates the log entry + a GitHub issue comment. Push WIP, apply `Status: Blocked`, post the comment. -- **Picking up an issue:** pull the branch, confirm your local `act` dry-run works, then `/handoff in`. Remove `Status: Blocked`, post the comment. -- Outgoing entry must be detailed enough that the incoming engineer needs **zero questions**. - ---- - -## Available skills - -- `/add-ci-workflow ` — scaffold a new `ci-.yml` reusable workflow with inputs, outputs, and jobs -- `/add-cd-workflow ` — same for CD (`cd-.yml`) -- `/review-workflow ` — audit for zero-JS rule, kebab-case inputs, typed schema -- `/generate-caller-example ` — produce the 10-line YAML a consumer pastes -- `/bump-workflow-version ` — decide patch/minor/major and update `README.md` caller examples -- `/handoff [out|in]` — generate a rotation handoff log entry + GitHub comment - ---- - -## PR authoring - -Use `.github/pull_request_template.md`. PR body mirrors the issue structure. Draft from the issue file. - -Always include `Closes #`. - ---- - -## User preferences - -- No auto-commits — the developer runs all `git` commands themselves. -- Brief, direct replies in chat. -- Don't create unsolicited documentation files. -- British English in prose. +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2cb2b42 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,62 @@ +# Contributing to wp-shared-workflows + +Thanks for your interest in improving `rtCamp/wp-shared-workflows`. This repository ships **workflow +contracts** rather than application code: the moment a workflow is tagged, its inputs, secrets and +outputs are public API, and every rtCamp repo pinned at `@v1` picks up the change on its next run. A +renamed input is not a refactor — it breaks every consumer at workflow-validation time, before a +single job starts. Treat the input surface as stable. + +## Ground rules + +- **Conventions live in [AGENTS.md](AGENTS.md).** Read it before your first change — it covers the + repo layout, the shape every workflow follows, and the coding standards CI enforces. +- **Every workflow has exactly one caller example** at `examples/.yml`. Add or update it + in the same PR; CI fails otherwise. +- **Repo-local automation is POSIX shell** under `bin/`. Logic that needs a real language belongs in + [`@rtcamp/wp-tooling`](https://github.com/rtCamp/wp-tooling) and is invoked via `npx wp-tooling`. +- **Third-party actions are pinned to a commit SHA** with a trailing `# vX.Y.Z` comment. + +## Development setup + +There is nothing to build. Install the linters once: + +```bash +brew install actionlint yq jq # or your platform's equivalent +``` + +## Before you open a PR + +The first three must exit `0`; they are the same checks CI runs: + +```bash +pipx run yamllint . # style +actionlint .github/workflows/*.yml examples/*.yml # workflow correctness +bin/check-workflows.sh # examples match the workflows +act workflow_call -W .github/workflows/ci-build.yml --dryrun # plan one workflow locally +``` + +`bin/check-workflows.sh` is the one that matters most: it proves every example passes only inputs and +secrets its workflow actually declares, supplies every required one, and is pinned at `@v1`. It also +enforces kebab-case input names, input descriptions and named steps. + +`act` needs a running Docker daemon. `--dryrun` resolves the job graph and prints the steps it would +run without executing them, which is the closest you can get to a real runner locally. + +None of this verifies input *values* — a wrong `build-command` or `artifact-path` passes every check +here. Before tagging, smoke-test against a real consumer repository by temporarily pointing its +caller at your branch. + +## Pull request checklist + +- [ ] Branch is `/task/`, based on the active release branch. +- [ ] The three commands above pass locally. +- [ ] Every new or changed input has a `description:`. +- [ ] `examples/.yml` added or updated to match. +- [ ] `CHANGELOG.md` entry added under the current version heading. +- [ ] Breaking changes to an input surface are called out in the PR description. +- [ ] Smoke-tested against a consumer repo, or explicitly noted why not. +- [ ] Commits follow [Conventional Commits](https://www.conventionalcommits.org/). + +## License + +GPL-2.0-or-later. See [LICENSE](LICENSE). diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..23cb790 --- /dev/null +++ b/LICENSE @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + {description} + Copyright (C) {year} {fullname} + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + {signature of Ty Coon}, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. diff --git a/README.md b/README.md index 2567959..4143c97 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,11 @@ # wp-shared-workflows -Reusable GitHub Actions workflows for rtCamp WordPress projects. Pure YAML — zero JavaScript. Consumed by every rtCamp repo via `uses: rtCamp/wp-shared-workflows/.github/workflows/.yml@v1`. +Reusable GitHub Actions workflows for rtCamp WordPress projects. Pure YAML — nothing to install. -## What's inside - -- CI workflows — lint (PHP / JS / CSS), test (PHPUnit / Jest / pa11y), build, detect-changes -- CI orchestrator — `wp-ci.yml` composes individual workflows based on `project-type` preset (plugin / theme / package) -- CD workflows — GitHub Release, WordPress.org SVN deploy, S3 artifact upload, built-branch publish -- CD orchestrator — `wp-cd.yml` -- Version monitor — `version-monitor.yml` runs monthly and opens draft PRs for version bumps - -## Development - -See [`CLAUDE.md`](./CLAUDE.md) for workflow conventions, version-tag strategy, testing, and git workflow. - -Per-issue progress lives in [`.claude/issues/`](./.claude/issues/). Claude skills live in [`.claude/commands/`](./.claude/commands/). - -## Consumer example - -```yaml -# .github/workflows/ci.yml in any rtCamp repo -name: CI -on: [push, pull_request] -permissions: - contents: read -jobs: - ci: - uses: rtCamp/wp-shared-workflows/.github/workflows/wp-ci.yml@v1 - with: - project-type: "plugin" # plugin | theme | package -``` - -## Individual workflows - -### `wp-ci.yml`: CI orchestrator - -Call this once and it routes to the right subset of the individual CI workflows for your `project-type`. `detect-changes` runs first; every downstream job is gated on its per-bucket counts, so a PR that touched no PHP skips PHP lint and tests, and so on. A consumer adds a ~10-line caller and never wires the underlying workflows by hand. +## Quick start ```yaml -# .github/workflows/ci.yml in the consumer +# .github/workflows/ci.yml name: CI on: [push, pull_request] permissions: @@ -48,753 +15,76 @@ jobs: uses: rtCamp/wp-shared-workflows/.github/workflows/wp-ci.yml@v1 with: project-type: plugin # plugin | theme | package - # skip: "a11y" # optional: comma-separated job ids - # enable-phpstan: true # optional: run PHPStan after PHPCS - # use-wp-env: false # optional: standalone PHPUnit for a pure Composer library - # run-a11y: ${{ contains(github.event.pull_request.labels.*.name, 'Run a11y') }} # optional: gate a11y on a label - # Optional: fan PHPUnit across a PHP x WordPress grid. Under the default wp-env - # each cell pins PHP + WordPress core; drop cells via test-php-exclude — each - # {php, wp} must match a cell in the product. Omit all three for a single 8.3 leg. - php-versions: '["8.1","8.2","8.3"]' - wp-versions: '["6.7","6.8","6.9"]' - test-php-exclude: '[{"php":"8.1","wp":"6.9"}]' -``` - -| Input | Type | Default | Description | -| ------------------ | ------- | ------------ | ---------------------------------------------------------------------------------------------------- | -| `project-type` | string | — | **Required.** `plugin` \| `theme` \| `package` — selects the job preset. Describes the unit at `working-dir`, not the repository. | -| `working-dir` | string | `"."` | Directory holding the unit this call targets, relative to the repo root. `"."` is the repo root itself. | -| `skip` | string | `""` | Comma-separated job ids to drop without forking the orchestrator. Disable PHP tests with `test-php` here — not an empty array. | -| `enable-phpstan` | boolean | `false` | Run PHPStan (whole-project) after PHPCS in `lint-php`. | -| `run-a11y` | boolean | `false` | Run the `a11y` job. Off by default — slow and needs pa11y config. Gate it on the `Run a11y` label at the caller. | -| `use-wp-env` | boolean | `true` | Run `test-php` under `@wordpress/env`. Set `false` only for a pure Composer library that runs standalone PHPUnit. | -| `php-versions` | string | `["8.3"]` | Non-empty JSON array of PHP versions; crossed with `wp-versions` to fan out `test-php`. Empty `[]` is a matrix error. | -| `wp-versions` | string | `[""]` | JSON array of WordPress core versions for wp-env; crossed with `php-versions`. Empty string = `.wp-env.json` default; ignored when `use-wp-env: false`. | -| `test-php-exclude` | string | `[]` | JSON array of `{php, wp}` cells to drop from the product; both keys must match a cell. | -| `build-artifact-path` | string | `""` | Packaged installable plugin/theme dir the build produces (e.g. `dist/my-plugin/`). Set this to run the `build-artifact` install test; empty skips it. | -| `build-artifact-slug` | string | `""` | Slug to activate in the `build-artifact` test. Empty uses `working-dir`'s basename, or the repo name when `working-dir` is `"."`. | -| `ignore-paths` | string | `""` | Regex of paths `detect-changes` excludes from its counts and file lists. Empty uses the CLI's built-in ignore set. | -| `base-ref` | string | `""` | Explicit git ref `detect-changes` diffs `HEAD` against. Empty lets the CLI resolve it from the PR base or push event. | -| `gated-paths` | string | `""` | Newline-separated path prefixes (relative to `working-dir`) that must not be committed in a PR, e.g. `assets/build/`. Empty skips the `artifact-gate` job entirely. | -| `wp-tooling-ref` | string | pinned SHA | Git ref of `rtCamp/wp-tooling`'s `npm/wp-tooling` branch that `detect-changes` installs the CLI from. Defaults to a pinned commit; override to track the branch tip. | - -**Project-type presets** (a job also runs only when `detect-changes` reports the relevant bucket changed): - -| Preset | Jobs | -| --------- | ---- | -| `plugin` | detect-changes, lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact†, a11y‡, artifact-gate§ | -| `theme` | detect-changes, lint-css, lint-js, lint-php, test-js, test-php, build, build-artifact†, a11y‡, artifact-gate§ | -| `package` | detect-changes, lint-php, test-php, artifact-gate§ | - -† `build-artifact` runs only when `build-artifact-path` is set — the default `build` output is not an installable directory. -‡ `a11y` runs only when `run-a11y: true` — it is slow and needs pa11y config, so gate it on the `Run a11y` label at the caller. -§ `artifact-gate` runs only when `gated-paths` is set. It fails a PR that commits generated output, so it is opt-in — set it only where CI produces that output rather than the repo committing it. - -Skippable job ids (for `skip`): `lint-css`, `lint-js`, `lint-php`, `test-js`, `test-php`, `build`, `build-artifact`, `a11y`, `artifact-gate`. `validate-inputs` and `detect-changes` always run and aren't skippable. Matching is comma-exact, so `skip: build` drops `build` but not `build-artifact`. - -Notes: - -- **Concurrency** — duplicate runs on the same ref (e.g. a force-push) are cancelled. The group includes `project-type` and `working-dir` (`ci-${{ github.ref }}--`) so that sibling calls do not cancel each other. -- **PHP / WordPress matrix** — `test-php` fans out over `php-versions` × `wp-versions` minus `test-php-exclude`. With `use-wp-env: true` (the default) each cell boots `@wordpress/env`, pinning `WP_ENV_PHP_VERSION` and `WP_ENV_CORE` — this suits plugins, themes, and packages whose suite tests against WordPress (e.g. via `wp-phpunit`), and the consumer needs a `.wp-env.json` plus `wp-env` and `test:php` npm scripts. A pure Composer library sets `use-wp-env: false` to run **standalone** PHPUnit (`vendor/bin/phpunit`), where the `wp` dimension is inert and no Node/Docker is required. Node defaults to 22; defaults run a single PHP 8.3 leg against the consumer's `.wp-env.json` WordPress version. -- **Static analysis & coverage** — PHPStan is off by default; opt in with `enable-phpstan: true`. The orchestrator does not yet produce a coverage report (a v1.x follow-up), so it does not fully replace a pipeline that gated on coverage. -- **`build-artifact`** — opt-in. Set `build-artifact-path` to the installable dir your build produces (the default `build` output is bare `build/`, not installable); the `build` job then uploads that path and `build-artifact` boots it in WordPress. `build-artifact-slug` overrides the activated slug (it defaults to `basename(working-dir)`, or the repo name when `working-dir` is `"."`); install path follows `project-type`. - -### `version-monitor.yml`: monthly version monitor - -Runs on a monthly schedule and opens a draft PR with the version bumps detected across npm, GitHub Actions, PHP, Node, WP-CLI, and container base images — the moving versions Dependabot does not cover. Minor and patch bumps are applied automatically; major bumps are listed in the PR body for manual review rather than applied. Re-runs in the same calendar month update the existing PR instead of opening a duplicate. Detection and patching run through `npx wp-tooling version-monitor`; the draft PR is opened and updated with [`peter-evans/create-pull-request`](https://github.com/peter-evans/create-pull-request) (SHA-pinned). - -Requires a `.github/version-monitor.yml` config in the consumer repo listing which sources to watch — see [`@rtcamp/wp-tooling`](https://github.com/rtCamp/wp-tooling) for the full schema. - -```yaml -# .github/workflows/version-monitor.yml in the consumer -name: Version Monitor -on: - schedule: - - cron: "0 6 1 * *" # 06:00 UTC, first of each month - workflow_dispatch: -jobs: - monitor: - permissions: - contents: write - pull-requests: write - uses: rtCamp/wp-shared-workflows/.github/workflows/version-monitor.yml@v1 - with: - base-branch: main - pr-assignees: "Adi-ty" -``` - -| Input | Type | Default | Description | -| -------------- | ------ | ------------------- | ---------------------------------------------------- | -| `node-version` | string | `"22"` | Node.js version used to install and run wp-tooling. | -| `base-branch` | string | `"main"` | Branch the draft PR is opened against. | -| `pr-label` | string | `"version-monitor"` | Label applied to the draft PR. | -| `pr-assignees` | string | `""` | Comma-separated GitHub usernames assigned to the PR. | -| `wp-tooling-ref` | string | pinned SHA | Git ref of `rtCamp/wp-tooling`'s `npm/wp-tooling` branch the CLI is installed from. Defaults to a pinned commit; override to track the branch tip. | - -The calling job must grant `permissions: contents: write` and `pull-requests: write` so the workflow can push the `version-monitor/YYYY-MM` branch and open the PR, and the repo must have **Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"** enabled, or PR creation is blocked. Major bumps are never auto-applied — a bare version-string swap is rarely a safe major upgrade — so a month of only major bumps produces no diff and no PR; the run fails with the bump list in the log so they are surfaced rather than passing silently. The run also fails when a detector could not be checked (a PR may still carry the bumps that were found), so a scheduled run is never green while blind. - -### `ci-detect-changes.yml`: changed-file detection - -Buckets the files changed in a PR or push and exposes, per language bucket, both a **count** (for job gating) and the **exact file list** (for selective linting). Wraps the [`wp-tooling detect-changes`](https://github.com/rtCamp/wp-tooling) CLI — base-ref resolution and the bucket rules live there. Run it as a pre-run job, then feed its `*-files` outputs into the lint workflows so each one lints only what the PR touched. - -```yaml -jobs: - detect: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-detect-changes.yml@v1 - - lint-css: - needs: detect - if: ${{ needs.detect.outputs.css-count > 0 }} - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-css.yml@v1 - with: - changed-files: ${{ needs.detect.outputs.css-files }} - - lint-php: - needs: detect - if: ${{ needs.detect.outputs.php-count > 0 }} - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-php.yml@v1 - with: - changed-files: ${{ needs.detect.outputs.php-files }} -``` - -| Input | Type | Default | Description | -| -------------- | ------ | ------- | ------------------------------------------------------------------------------------------ | -| `node-version` | string | `"22"` | Node.js version used to run the wp-tooling CLI. | -| `ignore-paths` | string | `""` | Regex of paths to exclude from counts and file lists. Empty uses the CLI's built-in ignore set. | -| `base-ref` | string | `""` | Explicit ref to diff `HEAD` against. Empty lets the CLI resolve it from the PR base or push event. | -| `wp-tooling-ref` | string | pinned SHA | Git ref of `rtCamp/wp-tooling`'s `npm/wp-tooling` branch the CLI is installed from. Defaults to a pinned commit; override to track the branch tip. | -| `working-dir` | string | `"."` | Restricts the css/js/php counts and file lists to this directory, and makes those file lists relative to it. A **path scope, not a working directory** — the diff is always taken from the repo root. | - -| Output | Description | -| ------------------------------------------------- | ---------------------------------------------------------------------------------- | -| `total-count` / `ignored-count` | Changed files kept after / dropped by the ignore filter. **Always repo-wide** — not restricted by `working-dir`. | -| `css-count` / `js-count` / `php-count` | Per-bucket change counts under `working-dir`. Gate downstream jobs on these. | -| `gha-count` / `gha-files` | Changed workflow files. **Always repo-wide** — workflow files only exist at `.github/workflows/` in the repo root, so scoping them would always yield nothing. | -| `css-files` / `js-files` / `php-files` | Newline-separated paths per bucket, **relative to `working-dir`**, ready for the lint workflows' `changed-files`. | - -`@rtcamp/wp-tooling` is not on the npm registry yet, so the CLI is installed from the public `rtCamp/wp-tooling` repo's `npm/wp-tooling` branch, which carries the package at its root — no token needed. The install uses `--ignore-scripts`, and `wp-tooling-ref` defaults to a **pinned commit SHA** so a change on that branch cannot alter what your CI executes; override it to track the tip. The workflow runs unconditionally — count-based gating is the caller's (or orchestrator's) job, not the detector's. - -> **Gate on the count, always.** An empty `changed-files` makes every lint workflow fall back to a whole-project run. Without the `if: … > 0` guard, a PR that touched no CSS would start the linter with nothing to do and it would silently lint the entire project instead of skipping. - -### `ci-lint-css.yml`: Stylelint - -Runs Stylelint over the project, or only over the files in `changed-files` when that input is non-empty. - -```yaml -jobs: - lint-css: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-css.yml@v1 - with: - node-version: "22" -``` - -| Input | Type | Default | Description | -| --------------- | ------ | ------------------ | ---------------------------------------------------------------------------- | -| `node-version` | string | `"22"` | Node.js version. | -| `lint-command` | string | `"npm run lint:css"` | Whole-project Stylelint command. Used when `changed-files` is empty. | -| `changed-files` | string | `""` | Newline-separated CSS files to lint. Empty = run `lint-command` whole-project. | -| `working-dir` | string | `"."` | Directory the job runs in. | - -### `ci-lint-js.yml`: ESLint - -Runs ESLint, with optional `package.json` validation. `changed-files` scopes ESLint to just the listed files. - -```yaml -jobs: - lint-js: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-js.yml@v1 - with: - node-version: "22" -``` - -| Input | Type | Default | Description | -| ----------------------- | ------- | ----------------- | ---------------------------------------------------------------------------- | -| `node-version` | string | `"22"` | Node.js version. | -| `lint-command` | string | `"npm run lint:js"` | Whole-project ESLint command. Used when `changed-files` is empty. | -| `changed-files` | string | `""` | Newline-separated JS files to lint. Empty = run `lint-command` whole-project. | -| `validate-package-json` | boolean | `true` | Run `npm run lint:package-json` before ESLint. | -| `working-dir` | string | `"."` | Directory the job runs in. | - -### `ci-lint-php.yml`: PHPCS + optional PHPStan - -Runs PHPCS with `cs2pr` annotations and, when `enable-phpstan` is true, PHPStan. `changed-files` scopes **PHPCS** to the listed files; PHPStan always runs whole-project because it analyses cross-file dependencies. - -```yaml -jobs: - lint-php: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-php.yml@v1 - with: - php-version: "8.3" - enable-phpstan: true -``` - -| Input | Type | Default | Description | -| ------------------ | ------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- | -| `php-version` | string | `"8.3"` | PHP version. | -| `enable-phpstan` | boolean | `false` | Run PHPStan after PHPCS. | -| `phpcs-command` | string | `"vendor/bin/phpcs"` | PHPCS binary path or custom command. | -| `changed-files` | string | `""` | Newline-separated PHP files to lint with PHPCS. Empty = lint the whole project. | -| `phpstan-command` | string | `"vendor/bin/phpstan analyse"` | Shell command that runs PHPStan. | -| `phpstan-level` | string | `""` | Override PHPStan level. Empty uses the level from `phpstan.neon.dist`. | -| `composer-flags` | string | `"--prefer-dist --optimize-autoloader --no-progress --no-interaction --no-scripts"` | Flags passed to `composer install`. Keeps `--no-scripts` for hygiene. | -| `validate-composer`| boolean | `true` | Run `composer validate` before installing. | -| `working-dir` | string | `"."` | Directory the job runs in. | - -### `ci-build.yml`: production build - -Runs the consumer's production build, with an optional artifact upload for downstream CD jobs. Default shape is build-only (no artifact written). - -**Node-only build (default):** frontend-heavy plugin or theme. - -```yaml -jobs: - build: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 - with: - node-version: "22" -``` - -**Node-only build with artifact upload:** hand the output to a downstream CD job. - -```yaml -jobs: - build: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 - with: - node-version: "22" - upload-artifact: true -``` - -**Node + Composer:** plugin that ships `vendor/` alongside compiled JS. - -```yaml -jobs: - build: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 - with: - node-version: "22" - install-composer-deps: true - php-version: "8.3" - upload-artifact: true -``` - -**Composer-only:** pure PHP package, no JS toolchain. - -```yaml -jobs: - build: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 - with: - install-node-deps: false - install-composer-deps: true - php-version: "8.3" -``` - -| Input | Type | Default | Description | -| ----------------------- | ------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -| `install-node-deps` | boolean | `true` | Install Node dependencies before the build. | -| `node-version` | string | `"22"` | Node.js version (used only when `install-node-deps` is true). | -| `install-composer-deps` | boolean | `false` | Install Composer dependencies before the build. | -| `php-version` | string | `"8.3"` | PHP version (used only when `install-composer-deps` is true). | -| `composer-flags` | string | `"--no-dev --prefer-dist --optimize-autoloader --no-progress --no-interaction --no-scripts"` | Flags passed to `composer install`. | -| `build-command` | string | `""` | Build command. Empty means `npm run build:prod` when `install-node-deps` is true, otherwise `composer run-script build`. | -| `upload-artifact` | boolean | `false` | Upload the build output as a GitHub Actions artifact for downstream jobs. | -| `artifact-name` | string | `"build"` | Artifact name. Must match the name in the downstream `actions/download-artifact` step. | -| `artifact-path` | string | `"build/"` | Path to upload. Resolved as `working-dir/artifact-path`. | -| `retention-days` | number | `7` | Days to keep the artifact before GitHub deletes it. | -| `working-dir` | string | `"."` | Directory the job runs in. | - -A misconfigured `artifact-path` fails loudly via `if-no-files-found: error`. No silent empty artifacts. -### `ci-test-php.yml`: PHPUnit - -Runs PHPUnit either against a real WordPress environment via [`@wordpress/env`](https://github.com/WordPress/gutenberg/tree/trunk/packages/env) (default) or standalone for Composer libraries. - -**Plugin or theme:** WordPress integration tests via `wp-env` (default). - -```yaml -jobs: - test-php: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-php.yml@v1 - with: - php-version: "8.3" -``` - -**Composer package:** standalone PHPUnit, no Node, no Docker. - -```yaml -jobs: - test-php: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-php.yml@v1 - with: - php-version: "8.3" - use-wp-env: false -``` - -| Input | Type | Default | Description | -| ---------------- | ------- | ------------------------------------------------------------- | -------------------------------------------------------------------------- | -| `php-version` | string | `"8.3"` | PHP version to install. | -| `node-version` | string | `"22"` | Node.js version. Consumed only when `use-wp-env: true`. | -| `wp-version` | string | `""` | WordPress core version for wp-env, e.g. `"6.8"` (resolved as `WordPress/WordPress#`). Empty uses the consumer's `.wp-env.json`. Ignored when `use-wp-env: false`. | -| `use-wp-env` | boolean | `true` | Start `@wordpress/env` before tests for WordPress integration runs. | -| `test-command` | string | `""` | PHPUnit command. Empty means `npm run test:php` in wp-env mode, `vendor/bin/phpunit` standalone. | -| `composer-flags` | string | `"--no-interaction --prefer-dist --no-progress --no-scripts"` | Flags passed to `composer install`. Keep `--no-scripts` for supply-chain hygiene. | -| `working-dir` | string | `"."` | Directory the job runs in. | - -Each workflow can be called independently, so you can wire them into your own job graph if the orchestrator preset does not fit your setup. - -### `ci-test-js.yml` — Jest tests - -Runs JavaScript unit tests using Jest with optional transform/result caching across runs. - -```yaml -# .github/workflows/ci.yml -name: CI -on: [push, pull_request] -jobs: - test-js: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-js.yml@v1 - with: - node-version: "22" -``` - -| Input | Type | Default | Description | -| -------------- | ------- | -------------------------- | ------------------------------------------------ | -| `node-version` | string | `"22"` | Node.js version to install. | -| `test-command` | string | `"npm run test:js -- --ci"`| Shell command that runs Jest. | -| `enable-cache` | boolean | `true` | Cache Jest transform/result data across runs. | -| `working-dir` | string | `"."` | Directory the job runs in. | - -### `ci-test-a11y.yml` — accessibility tests - -Runs `pa11y-ci` against the built site served by `@wordpress/env`. The reusable workflow is trigger-agnostic — wire the `Run a11y` label gate at the caller because a11y runs are slower than the rest of the CI matrix. - -```yaml -# .github/workflows/ci.yml in the consumer -name: CI -on: - pull_request: - types: [labeled, synchronize, reopened] -jobs: - test-a11y: - if: contains(github.event.pull_request.labels.*.name, 'Run a11y') - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-a11y.yml@v1 - with: - node-version: "22" -``` - -| Input | Type | Default | Description | -| --------------- | ------ | ---------------------- | ------------------------------------------------------------------------ | -| `node-version` | string | `"22"` | Node.js version to install. | -| `build-command` | string | `"npm run build:prod"` | Shell command that produces the production build pa11y will test against. | -| `test-command` | string | `"npm run test:a11y"` | Shell command that runs pa11y-ci. | -| `working-dir` | string | `"."` | Directory the job runs in. | - -Step order is load-bearing: build runs **before** `wp-env start` so pa11y sees compiled CSS/JS. `wp-env stop` uses `if: always()` so a failing pa11y run does not leak a Docker stack into the next job. - -## Individual workflows - -### `ci-build-artifact-gate.yml`: block committed build artifacts - -Fails a PR if it touches any file under the configured path prefixes (default: `assets/build/`). Pair it with `ci-build.yml` so the build output produced by CI is the only source of truth, never a stale tree committed by hand. - -**Default:** gate `assets/build/` in a flat repo. - -```yaml -jobs: - artifact-gate: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 -``` - -**Multiple gated paths:** - -```yaml -jobs: - artifact-gate: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 - with: - gated-paths: | - assets/build/ - dist/ - public/build/ -``` - -| Input | Type | Default | Description | -| ------------- | ------ | ----------------- | --------------------------------------------------------------------------------- | -| `gated-paths` | string | `"assets/build/"` | Newline-separated path prefixes whose contents must not be committed in a PR. | -| `working-dir` | string | `"."` | Directory the gated path prefixes are anchored under. | - -Only meaningful on `pull_request` events. On other triggers it logs a notice and exits 0 so the workflow stays inert outside PRs. The check compares `origin/..HEAD` with `--diff-filter=ACMR`, so deletions are ignored: removing a previously-committed artifact in the PR does not trip the gate. - -### `cd-split-composer-packages.yml`: split Composer packages to mirror repos - -Splits Composer-package subtrees out of one repository into standalone mirror repos, so Packagist can serve each package from its own repository. A `splitsh.json` (by default at the repo root) is the single source of truth — to add or remove a package, edit that file, never the workflow. - -`splitsh.json` lives in the **calling** repository (e.g. `wp-tooling`), not in this repo. As a reusable workflow, `actions/checkout` pulls the caller's repository by default, so the config is read from the caller's checkout — `config-file` is a path relative to that checkout, never the file's contents. - -`splitsh.json`: - -```json -{ - "organization": "rtCamp", - "subtrees": { - "wp-phpcs": "composer-packages/phpcs", - "wp-phpstan": "composer-packages/phpstan" - }, - "defaults": { - "branch": "main", - "user_name": "github-actions[bot]", - "user_email": "github-actions[bot]@users.noreply.github.com" - } -} -``` - -Caller — split on every `v*` tag push: - -```yaml -# .github/workflows/split.yml in the source repository -name: Split Composer Packages -on: - push: - tags: ["v*"] -jobs: - split: - uses: rtCamp/wp-shared-workflows/.github/workflows/cd-split-composer-packages.yml@v1 - with: - tag: ${{ github.ref_name }} - secrets: - split-token: ${{ secrets.SPLIT_TOKEN }} -``` - -The reusable workflow owns no trigger of its own — the caller decides when it runs. To also allow a manual smoke-test run (the `workflow_dispatch` path the standalone version had), add the trigger and pass the tag through. On a manual run `github.ref_name` is a **branch**, not a tag, so the dispatch input must win: - -```yaml -# .github/workflows/split.yml in the source repository -name: Split Composer Packages -on: - push: - tags: ["v*"] - workflow_dispatch: - inputs: - test_tag: - description: "Throwaway tag to push to mirrors (e.g. v0.0.0-test)" - required: true - default: "v0.0.0-test" -jobs: - split: - uses: rtCamp/wp-shared-workflows/.github/workflows/cd-split-composer-packages.yml@v1 - with: - # Manual run → use the dispatch input; tag push → the pushed tag. - tag: ${{ github.event.inputs.test_tag || github.ref_name }} - secrets: - split-token: ${{ secrets.SPLIT_TOKEN }} -``` - -| Input | Type | Default | Description | -| ------------- | ------ | ---------------- | ---------------------------------------------------------------------------------------- | -| `tag` | string | `""` | Tag to push to the mirror repos. When empty, falls back to the caller's `github.ref_name`. | -| `config-file` | string | `"splitsh.json"` | Path to the splitsh config file, relative to the repo root. | - -| Secret | Required | Description | -| ------------- | -------- | ------------------------------------------------------------------------------------------------------ | -| `split-token` | yes | Token (fine-grained PAT or GitHub App token) with `contents: write` on every mirror repo in the config. | - -The `subtrees` map accepts both the shorthand string form (`"mirror": "path/in/repo" `) and the object form (`"mirror": { "prefixes": [{ "from": "path" }] }`). Each subtree is force-pushed to its mirror in parallel with `fail-fast: false`, so one failing package does not abort the rest. A missing or empty config fails the run loudly. - -### `cd-built-branch.yml`: publish the built tree to a deploy branch - -Builds the project and force-pushes **source plus generated output** (Composer `vendor/`, compiled `assets/build/`) to a dedicated branch, for platforms that deploy from a git branch rather than an artifact. - -Two invariants make this safe to point a production environment at: - -- **The source branch never contains generated output.** Pair this workflow with `ci-build-artifact-gate.yml` on the *same* path list — whatever you gate, you publish. -- **The target branch is always one commit whose parent is the source commit.** So `git diff main..main-built` shows exactly the generated files and nothing else. - -> **Requirements.** The caller must grant `permissions: contents: write` — a called workflow can only reduce the caller's grant, never raise it. The target branch must allow force-pushes. And note that **pushes made with the default `GITHUB_TOKEN` do not trigger further workflow runs**; if something must fire on a push to the deploy branch, supply `push-token`. - -```yaml -# .github/workflows/publish-built-branch.yml in the consumer -name: Publish built branch -on: - push: - branches: [main] - workflow_dispatch: -permissions: - contents: write -jobs: - publish: - uses: rtCamp/wp-shared-workflows/.github/workflows/cd-built-branch.yml@v1 -``` - -That 12-line caller covers a single-plugin or single-theme repo: `targets` defaults to `[{"dir": "."}]`, and `vendor/` / `assets/build/` are inferred from the presence of `composer.json` and `package-lock.json`. - -| Input | Type | Default | Description | -| ----------------- | ------- | -------------------- | ---------------------------------------------------------------------------------------------- | -| `targets` | string | `[{"dir": "."}]` | JSON array of build **objects**. Each needs `dir`; may override `name`, `php-version`, `node-version`, `composer-flags`, `build-command`, `publish-paths`, `verify-paths`, `composer`, `node`, `optional`. Per-target `publish-paths`/`verify-paths` accept either a JSON array (`["vendor","dist"]`) or a newline string. | -| `target-branch` | string | `"main-built"` | Branch the built tree is force-pushed to. Must allow force-pushes. | -| `source-ref` | string | `""` | Commit/tag/branch to build. Empty uses the triggering commit. A full SHA rebuilds an older commit. | -| `publish-paths` | string | `""` | Newline-separated generated paths to publish, relative to each target's `dir`. Empty auto-resolves to `vendor/` (Composer targets) plus `assets/build/` (Node targets). | -| `verify-paths` | string | `""` | Newline-separated paths that must exist after the build. Files must exist; directories must be non-empty. Empty auto-resolves to `vendor/autoload.php` for Composer targets. | -| `node-version` | string | `"22"` | Default Node.js version, overridable per target. | -| `php-version` | string | `"8.3"` | Default PHP version, overridable per target. | -| `composer-flags` | string | `--no-dev …` | Flags passed to `composer install`. | -| `build-command` | string | `""` | Empty defaults to `npm run build:prod`. Only run for targets with a `package-lock.json`. | -| `commit-subject` | string | `""` | Subject of the published commit. Empty uses `build: publish built tree for `. | -| `allow-rewind` | boolean | `false` | Allow publishing a commit that is not a descendant of what the branch already publishes — a rollback, or a rebuild after the source branch was force-pushed. | -| `dry-run` | boolean | `false` | Build, verify and commit, but do not push. | -| `retention-days` | number | `3` | Days to keep the intermediate build tarballs. | - -| Secret | Required | Description | -| ---------------- | -------- | ---------------------------------------------------------------------------------------------- | -| `push-token` | no | Token with `contents: write` used for the push. Supply one when the push must trigger further workflows, or when a ruleset needs a bypass actor. | - -| Output | Description | -| --------------- | ---------------------------------------------------------------------- | -| `published` | `'true'` when a commit was pushed; `'false'` on a dry run. | -| `published-sha` | SHA of the commit created on the target branch. Empty on a dry run. | -| `source-sha` | Resolved source commit that was built — the published commit's parent. | -| `targets` | The resolved build matrix as compact JSON. | - -**Rollback** is a `workflow_dispatch` with `source-ref: ` **and** `allow-rewind: true`. Without the flag the dispatch is refused, since moving the deploy branch off a newer tree should be deliberate. Re-running an older run from the Actions UI does *not* roll back — a re-run cannot change these inputs, so it is indistinguishable from a run that lost a push race and it ends green without publishing. - -**Losing a push race is not a failure.** If two pushes land close together and the newer run publishes first, the older run finds the branch already ahead of it, logs a `::notice::` and ends **green** without pushing — the correct tree is already live. Only an explicit `source-ref` rollback errors without `allow-rewind`. - -Notes: - -- **Every run rebuilds and republishes every target.** The branch must always be a complete deployable tree, and each run resets it to the source commit — so a skipped target would simply be absent, not stale. Consequently: **do not put a `paths:` filter on the push trigger.** A filtered-out commit leaves the branch's parent behind, and those changes never reach the deploy branch. -- **A target's `dir` must exist, or the run fails** — a typo'd or removed path never silently shrinks the published tree. To list a plugin or theme that has not been scaffolded yet, mark it `"optional": true`; an absent optional target is skipped with a `::warning::` and listed in the run summary instead of failing the run. -- **`node_modules/` is never published**, and listing it in `publish-paths` is a hard error. Only the declared paths are staged, so anything an npm lifecycle script wrote elsewhere stays out of the branch. -- **Nested `.git` directories inside published paths are removed** before staging. A dependency installed from source leaves one, and `git add` would record it as a gitlink — publishing an empty directory instead of the package's files. -- If the repo uses `* text=auto` in `.gitattributes`, add `vendor/** -text`. Line-ending normalisation is applied at `git add` time and can corrupt binary assets that lack a `binary` attribute. -- The branch's history is rewritten on every run, so old trees are orphaned until GitHub's GC runs; server-side repo size grows over time. That is inherent to build-to-branch. -- Not part of `wp-cd.yml`. That orchestrator is tag-and-artifact driven; this is push-and-self-building, and combining them would build the project twice. - -**Setup:** point your branch-deploy platform at `main-built`, keep PR CI on `main`, and never commit to `main-built` by hand. - -### `ci-test-build-artifact.yml`: boot the built artifact - -A green `ci-build.yml` run only proves the build did not crash — not that the packaged output installs and boots. This workflow downloads the artifact, boots a real WordPress in [`@wordpress/env`](https://github.com/WordPress/gutenberg/tree/trunk/packages/env), activates the plugin/theme, and runs `wp doctor`. It catches PHP files referenced but never copied into the bundle, an over-eager `.distignore`, and path-cased files that break on Linux. Pair it with `ci-build.yml`. - -**Plugin:** build with an uploaded artifact, then boot it. - -```yaml -jobs: - build: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 - with: - upload-artifact: true - artifact-name: "plugin-dist" - artifact-path: "dist/my-plugin/" # a complete installable plugin dir, not bare build/ - test-artifact: - needs: build - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-build-artifact.yml@v1 - with: - artifact-name: "plugin-dist" - slug: "my-plugin" -``` - -**Theme:** install under `wp-content/themes` and activate as a theme. - -```yaml -jobs: - test-artifact: - needs: build - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-build-artifact.yml@v1 - with: - artifact-name: "theme-dist" - slug: "my-theme" - install-path: "wp-content/themes" ``` -| Input | Type | Default | Description | -| --------------- | ------ | --------------------- | ------------------------------------------------------------------------------------------------- | -| `artifact-name` | string | _required_ | Artifact to download. Must match the `artifact-name` uploaded by `ci-build.yml` in the same run. | -| `slug` | string | _required_ | Plugin or theme directory slug to activate. | -| `node-version` | string | `"22"` | Node.js version used to run `@wordpress/env`. | -| `php-version` | string | `"8.3"` | PHP version wp-env boots with. | -| `wp-version` | string | `"latest"` | WordPress version wp-env boots with. `latest` uses the newest stable release. | -| `install-path` | string | `"wp-content/plugins"`| Destination under the WordPress root. A path ending in `themes` activates a theme, else a plugin. | -| `smoke-script` | string | `""` | Optional path inside the artifact to a shell script, run in the container after activation. | -| `doctor-ignore-checks` | string | `"constant-wp-debug-falsy"` | Comma-separated `wp doctor` check names excluded from the error gate (production-oriented checks that wp-env's dev defaults always trip). | -| `working-dir` | string | `"."` | Directory the job runs in. wp-env runs here (so a `.wp-env.json` in this directory is picked up) and the artifact is downloaded into it. | +That is a complete CI setup: lint CSS/JS/PHP, Jest, PHPUnit, and build — each job gated on what +actually changed, so a docs-only PR runs almost nothing. -`wp doctor check --all` includes production-oriented checks that a dev wp-env always trips — notably `constant-wp-debug-falsy`, because wp-env enables `WP_DEBUG` by default. Those are excluded from the gate via `doctor-ignore-checks` (extend the comma-separated list if your wp-env config trips others); every other `error`-severity check still fails the build. +## Workflows -The run writes a `.wp-env.override.json` into `working-dir`, **overwriting any existing file of that name**. The override clears `plugins` and `themes` and mounts only the downloaded artifact, so the boot tests the packaged output rather than the working tree that a consumer's own `.wp-env.json` would map. +Each workflow declares its inputs, secrets and outputs in its own `workflow_call` block, and GitHub +renders those descriptions when you wire up a caller. Every example is a complete consumer workflow +you can copy as-is. -The artifact must be a **complete installable plugin/theme directory** (main PHP file plus assets), so point `ci-build.yml`'s `artifact-path` at a packaged dist directory, not bare `build/`. `actions/download-artifact` restores the uploaded directory contents uncompressed, so there is no unzip step. The workflow writes a `.wp-env.override.json` that pins `phpVersion`/`core` and mounts **only** the downloaded artifact — it clears `plugins`/`themes` from the consumer's `.wp-env.json` so the test reflects the packaged output in isolation, not the dev source tree. It then runs `wp activate ` and `wp doctor check --all` (failing only on `error` severity), and always runs `wp-env stop` so no container leaks into the next job. +### CI -### `cd-github-release.yml`: GitHub Release +| Workflow | What it does | Example | +|---|---|---| +| [`wp-ci.yml`](.github/workflows/wp-ci.yml) | CI orchestrator. One call per unit; routes to the right jobs for `project-type` | [example](examples/wp-ci.yml) | +| [`ci-detect-changes.yml`](.github/workflows/ci-detect-changes.yml) | Buckets changed files, exposes per-type counts and file lists | [example](examples/ci-detect-changes.yml) | +| [`ci-lint-css.yml`](.github/workflows/ci-lint-css.yml) | Stylelint | [example](examples/ci-lint-css.yml) | +| [`ci-lint-js.yml`](.github/workflows/ci-lint-js.yml) | ESLint + optional `package.json` validation | [example](examples/ci-lint-js.yml) | +| [`ci-lint-php.yml`](.github/workflows/ci-lint-php.yml) | PHPCS with `cs2pr` annotations + optional PHPStan | [example](examples/ci-lint-php.yml) | +| [`ci-test-js.yml`](.github/workflows/ci-test-js.yml) | Jest | [example](examples/ci-test-js.yml) | +| [`ci-test-php.yml`](.github/workflows/ci-test-php.yml) | PHPUnit, via `@wordpress/env` or standalone | [example](examples/ci-test-php.yml) | +| [`ci-test-a11y.yml`](.github/workflows/ci-test-a11y.yml) | pa11y-ci WCAG2AA | [example](examples/ci-test-a11y.yml) | +| [`ci-build.yml`](.github/workflows/ci-build.yml) | Production build + optional artifact upload | [example](examples/ci-build.yml) | +| [`ci-build-artifact-gate.yml`](.github/workflows/ci-build-artifact-gate.yml) | Fails a PR that commits build output | [example](examples/ci-build-artifact-gate.yml) | +| [`ci-test-build-artifact.yml`](.github/workflows/ci-test-build-artifact.yml) | Boots the packaged artifact in real WordPress | [example](examples/ci-test-build-artifact.yml) | -On a `v*.*.*` tag push, publishes a GitHub Release: the body is pulled from the matching `CHANGELOG.md` section, the named build artifact is attached, and `draft` / `prerelease` are honoured. Uses the `gh` CLI (no third-party action). Usually called by `wp-cd.yml`, but works standalone. +### CD -```yaml -# .github/workflows/release.yml in the consumer -name: Release -on: - push: - tags: - - "v*.*.*" -jobs: - build: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 - with: - upload-artifact: true - artifact-name: "release" - github-release: - needs: build - permissions: - contents: write - uses: rtCamp/wp-shared-workflows/.github/workflows/cd-github-release.yml@v1 - with: - tag: ${{ github.ref_name }} - artifact-name: "release" -``` - -| Input | Type | Default | Description | -| ---------------- | ------- | ---------------- | --------------------------------------------------------------------------------- | -| `tag` | string | _(required)_ | Tag that triggered the release, e.g. `v1.2.3`. | -| `artifact-name` | string | _(required)_ | Build artifact to download and attach. Must match the producing job's name. | -| `changelog-path` | string | `"CHANGELOG.md"` | Changelog whose matching section becomes the release body. | -| `draft` | boolean | `false` | Create the Release as a draft. | -| `prerelease` | boolean | `false` | Mark the Release as a prerelease. | -| `working-dir` | string | `"."` | Prefixes `changelog-path`. A **path prefix, not a working directory** — the attached files come from the artifact, which the build already scoped. | - -The calling job must grant `permissions: contents: write`. The artifact must be produced **in the same workflow run** — `download-artifact` only sees the current run's artifacts. The changelog heading must contain the tag's version (`## v1.2.3` or `## [1.2.3]`, with an optional trailing date); `## Unreleased` is never matched. A missing or empty section fails the workflow rather than publishing a Release with no notes. - -### `cd-wp-org.yml`: WordPress.org deploy - -Deploys a plugin to the [WordPress.org plugin directory](https://plugins.svn.wordpress.org/) over SVN on a release tag, wrapping the standard [`10up/action-wordpress-plugin-deploy`](https://github.com/10up/action-wordpress-plugin-deploy) (SHA-pinned). Before deploying it fails fast unless `readme.txt`'s `Stable tag` matches the release tag, then syncs the build artifact to `trunk/` + `tags//` and the `assets-path` directory to SVN `/assets/`. `dry-run` runs everything except the final commit. - -```yaml -# .github/workflows/deploy-wp-org.yml in the consumer -name: Deploy to WordPress.org -on: - push: - tags: ["v*.*.*"] -permissions: - contents: read -jobs: - build: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 - with: - upload-artifact: true - artifact-name: wp-org-build - # The artifact root must contain readme.txt, so point artifact-path at a - # packaged plugin dir (not bare build/). Adjust build-command to whatever - # produces that dir in your repo. - build-command: "npm run build:prod" - artifact-path: "dist/my-plugin/" - deploy: - needs: build - uses: rtCamp/wp-shared-workflows/.github/workflows/cd-wp-org.yml@v1 - with: - slug: my-plugin - tag: ${{ github.ref_name }} - artifact-name: wp-org-build - secrets: - WP_ORG_USERNAME: ${{ secrets.WP_ORG_USERNAME }} - WP_ORG_PASSWORD: ${{ secrets.WP_ORG_PASSWORD }} -``` +Each is opt-in — call the ones you need from your own release trigger. -| Input | Type | Default | Description | -| --------------- | ------- | ------------------ | ---------------------------------------------------------------------------- | -| `slug` | string | _(required)_ | **Required.** Plugin slug on wordpress.org. | -| `tag` | string | _(required)_ | **Required.** Release tag, e.g. `v1.2.3`. A leading `v` is stripped. | -| `artifact-name` | string | _(required)_ | **Required.** Build artifact to download and deploy (must match the producer). | -| `assets-path` | string | `".wordpress-org"` | Local directory mapped to SVN `/assets/`. Skipped if absent. | -| `dry-run` | boolean | `false` | Run the full deploy except the final SVN commit. | -| `working-dir` | string | `"."` | Prefixes `assets-path`. A **path prefix, not a working directory** — the deployed files come from the artifact, which the build already scoped. | +| Workflow | What it does | Example | +|---|---|---| +| [`cd-github-release.yml`](.github/workflows/cd-github-release.yml) | GitHub Release from a tag + artifact, notes from `CHANGELOG.md` | [example](examples/cd-github-release.yml) | +| [`cd-wp-org.yml`](.github/workflows/cd-wp-org.yml) | WordPress.org SVN deploy | [example](examples/cd-wp-org.yml) | +| [`cd-s3.yml`](.github/workflows/cd-s3.yml) | S3 upload + optional CloudFront invalidation | [example](examples/cd-s3.yml) | +| [`cd-built-branch.yml`](.github/workflows/cd-built-branch.yml) | Force-pushes source + generated output to a deploy branch | [example](examples/cd-built-branch.yml) | -| Secret | Required | Description | -| ----------------- | -------- | -------------------------------------------------------------------- | -| `WP_ORG_USERNAME` | yes | WordPress.org account username with commit access to the plugin. | -| `WP_ORG_PASSWORD` | yes | WordPress.org account password. | +### Maintenance -Add the secrets under the consumer repo's **Settings → Secrets and variables → Actions**, then pass them through as shown above (reusable-workflow secrets are not inherited automatically). +| Workflow | What it does | Example | +|---|---|---| +| [`version-monitor.yml`](.github/workflows/version-monitor.yml) | Monthly version-bump check that opens a draft PR | [example](examples/version-monitor.yml) | -Notes: +## Versioning -- **Same-run artifact** — `actions/download-artifact` only sees the current run's artifacts, so build and deploy must run in the same workflow (`deploy` `needs: build`). -- **Assets** are read from the *checked-out repo* at `assets-path` (not from the artifact); the build artifact supplies the plugin files for `trunk/`. -- **`Stable tag`** in `readme.txt` must equal the tag with any leading `v` removed (`v1.2.3` → `1.2.3`). Plugins using `Stable tag: trunk` are not supported by the strict check. -- **Immutable tags** — WordPress.org SVN tags are release snapshots; the deploy action errors (non-zero) if `tags/` already exists, so re-deploying the same version fails rather than overwriting it. -- **`dry-run`** still checks out the live WP.org SVN repo for the slug; it only skips the commit, so exercising it end to end needs a real published slug. +Pin a version tag. `@v1` and `@v1.2` are aliases that move forward to compatible releases; an exact +`@v1.2.3` never changes. -### `cd-s3.yml`: S3 deploy +| Pin | Resolves to | +|---|---| +| `@v1` | Latest `v1.x.y` — recommended | +| `@v1.2` | Latest patch of the `v1.2` line | +| `@v1.2.3` | One exact release | -Distributes a private / customer plugin by uploading the build artifact to an S3 bucket on a release tag — a versioned object (`.zip`) plus a rolling `latest.zip` that always overwrites — and optionally invalidates a CloudFront distribution so the new `latest.zip` is served immediately. Uses the official [`aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials) (SHA-pinned) and the preinstalled AWS CLI. +Within a major version, inputs are only ever added, and always with a default. Removing or renaming +an input, or making one required, ships as a new major. -```yaml -# .github/workflows/deploy-s3.yml in the consumer -name: Deploy to S3 -on: - push: - tags: ["v*.*.*"] -permissions: - contents: read -jobs: - build: - uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 - with: - upload-artifact: true - artifact-name: s3-build - # build-command / artifact-path must produce exactly one .zip in the artifact. - deploy: - needs: build - uses: rtCamp/wp-shared-workflows/.github/workflows/cd-s3.yml@v1 - with: - tag: ${{ github.ref_name }} - artifact-name: s3-build - bucket: my-customer-bucket - prefix: "plugins/my-plugin/" - # cloudfront-distribution-id: "E123ABC" # optional - secrets: - AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} - AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} -``` - -| Input | Type | Default | Description | -| ---------------------------- | ------ | ------------- | ------------------------------------------------------------------------ | -| `tag` | string | _(required)_ | **Required.** Release tag; the versioned object is keyed `.zip`. | -| `artifact-name` | string | _(required)_ | **Required.** Build artifact to download (must match the producer). | -| `bucket` | string | _(required)_ | **Required.** Target S3 bucket name. | -| `prefix` | string | `""` | Optional S3 key prefix, e.g. `plugins/myplugin/` (include the trailing slash). | -| `cloudfront-distribution-id` | string | `""` | If set, invalidate `/*` on this distribution after upload. | -| `region` | string | `"us-east-1"` | AWS region of the bucket. | +## Contributing -| Secret | Required | Description | -| ----------------------- | -------- | -------------------------------- | -| `AWS_ACCESS_KEY_ID` | yes | AWS access key id (see IAM below). | -| `AWS_SECRET_ACCESS_KEY` | yes | AWS secret access key. | +Conventions live in [AGENTS.md](AGENTS.md); the PR process is in [CONTRIBUTING.md](CONTRIBUTING.md). -**Required IAM permissions.** The credentials need write access to the prefix, plus -`cloudfront:CreateInvalidation` only if you pass a distribution id: - -```json -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "s3:PutObject", - "Resource": "arn:aws:s3:::my-customer-bucket/plugins/my-plugin/*" - }, - { - "Effect": "Allow", - "Action": "cloudfront:CreateInvalidation", - "Resource": "arn:aws:cloudfront:::distribution/E123ABC" - } - ] -} -``` - -Notes: - -- **Same-run artifact** — `actions/download-artifact` only sees the current run's artifacts, so build and deploy must run in the same workflow (`deploy` `needs: build`), and the artifact must contain exactly one `.zip`. -- **Bucket region** should match `region`; otherwise `aws s3 cp` issues a redirect and runs slower. -- **Pre-existing infra** — the bucket and (if used) the CloudFront distribution must already exist; this workflow does not create or configure them. -- **`latest.zip` is CloudFront-cached** — the invalidation step is what makes "always-latest" actually serve the new build. +Every example is verified in CI by [`bin/check-workflows.sh`](bin/check-workflows.sh): the `with:` +and `secrets:` keys must exist on the workflow being called, every required input must be supplied, +and the ref must be `@v1`. An example cannot silently drift out of date. ## License -GPL-2.0-or-later +GPL-2.0-or-later. See [LICENSE](LICENSE). + +

+ rtCamp +

diff --git a/bin/check-workflows.sh b/bin/check-workflows.sh new file mode 100755 index 0000000..4d796df --- /dev/null +++ b/bin/check-workflows.sh @@ -0,0 +1,159 @@ +#!/usr/bin/env bash +# +# Validates this repo's own contract: +# 1. Every reusable workflow has exactly one caller example, and vice versa. +# 2. Every `uses:` in an example resolves to a workflow in this repo, pinned at @v1. +# 3. Every `with:` / `secrets:` key an example passes is actually declared by that +# workflow, and every required input/secret is supplied. +# 4. Repo conventions: kebab-case input names, every input documented, every step named. +# +# Requires: yq (v4) and jq. Both are preinstalled on GitHub's ubuntu runners; +# locally, `brew install yq jq`. +# Run from anywhere: bin/check-workflows.sh + +set -euo pipefail + +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$ROOT" + +WORKFLOW_DIR=".github/workflows" +EXAMPLE_DIR="examples" +SELF_CHECK="ci-self-check.yml" +EXPECTED_REF="v1" +USES_PREFIX="rtCamp/wp-shared-workflows/.github/workflows" + +fail=0 + +err() { + echo "::error::$*" + fail=1 +} + +for tool in yq jq; do + command -v "$tool" >/dev/null 2>&1 || { + echo "$tool is required but not installed — brew install yq jq" >&2 + exit 127 + } +done + +as_json() { yq -o=json '.' "$1"; } + +# --- 1. one example per workflow, one workflow per example ------------------- + +for wf in "$WORKFLOW_DIR"/*.yml; do + base="$(basename "$wf")" + [ "$base" = "$SELF_CHECK" ] && continue + [ -f "$EXAMPLE_DIR/$base" ] || + err "$wf has no caller example — create $EXAMPLE_DIR/$base" +done + +for ex in "$EXAMPLE_DIR"/*.yml; do + base="$(basename "$ex")" + [ -f "$WORKFLOW_DIR/$base" ] || + err "$ex has no matching workflow at $WORKFLOW_DIR/$base — rename or remove it" +done + +# --- 2 + 3. every example call matches the workflow it calls ----------------- + +for ex in "$EXAMPLE_DIR"/*.yml; do + ex_json="$(as_json "$ex")" + + while IFS= read -r job; do + [ -n "$job" ] || continue + uses="$(jq -r --arg j "$job" '.jobs[$j].uses' <<<"$ex_json")" + + case "$uses" in + "$USES_PREFIX"/*) ;; + *) + err "$ex job '$job' calls '$uses'; examples must call $USES_PREFIX/.yml@$EXPECTED_REF" + continue + ;; + esac + + rest="${uses#"$USES_PREFIX"/}" + wf_name="${rest%@*}" + ref="${rest##*@}" + + [ "$ref" = "$EXPECTED_REF" ] || + err "$ex job '$job' pins @$ref; examples must pin @$EXPECTED_REF so a consumer can paste them as-is" + + if [ ! -f "$WORKFLOW_DIR/$wf_name" ]; then + err "$ex job '$job' calls '$wf_name', which does not exist in $WORKFLOW_DIR" + continue + fi + + wf_json="$(as_json "$WORKFLOW_DIR/$wf_name")" + + declared_inputs="$(jq -r '(.["on"].workflow_call.inputs // {}) | keys[]' <<<"$wf_json")" + required_inputs="$(jq -r '(.["on"].workflow_call.inputs // {}) | to_entries[] + | select(.value.required == true) | .key' <<<"$wf_json")" + declared_secrets="$(jq -r '(.["on"].workflow_call.secrets // {}) | keys[]' <<<"$wf_json")" + required_secrets="$(jq -r '(.["on"].workflow_call.secrets // {}) | to_entries[] + | select(.value.required == true) | .key' <<<"$wf_json")" + + given_inputs="$(jq -r --arg j "$job" '(.jobs[$j].with // {}) + | if type == "object" then keys[] else empty end' <<<"$ex_json")" + given_secrets="$(jq -r --arg j "$job" '(.jobs[$j].secrets // {}) + | if type == "object" then keys[] else empty end' <<<"$ex_json")" + + while IFS= read -r key; do + [ -n "$key" ] || continue + grep -qxF "$key" <<<"$declared_inputs" || + err "$ex job '$job' passes input '$key', which $wf_name does not declare" + done <<<"$given_inputs" + + while IFS= read -r key; do + [ -n "$key" ] || continue + grep -qxF "$key" <<<"$declared_secrets" || + err "$ex job '$job' passes secret '$key', which $wf_name does not declare" + done <<<"$given_secrets" + + while IFS= read -r key; do + [ -n "$key" ] || continue + grep -qxF "$key" <<<"$given_inputs" || + err "$ex job '$job' omits required input '$key' of $wf_name" + done <<<"$required_inputs" + + while IFS= read -r key; do + [ -n "$key" ] || continue + grep -qxF "$key" <<<"$given_secrets" || + err "$ex job '$job' omits required secret '$key' of $wf_name" + done <<<"$required_secrets" + + done < <(jq -r '(.jobs // {}) | to_entries[] | select(.value.uses != null) | .key' <<<"$ex_json") +done + +# --- 4. repo conventions ----------------------------------------------------- + +for wf in "$WORKFLOW_DIR"/*.yml; do + base="$(basename "$wf")" + wf_json="$(as_json "$wf")" + + while IFS= read -r key; do + [ -n "$key" ] || continue + [[ "$key" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]] || + err "$base input '$key' is not kebab-case" + done < <(jq -r '(.["on"].workflow_call.inputs // {}) | keys[]' <<<"$wf_json") + + while IFS= read -r key; do + [ -n "$key" ] || continue + err "$base input '$key' has no description" + done < <(jq -r '(.["on"].workflow_call.inputs // {}) | to_entries[] + | select((.value.description // "") == "") | .key' <<<"$wf_json") + + while IFS= read -r loc; do + [ -n "$loc" ] || continue + err "$base has an unnamed step at $loc" + done < <(jq -r '(.jobs // {}) | to_entries[] as $j + | ($j.value.steps // []) | to_entries[] + | select((.value.name // "") == "") + | "job \($j.key) step #\(.key)"' <<<"$wf_json") +done + +if [ "$fail" -ne 0 ]; then + echo "" + echo "Workflow/example contract check FAILED." >&2 + exit 1 +fi + +echo "Workflow/example contract check passed." diff --git a/examples/cd-built-branch.yml b/examples/cd-built-branch.yml new file mode 100644 index 0000000..cc3f171 --- /dev/null +++ b/examples/cd-built-branch.yml @@ -0,0 +1,37 @@ +name: Publish built branch + +on: + push: + branches: + - main + workflow_dispatch: + inputs: + source-ref: + description: "Commit or ref to rebuild and republish. Empty builds the current branch tip." + type: string + default: "" + allow-rewind: + description: "Permit publishing a source ref older than what is already on the target branch." + type: boolean + default: false + +permissions: + contents: read + +jobs: + publish: + permissions: + contents: write + uses: rtCamp/wp-shared-workflows/.github/workflows/cd-built-branch.yml@v1 + with: + target-branch: main-built + source-ref: ${{ inputs.source-ref || '' }} + allow-rewind: ${{ inputs.allow-rewind || false }} + node-version: "22" + php-version: "8.3" + targets: >- + [ + {"dir": "plugins/acme-blocks", "publish-paths": ["vendor", "assets/build"]}, + {"dir": "plugins/acme-crm", "publish-paths": ["vendor"]}, + {"dir": "themes/acme-theme", "publish-paths": ["assets/build"], "optional": true} + ] diff --git a/examples/cd-github-release.yml b/examples/cd-github-release.yml new file mode 100644 index 0000000..6192389 --- /dev/null +++ b/examples/cd-github-release.yml @@ -0,0 +1,31 @@ +name: Release + +on: + push: + tags: + - "v*.*.*" + +permissions: + contents: read + +jobs: + build: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 + with: + working-dir: plugins/acme-blocks + install-composer-deps: true + build-command: npm run build:prod && npm run package + upload-artifact: true + artifact-name: acme-blocks + artifact-path: dist/acme-blocks + + release: + needs: build + permissions: + contents: write + uses: rtCamp/wp-shared-workflows/.github/workflows/cd-github-release.yml@v1 + with: + tag: ${{ github.ref_name }} + artifact-name: acme-blocks + working-dir: plugins/acme-blocks + changelog-path: CHANGELOG.md diff --git a/examples/cd-s3.yml b/examples/cd-s3.yml new file mode 100644 index 0000000..088de8b --- /dev/null +++ b/examples/cd-s3.yml @@ -0,0 +1,34 @@ +name: Deploy to S3 + +on: + push: + tags: + - "v*.*.*" + +permissions: + contents: read + +jobs: + build: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 + with: + working-dir: plugins/acme-crm + install-composer-deps: true + build-command: npm run build:prod && npm run package + upload-artifact: true + artifact-name: acme-crm + artifact-path: dist/acme-crm.zip + + deploy: + needs: build + uses: rtCamp/wp-shared-workflows/.github/workflows/cd-s3.yml@v1 + with: + tag: ${{ github.ref_name }} + artifact-name: acme-crm + bucket: acme-plugin-releases + prefix: acme-crm/ + region: ap-south-1 + cloudfront-distribution-id: E1ACMEDISTRIBUTION + secrets: + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} diff --git a/examples/cd-wp-org.yml b/examples/cd-wp-org.yml new file mode 100644 index 0000000..d61ca32 --- /dev/null +++ b/examples/cd-wp-org.yml @@ -0,0 +1,34 @@ +name: Deploy to WordPress.org + +on: + push: + tags: + - "v*.*.*" + +permissions: + contents: read + +jobs: + build: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 + with: + working-dir: plugins/acme-blocks + install-composer-deps: true + build-command: npm run build:prod && npm run package + upload-artifact: true + artifact-name: acme-blocks + artifact-path: dist/acme-blocks + + deploy: + needs: build + uses: rtCamp/wp-shared-workflows/.github/workflows/cd-wp-org.yml@v1 + with: + slug: acme-blocks + tag: ${{ github.ref_name }} + artifact-name: acme-blocks + working-dir: plugins/acme-blocks + assets-path: .wordpress-org + dry-run: false + secrets: + WP_ORG_USERNAME: ${{ secrets.WP_ORG_USERNAME }} + WP_ORG_PASSWORD: ${{ secrets.WP_ORG_PASSWORD }} diff --git a/examples/ci-build-artifact-gate.yml b/examples/ci-build-artifact-gate.yml new file mode 100644 index 0000000..74f4b9f --- /dev/null +++ b/examples/ci-build-artifact-gate.yml @@ -0,0 +1,16 @@ +name: Block committed build artifacts + +on: + pull_request: + +permissions: + contents: read + +jobs: + artifact-gate: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build-artifact-gate.yml@v1 + with: + working-dir: plugins/acme-blocks + gated-paths: | + assets/build/ + dist/ diff --git a/examples/ci-build.yml b/examples/ci-build.yml new file mode 100644 index 0000000..7a085a4 --- /dev/null +++ b/examples/ci-build.yml @@ -0,0 +1,25 @@ +name: Build + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +jobs: + build: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 + with: + working-dir: plugins/acme-blocks + install-node-deps: true + install-composer-deps: true + node-version: "22" + php-version: "8.3" + build-command: npm run build:prod + upload-artifact: true + artifact-name: acme-blocks + artifact-path: dist/acme-blocks + retention-days: 7 diff --git a/examples/ci-detect-changes.yml b/examples/ci-detect-changes.yml new file mode 100644 index 0000000..93d79e0 --- /dev/null +++ b/examples/ci-detect-changes.yml @@ -0,0 +1,30 @@ +name: Detect changes + +on: + pull_request: + +permissions: + contents: read + +jobs: + detect: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-detect-changes.yml@v1 + with: + working-dir: plugins/acme-blocks + ignore-paths: '(^|/)docs/|\.md$' + + lint-php: + needs: detect + if: needs.detect.outputs.php-count != '0' + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-php.yml@v1 + with: + working-dir: plugins/acme-blocks + changed-files: ${{ needs.detect.outputs.php-files }} + + lint-js: + needs: detect + if: needs.detect.outputs.js-count != '0' + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-js.yml@v1 + with: + working-dir: plugins/acme-blocks + changed-files: ${{ needs.detect.outputs.js-files }} diff --git a/examples/ci-lint-css.yml b/examples/ci-lint-css.yml new file mode 100644 index 0000000..ae564f2 --- /dev/null +++ b/examples/ci-lint-css.yml @@ -0,0 +1,15 @@ +name: Lint CSS + +on: + pull_request: + +permissions: + contents: read + +jobs: + lint-css: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-css.yml@v1 + with: + working-dir: plugins/acme-blocks + node-version: "22" + lint-command: npm run lint:css diff --git a/examples/ci-lint-js.yml b/examples/ci-lint-js.yml new file mode 100644 index 0000000..af4a75a --- /dev/null +++ b/examples/ci-lint-js.yml @@ -0,0 +1,16 @@ +name: Lint JS + +on: + pull_request: + +permissions: + contents: read + +jobs: + lint-js: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-js.yml@v1 + with: + working-dir: plugins/acme-blocks + node-version: "22" + lint-command: npm run lint:js + validate-package-json: true diff --git a/examples/ci-lint-php.yml b/examples/ci-lint-php.yml new file mode 100644 index 0000000..d80dd80 --- /dev/null +++ b/examples/ci-lint-php.yml @@ -0,0 +1,17 @@ +name: Lint PHP + +on: + pull_request: + +permissions: + contents: read + +jobs: + lint-php: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-lint-php.yml@v1 + with: + working-dir: plugins/acme-blocks + php-version: "8.3" + enable-phpstan: true + phpstan-level: "5" + validate-composer: true diff --git a/examples/ci-test-a11y.yml b/examples/ci-test-a11y.yml new file mode 100644 index 0000000..fd96aba --- /dev/null +++ b/examples/ci-test-a11y.yml @@ -0,0 +1,20 @@ +name: Test accessibility + +on: + pull_request: + types: + - labeled + - synchronize + +permissions: + contents: read + +jobs: + test-a11y: + if: contains(github.event.pull_request.labels.*.name, 'Run a11y') + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-a11y.yml@v1 + with: + working-dir: themes/acme-theme + node-version: "22" + build-command: npm run build:prod + test-command: npm run test:a11y diff --git a/examples/ci-test-build-artifact.yml b/examples/ci-test-build-artifact.yml new file mode 100644 index 0000000..a1a0dc3 --- /dev/null +++ b/examples/ci-test-build-artifact.yml @@ -0,0 +1,29 @@ +name: Test build artifact + +on: + pull_request: + +permissions: + contents: read + +jobs: + build: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-build.yml@v1 + with: + working-dir: plugins/acme-blocks + install-composer-deps: true + build-command: npm run build:prod && npm run package + upload-artifact: true + artifact-name: acme-blocks + artifact-path: dist/acme-blocks + + test-build-artifact: + needs: build + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-build-artifact.yml@v1 + with: + artifact-name: acme-blocks + slug: acme-blocks + working-dir: plugins/acme-blocks + php-version: "8.3" + wp-version: latest + install-path: wp-content/plugins diff --git a/examples/ci-test-js.yml b/examples/ci-test-js.yml new file mode 100644 index 0000000..e541cc0 --- /dev/null +++ b/examples/ci-test-js.yml @@ -0,0 +1,16 @@ +name: Test JS + +on: + pull_request: + +permissions: + contents: read + +jobs: + test-js: + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-js.yml@v1 + with: + working-dir: plugins/acme-blocks + node-version: "22" + test-command: npm run test:js -- --ci + enable-cache: true diff --git a/examples/ci-test-php.yml b/examples/ci-test-php.yml new file mode 100644 index 0000000..3e335cb --- /dev/null +++ b/examples/ci-test-php.yml @@ -0,0 +1,22 @@ +name: Test PHP + +on: + pull_request: + +permissions: + contents: read + +jobs: + test-php: + name: PHP ${{ matrix.php-version }} / WP ${{ matrix.wp-version }} + strategy: + fail-fast: false + matrix: + php-version: ["8.2", "8.3", "8.4"] + wp-version: ["6.7", "6.8"] + uses: rtCamp/wp-shared-workflows/.github/workflows/ci-test-php.yml@v1 + with: + working-dir: plugins/acme-blocks + php-version: ${{ matrix.php-version }} + wp-version: ${{ matrix.wp-version }} + use-wp-env: true diff --git a/examples/version-monitor.yml b/examples/version-monitor.yml new file mode 100644 index 0000000..dde0f18 --- /dev/null +++ b/examples/version-monitor.yml @@ -0,0 +1,20 @@ +name: Version monitor + +on: + schedule: + - cron: "0 3 1 * *" + workflow_dispatch: + +permissions: + contents: read + +jobs: + version-monitor: + permissions: + contents: write + pull-requests: write + uses: rtCamp/wp-shared-workflows/.github/workflows/version-monitor.yml@v1 + with: + base-branch: main + pr-label: version-monitor + pr-assignees: acme-maintainer diff --git a/examples/wp-ci.yml b/examples/wp-ci.yml new file mode 100644 index 0000000..98ce059 --- /dev/null +++ b/examples/wp-ci.yml @@ -0,0 +1,42 @@ +name: CI + +on: + pull_request: + types: + - opened + - synchronize + - reopened + - ready_for_review + push: + branches: + - main + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + ci: + name: ${{ matrix.working-dir }} + strategy: + fail-fast: false + matrix: + include: + - working-dir: plugins/acme-blocks + project-type: plugin + - working-dir: plugins/acme-crm + project-type: plugin + - working-dir: themes/acme-theme + project-type: theme + uses: rtCamp/wp-shared-workflows/.github/workflows/wp-ci.yml@v1 + with: + project-type: ${{ matrix.project-type }} + working-dir: ${{ matrix.working-dir }} + enable-phpstan: true + php-versions: '["8.2", "8.3", "8.4"]' + wp-versions: '["6.7", "6.8"]' + gated-paths: assets/build/ + build-artifact-path: dist/ From 575e48fd12552068bc98ba67b84d4b5f1dc15d33 Mon Sep 17 00:00:00 2001 From: Aditya Singh <92062352+Adi-ty@users.noreply.github.com> Date: Tue, 29 Sep 2026 11:46:05 +0530 Subject: [PATCH 41/43] fix(ci): route caller inputs through env and fix release/cache handling per review (#34) * fix(ci): route caller inputs through env and fix release/cache handling per review * fix(ci): distinguish archive assets and order superseded summary * fix(ci): restrict release slug to a safe filename charset --- .github/workflows/cd-built-branch.yml | 24 ++++++-- .github/workflows/cd-github-release.yml | 73 ++++++++++++++++++++++--- .github/workflows/ci-build.yml | 13 ++++- .github/workflows/ci-lint-css.yml | 3 +- .github/workflows/ci-lint-js.yml | 3 +- .github/workflows/ci-lint-php.yml | 36 ++++++++---- .github/workflows/ci-self-check.yml | 2 +- .github/workflows/ci-test-a11y.yml | 10 +++- .github/workflows/ci-test-js.yml | 23 ++++++-- .github/workflows/ci-test-php.yml | 13 ++++- AGENTS.md | 38 +++++++++++-- CHANGELOG.md | 6 ++ CONTRIBUTING.md | 2 +- bin/check-workflows.sh | 14 ++++- 14 files changed, 214 insertions(+), 46 deletions(-) diff --git a/.github/workflows/cd-built-branch.yml b/.github/workflows/cd-built-branch.yml index f69eb58..fe6c83d 100644 --- a/.github/workflows/cd-built-branch.yml +++ b/.github/workflows/cd-built-branch.yml @@ -90,10 +90,12 @@ on: required: false outputs: published: - description: "'true' when a commit was pushed to the target branch, 'false' on a dry run." + description: >- + 'true' when this run pushed a commit to the target branch; 'false' on a dry run, or when a + newer run already published a descendant and this one stood down. value: ${{ jobs.publish.outputs.published }} published-sha: - description: "SHA of the commit created on the target branch. Empty on a dry run." + description: "SHA this run pushed to the target branch. Empty whenever no push happened." value: ${{ jobs.publish.outputs.published-sha }} source-sha: description: "Resolved source commit that was built. This is the published commit's parent." @@ -333,7 +335,13 @@ jobs: - name: Install Composer dependencies if: ${{ matrix.composer == 'true' }} - run: composer install ${{ matrix.composer-flags }} + shell: bash + env: + COMPOSER_FLAGS: ${{ matrix.composer-flags }} + run: | + set -euo pipefail + read -r -a composer_args <<< "$COMPOSER_FLAGS" || true + composer install "${composer_args[@]}" - name: Install npm dependencies if: ${{ matrix.node == 'true' }} @@ -341,7 +349,10 @@ jobs: - name: Build production assets if: ${{ matrix.node == 'true' }} - run: ${{ matrix.build-command }} + shell: bash + env: + BUILD_COMMAND: ${{ matrix.build-command }} + run: bash -eo pipefail -c "$BUILD_COMMAND" - name: Verify build output working-directory: ${{ github.workspace }} @@ -511,6 +522,7 @@ jobs: { echo "published=false" echo "published-sha=" + echo "superseded=true" } >> "$GITHUB_OUTPUT" exit 0 else @@ -615,6 +627,7 @@ jobs: PUBLISH_PATHS: ${{ needs.discover.outputs.publish-paths }} PUBLISHED: ${{ steps.publish.outputs.published }} PUBLISHED_SHA: ${{ steps.publish.outputs.published-sha }} + SUPERSEDED: ${{ steps.publish.outputs.superseded }} DRY_RUN: ${{ inputs.dry-run }} run: | set -euo pipefail @@ -623,6 +636,9 @@ jobs: echo if [ "${PUBLISHED:-}" = "true" ]; then echo "Force-pushed \`${TARGET_BRANCH}\` at \`${PUBLISHED_SHA}\`." + elif [ "${SUPERSEDED:-}" = "true" ]; then + echo "**Superseded** — a newer run already published a descendant of this run's" \ + "source commit, so \`${TARGET_BRANCH}\` is already ahead. Nothing was pushed." elif [ "$DRY_RUN" = "true" ]; then echo "**Dry run** — the commit was created but not pushed." else diff --git a/.github/workflows/cd-github-release.yml b/.github/workflows/cd-github-release.yml index dee63d9..4e485e6 100644 --- a/.github/workflows/cd-github-release.yml +++ b/.github/workflows/cd-github-release.yml @@ -8,9 +8,21 @@ on: type: string required: true artifact-name: - description: "Name of the build artifact to download and attach. Must match the name used by the producing job (e.g. ci-build.yml's artifact-name)." + description: >- + Name of the build artifact to download and attach. Must match the name used by the + producing job (e.g. ci-build.yml's artifact-name). Packaged into a single .zip unless + the artifact is exactly one archive (.zip/.tar.gz/.tgz/.tar.bz2/.tar.xz/.tar), which is + attached as-is. type: string required: true + slug: + description: >- + Directory name at the root of the packaged zip, e.g. 'acme-blocks', so the asset installs + straight through wp-admin. Letters, digits, dots, underscores and hyphens only, and not + leading with '-'. Defaults to artifact-name. Ignored when the artifact is already a single + archive. + type: string + default: "" changelog-path: description: "Path to the changelog whose matching section becomes the release body." type: string @@ -102,23 +114,66 @@ jobs: exit 1 fi + - name: Package release asset + id: asset + shell: bash + env: + ARTIFACT_NAME: ${{ inputs.artifact-name }} + SLUG: ${{ inputs.slug != '' && inputs.slug || inputs.artifact-name }} + run: | + set -euo pipefail + # dotglob so a plugin's .htaccess/.editorconfig is counted and packaged; bash's dotglob + # never matches '.' or '..', so the entry count stays honest. + shopt -s nullglob dotglob + entries=(artifact/*) + if [ ${#entries[@]} -eq 0 ]; then + echo "::error::Downloaded artifact '$ARTIFACT_NAME' contains no files to attach" + exit 1 + fi + # A newline in a name would inject extra keys when the asset is written to $GITHUB_OUTPUT. + case "${entries[*]}" in + *$'\n'*) echo "::error::Artifact '$ARTIFACT_NAME' contains a file whose name has a newline"; exit 1 ;; + esac + + # Already packaged by the build (artifact-path: dist/foo.zip) — attach it untouched. + if [ ${#entries[@]} -eq 1 ] && [ -f "${entries[0]}" ]; then + lower="$(printf '%s' "${entries[0]}" | tr '[:upper:]' '[:lower:]')" + case "$lower" in + *.zip|*.tar.gz|*.tgz|*.tar.bz2|*.tar.xz|*.tar) + echo "::notice::Attaching '${entries[0]}' as-is (already an archive)." + echo "asset=${entries[0]}" >> "$GITHUB_OUTPUT" + exit 0 + ;; + esac + fi + + # Directory artifact: gh release create only accepts files, and a WordPress zip must carry + # a single / root for wp-admin -> Upload Plugin to install it. Re-root, then zip. + # Restricted charset: the slug becomes a directory, an archive name and a $GITHUB_OUTPUT + # value, and a leading '-' would reach gh release create as a flag rather than a path. + case "$SLUG" in + -*|*[!a-zA-Z0-9._-]*|.|..|"") + echo "::error::slug must be letters, digits, dots, underscores or hyphens, and must not start with '-' (got '$SLUG')" + exit 1 + ;; + esac + mkdir -p "pkg/$SLUG" + cp -R artifact/. "pkg/$SLUG/" + ( cd pkg && zip -qr "../${SLUG}.zip" "$SLUG" ) + echo "::notice::Packaged ${#entries[@]} top-level entries into ${SLUG}.zip (root: ${SLUG}/)." + echo "asset=${SLUG}.zip" >> "$GITHUB_OUTPUT" + - name: Create GitHub Release shell: bash env: GH_TOKEN: ${{ github.token }} TAG: ${{ inputs.tag }} - ARTIFACT_NAME: ${{ inputs.artifact-name }} + ASSET: ${{ steps.asset.outputs.asset }} DRAFT: ${{ inputs.draft }} PRERELEASE: ${{ inputs.prerelease }} run: | set -euo pipefail - shopt -s nullglob - files=(artifact/*) - if [ ${#files[@]} -eq 0 ]; then - echo "::error::Downloaded artifact '$ARTIFACT_NAME' contains no files to attach" - exit 1 - fi - args=(release create "$TAG" "${files[@]}" --verify-tag --title "$TAG" --notes-file release-notes.md) + args=(release create "$TAG" "$ASSET" --verify-tag --title "$TAG" --notes-file release-notes.md) if [ "$DRAFT" = "true" ]; then args+=(--draft) fi diff --git a/.github/workflows/ci-build.yml b/.github/workflows/ci-build.yml index 7caf6b2..15b819b 100644 --- a/.github/workflows/ci-build.yml +++ b/.github/workflows/ci-build.yml @@ -81,14 +81,23 @@ jobs: - name: Install Composer dependencies if: ${{ inputs.install-composer-deps }} - run: composer install ${{ inputs.composer-flags }} + shell: bash + env: + COMPOSER_FLAGS: ${{ inputs.composer-flags }} + run: | + set -euo pipefail + read -r -a composer_args <<< "$COMPOSER_FLAGS" || true + composer install "${composer_args[@]}" - name: Install npm dependencies if: ${{ inputs.install-node-deps }} run: npm ci - name: Build production assets - run: ${{ inputs.build-command != '' && inputs.build-command || (inputs.install-node-deps && 'npm run build:prod' || 'composer run-script build') }} + shell: bash + env: + BUILD_COMMAND: ${{ inputs.build-command != '' && inputs.build-command || (inputs.install-node-deps && 'npm run build:prod' || 'composer run-script build') }} + run: bash -eo pipefail -c "$BUILD_COMMAND" - name: Upload build artifact if: ${{ inputs.upload-artifact }} diff --git a/.github/workflows/ci-lint-css.yml b/.github/workflows/ci-lint-css.yml index 6080071..b129896 100644 --- a/.github/workflows/ci-lint-css.yml +++ b/.github/workflows/ci-lint-css.yml @@ -49,9 +49,10 @@ jobs: shell: bash env: CHANGED_FILES: ${{ inputs.changed-files }} + LINT_COMMAND: ${{ inputs.lint-command }} run: | if [ -n "$CHANGED_FILES" ]; then printf '%s\n' "$CHANGED_FILES" | xargs -d '\n' --no-run-if-empty npx --no-install stylelint -- else - ${{ inputs.lint-command }} + bash -eo pipefail -c "$LINT_COMMAND" fi diff --git a/.github/workflows/ci-lint-js.yml b/.github/workflows/ci-lint-js.yml index 475841b..1263486 100644 --- a/.github/workflows/ci-lint-js.yml +++ b/.github/workflows/ci-lint-js.yml @@ -57,9 +57,10 @@ jobs: shell: bash env: CHANGED_FILES: ${{ inputs.changed-files }} + LINT_COMMAND: ${{ inputs.lint-command }} run: | if [ -n "$CHANGED_FILES" ]; then printf '%s\n' "$CHANGED_FILES" | xargs -d '\n' --no-run-if-empty npx --no-install eslint -- else - ${{ inputs.lint-command }} + bash -eo pipefail -c "$LINT_COMMAND" fi diff --git a/.github/workflows/ci-lint-php.yml b/.github/workflows/ci-lint-php.yml index 300a37c..6ca420c 100644 --- a/.github/workflows/ci-lint-php.yml +++ b/.github/workflows/ci-lint-php.yml @@ -82,30 +82,42 @@ jobs: composer-${{ runner.os }}-php${{ inputs.php-version }}- - name: Install Composer dependencies - run: composer install ${{ inputs.composer-flags }} + shell: bash + env: + COMPOSER_FLAGS: ${{ inputs.composer-flags }} + run: | + set -euo pipefail + read -r -a composer_args <<< "$COMPOSER_FLAGS" || true + composer install "${composer_args[@]}" - name: Run PHPCS shell: bash env: CHANGED_FILES: ${{ inputs.changed-files }} + PHPCS_COMMAND: ${{ inputs.phpcs-command }} run: | set -euo pipefail + # phpcs-command is a command and runs as shell; the report flags are appended as "$@" so + # they stay argv. The pipe to cs2pr stays out here, so a non-zero phpcs still trips + # pipefail exactly as before. + args=(-q --report=checkstyle --runtime-set ignore_warnings_on_exit 1) if [ -n "$CHANGED_FILES" ]; then tmp_list=$(mktemp) trap 'rm -f "$tmp_list"' EXIT printf '%s\n' "$CHANGED_FILES" > "$tmp_list" - ${{ inputs.phpcs-command }} --file-list="$tmp_list" \ - -q --report=checkstyle \ - --runtime-set ignore_warnings_on_exit 1 \ - | cs2pr --graceful-warnings - else - ${{ inputs.phpcs-command }} -q --report=checkstyle \ - --runtime-set ignore_warnings_on_exit 1 \ - | cs2pr --graceful-warnings + args=(--file-list="$tmp_list" "${args[@]}") fi + bash -eo pipefail -c "$PHPCS_COMMAND \"\$@\"" _ "${args[@]}" \ + | cs2pr --graceful-warnings - name: Run PHPStan if: ${{ inputs.enable-phpstan }} - run: >- - ${{ inputs.phpstan-command }} - ${{ inputs.phpstan-level != '' && format('--level={0}', inputs.phpstan-level) || '' }} + shell: bash + env: + PHPSTAN_COMMAND: ${{ inputs.phpstan-command }} + PHPSTAN_LEVEL: ${{ inputs.phpstan-level }} + run: | + set -eo pipefail + args=() + [ -z "$PHPSTAN_LEVEL" ] || args+=("--level=$PHPSTAN_LEVEL") + bash -eo pipefail -c "$PHPSTAN_COMMAND \"\$@\"" _ "${args[@]}" diff --git a/.github/workflows/ci-self-check.yml b/.github/workflows/ci-self-check.yml index 28adae0..1d53e86 100644 --- a/.github/workflows/ci-self-check.yml +++ b/.github/workflows/ci-self-check.yml @@ -29,7 +29,7 @@ jobs: run: pipx install yamllint - name: Run yamllint - run: yamllint -c .yamllint.yml .github/workflows/ examples/ + run: yamllint -c .yamllint.yml . - name: Install actionlint run: | diff --git a/.github/workflows/ci-test-a11y.yml b/.github/workflows/ci-test-a11y.yml index 71ea290..ffce09e 100644 --- a/.github/workflows/ci-test-a11y.yml +++ b/.github/workflows/ci-test-a11y.yml @@ -46,13 +46,19 @@ jobs: run: npm ci - name: Build production assets - run: ${{ inputs.build-command }} + shell: bash + env: + BUILD_COMMAND: ${{ inputs.build-command }} + run: bash -eo pipefail -c "$BUILD_COMMAND" - name: Start wp-env run: npm run wp-env start - name: Run pa11y-ci - run: ${{ inputs.test-command }} + shell: bash + env: + TEST_COMMAND: ${{ inputs.test-command }} + run: bash -eo pipefail -c "$TEST_COMMAND" - name: Stop wp-env if: always() diff --git a/.github/workflows/ci-test-js.yml b/.github/workflows/ci-test-js.yml index 14fb4e5..3a1028b 100644 --- a/.github/workflows/ci-test-js.yml +++ b/.github/workflows/ci-test-js.yml @@ -8,7 +8,10 @@ on: type: string default: "22" test-command: - description: "Shell command that runs Jest." + description: >- + Shell command that runs Jest. When enable-cache is true, --cacheDirectory= is + appended as "$@", so a custom command must forward its arguments through to Jest — the + default does, via npm's `--` separator. type: string default: "npm run test:js -- --ci" enable-cache: @@ -52,12 +55,24 @@ jobs: uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0 with: path: ${{ steps.jest-cache.outputs.dir }} - key: jest-${{ runner.os }} + # Keyed on the lockfile: a bare 'jest-' key is written once and never updated again, + # so the cache would freeze at whatever the first run happened to produce. + key: jest-${{ runner.os }}-${{ hashFiles(format('{0}/package-lock.json', inputs.working-dir)) }} + restore-keys: | + jest-${{ runner.os }}- - name: Install npm dependencies run: npm ci - name: Run Jest - run: ${{ inputs.test-command }} + shell: bash env: - JEST_CACHE_DIRECTORY: ${{ steps.jest-cache.outputs.dir }} + TEST_COMMAND: ${{ inputs.test-command }} + # Jest reads cacheDirectory from its config or --cacheDirectory only; there is no + # environment variable for it, so the flag has to be appended to the command. + JEST_CACHE_DIR: ${{ steps.jest-cache.outputs.dir }} + run: | + set -eo pipefail + args=() + [ -z "$JEST_CACHE_DIR" ] || args+=("--cacheDirectory=$JEST_CACHE_DIR") + bash -eo pipefail -c "$TEST_COMMAND \"\$@\"" _ "${args[@]}" diff --git a/.github/workflows/ci-test-php.yml b/.github/workflows/ci-test-php.yml index 510559f..fd9bcca 100644 --- a/.github/workflows/ci-test-php.yml +++ b/.github/workflows/ci-test-php.yml @@ -73,7 +73,13 @@ jobs: cache-dependency-path: ${{ inputs.working-dir != '.' && format('{0}/package-lock.json', inputs.working-dir) || '' }} - name: Install Composer dependencies - run: composer install ${{ inputs.composer-flags }} + shell: bash + env: + COMPOSER_FLAGS: ${{ inputs.composer-flags }} + run: | + set -euo pipefail + read -r -a composer_args <<< "$COMPOSER_FLAGS" || true + composer install "${composer_args[@]}" - name: Install npm dependencies if: ${{ inputs.use-wp-env }} @@ -84,7 +90,10 @@ jobs: run: npm run wp-env start - name: Run PHPUnit - run: ${{ inputs.test-command != '' && inputs.test-command || (inputs.use-wp-env && 'npm run test:php' || 'vendor/bin/phpunit') }} + shell: bash + env: + TEST_COMMAND: ${{ inputs.test-command != '' && inputs.test-command || (inputs.use-wp-env && 'npm run test:php' || 'vendor/bin/phpunit') }} + run: bash -eo pipefail -c "$TEST_COMMAND" - name: Stop wp-env if: ${{ inputs.use-wp-env && always() }} diff --git a/AGENTS.md b/AGENTS.md index ed12b4a..f3254d2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ brew install actionlint yq jq # the only tooling this repo needs ``` -Nothing to build, no `package.json`, no `node_modules`. Every file here is YAML or POSIX shell. +Nothing to build, no `package.json`, no `node_modules`. Every file here is YAML or Bash. ### Key Directories @@ -55,13 +55,39 @@ jobs: - 2-space indent, `kebab-case` input names, a `description:` on every input, a `name:` on every job and step. `bin/check-workflows.sh` enforces all four. - Third-party actions pinned to a commit SHA with a trailing `# vX.Y.Z` comment. -- User-controlled values reach a `run:` body through step `env:`, never through `${{ }}` interpolation: +- Caller values reach a `run:` body through step `env:`, never through `${{ }}` interpolation. `bin/check-workflows.sh` enforces this — interpolation is still fine in `env:`, `with:` and `if:`, which are not shell. Two shapes: + +**Value inputs** (`composer-flags`, `phpstan-level`, `changed-files`) become argv, so shell metacharacters stay literal: + +```yaml + - name: Install Composer dependencies + shell: bash + env: + COMPOSER_FLAGS: ${{ inputs.composer-flags }} + run: | + set -euo pipefail + read -r -a composer_args <<< "$COMPOSER_FLAGS" || true + composer install "${composer_args[@]}" +``` + +**Command inputs** (`build-command`, `test-command`, `*-command`) *are* shell — running them is the contract, not a leak. Routing them through `env:` stops render-time splicing, where a newline in the value injects extra lines into the generated script and a quote corrupts the command after it: ```yaml - - name: Resolve targets + - name: Build production assets + shell: bash env: - INPUT_TARGETS: ${{ inputs.targets }} - run: jq -e 'type == "array"' <<<"$INPUT_TARGETS" + BUILD_COMMAND: ${{ inputs.build-command }} + run: bash -eo pipefail -c "$BUILD_COMMAND" +``` + +Use `bash -eo pipefail -c`, never bare `bash -c`: `-e` is not inherited, so a bare `bash -c "false; echo x"` exits **0** and a failing build passes green. Those flags reproduce GitHub's own `shell: bash` default. `-u` is deliberately omitted — GitHub does not set it either, and it would break consumer commands that reference unset variables. Append arguments as quoted positionals so they cannot be re-parsed as shell: + +```yaml + run: | + set -eo pipefail + args=() + [ -z "$PHPSTAN_LEVEL" ] || args+=("--level=$PHPSTAN_LEVEL") + bash -eo pipefail -c "$PHPSTAN_COMMAND \"\$@\"" _ "${args[@]}" ``` ## Architectural decisions @@ -70,7 +96,7 @@ jobs: - **Orchestrator plus leaves**: `wp-ci.yml` composes the CI leaves via `jobs..uses`, so a consumer wires up one job instead of ten. The `cd-*` workflows have no orchestrator by design — a consumer calls the ones it needs from its own release trigger, and each stays independently useful. - **One unit per call**: `project-type` describes the unit at `working-dir`, not the repository. A repo with two plugins and a theme calls `wp-ci.yml` three times, usually via a matrix in the caller. Sibling calls don't cancel each other, and each derives its own artifact name. - **Everything gated on what changed**: `ci-detect-changes.yml` buckets the diff and every downstream job keys off it, so a docs-only PR runs almost nothing. -- **Logic that needs a real language lives elsewhere**: `@rtcamp/wp-tooling`, invoked as `npx wp-tooling `. Repo-local automation is POSIX shell under `bin/`. +- **Logic that needs a real language lives elsewhere**: `@rtcamp/wp-tooling`, invoked as `npx wp-tooling `. Repo-local automation is Bash under `bin/`. - **Examples are executable documentation**: one per workflow, verified in CI, comment-free, pinned `@v1`. They target a `wp-content`-shaped monorepo because that is the shape people get wrong. Anything consuming a build artifact shows the producing `ci-build` job and the `needs:` edge in the same file. - **Prefer official tooling**: `actions/checkout`, `actions/setup-node`, `shivammathur/setup-php`, and WordPress/Automattic-maintained actions over third-party ones. diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ad7df3..bd74d75 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,12 @@ First tagged release. Consumers pin `@v1`. ### Changed +- Caller values no longer reach a `run:` body through `${{ }}` interpolation — a convention `AGENTS.md` already documented but sixteen steps across eight workflows broke. Value inputs (`composer-flags`, `phpstan-level`) now travel through step `env:` and become argv, so shell metacharacters in them stay literal instead of executing. Command inputs (`build-command`, `test-command`, `phpcs-command`, `phpstan-command`, `lint-command`, and `cd-built-branch.yml`'s per-target equivalents) also travel through `env:` and are run as `bash -eo pipefail -c "$COMMAND"`: executing them is the contract, but routing them through the environment stops render-time splicing, where a newline in the value injects extra lines into the generated script. `-eo pipefail` is not optional — a bare `bash -c` does not inherit `set -e`, so a failing command would exit 0 and pass a job green. `bin/check-workflows.sh` now fails on any `${{ inputs. }}`/`${{ matrix. }}` inside a `run:` body, so the convention is verified rather than merely documented. +- `cd-github-release.yml` packages the release asset instead of attaching the artifact's top-level entries directly. `gh release create` only accepts files, but `download-artifact` unpacks a directory artifact, so any plugin with a subdirectory — including the shape `examples/cd-github-release.yml` produces — failed at the upload. A directory artifact is now re-rooted under `/` and zipped to a single `.zip` that installs through wp-admin; an artifact that is already a single archive is attached untouched, so a pre-zipped `artifact-path` keeps working. The two cases are told apart by archive extension rather than file count, so a single-file plugin still gets packaged. Adds an optional `slug` input (defaults to `artifact-name`). +- `ci-test-js.yml`'s `enable-cache` now caches something. Jest has no `JEST_CACHE_DIRECTORY` environment variable, so the previous wiring cached an always-empty directory, and the fixed `jest-` key was written once and never updated again. The cache directory is now passed as a real `--cacheDirectory` argument and the key includes the `working-dir`-scoped lockfile hash with a `restore-keys` fallback. A custom `test-command` must forward its arguments for the flag to land; the default does. +- `ci-self-check.yml` runs `yamllint` over the whole repository rather than just `.github/workflows/` and `examples/`, matching the `yamllint .` that `AGENTS.md` tells contributors to run — previously `.yamllint.yml` and `.github/actionlint.yaml` could fail locally while CI stayed green. +- `cd-built-branch.yml`'s `published` and `published-sha` output descriptions now cover every no-push outcome. A run superseded by a newer one also reports `published=false` with an empty SHA, so `false` never meant "dry run" on its own. The job summary distinguishes the two cases as well, instead of reporting a superseded run as "Publish did not complete". +- `AGENTS.md` and `CONTRIBUTING.md` describe `bin/` as Bash, not POSIX shell — `bin/check-workflows.sh` uses `BASH_SOURCE`, `[[ ]]`, arrays and process substitution, so the POSIX label gave contributors the wrong portability contract. - Documentation restructured for a public `main`. Caller examples move out of `README.md` into [`examples/`](examples/), one runnable file per workflow, verified in CI by `bin/check-workflows.sh`. `README.md` is now a workflow index plus a versioning guide, and no longer duplicates the input tables — each workflow's `workflow_call` block is the single source of truth, and GitHub renders those descriptions when a caller is configured. Repo conventions move to a tool-agnostic [`AGENTS.md`](AGENTS.md), which `CLAUDE.md` imports. Adds `LICENSE` (GPL-2.0-or-later, previously declared but absent) and `CONTRIBUTING.md`. - `version-monitor.yml` now pins `actions/checkout` and `actions/setup-node` to the same SHAs as the other fifteen workflows, and its job carries an explicit `name:`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2cb2b42..04fff15 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ single job starts. Treat the input surface as stable. repo layout, the shape every workflow follows, and the coding standards CI enforces. - **Every workflow has exactly one caller example** at `examples/.yml`. Add or update it in the same PR; CI fails otherwise. -- **Repo-local automation is POSIX shell** under `bin/`. Logic that needs a real language belongs in +- **Repo-local automation is Bash** under `bin/`. Logic that needs a real language belongs in [`@rtcamp/wp-tooling`](https://github.com/rtCamp/wp-tooling) and is invoked via `npx wp-tooling`. - **Third-party actions are pinned to a commit SHA** with a trailing `# vX.Y.Z` comment. diff --git a/bin/check-workflows.sh b/bin/check-workflows.sh index 4d796df..7305039 100755 --- a/bin/check-workflows.sh +++ b/bin/check-workflows.sh @@ -5,7 +5,8 @@ # 2. Every `uses:` in an example resolves to a workflow in this repo, pinned at @v1. # 3. Every `with:` / `secrets:` key an example passes is actually declared by that # workflow, and every required input/secret is supplied. -# 4. Repo conventions: kebab-case input names, every input documented, every step named. +# 4. Repo conventions: kebab-case input names, every input documented, every step named, +# and no caller value interpolated into a `run:` body. # # Requires: yq (v4) and jq. Both are preinstalled on GitHub's ubuntu runners; # locally, `brew install yq jq`. @@ -148,6 +149,17 @@ for wf in "$WORKFLOW_DIR"/*.yml; do | ($j.value.steps // []) | to_entries[] | select((.value.name // "") == "") | "job \($j.key) step #\(.key)"' <<<"$wf_json") + + # A caller value spliced into a run: body at render time can break the script around it — a + # newline injects extra shell lines, a quote corrupts the next command. Inspects .run only, so + # env:, with: and if: expressions stay legal. See "Code quality" in AGENTS.md. + while IFS= read -r loc; do + [ -n "$loc" ] || continue + err "$base interpolates a caller value into a run: body at $loc — pass it via step env:" + done < <(jq -r '(.jobs // {}) | to_entries[] as $j + | ($j.value.steps // []) | to_entries[] + | select((.value.run // "") | test("\\$\\{\\{\\s*(inputs|matrix)\\.")) + | "job \($j.key) step #\(.key) (\(.value.name // "unnamed"))"' <<<"$wf_json") done if [ "$fail" -ne 0 ]; then From eb16304c561af3afbd26456617e68d8570e74c31 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Fri, 2 Oct 2026 01:06:21 +0530 Subject: [PATCH 42/43] fix(ci): lint the whole project when Stylelint's changed files include manifests ci-detect-changes lists package.json and package-lock.json in css-files so a dependency change re-runs Stylelint, but ci-lint-css passed them straight to Stylelint, which failed with CssSyntaxError. Lint changed stylesheets file by file only when nothing else is in the list; otherwise run lint-command over the whole project, since a dependency change can affect every stylesheet. --- .github/workflows/ci-lint-css.yml | 11 ++++++++--- CHANGELOG.md | 6 ++++++ 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci-lint-css.yml b/.github/workflows/ci-lint-css.yml index b129896..24e7325 100644 --- a/.github/workflows/ci-lint-css.yml +++ b/.github/workflows/ci-lint-css.yml @@ -12,7 +12,7 @@ on: type: string default: "npm run lint:css" changed-files: - description: "Newline-separated list of CSS files to lint. Empty = run lint-command over the whole project." + description: "Newline-separated changed files (ci-detect-changes' css-files). Stylesheets are linted file by file; if the list is empty or holds anything else (package.json, package-lock.json), lint-command runs over the whole project." type: string default: "" working-dir: @@ -51,8 +51,13 @@ jobs: CHANGED_FILES: ${{ inputs.changed-files }} LINT_COMMAND: ${{ inputs.lint-command }} run: | - if [ -n "$CHANGED_FILES" ]; then - printf '%s\n' "$CHANGED_FILES" | xargs -d '\n' --no-run-if-empty npx --no-install stylelint -- + # css-files also lists package.json and package-lock.json, so a dependency + # change re-runs this job. Stylelint cannot parse them, and a dependency + # change can affect every stylesheet, so lint the whole project then. + stylesheets=$(printf '%s\n' "$CHANGED_FILES" | grep -E '\.s?css$' || true) + others=$(printf '%s\n' "$CHANGED_FILES" | grep -vE '^$|\.s?css$' || true) + if [ -n "$stylesheets" ] && [ -z "$others" ]; then + printf '%s\n' "$stylesheets" | xargs -d '\n' --no-run-if-empty npx --no-install stylelint -- else bash -eo pipefail -c "$LINT_COMMAND" fi diff --git a/CHANGELOG.md b/CHANGELOG.md index bd74d75..88946b4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,12 @@ All notable changes to `@rtcamp/wp-shared-workflows` are documented in this file The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +## Unreleased + +### Fixed + +- `ci-lint-css.yml` no longer passes `package.json` and `package-lock.json` to Stylelint. `ci-detect-changes` lists them in `css-files` so that a dependency change re-runs the job, and Stylelint failed on them with `CssSyntaxError`. When `changed-files` holds anything other than stylesheets, or is empty, the job now runs `lint-command` over the whole project. + ## v1.0.0 - 2026-08-10 First tagged release. Consumers pin `@v1`. From 30a46592799eb8742b2027823fa6c8f8a6db9178 Mon Sep 17 00:00:00 2001 From: Aryan Jasala Date: Fri, 2 Oct 2026 02:31:13 +0530 Subject: [PATCH 43/43] fix(ci): lint only existing PHP files with PHPCS ci-detect-changes lists composer.json, composer.lock and the PHPStan config in php-files, and a change that deletes PHP files lists those too. ci-lint-php passed the whole list to PHPCS, which failed with 'does not exist' for deleted files and 'Start tag expected' for the config files, as on rtCamp/theme-elementary#692. Lint changed PHP files that still exist file by file only when nothing else is in the list; otherwise lint the whole project, since a dependency or ruleset change can affect every file. --- .github/workflows/ci-lint-php.yml | 13 ++++++++++--- CHANGELOG.md | 1 + 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci-lint-php.yml b/.github/workflows/ci-lint-php.yml index 6ca420c..40d53c2 100644 --- a/.github/workflows/ci-lint-php.yml +++ b/.github/workflows/ci-lint-php.yml @@ -16,7 +16,7 @@ on: type: string default: "vendor/bin/phpcs" changed-files: - description: "Newline-separated list of PHP files to lint with PHPCS. Empty = lint the whole project. PHPStan always runs whole-project — it analyses cross-file dependencies." + description: "Newline-separated changed files (ci-detect-changes' php-files). PHP files that still exist are linted file by file; if the list is empty or holds anything else (composer.json, composer.lock, PHPStan config), PHPCS lints the whole project. PHPStan always runs whole-project — it analyses cross-file dependencies." type: string default: "" phpstan-command: @@ -101,10 +101,17 @@ jobs: # they stay argv. The pipe to cs2pr stays out here, so a non-zero phpcs still trips # pipefail exactly as before. args=(-q --report=checkstyle --runtime-set ignore_warnings_on_exit 1) - if [ -n "$CHANGED_FILES" ]; then + # php-files also lists composer.json, composer.lock and the PHPStan config, so a + # dependency or config change re-runs this job, and it can name files the change + # deleted. PHPCS only takes PHP files that exist; when anything else changed, a + # dependency or ruleset change can affect every file, so lint the whole project. + php_files=$(printf '%s\n' "$CHANGED_FILES" | grep -E '\.php$' \ + | while IFS= read -r file; do [ ! -f "$file" ] || printf '%s\n' "$file"; done || true) + others=$(printf '%s\n' "$CHANGED_FILES" | grep -vE '^$|\.php$' || true) + if [ -n "$php_files" ] && [ -z "$others" ]; then tmp_list=$(mktemp) trap 'rm -f "$tmp_list"' EXIT - printf '%s\n' "$CHANGED_FILES" > "$tmp_list" + printf '%s\n' "$php_files" > "$tmp_list" args=(--file-list="$tmp_list" "${args[@]}") fi bash -eo pipefail -c "$PHPCS_COMMAND \"\$@\"" _ "${args[@]}" \ diff --git a/CHANGELOG.md b/CHANGELOG.md index 88946b4..2459d93 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Fixed - `ci-lint-css.yml` no longer passes `package.json` and `package-lock.json` to Stylelint. `ci-detect-changes` lists them in `css-files` so that a dependency change re-runs the job, and Stylelint failed on them with `CssSyntaxError`. When `changed-files` holds anything other than stylesheets, or is empty, the job now runs `lint-command` over the whole project. +- `ci-lint-php.yml` no longer passes deleted files or non-PHP files to PHPCS. `ci-detect-changes` lists `composer.json`, `composer.lock` and the PHPStan config in `php-files`, and a change that deletes PHP files lists them too, so PHPCS failed with `does not exist` or `Start tag expected`. Changed PHP files that still exist are linted file by file; if the list holds anything else, PHPCS lints the whole project. ## v1.0.0 - 2026-08-10