0007: Check records in CI

Context#

The build validates the shape of every record: a status outside the configured list or a date that is not a date fails it. It does not validate meaning. A supersedes entry can point at a record that does not exist, two files in one folder can share a number, a record can carry supersededBy while its status still says accepted, and an RFC can sit past its reviewBy date for months. None of this breaks the HTML, so none of it failed a pull request, and the build itself takes long enough that nobody runs it just to check a link.

Decision#

inkan check reads every record directly, without Astro, and runs a fixed set of rules over them. Problems that make the site wrong are errors and set the exit code to 1; problems that make it worse are warnings and only fail with --strict. The output names the file and the front matter line, so it reads like a linter. On GitHub Actions each problem is also emitted as an annotation, so it appears inline in the pull request. The CI files that inkan init creates run check before the build.

How to use it#

Run it#

1
npx inkan check

1
decisions/payments/adr/0003-use-stripe.md:9 error supersedes points to "payments/adr/0001-build-our-own-gateway", which does not exist, did you mean "payments/adr/0001-build-our-own-card-gateway"?
2
decisions/payments/adr/0003-use-stripe.md:6 warning author "jule" is not in _authors.yml, did you mean "jules"?
3

4
decisions/sre/_project.yml warning project "sre" has no owners
5

6
1 error, 2 warnings (41 records in 7 projects).

Each line is path:line level message. The path is relative to the folder you run in (or to the site root when the file is outside it), and the line points at the offending front matter key when there is one. Problems are grouped by file. With nothing to report the output is one line: No problems found (40 records in 7 projects).

init adds check to package.json, so npm run check does the same.

The rules#

Errors (the site would be wrong):

Warnings (the site is incomplete or misleading):

Both project rules skip projects that come from sources. Reference values are matched the way the site matches them: full id, short id (sre/adr/3), reference (SRE-ADR-0003) or file path; see Link records by path.

Exit codes#

JSON output#

1
npx inkan check --format json

1
{
2
  "ok": false,
3
  "errors": 1,
4
  "warnings": 1,
5
  "records": 41,
6
  "projects": 7,
7
  "problems": [
8
    {
9
      "level": "error",
10
      "rule": "missing-record",
11
      "message": "supersedes points to \"payments/adr/0001-build-our-own-gateway\", which does not exist, did you mean \"payments/adr/0001-build-our-own-card-gateway\"?",
12
      "file": "decisions/payments/adr/0003-use-stripe.md",
13
      "line": 9,
14
      "record": "payments/adr/0003-use-stripe"
15
    }
16
  ]
17
}

ok is true when there are no errors, regardless of warnings. line and record are absent when they do not apply (a project-owners problem has no record). The exit code follows the same rules as the text output, so a script can read the JSON and still rely on the status.

GitHub Actions annotations#

When GITHUB_ACTIONS=true, check prints one workflow command per problem after the report:

1
::error file=decisions/payments/adr/0003-use-stripe.md,line=9,title=inkan check (missing-record)::supersedes points to ...

GitHub turns these into annotations on the changed files in the pull request. Paths are relative to GITHUB_WORKSPACE (or the repository root); files outside the workspace and under node_modules, such as fetched sources, get no annotation. GitLab has no equivalent; the job log and the exit code carry the result there.

In the starter CI files#

inkan init writes a GitHub workflow and a GitLab pipeline that run check before the build on every pull or merge request and on the default branch:

1
- uses: actions/checkout@v4
2
  with:
3
    fetch-depth: 0 # full history for "Last updated"
4
- uses: actions/setup-node@v4
5
  with:
6
    node-version: 22
7
- run: npm install
8
- run: npx inkan check # broken links, duplicate numbers, unknown statuses … as PR annotations
9
- run: npm run build

1
variables:
2
  GIT_DEPTH: 0 # full history for "Last updated"
3

4
build:
5
  script:
6
    - npm install
7
    - npx inkan check
8
    - npm run build

A failing check stops the job before the build runs. Add --strict to the step when you want warnings to block merges too. The full history (fetch-depth: 0, GIT_DEPTH: 0) is for the dates and authors inferred from git, not for check. See GitHub and GitLab Pages.

What it does not check#

check reads the front matter and the folder layout. It does not render Markdown, so broken relative links in the body, missing images and Mermaid syntax errors are left to the build, and it does not validate inkan.config.* beyond loading it (the schema runs on load, so a bad config still fails). Content from repo sources is included: missing clones are fetched first, with progress on stderr. See Validate config and content at build time for what the build covers.

Consequences#

• Reference and numbering mistakes fail a pull request within seconds, with the file and line, and show up inline on GitHub.
• Errors and warnings are separate by design: a project without owners should not block a hotfix to a record, but --strict is there for repositories that want a clean log.
• The rule set is fixed. There is no configuration to disable one rule; keep the warning level in mind when a rule does not fit your process.
• check is a second validator next to the build, with its own messages. The two agree on what a valid status and date are, because both read the same config, but check is stricter about dates (the build accepts anything Date can parse).
• Records in repo sources are checked but cannot be fixed here; the fix goes to the source repository.