{"id":19641,"library":"eslint-formatter-gitlab","title":"eslint-formatter-gitlab","description":"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.","status":"active","version":"7.1.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","eslint","eslint-formatter","eslintformatter","gitlab","gitlab-ci","typescript"],"install":[{"cmd":"npm install eslint-formatter-gitlab","lang":"bash","label":"npm"},{"cmd":"yarn add eslint-formatter-gitlab","lang":"bash","label":"yarn"},{"cmd":"pnpm add eslint-formatter-gitlab","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for ESLint formatter API (>=9)","package":"eslint","optional":false}],"imports":[{"note":"ESM-only since v7; CommonJS require fails. Use dynamic import() if needed.","wrong":"const formatter = require('eslint-formatter-gitlab')","symbol":"default (formatter function)","correct":"import formatter from 'eslint-formatter-gitlab'"},{"note":"Use 'gitlab' as the formatter name, not the full package name.","wrong":"eslint.loadFormatter('eslint-formatter-gitlab')","symbol":"ESLint formatter name","correct":"eslint.loadFormatter('gitlab')"},{"note":"Package ships TypeScript declarations; no separate type import needed.","wrong":null,"symbol":"TypeScript types","correct":"import type { LintResult } from 'eslint'\nimport formatter from 'eslint-formatter-gitlab'"}],"quickstart":{"code":"// .gitlab-ci.yml\neslint:\n  image: node:22-alpine\n  script:\n    - npm ci\n    - npx eslint --format gitlab .\n  artifacts:\n    reports:\n      codequality: gl-codequality.json\n\n// Programmatic use:\nimport { ESLint } from 'eslint';\nimport formatter from 'eslint-formatter-gitlab';\n\nconst eslint = new ESLint();\nconst results = await eslint.lintFiles(['src/']);\nconst output = await formatter(results);\n// output contains Code Quality JSON and console text","lang":"typescript","description":"Shows both GitLab CI job configuration and programmatic usage for generating Code Quality reports."},"warnings":[{"fix":"Use ESM imports or upgrade to Node >= 20. For CJS, pin to v6.","message":"v7 dropped CommonJS support; requires ESM.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Upgrade to ESLint 9 or use eslint-formatter-gitlab@6.","message":"v7 requires ESLint 9. Not compatible with ESLint 8.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Use Node.js >= 20.","message":"v7 requires Node.js 20. Older Node versions break.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Set CI_CONFIG_PATH if your CI config is at a non-default location.","message":"Environment variable CI_CONFIG_PATH must point to the correct .gitlab-ci.yml path; defaults to '.gitlab-ci.yml'.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the job in .gitlab-ci.yml has 'artifacts: reports: codequality: ...' set.","message":"Output file location is read from the 'codequality:report' artifact path inside the job definition; if misconfigured, the artifact may be missing.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set CI_PROJECT_DIR environment variable in CI jobs to the project root.","message":"The formatter uses process.cwd() if CI_PROJECT_DIR is not set; may cause relative path mismatches in CI.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Switch to import or dynamic import(). If using CJS, use eslint-formatter-gitlab@6.","cause":"Using require() on an ESM-only package (v7+).","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"},{"fix":"Use 'npx eslint --format gitlab' instead of '--format eslint-formatter-gitlab'.","cause":"Using the full package name in eslint --format (should be just 'gitlab').","error":"Cannot find module 'eslint-formatter-gitlab'"},{"fix":"Install eslint types: npm i -D @types/eslint. Ensure tsconfig has 'moduleResolution': 'node16' or 'bundler'.","cause":"TypeScript not finding types; missing @types/eslint or incorrect tsconfig.","error":"Failed to load formatter 'gitlab': Could not find a declaration file for module 'eslint-formatter-gitlab'."},{"fix":"Run inside a GitLab CI job, or set CI_JOB_NAME manually for local testing (not recommended).","cause":"Running outside GitLab CI or missing predefined environment variables.","error":"Warning: Code Quality report not generated because CI_JOB_NAME environment variable is not set."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}