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 project 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 project decides, not the pipeline. A project 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 project’s folder from there, so a project in a sub-folder (docs/Blueprints) works as is. The job installs the CLI with the install script, with no Node to set up: the project’s pin when it has one (eidos version pin), else the version that wrote the job (EIDOS_VERSION below). A failed download fails the step. Without a pin, run the command again after upgrading the CLI to move the version.

The job runs only when a merge request changes a file in the project’s folder (paths on GitHub, changes on GitLab), so a merge request over code alone starts no job; a project at the top of the repository runs it on every one.

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:
    paths:
      - "Blueprints/**"
permissions:
  contents: read
jobs:
  eidos-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://eidosmd.com/install -o /tmp/eidos-install && EIDOS_VERSION=0.17.1 sh /tmp/eidos-install
      - run: eidos 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: buildpack-deps:bookworm
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
      changes:
        - "Blueprints/**/*"
  script:
    - curl -fsSL https://eidosmd.com/install -o /tmp/eidos-install && EIDOS_VERSION=0.17.1 EIDOS_INSTALL_DIR=/usr/local/bin sh /tmp/eidos-install
    - eidos 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 project), 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 →