Add opt-in `.pcpignore` exclusions for local and CI scans

[davidperezgar]

This proposal reflects a broad consensus reached during a Plugins Team meeting: Plugin Check should support developer-controlled exclusions for local and CI workflows, while WordPress.org must always scan the complete distributed plugin.

Add an optional configuration file—similar in purpose to PHPCS exclusions—so plugin developers can exclude development-only files and directories from Plugin Check when running it locally, in WP-CLI, or as part of a GitHub Action.

This would let repositories run Plugin Check cleanly without reporting issues from files that are not part of the distributed plugin, such as vendor/, documentation, tests, or build tooling.

Proposed approach

Use a .pcpignore file at the plugin root, with an intuitive ignore-pattern syntax similar to other developer tools.

Example:

vendor/
docs/
tests/
node_modules/
*.map

The file should exclude matching files and directories only when custom exclusions are explicitly enabled.

Key rule: never apply it on WordPress.org

.pcpignore must be honored only for local and CI use cases, including WP-CLI and GitHub Actions.

It must be completely ignored by scans run on WordPress.org. The Plugin Directory must continue analyzing the actual distributed plugin files, without developer-defined exclusions.

WP-CLI behavior

Require an explicit opt-in flag, for example:

wp plugin check my-plugin --use-pcpignore

Without the flag, WP-CLI should retain its current behavior and scan all applicable files.

Potential Web Scanner behavior

If exposed in the Plugin Check Web Scanner, provide an explicit disabled-by-default option, such as:

Use .pcpignore custom exclusions

This option should only be available in local/development contexts and must not affect WordPress.org scans.

Acceptance criteria

• Developers can add a .pcpignore file to exclude development-only files and folders.
• The file uses documented, predictable ignore-pattern semantics.
• .pcpignore is applied only when the WP-CLI opt-in flag is supplied.
• The feature works in local and GitHub Actions/CI workflows.
• WordPress.org scans never read or apply .pcpignore.
• Existing built-in exclusions and default scan behavior remain unchanged.
• Invalid or unreadable ignore files do not cause a scan failure; they produce a useful warning where appropriate.
• Add tests for pattern matching, opt-in behavior, CI/WP-CLI use, and the WordPress.org exclusion rule.

Next step

Open a PR to define the exact ignore-pattern semantics, WP-CLI flag name, Web Scanner UX, and the mechanism that distinguishes local/CI scans from WordPress.org scans.

---

Disclosure: This issue was drafted with assistance from OpenAI Codex and reviewed by its author.