gitlab-ci-lint

library1.1.0jsnpmunverified

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.

devops

npm install gitlab-ci-lint

github ↗package ↗

INSTALL

IMPORT

SIG · GITLAB-CI-LINT

gitlab-ci-lint

devopsjavascriptv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

lintFile

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

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

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

default

✓ import gitlabCILint from 'gitlab-ci-lint'

✗ const gitlabCILint = require('gitlab-ci-lint').default

The package has both default and named exports; default export is a namespaced object.

lintFile

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

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

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

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));

gitlab-ci-lint --version

Debug

Known issues

gotchaThe package requires a network connection to the GitLab instance; no offline linting.

fix

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

affects: >=1.0.0

gotchaDefault 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.

affects: >=1.0.0

breakingVersion 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.

affects: >=1.1.0

Errors

Common errors & fixes

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

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'.

TypeError: gitlabCILint.lintFile is not a function

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.

Validation failed: 401 Unauthorized

Invalid or missing GitLab personal access token.

fix

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

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/BuBuaBu/gitlab-ci-lint ↗

packagehttps://www.npmjs.com/package/gitlab-ci-lint ↗