kiira/skills/ci-integration/SKILL.md

Command-line interface for Kiira: validate TypeScript and JavaScript code fences in your Markdown docs.

---
name: ci-integration
description: >
  Gate CI on Markdown doc errors and keep examples current. Load when wiring
  `kiira check` into CI, choosing a reporter, or interpreting exit codes.
  Covers exit codes (0 clean, 1 doc errors, 2 config/runtime failure), the
  `github`/`json`/`pretty` reporters (the JSON `schemaVersion`, the GitHub
  step summary), previewing fixes with `--fix --dry-run`, the
  `AlemTuzlak/kiira@v1` composite
  action, plain exit-code-gated steps for any runner, `--entry` overriding
  `include`, and `--static`/`--raw` for clean log capture.
type: lifecycle
library: kiira
library_version: "0.4.0"
sources:
  - "AlemTuzlak/kiira:docs/content/02-cli/05-exit-codes.mdx"
  - "AlemTuzlak/kiira:docs/content/02-cli/03-reporters.mdx"
  - "AlemTuzlak/kiira:docs/content/06-ci/01-github-action.mdx"
  - "AlemTuzlak/kiira:docs/content/02-cli/04-fix.mdx"
  - "AlemTuzlak/kiira:docs/content/03-configuration/05-programmatic-api.mdx"
  - "AlemTuzlak/kiira:packages/cli/src/index.ts"
---

# Kiira — CI Integration

`kiira check` is gated by its exit code: `0` clean, `1` validation errors (docs have
type errors), `2` config/runtime failure (broken config, unresolved tsconfig).

## Setup

GitHub Actions — use the composite action (its reporter defaults to `github`, so
failures appear as inline PR annotations):

```yaml
- uses: AlemTuzlak/kiira@v1
  with:
    command: pnpm kiira check
    reporter: github
```

## Core Patterns

### Gate any CI runner by exit code

GitLab, CircleCI, Jenkins — it's the same check; the runner fails on non-zero:

```yaml
# example step
- run: pnpm kiira check --reporter github
```

### Distinguish setup failures from doc failures

```bash
pnpm kiira check; status=$?
if [ "$status" -eq 2 ]; then echo "::error::Kiira config/setup problem"; fi
if [ "$status" -eq 1 ]; then echo "::error::docs have type errors"; fi
```

### Capture machine-readable or clean output

```bash
pnpm kiira check --reporter json > kiira-report.json   # 1-based positions, first key is "schemaVersion"
pnpm kiira check --static --raw > kiira-report.txt      # no spinner, no ANSI color
```

### Read the JSON report by `schemaVersion`

The JSON reporter's first key is `schemaVersion` (currently `1`). Within a version fields are
only added, so ignore unknown fields and check `schemaVersion` before relying on a shape.

### Step summary and fix preview

With `--reporter github`, Kiira also appends a summary (files, snippets, errors, warnings and
the first errors) to the file named by `GITHUB_STEP_SUMMARY` when it is set. To see what
`--fix` would change without writing, run `--fix --dry-run`: it prints a diff and keeps the
exit code of the check, so it is safe in CI.

```bash
pnpm kiira check --fix --dry-run   # diff on stdout (stderr with --reporter json); nothing written
```

To run Kiira from a script or test, `check()` from `kiira-core` returns the same result as an object.

## Common Mistakes

### HIGH Not distinguishing exit code 2 from 1

Wrong:

```bash
kiira check || echo "docs have errors"   # also fires on a broken config (exit 2)
```

Correct:

```bash
kiira check; status=$?
[ "$status" -eq 2 ] && echo "config/setup problem"
[ "$status" -eq 1 ] && echo "docs have type errors"
```

Exit `2` is a setup problem, not a docs problem; conflating them misreports a broken config as "docs broken".

Source: docs/content/02-cli/05-exit-codes.mdx; packages/cli/src/index.ts

### MEDIUM Using the pretty reporter for CI annotations

Wrong:

```yaml
- run: pnpm kiira check --reporter pretty   # no inline PR annotations; compact by default
```

Correct:

```yaml
- run: pnpm kiira check --reporter github
# or use the composite action (reporter defaults to github)
```

Inline annotations come from the `github` reporter; `pretty` is compact human output (needs `--verbose` for full messages) and emits no workflow commands.

Source: docs/content/02-cli/03-reporters.mdx; docs/content/06-ci/01-github-action.mdx

### MEDIUM Assuming `--entry` appends to `include`

Wrong:

```bash
# config include is ["docs/**"]; expecting both docs and README to be checked
kiira check --entry README.md   # checks ONLY README.md
```

Correct:

```bash
kiira check --entry docs --entry README.md   # both, explicitly (repeatable)
```

`--entry` (and positional paths) override the `include` globs rather than adding to them.

Source: docs/content/02-cli/02-flags.mdx; packages/cli/src/entries.ts

### LOW Spinner/color noise in captured logs

Wrong:

```bash
pnpm kiira check > report.txt   # spinner frames + escape codes end up in the file
```

Correct:

```bash
pnpm kiira check --static --raw > report.txt
# or: pnpm kiira check --reporter json > report.json
```

The animated spinner and ANSI colors render fine in a TTY but pollute redirected logs.

Source: docs/content/02-cli/02-flags.mdx; packages/cli/src/spinner.ts

### MEDIUM Tension: auto-fix to green vs masking real errors

Running `kiira check --fix` in CI to make the job pass can hide a genuinely wrong
example. Keep `--fix` out of the gating step; run it locally, commit the result, and
let CI verify. See `authoring-and-debugging-fences/SKILL.md` § Common Mistakes.

## See also

- `getting-started/SKILL.md` — the check you gate is the same one you ran locally.
- `monorepo-and-frameworks/SKILL.md` — `packageMode` and `overrides` decide what CI validates.
- `editor-vscode/SKILL.md` — the editor and CI share `kiira.config.ts`.