Checking in CI

eidos check gives the same review on a laptop, from an agent, and in a pipeline. Run it on every merge request and the things that are wrong on any reading never reach the default branch: a broken link, a missing or duplicate id (two branches can draw the same one), a variant the collection does not declare, frontmatter that does not parse.

What fails, and what only shows

• An error fails the job. It is wrong whatever the author meant.
• A warning never fails it, unless the root is strict. A missing or out-of-order section, a missing property: departing from a template is often deliberate, so a red build over it is noise. The warning shows on the merge request against the file it names, as a GitHub annotation or in GitLab’s Code Quality report, for the reviewer to weigh.
• The root decides, not the pipeline. A root whose owners made warnings fail (eidos setup --strict on, kept in .eidos/plugins/eidosmd/settings.yaml) fails on them in CI as it does on a laptop. The job adds no policy of its own.

One command

eidos ci --write github    # .github/workflows/eidos-check.yml
eidos ci --write gitlab    # an eidos-check job in .gitlab-ci.yml
eidos ci                   # print both and write nothing

The file is written at the top of the Git repository, and the job runs the check with --root set to the root’s folder from there, so a root in a sub-folder (docs/Blueprints) works as is. The job installs the CLI with npx, pinned to the version that wrote it; after upgrading the CLI, run the command again to move the pin.

A second run refreshes what the first wrote rather than adding another. In .gitlab-ci.yml the job sits between # eidos:ci:start and # eidos:ci:end, and every other line of the file stays as it was. A workflow at that path that eidos ci did not write, or an eidos-check job of your own outside the markers, is left alone and the command says so.

GitHub

.github/workflows/eidos-check.yml

name: Eidos check
on: pull_request
permissions:
  contents: read
jobs:
  eidos-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx --yes eidosmd@latest check --root Blueprints --format github

--format github prints one workflow command per finding (::error file=Blueprints/specs/login.md,line=12::link-broken: …), which GitHub draws as an annotation on the pull request’s files and lists on the run’s summary.

GitLab

.gitlab-ci.yml

eidos-check:
  image: node:22
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - npx --yes eidosmd@latest check --root Blueprints --format codequality > gl-code-quality-report.json
  artifacts:
    when: always
    reports:
      codequality: gl-code-quality-report.json

--format codequality prints a Code Quality report: an error is major, a warning minor, each with its file and line and a fingerprint that stays the same from run to run, so the merge request shows what it introduced and what it resolved. The findings also go to the job’s log. when: always keeps the report when an error fails the job.

Stages

The job takes GitLab’s default stage, test. If your file lists stages without test, add test to the list: a later eidos ci --write gitlab rewrites the job’s block, so a stage set inside it would not last.

The formats on their own

eidos check --format github
eidos check --format codequality > gl-code-quality-report.json

Both keep eidos check’s exit code: 0 with no errors, 1 with one (or with a warning on a strict root), 2 when the check could not run. Paths are relative to the Git top level, or to the working directory outside a repository. A finding that knows its line (a broken link, a heading) points at it; any other points at the file’s first line. --json is unchanged and carries the same line where there is one.

eidos check → · eidos ci →