Reusable GitHub Actions Workflows

This repository contains multiple reusable GitHub Actions workflows with distinct purposes. Each workflow can be called independently or chained together, depending on the project needs.

Table of Contents

• Versioning
• 1. Build Workflow
• 2. Release Workflow
• 3. PHP Tests Workflow
• 4. Deploy Workflow

---

Features

• Centralized build and release process.
• Monorepo friendly: build one project of a repository with working_directory.
• Multi-version PHP testing.
• Safe folder synchronization with configurable mappings.
• Reusable across multiple projects.

---

Versioning

Pin callers to the major tag @v3:

uses: WritePoetry/reusable-workflows/.github/workflows/build.yml@v3

Each release is cut as an immutable tag (v3.0.0, v3.1.0, …); the v3 tag is moved forward to the newest backward-compatible release. Use @main only for testing, or a full commit SHA for maximum reproducibility.

---

1. Build Workflow

Compiles assets (npm / Composer) and prepares artifacts for deployment or release. Designed for WordPress projects using @wordpress/scripts, at the repository root or inside a monorepo.

Inputs

Name	Description	Required	Default
working_directory	Path to the project to build, relative to the repo root. Set it to build one project of a monorepo.	No	.
artifact_name	Name of the folder artifact to upload. If empty, the folder upload is skipped.	No	""
create_zip	If true, runs npm run plugin-zip and uploads a version-named ZIP artifact called release-zip.	No	false
artifact_paths	Extra glob lines appended to the folder artifact path: (actions/upload-artifact syntax; prefix with ! to exclude).	No	excludes .git, .github, node_modules

Outputs

Name	Description
zip_file	File name of the generated ZIP (empty unless create_zip was true).

Behavior

• Node setup, npm ci, npm run build and composer install each run only when the matching manifest exists in working_directory, so npm-only, Composer-only and mixed projects all work.
• npm ci needs a committed package-lock.json (also used for the npm cache key); npm run build uses --if-present.
• The folder artifact is rooted at working_directory, so artifact_name must not contain /.

Requirements in the Consuming Project (only when create_zip: true)

• npm script: "plugin-zip": "wp-scripts plugin-zip".
• Versioning: the ZIP is named <package-name>-<version>.zip, from package.json name and the Git tag (v prefix stripped).

Usage Example

jobs:
  build:
    uses: WritePoetry/reusable-workflows/.github/workflows/build.yml@v3
    with:
      create_zip: true
    permissions:
      contents: read
      packages: read
    secrets: inherit

---

2. Release Workflow

Downloads a ZIP artifact and creates an official GitHub Release with automated changelogs. The job runs only for tag refs (refs/tags/*).

Inputs

Name	Description	Required	Default
artifact_zip_name	Name of the artifact containing the ZIP file(s).	No	release-zip

Usage Example

jobs:
  release:
    needs: build
    uses: WritePoetry/reusable-workflows/.github/workflows/release.yml@v3
    permissions:
      contents: write
    secrets: inherit

---

3. PHP Tests Workflow

Runs PHPUnit tests across multiple PHP versions, with optional WordPress integration testing and coding-standards checks.

Inputs

Name	Description	Required	Default
php_versions	JSON array of PHP versions used for matrix testing	No	['7.4', '8.0', '8.1', '8.2']
phpunit9_config	PHPUnit 9-specific configuration file, used only when detected	No	phpunit-9.xml

Requirements in the Consuming Project

• A valid composer.json including PHPUnit (and optionally WPCS).
• The script bin/install-wp-tests.sh for WordPress integration tests.

Behavior

• Lint gate: phpcs runs first; the matrix runs only if it passes.
• Matrix Testing: each PHP version runs independently.
• Database: spins up MySQL 5.7 and prepares wordpress_test automatically when bin/install-wp-tests.sh is present.
• Multisite: executes tests in both standard and Multisite (WP_MULTISITE=1) environments.

Usage Example

jobs:
  tests:
    uses: WritePoetry/reusable-workflows/.github/workflows/php-tests.yml@v3
    with:
      php_versions: "['8.1','8.2']"
    secrets: inherit

---

4. Deploy Workflow

Synchronizes selected local directories to a remote server over SSH. Each entry in mappings runs as its own matrix job. Source files come from a repository checkout, a downloaded build artifact, or both.

Inputs

Name	Description	Required	Default
host	Remote server host	Yes	—
username	SSH username for the remote server	Yes	—
folder	Base folder on the remote server where synchronization occurs	Yes	—
mappings	JSON array of {from, to, exclude} objects. from is a local path, to is appended to folder, exclude is a space-separated list of glob patterns.	No	Default WordPress structure
transport	ssh (rsync over SSH — fast, delta transfer, but the server user needs a shell) or sftp (lftp mirror over the SFTP subsystem — works with SFTP-only users, e.g. Cloudways application users).	No	ssh
artifact_name	Build artifact to download into the workspace before syncing. Skipped when empty.	No	""
checkout	Check out the calling repository. Set to false when artifact_name already contains everything to deploy.	No	true

Secrets

Name	Description	Required
ssh_key	Private SSH key for rsync / SFTP authentication	Yes

Behavior

• Missing from sources are skipped (the job succeeds).
• Host keys are pinned via ssh-keyscan and StrictHostKeyChecking=yes.
• transport: sftp supports directory mappings only, does not delete remote files, and apt-installs lftp on the runner.
• Set concurrency in the calling workflow if you need to serialize deploys.

Usage Example

jobs:
  deploy_files:
    uses: WritePoetry/reusable-workflows/.github/workflows/deploy.yml@v3
    with:
      host: example.com
      username: deploy
      folder: /var/www/html/wp-content
      mappings: |
        [
          {"from": "themes", "to": "/themes/"},
          {"from": "plugins", "to": "/plugins/", "exclude": ".git* node_modules"}
        ]
    secrets:
      ssh_key: ${{ secrets.SERVER_SSH_DEPLOY_KEY }}

---

Chaining: a complete pipeline

jobs:
  tests:
    uses: WritePoetry/reusable-workflows/.github/workflows/php-tests.yml@v3
    secrets: inherit

  build:
    needs: tests
    uses: WritePoetry/reusable-workflows/.github/workflows/build.yml@v3
    with:
      create_zip: true
    permissions:
      contents: read
      packages: read
    secrets: inherit

  release:
    needs: build
    uses: WritePoetry/reusable-workflows/.github/workflows/release.yml@v3
    permissions:
      contents: write
    secrets: inherit

Monorepo (build several projects, then deploy)

For a repository holding more than one buildable project, run the build in the calling workflow (a plain job or a matrix), upload one artifact with the whole deploy tree, then hand it to deploy.yml with checkout: false and artifact_name. See personal-website/.github/workflows/main.yml for a worked example.

Note on persistence: Artifacts are the only way to transfer files between jobs. upload-artifact saves build results and download-artifact retrieves them downstream. Job outputs carry metadata (like zip_file) only, never files.