{"id":25627,"library":"gitlab-ci-lint","title":"gitlab-ci-lint","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/BuBuaBu/gitlab-ci-lint","tags":["javascript","gitlab","gitlab-ci","lint",".gitlab-ci.yml"],"install":[{"cmd":"npm install gitlab-ci-lint","lang":"bash","label":"npm"},{"cmd":"yarn add gitlab-ci-lint","lang":"bash","label":"yarn"},{"cmd":"pnpm add gitlab-ci-lint","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM import uses named export; CommonJS require returns the whole module.","wrong":"const gitlabCILint = require('gitlab-ci-lint'); gitlabCILint.lintFile('.gitlab-ci.yml')","symbol":"lintFile","correct":"import { lintFile } from 'gitlab-ci-lint'"},{"note":"The package has both default and named exports; default export is a namespaced object.","wrong":"const gitlabCILint = require('gitlab-ci-lint').default","symbol":"default","correct":"import gitlabCILint from 'gitlab-ci-lint'"},{"note":"Named import is preferred; default import also works but is less explicit.","wrong":"import gitlabCILint from 'gitlab-ci-lint'; gitlabCILint.lintFile","symbol":"lintFile","correct":"import { lintFile } from 'gitlab-ci-lint'"}],"quickstart":{"code":"import { lintFile } from 'gitlab-ci-lint';\nconst fs = require('fs'); // Node.js\nconst ymlContent = fs.readFileSync('.gitlab-ci.yml', 'utf8');\nlintFile('.gitlab-ci.yml', process.env.GITLAB_URL ?? 'https://gitlab.com', process.env.GITLAB_TOKEN ?? '')\n  .then(result => console.log('Status:', result.status))\n  .catch(err => console.error('Lint failed:', err));","lang":"typescript","description":"Shows how to lint a .gitlab-ci.yml file using async/await with environment variables for URL and token."},"warnings":[{"fix":"Ensure GitLab instance is reachable and token has 'api' scope.","message":"The package requires a network connection to the GitLab instance; no offline linting.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use default import or named import with ES modules; require('gitlab-ci-lint') works for CommonJS.","message":"Default export object (require('gitlab-ci-lint')) has a lintFile method; direct import of lintFile via ESM may fail if project uses CommonJS.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use import instead of require, or set 'type': 'module' in package.json.","message":"Version 1.1.0 changed from CommonJS to ESM; breaking change for projects using require() without .mjs or 'type': 'module'.","severity":"breaking","affected_versions":">=1.1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'npm install -g gitlab-ci-lint' or install locally with 'npm install --save-dev gitlab-ci-lint'.","cause":"Package not installed or global install not in PATH.","error":"Error: Cannot find module 'gitlab-ci-lint'"},{"fix":"Use 'import { lintFile } from 'gitlab-ci-lint'' or 'const { lintFile } = require('gitlab-ci-lint')' in CommonJS.","cause":"Using default export from ESM incorrectly or mixing require/import.","error":"TypeError: gitlabCILint.lintFile is not a function"},{"fix":"Provide a valid token via --token flag or GITLAB_TOKEN environment variable.","cause":"Invalid or missing GitLab personal access token.","error":"Validation failed: 401 Unauthorized"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}