Skip to content

Integrations

- uses: actions/checkout@v7
- uses: polylint/skif@v0.8
with:
fail-on-warnings: true
Input Meaning
version skif version to install. Defaults to the version this release of the action was published with, whatever ref (tag, floating tag or commit SHA) uses it.
args Extra skif arguments: one line is split on spaces; several lines are one argument per line, so an argument may contain spaces.
working-directory Directory to run skif in.
fail-on-warnings Exit non-zero on any warning. Not added when args starts with a subcommand such as baseline or migrate.
from-sherif true or false (default): migration aid that lints with the translated sherif settings of a project that has no skif configuration yet (below).
install-only Put skif on PATH without running it.
token Token for the GitHub API and the release download. Defaults to the workflow’s GITHUB_TOKEN.
repository Advanced: the owner/repo the release assets come from. Defaults to polylint/skif.
verify-attestation Verify the archive’s build provenance with gh attestation verify (default true).

A job that replaces sherif can keep its settings with from-sherif: true, a migration aid that is off by default. With it, when no skif.toml or .skif.toml is found (in the working directory, above it up to the repository root, or anywhere git tracks one) and the root package.json has a sherif key or a script that runs sherif ("lint:deps": "sherif -i react -r unordered-dependencies"), the action runs skif migrate --from sherif --profile full into a temporary file and lints with --config <that file>. The flags are translated as skif migrate translates them, and skif’s default rules stay on. A setting that needs a human is reported as a warning and the rest still applies; a translation that fails is a warning and skif runs without it. The action does not do this for a skif subcommand in args (rules, update, …), when args has --config or --no-config. The translation is done by the action, not by skif: the skif binary never reads sherif configuration while linting (ADR 0003). Commit the output of skif migrate to settle the configuration and drop the input; from then on the action reads skif.toml. skif baseline write, prune and check get the translation too, through a temporary file that extends it and then the baseline file (--file, or skif.baseline.toml), since a baseline applies only through a configuration that extends it.

A release moves a floating tag: @vN for a stable major N from 1 on, and @v0.M for a 0.x line. @v0 itself never moves, because a 0.x minor release may break; pin @v0.7 to take every 0.7.x patch and nothing else. Every release of the action installs the skif version it was published with, so a full tag such as @v0.7.0 or a commit SHA never changes the installed version. The action downloads the release archive for the runner and verifies it against the release’s checksums.txt (again on every cache hit) and, where the gh CLI has the attestation command, against its build-provenance attestation. The attestation must come from the repository’s publish.yaml workflow (gh attestation verify --signer-workflow), so an attestation made by any other workflow does not pass. A release up to v0.6.0 is also accepted when attested by Goldziher/skif, the repository before the move to polylint. Outputs are version and path.

Code scanning with SARIF:

- uses: polylint/skif@v0.8
with:
args: --format sarif --output skif.sarif
- uses: github/codeql-action/upload-sarif@v4
if: always()
with:
sarif_file: skif.sarif

When GITHUB_ACTIONS=true and no --format is given, skif prints the human report plus GitHub annotations.

--format markdown (or disclosure, with each rule folded in a <details> section) renders a report to post as a pull request comment, and --format codeowners groups the findings by the owners in the repository’s CODEOWNERS file.

--format codeclimate writes the Code Climate JSON that GitLab Code Quality reads, so findings appear in the merge request widget and diff:

skif:
image: node:lts
script:
- npx @polylint/skif --format codeclimate --output gl-code-quality.json
artifacts:
when: always
reports:
codequality: gl-code-quality.json

Exit code 1 fails the job when errors remain; add allow_failure: true to report without blocking the pipeline.

One run can write several reports. Each --format FORMAT=FILE goes to its own file and at most one format goes to stdout, so this job keeps the human report in the job log, the JSON report as an artifact for scripts and the Code Quality report for the merge request:

skif:
image: node:lts
script:
- npx @polylint/skif --format human --format json=skif.json --format codeclimate=gl-code-quality.json
artifacts:
when: always
paths:
- skif.json
reports:
codequality: gl-code-quality.json

A run that fails before writing (a broken configuration, a rendering that fails) writes and replaces no file. A write that fails partway can leave the files written before it in place.

skif belongs in a pre-commit hook: a mismatched version or an unsorted dependency map is cheapest to fix before it is committed. Both hooks lint the whole workspace (pass_filenames: false) and pass --no-js, because JavaScript analysis reads every source file and belongs in CI. The fix hook also passes --no-install, so a commit never runs a package manager, and it is refused when CI is set.

