eslint-formatter-gitlab

7.1.0 verified Sat Apr 25 auth: no javascript

ESLint formatter that outputs results as GitLab Code Quality reports (gl-codequality.json) and prints issues to the console with merge request links. Version 7.1.0, released under MIT, requires Node.js 20+ and ESLint 9+. Integrates seamlessly with GitLab CI/CD using predefined environment variables, auto-detecting project configuration. Unlike generic formatters, it directly produces the artifact format expected by GitLab's Code Quality feature, enabling inline annotations in merge requests. Maintained by Remco Haszing, with TypeScript type definitions included.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using require() on an ESM-only package (v7+).

fix

Switch to import or dynamic import(). If using CJS, use eslint-formatter-gitlab@6.

error Cannot find module 'eslint-formatter-gitlab' ↓

cause Using the full package name in eslint --format (should be just 'gitlab').

fix

Use 'npx eslint --format gitlab' instead of '--format eslint-formatter-gitlab'.

error Failed to load formatter 'gitlab': Could not find a declaration file for module 'eslint-formatter-gitlab'. ↓

cause TypeScript not finding types; missing @types/eslint or incorrect tsconfig.

fix

Install eslint types: npm i -D @types/eslint. Ensure tsconfig has 'moduleResolution': 'node16' or 'bundler'.

error Warning: Code Quality report not generated because CI_JOB_NAME environment variable is not set. ↓

cause Running outside GitLab CI or missing predefined environment variables.

fix

Run inside a GitLab CI job, or set CI_JOB_NAME manually for local testing (not recommended).

Warnings

breaking v7 dropped CommonJS support; requires ESM. ↓

fix Use ESM imports or upgrade to Node >= 20. For CJS, pin to v6.

breaking v7 requires ESLint 9. Not compatible with ESLint 8. ↓

fix Upgrade to ESLint 9 or use eslint-formatter-gitlab@6.

breaking v7 requires Node.js 20. Older Node versions break. ↓

fix Use Node.js >= 20.

gotcha Environment variable CI_CONFIG_PATH must point to the correct .gitlab-ci.yml path; defaults to '.gitlab-ci.yml'. ↓

fix Set CI_CONFIG_PATH if your CI config is at a non-default location.

gotcha Output file location is read from the 'codequality:report' artifact path inside the job definition; if misconfigured, the artifact may be missing. ↓

fix Ensure the job in .gitlab-ci.yml has 'artifacts: reports: codequality: ...' set.

gotcha The formatter uses process.cwd() if CI_PROJECT_DIR is not set; may cause relative path mismatches in CI. ↓

fix Set CI_PROJECT_DIR environment variable in CI jobs to the project root.

Install

npm install eslint-formatter-gitlab

yarn add eslint-formatter-gitlab

pnpm add eslint-formatter-gitlab

Imports

default (formatter function)
wrong
```
const formatter = require('eslint-formatter-gitlab')
```
correct
```
import formatter from 'eslint-formatter-gitlab'
```
ESM-only since v7; CommonJS require fails. Use dynamic import() if needed.
ESLint formatter name
wrong
```
eslint.loadFormatter('eslint-formatter-gitlab')
```
correct
```
eslint.loadFormatter('gitlab')
```
Use 'gitlab' as the formatter name, not the full package name.

TypeScript types

import type { LintResult } from 'eslint'
import formatter from 'eslint-formatter-gitlab'

Package ships TypeScript declarations; no separate type import needed.

Quickstart

Shows both GitLab CI job configuration and programmatic usage for generating Code Quality reports.

// .gitlab-ci.yml
eslint:
  image: node:22-alpine
  script:
    - npm ci
    - npx eslint --format gitlab .
  artifacts:
    reports:
      codequality: gl-codequality.json

// Programmatic use:
import { ESLint } from 'eslint';
import formatter from 'eslint-formatter-gitlab';

const eslint = new ESLint();
const results = await eslint.lintFiles(['src/']);
const output = await formatter(results);
// output contains Code Quality JSON and console text