When you create a Pull Request (PR) on a VIP client site repository in the VIP GitHub organization (
https://github.com/wpcomvip/), you may see a review from our automated VIP Code Analysis bot. The bot’s GitHub username is
wpcomvip-vipgoci-bot. The bot scan is run under a TeamCity build.
The bot runs PHP_CodeSniffer (PHPCS) with the WordPress-VIP-Go standard, the PHP linter, and also checks SVG files.
The PHP linter will highlight code syntax and compilation errors. These are usually fatal and need to be addressed before the code is deployed.
PHPCS is a tool that will help you write VIP approved code by ensuring it meets VIP coding standards. The rules are designed to identify where code will not work, and to help you follow VIP best practices for writing secure, performant, and future-friendly code. We recommend you install the PHPCS and the standards locally by following the documentation here.
The bot works by adding a GitHub PR review (or reviews) detailing the feedback based on our standard. A review with no issues will show no interaction from the bot, whereas if the bot finds either PHPCS or PHP linting errors, the bot will comment on and review the PR:
You have several choices for each item of bot feedback:
- Address the feedback by amending your code
- Choose to ignore the feedback, and add code comments to instruct the bot to ignore the issue (see below)
- Dismiss the review issue via the GitHub PR interface
Many issues will be correct and should be addressed, but as with all automated feedback there will be some wrongly flagged issues that it is safe to ignore (false positives). There may also be some issues that the bot feedback misses (false negatives).
Code comments to ignore PHPCS feedback
You can configure the bot to ignore certain parts of files when running PHPCS as described in “Ignoring Parts of a File” from the PHPCS documentation. Here’s an example:
// Ignore a single line: $xmlPackage = new XMLPackage; // phpcs:ignore WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase -- reasons // Disable the a check for multiple lines, and then enable all checks at the end: // phpcs:disable WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase -- reasons $xmlPackage['error_code'] = get_default_error_code_value(); $xmlPackage->send(); // phpcs:enable
Read the PHPCS documentation for other methods to have the scanner ignore portions of a file or whole files.
Modifying the bot’s behavior
You can change the bot’s behavior by placing a configuration file named
.vipgoci_options at the root of the relevant repository. This file must contain a valid JSON string for this to work; if the file is not parsable, it will be ignored. This file is where you can add code to turn off support messages as well as adjust PHPCS severity levels.
Turning support messages off
By default, the bot will post a support message to new PRs explaining what it does as well as what to expect next. This message can be turned off. (See the example in the next section.)
Adjusting PHPCS severity
You can increase or decrease the number of warnings and errors generated by the bot by adjusting its PHPCS severity level.
By default, the bot runs at severity=1.
To turn off support comments and adjust the PHPCS severity level, use the following JSON snippet in your
Please note, while you can configure either parameter, you do not need to configure both. We recommend that you only configure the option that you need to configure. We also recommend that you only configure the PHPCS severity level if you understand how to use that PHPCS option and understand the implications of its use.
Skipping PHPCS scanning for specific pull requests
By default the bot will scan any new PRs with PHPCS and PHP Lint. However, in some cases you might not want it to scan the PHP code with PHPCS. To accomplish this, add a label to the relevant PR simply named
skip-phpcs-scan without any extra strings or content. Only use this label if you do not want the code to be reviewed by the bot.
Skipping PHPCS scanning for specific folders
You can add files to the root of the repository indicating folders that should not be scanned. For PHPCS, the file should be named
.vipgoci_phpcs_skip_folders. For PHP Linting the file should be named
.vipgoci_lint_skip_folders. Please ensure both files are located in the root of the repository.
List each folder to be skipped on individual lines within those files. For example, to skip PHP Linting, you would list folders in the file named
.vipgoci_lint_skip_folders like so:
With these two paths in the
.vipgoci_lint_skip_folders file, no PHP files in those folders will be checked for syntax errors. The usage is analogous with PHPCS. Note that regular expressions are not supported at this time.
We encourage you to use this feature sparingly. We view the checks as a safety mechanism that can save your sites from serious errors.
TeamCity Build Failed
Occasionally, the TeamCity build will “fail” and that will be noted on the pull request. Often, the cause is just a timeout – the maximum time was reached. This indicates only that the bot was unable to complete the scan – usually because there were many files. You may still merge the pull request or request a VIP review, but generally the best option if you need the results of the bot’s scan is to use PHPCS locally to run a scan on your codebase, or open smaller pull requests.
GitHub API communication error
Occasionally the bot will post a message to PRs saying that there has been a
GitHub API communication error and that a human should be contacted. This happens when the bot has a problem communicating with the GitHub API, and in most cases this is due to problems with the GitHub API itself. The message usually disappears when the PR is scanned again, which occurs when new commits are pushed to the PR.
If the problem persists, first check if there are any issues with the GitHub API (see here). If all systems appear operational, and the problem persists, please open a support ticket with us and we will investigate.