GitHub Action

OKForest Validate runs the rules on every pull request: the OKF specification, OKForest’s conventions, and D2 and Mermaid diagram syntax. Each finding is annotated on its file and line, the job summary lists them all, and errors fail the check. It is the same code as npx okforest validate.

.github/workflows/okforest-validate.yml

name: OKForest Validate

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: okforest/validate-action@v1

No Node setup or install step is needed, and it runs on Linux, macOS, and Windows runners. okforest init writes this workflow for you.

To keep changes with errors out of main, make the validate check required in a branch ruleset (Settings → Rules → Rulesets → Require status checks to pass), with GitHub Actions as its source.

Inputs

Input	Default	What it does
path	.	The tree’s root folder, relative to the workspace.
fail-on	error	What fails the step: error, warning (errors or warnings), or never (report only).
diagrams	true	Check D2 and Mermaid diagram syntax. false skips the checks.
annotations	true	Annotate each finding on its file and line.
summary	true	List every finding in the job summary.

Outputs

Output	What it is
ok	true when there are no errors (warnings and info allowed).
errors, warnings, infos	How many findings of each severity.
report	Path to the JSON report: the same document as okforest validate --format json.

To keep the report with the run:

      - uses: okforest/validate-action@v1
        id: okf
        with:
          path: knowledge
          fail-on: never
      - uses: actions/upload-artifact@v7
        with:
          name: okf-report
          path: ${{ steps.okf.outputs.report }}

Diagram checks

Mermaid is bundled. D2 is about 32 MB, so it is downloaded only when the tree has a d2 block, verified against a pinned checksum, and cached for the rest of the job. If the download fails, for example on a runner without internet access, D2 diagrams are reported as not checked (info) and the rest of the validation runs as usual.

Annotations

GitHub shows at most 10 error, 10 warning, and 10 notice annotations per step, and 50 per job. The job summary always lists every finding, linked to its line.

Versions

@v1 follows the latest 1.x release. Pin a release (@v1.0.0) or a commit SHA for fully reproducible runs. See the releases.