CI recipes: GitLab CI, Jenkins, pre-commit

docmeta is a plain CLI with a stable exit-code contract, so it drops into any CI system that can run a Node.js command and read its exit code. This page gives complete, runnable recipes for three common setups beyond GitHub Actions.

Every recipe relies on the same contract: docmeta exits 0 when all files are valid, 1 when one or more files fail validation, and 2 on an operational or usage error. Each platform fails the job on a non-zero exit, so the gate is enforced without extra scripting. For the full definition, see Exit codes & PR annotations.

GitLab CI

Add a job to .gitlab-ci.yml. The official node:20 image already has Node.js and npx, so the job is a single script line. GitLab marks the job failed on any non-zero exit, which is exactly docmeta’s contract.

Explicit targets
Targets from docmeta.config.yaml

validate-metadata:
  stage: test
  image: node:20
  script:
    - npx -y docmeta validate "docs/**/*.md"

validate-metadata:
  stage: test
  image: node:20
  # Targets come from paths: in docmeta.config.yaml at the repo root.
  script:
    - npx -y docmeta validate

If you collect machine-readable reports, capture the JSON output as an artifact:

validate-metadata:
  stage: test
  image: node:20
  script:
    - npx -y docmeta validate "docs/**/*.md" --format json | tee docmeta-report.json
  artifacts:
    when: always
    paths:
      - docmeta-report.json

tee writes the report to a file while passing docmeta’s exit code through, so the job still fails on validation errors. when: always keeps the artifact even when the job fails.

Jenkins

Use a declarative Jenkinsfile stage. A sh step fails the stage when the command returns a non-zero exit code, so the metadata gate works with no explicit status check.

pipeline {
  agent any
  stages {
    stage('Validate metadata') {
      steps {
        // Requires Node.js 24+ on the agent (npx ships with npm).
        sh 'npx -y docmeta validate "docs/**/*.md"'
      }
    }
  }
}

If your agents do not have Node.js 24+ on the PATH, provision it first. With the NodeJS plugin installed and a tool named node24 configured in Manage Jenkins → Tools, wrap the stage:

pipeline {
  agent any
  tools {
    nodejs 'node24'
  }
  stages {
    stage('Validate metadata') {
      steps {
        sh 'npx -y docmeta validate "docs/**/*.md"'
      }
    }
  }
}

To archive a machine-readable report, write JSON to a file and archive it. Run docmeta in a way that preserves its exit code:

stage('Validate metadata') {
  steps {
    sh 'npx -y docmeta validate "docs/**/*.md" --format json | tee docmeta-report.json'
  }
  post {
    always {
      archiveArtifacts artifacts: 'docmeta-report.json', allowEmptyArchive: true
    }
  }
}

pre-commit

A pre-commit hook catches metadata errors before they reach CI. Because there is no published hook repo, define a local hook in .pre-commit-config.yaml that runs docmeta through npx. The hook fails the commit when docmeta returns a non-zero exit code.

Validate staged files
Validate the whole repo

repos:
  - repo: local
    hooks:
      - id: docmeta
        name: docmeta validate
        entry: npx -y docmeta validate
        language: system
        # Run only on Markdown; pre-commit appends the staged file paths.
        files: \.md$

With entry: npx -y docmeta validate and no positional paths in the entry, pre-commit appends the list of staged, matched files as arguments, so each commit validates exactly what changed. language: system tells pre-commit to use the npx already on your PATH rather than managing its own environment; Node.js 24+ must be installed locally.

repos:
  - repo: local
    hooks:
      - id: docmeta
        name: docmeta validate
        entry: npx -y docmeta validate "docs/**/*.md"
        language: system
        pass_filenames: false
        always_run: true

Set pass_filenames: false so pre-commit does not append staged paths, and docmeta validates the fixed glob in the entry instead. always_run: true makes the hook run even when no matching files are staged.

Install and test the hook:

pre-commit install              # wire the hook into git
pre-commit run docmeta --all-files   # run it across the repo once

Next steps

Exit codes & PR annotationsThe exact 0/1/2 contract and the pretty, json, and github output shapes.

GitHub Actions recipeThe ready-made GitHub Actions workflow with inline PR annotations.