staabm / annotate-pull-request-from-checkstyle
Fund package maintenance!
staabm
Installs: 1 943 589
Dependents: 114
Suggesters: 0
Security: 0
Stars: 193
Watchers: 6
Forks: 24
Open Issues: 3
Requires
- php: ^5.3 || ^7.0 || ^8.0
- ext-libxml: *
- ext-simplexml: *
Requires (Dev)
- friendsofphp/php-cs-fixer: ^2.16.1
README
Turns checkstyle based XML-Reports into GitHub Pull Request Annotations via the Checks API. This script is meant for use within your GitHub Action.
That means you no longer search thru your GitHub Action logfiles. No need to interpret messages which are formatted differently with every tool. Instead you can focus on your Pull Request, and you don't need to leave the Pull Request area.
Images from https://github.com/mheap/phpunit-github-actions-printer
DEMO - See how Pull Request warnings/errors are rendered in action
Installation
Install the binary via composer
composer require staabm/annotate-pull-request-from-checkstyle --dev
💌 Give back some love
Consider supporting the project, so we can make this tool even better even faster for everyone.
Example Usage
cs2pr
can be used on a already existing checkstyle-report xml-file. Alternatively you might use it in the unix-pipe notation to chain it into your existing cli command.
Run one of the following commands within your GitHub Action workflow:
Process a checkstyle formatted file
cs2pr /path/to/checkstyle-report.xml
Available Options
--graceful-warnings
: Don't exit with error codes if there are only warnings--colorize
: Colorize the output. Useful if the same lint script should be used locally on the command line and remote on GitHub Actions. With this option, errors and warnings are better distinguishable on the command line and the output is still compatible with GitHub Annotations--notices-as-warnings
Converts notices to warnings. This can be useful because GitHub does not annotate notices.--prepend-filename
Prepend the filename to the output message--prepend-source
When the checkstyle generating tool provides asource
attribute, prepend the source to the output message.
Pipe the output of another commmand
... works for any command which produces a checkstyle-formatted report.
Examples can bee seen below:
Using PHPStan
phpstan analyse --error-format=checkstyle | cs2pr
Phpstan 0.12.32 introduced native github actions support, therefore you might use this instead:
phpstan analyse
Using Psalm
psalm --output-format=checkstyle | cs2pr
Psalm even supports the required format natively, therefore you might use this instead:
psalm --output-format=github
Using PHP Coding Standards Fixer
php-cs-fixer fix --dry-run --format=checkstyle | cs2pr
Using PHP_CodeSniffer
phpcs --report=checkstyle -q /path/to/code | cs2pr
Note: the -q
option means that no output will be shown in the action logs anymore.
To see the output both in the PR as well as in the action logs, use two steps, like so:
- name: Check PHP code style id: phpcs run: phpcs --report-full --report-checkstyle=./phpcs-report.xml - name: Show PHPCS results in PR if: ${{ always() && steps.phpcs.outcome == 'failure' }} run: cs2pr ./phpcs-report.xml
Using PHP Parallel Lint
vendor/bin/parallel-lint . --exclude vendor --checkstyle | cs2pr
Using Laravel Pint
- name: Show Pint results in PR run: pint --test --format=checkstyle | cs2pr
Note: if you want to have both logs and annotations you need to run pint
twice:
- name: Check PHP code style id: cs-check run: pint --test - name: Generate Annotations on CS errors if: failure() && steps.cs-check.outcome != 'success' run: pint --test --format=checkstyle | cs2pr
phpunit support?
PHPUnit does not support checkstyle, therefore cs2pr
will not work for you.
you might instead try
Example GithubAction workflow
If you're using shivammathur/setup-php
to setup PHP, cs2pr
binary is shipped within:
# ... jobs: phpstan-analysis: name: phpstan static code analysis runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Setup PHP uses: shivammathur/setup-php@v1 with: php-version: 7.3 coverage: none # disable xdebug, pcov tools: cs2pr - run: | composer install # install your apps dependencies vendor/bin/phpstan analyse --error-format=checkstyle | cs2pr
If you use a custom PHP installation, then your project needs to require staabm/annotate-pull-request-from-checkstyle
# ... jobs: phpstan-analysis: name: phpstan static code analysis runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Setup PHP run: # custom PHP installation - run: | composer install # install your apps dependencies composer require staabm/annotate-pull-request-from-checkstyle # install cs2pr vendor/bin/phpstan analyse --error-format=checkstyle | vendor/bin/cs2pr
Using cs2pr as a GitHub Action
You can also use cs2pr
itself as a GitHub Action. This is useful if you want to for instance use it for a project that does not use PHP or if you want to use it with a custom PHP installation.
See the example at the cs2pr GitHub Action repositiory.
Resources
Idea
This script is based on a suggestion of Benjamin Eberlei
The Code is inspired by https://github.com/mheap/phpunit-github-actions-printer