# ESLint Formatter for GitLab

[![gitlab pipeline](https://gitlab.com/remcohaszing/eslint-formatter-gitlab/badges/main/pipeline.svg)](https://gitlab.com/remcohaszing/eslint-formatter-gitlab/-/pipelines)
[![code coverage](https://gitlab.com/remcohaszing/eslint-formatter-gitlab/badges/main/coverage.svg)](https://gitlab.com/remcohaszing/eslint-formatter-gitlab/-/pipelines)
[![sponsors](https://img.shields.io/github/sponsors/remcohaszing)](https://github.com/sponsors/remcohaszing)
[![npm version](https://img.shields.io/npm/v/eslint-formatter-gitlab)](https://www.npmjs.com/package/eslint-formatter-gitlab)
[![npm downloads](https://img.shields.io/npm/dm/eslint-formatter-gitlab)](https://www.npmjs.com/package/eslint-formatter-gitlab)

<img alt="" height="256" src="https://gitlab.com/remcohaszing/eslint-formatter-gitlab/-/avatar">

Show ESLint results directly in the
[GitLab code quality](https://docs.gitlab.com/ee/ci/testing/code_quality.html) results.

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
  - [Programmatic usage](#programmatic-usage)
- [Example](#example)
- [Configuration](#configuration)
- [Compatibility](#compatibility)
- [License](#license)

## Installation

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

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

## Usage

Define a GitLab job to run `eslint`.

`.gitlab-ci.yml`:

```yaml
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.

```js
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](https://gitlab.com/remcohaszing/eslint-formatter-gitlab/merge_requests/1) of
`eslint-formatter-gitlab` itself.

## Configuration

ESLint formatters don’t take any configuration options. `eslint-formatter-gitlab` uses GitLab’s
[predefined environment variables](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html)
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](LICENSE.md) © [Remco Haszing](https://gitlab.com/remcohaszing)