repos:
- repo: https://github.com/polylint/skif
rev: v0.8.0 # use the latest release tag
hooks:
- id: skif # skif --no-js
- id: skif-fix # skif --fix --no-install --no-prompt --no-js (opt-in, rewrites manifests)

Both hooks run scripts/pre-commit/run-skif.sh, which needs neither Rust nor Node. It uses, in order, SKIF_BINARY (an error if it is not executable), skif on PATH, then the release pinned by the hook revision, downloaded once into ~/.cache/skif/pre-commit and verified against checksums.txt (and its build attestation, as the action checks it, when an authenticated gh is available).

The hooks run when package.json, pnpm-workspace.yaml, skif.toml or .skif.toml change. A configuration file that is only reached through extends can have any name and does not trigger them; add its path to the hook’s files pattern, or run skif yourself after changing it.

Add skif as a managed source in poly.toml:

[[hooks.sources]]
id = "skif"
git = "https://github.com/polylint/skif.git"
revision = "v0.8.0" # use the latest release tag
hooks = ["skif"]

poly-hooks.toml also provides skif-fix. Each hook has a system channel (skif on PATH) and an npm channel pinned to the release version (pnpm dlx @polylint/skif@<version>). Then:

Terminal window
poly hooks update
git add poly.toml poly-hooks.lock
poly hooks install

Lefthook is configured on the consumer side, so nothing ships from the skif repository:

pre-commit:
commands:
skif:
glob: "{package.json,**/package.json,pnpm-workspace.yaml,skif.toml,.skif.toml}"
run: skif --no-js

Wrap the skif binary in a native_binary target and run bazel run //:skif, or bazel run //:skif -- --fix. Under bazel run the binary, and the npm package’s skif bin, first change to the directory you ran Bazel from, so relative paths resolve against the source tree instead of the runfiles tree. Under bazel test, --cache keeps its store in $TEST_TMPDIR/skif/. The Bazel guide covers fetching the release archives, bazel test inputs, what skif reads from BUILD and MODULE.bazel files, and its limits.

Run skif once at the workspace root, as a root script or a root task, not as a task of every package. See Turborepo, Nx and Lerna.

The @polylint/skif package is a native addon built with napi-rs for the Node.js lines that are not end-of-life (22, 24 and 26; see the Node.js release schedule) and Bun 1.x; older versions may work but are not supported. It is ESM only (from CommonJS use import(), or require() on Node 22.12+), has no install script, and downloads nothing at install time: one platform package per target is an optional dependency, so your package manager installs only the one that matches the machine: macOS, Linux (glibc and musl) and Windows, each on x64 and arm64.

import { lint, lintAsync, run } from "@polylint/skif";
const report = JSON.parse(lint("./my-monorepo", { production: true }));
console.log(report.summary);
const outcome = await lintAsync("./my-monorepo");
if (outcome.error) console.error(outcome.error.kind, outcome.error.message, outcome.error.path);
else console.log(JSON.parse(outcome.report).summary);
const exitCode = run(["--format", "json", "./my-monorepo"]);
  • lint(path, options?) lints the project containing path and returns the JSON report as a string. With { recursive: true } it lints every workspace and standalone package at or below path, like skif -r, and the report gains a roots array. It applies the CLI’s configuration checks ([lint] require-ignore-reasons, [js] tsconfig), writes no files and prints only the CLI’s warnings, to stderr. It blocks the event loop, so use lintAsync in a server. The options mirror the flags of the same name: noJs, production, failOnWarnings, ignoreRules, ignorePackages, ignoreDependencies, recursive, config (use that file and the files it extends instead of discovering skif.toml files) and noConfig (read no file). The options typeAware and noTypeAware were removed in 0.9.0 with type-aware analysis and are rejected with the message of the removed flags.
  • lintAsync(path, options?) does the same on a worker thread and resolves with { report } or, when the lint cannot run, { error: { kind, message, path? } }. kind is config, workspace, io, usage, ci-refusal or internal.
  • run(argv) runs the full command line (argv excludes the program name) and returns its exit code. Output streams to the process’s stdout and stderr. It never changes the process’s current directory, also under bazel run; the package’s skif bin does that before it calls run (Bazel).

Types ship in index.d.ts. Both lint and lintAsync read the configuration file the way the command line does.