gitlab-ci-lint

1.1.0 verified Fri May 01 auth: no javascript

Gitlab-ci-lint is a CLI tool and Node.js library to validate .gitlab-ci.yml files against a GitLab instance's CI lint API. The current stable version is 1.1.0, with a low release cadence. It supports custom GitLab URLs and personal access tokens, making it suitable for self-hosted GitLab. No official alternatives exist.

Common errors

error Error: Cannot find module 'gitlab-ci-lint' ↓

cause Package not installed or global install not in PATH.

fix

Run 'npm install -g gitlab-ci-lint' or install locally with 'npm install --save-dev gitlab-ci-lint'.

error TypeError: gitlabCILint.lintFile is not a function ↓

cause Using default export from ESM incorrectly or mixing require/import.

fix

Use 'import { lintFile } from 'gitlab-ci-lint'' or 'const { lintFile } = require('gitlab-ci-lint')' in CommonJS.

error Validation failed: 401 Unauthorized ↓

cause Invalid or missing GitLab personal access token.

fix

Provide a valid token via --token flag or GITLAB_TOKEN environment variable.

Warnings

gotcha The package requires a network connection to the GitLab instance; no offline linting. ↓

fix Ensure GitLab instance is reachable and token has 'api' scope.

gotcha Default export object (require('gitlab-ci-lint')) has a lintFile method; direct import of lintFile via ESM may fail if project uses CommonJS. ↓

fix Use default import or named import with ES modules; require('gitlab-ci-lint') works for CommonJS.

breaking Version 1.1.0 changed from CommonJS to ESM; breaking change for projects using require() without .mjs or 'type': 'module'. ↓

fix Use import instead of require, or set 'type': 'module' in package.json.

Install

npm install gitlab-ci-lint

yarn add gitlab-ci-lint

pnpm add gitlab-ci-lint

Imports

lintFile

wrong

const gitlabCILint = require('gitlab-ci-lint'); gitlabCILint.lintFile('.gitlab-ci.yml')

correct

import { lintFile } from 'gitlab-ci-lint'

ESM import uses named export; CommonJS require returns the whole module.

default
wrong
```
const gitlabCILint = require('gitlab-ci-lint').default
```
correct
```
import gitlabCILint from 'gitlab-ci-lint'
```
The package has both default and named exports; default export is a namespaced object.

lintFile

wrong

import gitlabCILint from 'gitlab-ci-lint'; gitlabCILint.lintFile

correct

import { lintFile } from 'gitlab-ci-lint'

Named import is preferred; default import also works but is less explicit.

Quickstart

Shows how to lint a .gitlab-ci.yml file using async/await with environment variables for URL and token.

import { lintFile } from 'gitlab-ci-lint';
const fs = require('fs'); // Node.js
const ymlContent = fs.readFileSync('.gitlab-ci.yml', 'utf8');
lintFile('.gitlab-ci.yml', process.env.GITLAB_URL ?? 'https://gitlab.com', process.env.GITLAB_TOKEN ?? '')
  .then(result => console.log('Status:', result.status))
  .catch(err => console.error('Lint failed:', err));