GitHub Action: knip-reporter

⚙️📄 Report the results from knip on pull requests.

This action posts a knip report as comments on a pull request. It can run knip itself, or consume an existing report.

Usage

There are two primary ways to use this action, which will depend on your requirements. This action can run knip itself (default), or you can use knip to generate the report. Once a report has been generated/provided, this action works with that report.

Generate the report

The execution of knip requires you to have followed the general knip setup and have a command script present in your package.json file, knip, by default but this can be of any name. If this script name deviates from the standard knip setup, please provide the script name in the config.

knip-reporter appends a reporter to the knip command used, --reporter json, to output a parseable report with information needed for annotations where supported.

name: Pull Request
on:
  pull_request:

# This permissions config is only required if you are
# not providing own permissive token
permissions:
  checks: write
  pull-requests: write

steps:
  - name: Post the knip results
    uses: codex-/knip-reporter@v3

Provide the report

If you wish to avoid having this action run any commands itself, you can provide the path to an existing report for knip-reporter to work with.

The provided report must be generated with the JSON reporter (using --reporter json)

name: Pull Request
on:
  pull_request:

# This permissions config is only required if you are
# not providing own permissive token
permissions:
  checks: write
  pull-requests: write

steps:
  - name: Generate the knip report
    # `--silent` will stop the wrapping output from pnpm, leaving just the report
    run: pnpm --silent knip --reporter json > knip-report.json
    continue-on-error: true # Any reports generated with content result in a non-zero exit code

  - name: Post the knip results
    uses: codex-/knip-reporter@v3
    with:
      json_report_path: ./knip-report.json

Config

The following inputs are supported

Input	Description	Required	Default
token	GitHub Personal Access Token for making API requests.	false	${{ github.token }}
command_script_name	The package script that runs knip.	false	knip
comment_id	ID to use when updating the PR comment. Spaces will be replaced with dashes.	false	${{ github.workflow }}-knip-reporter
annotations	Annotate the project code with the knip results.	false	true
verbose	Include annotated items in the comment report.	false	false
ignore_results	Do not fail the action run if knip results are found.	false	false
working_directory	Run knip in a different directory.	false	.
json_report_path	Use a pre-existing knip report instead of running knip. Relative paths are resolved against working_directory.	false

Issues

If you encounter a case where comments are not being posted, or known sections are missing from the report, please enable step debug logging and create an issue with the results and expected behaviour.

APIs Used

• Checks
  • Check Runs
    • Create a check run
      • POST /repos/{owner}/{repo}/check-runs
    • Update a check run
      • PATCH /repos/{owner}/{repo}/check-runs/{check_run_id}
• Issues
  • Comments
    • Create an issue comment
      • POST /repos/{owner}/{repo}/issues/{issue_number}/comments
    • List issue comments
      • GET /repos/{owner}/{repo}/issues/{issue_number}/comments
    • Update an issue comment
      • PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}
    • Delete an issue comment
      • DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}