wp-github-actions

WordPress プラグインの GitHub Actions

このスキルは、GitHub Actions を使って WordPress プラグイン向けの包括的な CI/CD パイプラインを設定するのに役立ちます。プラグインの作成者が、手作業を減らしながら、より高品質なコードをリリースできるようにすることが目標です。

このスキルで扱う内容

健全な WordPress プラグインには、いくつかのカテゴリのワークフローが必要です。すべてのプラグインにすべてが必要なわけではありません。適切な組み合わせは、プラグインの複雑さ、JavaScript/CSS アセットの有無、Composer の使用有無などによって異なります。どのワークフローが該当するかを判断し、設定してください。

ワークフローは次のカテゴリに分かれます。

1. コード品質 — WPCS/PHPCS チェック、PHP の lint、JS/CSS の lint
2. テスト — WordPress テストライブラリを使った PHPUnit
3. 静的解析 — WordPress 拡張機能を使った PHPStan
4. 依存関係管理 — PR での Composer 差分確認、セキュリティスキャン
5. プレビュー — WordPress Playground の PR プレビュー
6. デプロイ — タグまたはリリース時の WordPress.org への自動デプロイ

各ワークフローの詳細な設定については、すぐに使える YAML テンプレートと設定ファイルを含む references/workflows.md をお読みください。

リクエストへの対応方法

ステップ 1：プラグインを把握する

ワークフローファイルを作成する前に、対象のプラグインについて確認してください。

• プラグインは Composer を使っていますか？ composer.json があるか確認します。ある場合、Composer 関連のワークフロー（差分確認、セキュリティ、自動読み込み）が該当します。
• JavaScript/CSS アセットはありますか？ package.json、JS/CSS のソースファイル、またはビルドプロセスの有無を確認します。ある場合、JS/CSS の lint と、必要に応じてビルドステップが重要です。
• テストはありますか？ tests/ ディレクトリ、phpunit.xml、または phpunit.xml.dist があるか確認します。ある場合、PHPUnit ワークフローを設定します。ない場合は、テストを追加する価値があることに触れますが、無理に追加しないでください。
• WordPress.org に登録されていますか？ .wordpress-org ディレクトリがあるか確認するか、ユーザーに尋ねます。登録されている場合は、デプロイワークフローが該当し、.distignore も設定する必要があります。
• どの PHP バージョンをサポートすべきですか？ WordPress 自体は PHP 7.4 以降を必要としますが、多くのプラグインは 7.4、8.0、8.1、8.2、8.3 を対象にしています。プラグインの readme を確認するか、ユーザーに尋ねます。
• どの WordPress バージョンを対象にしていますか？ 同様に、プラグインが互換性を宣言している WP バージョンを確認します。

ステップ 2：ワークフローのセットを推奨する

確認した内容をもとに、設定するワークフローを推奨します。多くのプラグインに適したデフォルトは次のとおりです。

• WPCS チェック（ほぼ常に）
• PHP の lint（ほぼ常に — 複数の PHP バージョンにわたる構文エラーを検出します）
• PHPUnit テスト（テストがある場合）
• WordPress.org へのデプロイ（WordPress.org に登録されている場合）
• Playground の PR プレビュー（どのプラグインにもあると便利です）

条件に応じて、次のワークフローも設定します。

• JS/CSS の lint（プラグインにフロントエンドのアセットがある場合）
• Composer 差分確認＋セキュリティ（Composer を使っている場合）
• PHPStan（より踏み込んだ静的解析を必要とするプラグイン向け）

ステップ 3：ワークフローファイルを作成する

各ワークフローを個別の YAML ファイルとして .github/workflows/ に作成します。1 つの大きなワークフローにまとめるのではなく、ファイルを分けることで、PR でのフィードバックが明確になり（各チェックの結果が個別に表示されます）、個々のチェックを有効化・無効化しやすくなります。

references/workflows.md のテンプレートを出発点として使い、対象のプラグインに合わせて調整してください。一般的な調整には、PHP バージョンのマトリックス、WPCS 標準、ファイルパスの変更や、ビルドステップのあるプラグインに合わせたデプロイワークフローの調整などがあります。

ステップ 4：補助設定ファイルを作成する

設定するワークフローによっては、次のファイルも必要になる場合があります。

• phpcs.xml.dist — カスタム PHPCS ルールセット（ルールの除外やカスタム設定が必要な場合）
• .distignore — WordPress.org へのデプロイから除外するファイル
• phpstan.neon または phpstan.neon.dist — PHPStan の設定

ステップ 5：シークレットの設定を案内する

デプロイワークフローを追加する場合は、GitHub でリポジトリシークレットを 2 つ設定する必要があることをユーザーに案内してください。

• SVN_USERNAME — WordPress.org のユーザー名
• SVN_PASSWORD — WordPress.org のパスワード

次の手順を案内してください：リポジトリの「Settings」>「Secrets and variables」>「Actions」>「New repository secret」。

命名規則

各ファイルの用途がひと目でわかる、説明的なワークフローファイル名を使用してください。

• wpcs.yml — WordPress コーディング標準
• phpunit.yml — PHPUnit テスト
• lint-php.yml — PHP 構文のリント
• lint-js-css.yml — JavaScript と CSS のリント
• phpstan.yml — 静的解析
• composer-diff.yml — PR での Composer 依存関係の差分
• security.yml — Composer のセキュリティスキャン
• playground-preview.yml — WordPress Playground の PR プレビュー
• deploy.yml — WordPress.org へのデプロイ

重要な詳細

ブランチ名：多くの WordPress プラグインリポジトリでは、WordPress.org の SVN 規約に合わせて、デフォルトブランチに trunk を使用しています。一方で、main や master を使用するリポジトリもあります。ワークフローのトリガーでは、必ず実際のリポジトリを確認し、正しいブランチ名を使用してください。

PHP バージョンマトリックス：WordPress 6.x には PHP 7.4 以降が必要です。PHPUnit 用の適切なデフォルトマトリックスは ['7.4', '8.0', '8.1', '8.2', '8.3'] ですが、WPCS とリントには最新の安定版 PHP のみを使用してください（マトリックスは不要です）。

WordPress バージョンマトリックス：PHPUnit では、少なくとも latest を対象にテストし、前のメジャーバージョンも追加することを検討してください。今後の問題を早期に検出するため、nightly も対象にテストするプラグインもあります。

10up エコシステム：10up は、WordPress 専用の、十分に保守された GitHub Actions を提供しています。これらは WordPress 固有のエッジケースに適切に対応するため、利用できる場合は汎用的な代替手段よりも優先してください。主なものは、コーディング標準用の 10up/wpcs-action と、デプロイ用の 10up/action-wordpress-plugin-deploy です。