Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/xantorres/repokernel/llms.txt

Use this file to discover all available pages before exploring further.

Every pull request that touches a RepoKernel-governed repo can be automatically validated before merge. The official rk-validate composite GitHub Action installs Node 20 and repokernel, runs rk validate, posts a sticky PR comment with severity counts, emits inline file annotations on every finding, and uploads the full JSON findings as a workflow artifact. Repos without repokernel.config.yaml are skipped gracefully — the action exits neutral so you can add it to an org-wide reusable workflow without blocking teams that haven’t adopted RepoKernel yet.

​
Quick start

1

Add the workflow file

Create .github/workflows/repokernel.yml in your repository:
name: RepoKernel
on:
  pull_request:
permissions:
  contents: read
  pull-requests: write
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: xantorres/repokernel/.github/actions/rk-validate@v1
        with:
          fail-on: P0,P1
          version: 1.33.1
That’s the complete workflow. The action handles Node setup and repokernel installation itself — no matrix, no separate toolchain step.
2

Set permissions

The pull-requests: write permission is required to post and update the sticky PR comment. If you set comment-on-pr: false, you can drop that permission and keep only contents: read.
3

Pin versions for reproducibility

Pin both the action ref and the version input together so upgrades are explicit and auditable. See the Pinning section for the exact syntax.

​
Inputs

InputDefaultPurpose
fail-onP0,P1Severity threshold for failure. Comma list collapses to least-severe. Use P0 for warn-only, P0,P1,P2 for strict.
working-directory.Directory containing repokernel.config.yaml. Set when RepoKernel governs a sub-tree. Must resolve under GITHUB_WORKSPACE.
versionlatestnpm version of repokernel. Pin to a specific release (e.g. 1.33.1) for reproducible CI.
json-artifacttrueUpload rk-findings.json as a workflow artifact (14-day retention).
comment-on-prtruePost a sticky comment with severity counts and the first 25 findings. Requires pull-requests: write.
treat-runtime-asfailureHow to treat EXIT_RUNTIME (2) — tool or environment crash, not a project-state breach. failure blocks the PR; neutral exits 0 with stderr surfaced in the step summary.
Set treat-runtime-as: neutral when your CI infrastructure is flaky — npm install hiccups or transient runtime crashes won’t block unrelated PRs, while genuine project-state findings (exit 1) still fail the check.

​
Outputs

OutputDescription
exit-code0 on success or skip; 1 on findings breach; 2 on runtime error.
findings-jsonPath to rk-findings.json (empty string when skipped).

​
Behavior matrix

Repo staterk validate exitAction result
repokernel.config.yaml absentnot runNeutral exit 0; skip message in summary; no comment; no artifact
Validate runs cleanly0Exit 0; “OK” summary and comment
Validate finds breaches1Exit 1; GitHub annotations; summary table; PR comment
Validate fails to run2Exit 2; stderr in summary. Set treat-runtime-as: neutral to convert to neutral exit 0.

​
Pinning

Floating @v1 or version: latest means a new release can change behavior on existing PRs without warning. For reproducible CI, always pin both the action ref and the npm version to the same release and bump them together.
Pin both the action ref and the version input: 
- uses: xantorres/repokernel/.github/actions/rk-validate@v1.33.1
  with:
    fail-on: P0,P1
    version: 1.33.1   # do not float
When you upgrade to a new release, bump both refs in the same commit.

​
Required permissions

PermissionWhy
contents: readRead the PR’s file tree.
pull-requests: writePost and update the sticky PR comment. Only required when comment-on-pr: true (the default).

​
Using the exit code in downstream steps

The action already exits non-zero on EXIT_FINDINGS, so most workflows don’t need to inspect exit-code directly. It’s useful when you want to chain additional reporting — for example, uploading findings to a SARIF dashboard: 
- id: rk
  uses: xantorres/repokernel/.github/actions/rk-validate@v1
- name: Block on findings
  if: steps.rk.outputs.exit-code != '0'
  run: |
    echo "RepoKernel findings present — see PR comment" >&2
    exit 1

​
Self-hosting and forks

The action is a single composite YAML — no marketplace listing, nothing to compile, nothing to publish. Point uses: at any fork or feature branch directly: 
- uses: my-org/repokernel/.github/actions/rk-validate@my-feature-branch

​
Alternative for non-GitHub CI

If you’re running on GitLab CI, Jenkins, CircleCI, or another platform, the equivalent invocation is: 
npm install -g repokernel@1.33.1
rk validate --json --fail-on P0,P1 > rk-findings.json
echo $?  # 0 = ok / 1 = findings / 2 = runtime
Wrap your platform’s neutral-skip and annotation conventions around the JSON output. The exit codes are stable: 0 clean, 1 findings breach, 2 runtime error. See the action source for a complete working reference.

​
Known limitations

  • No per-rule overrides yet. A single fail-on threshold applies to the whole report. Per-rule severity overrides are on the product backlog.
  • Best-effort line annotations. JSON findings include file and a stable line fallback when the source file is available. Some project-level findings still point at the nearest owning file rather than an exact field.
  • Public npm install per run. The action installs repokernel from npm on every run — there is no Docker image. For air-gapped CI, fork the action and replace the install step with a private mirror.

Build docs developers (and LLMs) love

Get started for freeTalk to us