ESLint Formatter for GitLab

Show ESLint results directly in the GitLab code quality results.

Table of Contents

• Installation
• Usage
  • Programmatic usage
• Example
• Configuration
• Compatibility
• License

Installation

Install eslint and eslint-formatter-gitlab using your package manager.

npm install --save-dev eslint eslint-formatter-gitlab

Usage

Define a GitLab job to run eslint.

.gitlab-ci.yml:

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

The formatter automatically detects a GitLab CI environment. It detects where to output the code quality report based on the GitLab configuration file. It also prints ESLint issues to the GitLab job console with links.

Programmatic usage

The formatter can be used programmatically using ESLint.

import { ESLint } from 'eslint'

const eslint = new ESLint()
const formatter = await eslint.loadFormatter('gitlab')
const results = await eslint.lintFiles([])
const formatted = await formatter.format(results)

Example

An example of the results can be seen in Merge Request !1 of eslint-formatter-gitlab itself.

Configuration

ESLint formatters don’t take any configuration options. eslint-formatter-gitlab uses GitLab’s predefined environment variables to configure the output. The following predefined environment variables are used:

• CI_COMMIT_SHORT_SHA to generate a link in the console output.
• CI_CONFIG_PATH to determine the GitLab CI configuration file to use. (Default: .gitlab-ci.yml)
• CI_JOB_NAME to determine which job configuration to read the code quality report path from.
• CI_PROJECT_DIR To determine relative paths. (Default: current working directory)
• CI_PROJECT_URL to generate a link in the console output.

In addition, the environment variable ESLINT_CODE_QUALITY_REPORT is used to override the location to store the code quality report.

Compatibility

This package is compatible with Node.js 20 or greater and ESLint 9 or greater.

License

MIT © Remco Haszing