Гид по технологиям

Расшаривание конфигурации ESLint через приватный npm-реестр GitLab

• 8 min read • DevOps • Обновлено 29 Nov 2025
ESLint: конфиг через приватный npm в GitLab
ESLint: конфиг через приватный npm в GitLab

Важное: используйте project-level токены для CI и держите секреты в переменных GitLab CI/CD. Проектный endpoint обязателен для публикации, а instance-level — удобен для установки зависимостей.

Графика с логотипами GitLab и ESLint рядом

Быстрые ссылки

  • Начало работы
  • Создание конфигурации ESLint
  • Аутентификация в npm-реестре
  • Публикация в npm-реестр GitLab
  • Установка пакетов из реестра
  • Использование пакетов в CI
  • Резюме

Введение

ESLint статически анализирует JavaScript/TypeScript-код, находит ошибки и предлагает фиксить стили. Общий конфиг позволяет поддерживать единые правила по всем проектам команды и снизить дублирование. В статье показано, как создать пакет с конфигом ESLint и сделать его доступным через приватный npm-реестр GitLab.

Кому это нужно: тимлидам, разработчикам и инженерам CI, которые хотят централизовать правила линтинга и упростить их распространение.

Ключевая идея в одной строке: положите конфиг в npm-пакет, опубликуйте в GitLab Packages, подключите в projects как devDependency.

Начало работы

ESLint допускает любой npm-пакет в роли плагина или шаред-конфига — точкой входа пакета должен быть экспорт объекта конфигурации ESLint.

  1. Создайте новый проект в GitLab, который будет держать ваш пакет-конфиг.
  2. Клонируйте репозиторий локально.
  3. Добавьте package.json, который описывает npm-пакет.

Пример package.json для конфигурации (замените значения на свои):

{
  "name": "@example-group/eslint-config",
  "author": "Example Author",
  "description": "An example description",
  "version": "1.1.0",
  "main": ".eslintrc.js",
  "peerDependencies": {
    "eslint": ">=7"
  }
}

Обратите внимание на формат имени пакета: “@scope/name”. Scope должен соответствовать namespace в GitLab (например @group/project). Символ @ создаёт область (scope), которую мы потом будем привязывать к приватному реестру GitLab.

Поле “main” указывает файл с конфигурацией ESLint — в примере это .eslintrc.js. ESLint указан в peerDependencies: это значит, что проекты, подключающие ваш пакет, должны сами иметь eslint в своих зависимостях.

Создание конфигурации ESLint

Создайте файл конфигурации ESLint в корне репозитория. Он должен совпадать с указанием в “main” package.json. Вот минимальный пример файла .eslintrc.js:

module.exports = {
  "extends": ["eslint:recommended"],
  "rules": {
    "comma-dangle": ["error", "never"],
    "indent": ["error", "tab", {"SwitchCase": 1}],
    "max-classes-per-file": ["error", 1]
  }
};

Пояснение к правилам в примере:

  • comma-dangle: запрещает висячие запятые;
  • indent: требует табы вместо пробелов и корректирует отступ для case внутри switch;
  • max-classes-per-file: ограничивает число именованных классов в файле одному.

Советы по разработке конфига:

  • Начните с “eslint:recommended” или базовых пресетов (Airbnb, Standard) и наращивайте правила по мере нужды.
  • Документируйте каждое правило в README (почему включено/исключено).
  • Разделяйте правила для разных сред (browser, node) в отдельных конфигурациях, если проекты у вас разнородные.

Аутентификация в npm-реестре GitLab

Перед публикацией настройте npm на использование приватного реестра GitLab. Для этого потребуется Personal Access Token или project access token с нужными скоупами.

  1. В правом верхнем углу GitLab нажмите на иконку профиля → Preferences → Access Tokens.
  2. Создайте токен с правами read_registry и write_registry (для публикации у вас должен быть write_registry).
  3. Скопируйте значение токена — после сохранения оно больше не будет доступно.

Скриншот создания токена доступа в GitLab

Далее подключите npm к приватному реестру (пример для instance-level реестра):

npm config set @example-group:registry https://gitlab.example.com/api/v4/packages/npm/
npm config set -- '//gitlab.example.com/api/v4/packages/npm/:_authToken' "$API_TOKEN"
  • Первый вызов указывает npm, что пакеты из scope @example-group нужно брать из приватного реестра GitLab.
  • Второй задаёт токен для аутентификации. Замените $API_TOKEN на созданный токен.

Важно: для каждого приватного scope нужен свой authToken. Если вы работаете в нескольких группах — настройте scope под каждую из них.

Публикация в npm-реестр GitLab

Для установки достаточно instance-level endpoint, а для публикации нужно использовать project-level API endpoint. Project-level URL привязан к конкретному проекту и выглядит так:

https://gitlab.example.com/api/v4/projects//packages/npm/

Настройка npm для публикации в конкретный проект (при условии, что токен имеет write_registry для этого проекта):

npm config set -- '//gitlab.example.com/api/v4/projects//packages/npm/:_authToken' "$API_TOKEN"

Замените на ID проекта, который выводится рядом с названием проекта в GitLab.

Добавьте в package.json publishConfig, чтобы npm publish отправлял пакет в GitLab, а не в npmjs.com:

{
  "publishConfig": {
    "@example-group:registry": "https://gitlab.example.com/api/v4/projects//packages/npm/"
  }
}

После этого выполните:

npm publish

В интерфейсе GitLab ваш пакет появится в разделе “Packages & Registries” проекта.

Скриншот реестра пакетов GitLab

Примечание: нельзя перезаписывать уже опубликованные версии. Для каждого релиза используйте новую версию (обновляйте поле version в package.json).

Установка пакетов из реестра

Проекты, которые будут использовать ваш конфиг, должны настроить npm так, чтобы пакеты из вашего scope брались из приватного реестра. Если использован instance-level endpoint (api/v4/packages/npm/), достаточно настроить scope один раз.

Пример package.json в проекте-потребителе:

{
  "name": "demo",
  "version": "1.1.0",
  "devDependencies": {
    "@example-group/eslint-config": "^1.1",
    "eslint": "^7.2"
  },
  "scripts": {
    "lint": "eslint ."
  },
  "eslintConfig": {
    "extends": [
      "@example-group/eslint-config"
    ]
  }
}

Рекомендации:

  • Подключайте конфиг как devDependency, чтобы он не попадал в production-сборку.
  • Убедитесь, что проект также имеет зависимость eslint нужной версии (peerDependency в вашем пакете).
  • Для monorepo можно использовать workspace-специфику или ссылку на локальный пакет в режиме разработки.

Использование пакетов в CI

В CI нужно лишь обеспечить, чтобы npm мог аутентифицироваться в реестре перед установкой зависимостей.

Пример .gitlab-ci.yml для запуска ESLint в пайплайне:

stages:
  - lint

lint:
  stage: lint
  image: node:14
  script:
    - npm config set @example-group:registry https://gitlab.example.com/api/v4/packages/npm/
    - npm config set -- '//gitlab.example.com/api/v4/packages/npm/:_authToken' "${API_TOKEN}"
    - npm ci
    - npm run lint -- --cache
  cache:
    key: $CI_COMMIT_REF_SLUG
    paths:
      - .eslintcache
      - node_modules/

Подключите переменную CI/CD (API_TOKEN) в настройках проекта в GitLab → Settings → CI/CD → Variables. Для безопасности установите защиту и masked, если это нужно.

Если вы планируете публиковать из CI, используйте project-level токен с write_registry и автоматизируйте шаг increment-version (см. раздел «Методика версионирования» ниже).

Методика версионирования и релизов

Чтобы поддерживать корректные релизы и автоматизацию, придерживайтесь простого процесса:

  1. Пробел регистрируйте правила семантического версионирования (SemVer): мажорные — breaking changes, минорные — новые правила, патчи — исправления.
  2. Автоматизируйте bump версии в CI или используйте релизные ветки (release/*). Примеры инструментов: npm version, standard-version, semantic-release.
  3. Перед npm publish в CI убедитесь, что версия отличается от уже опубликованной.
  4. Тегируйте релиз в Git (git tag vX.Y.Z) и публикуйте тег в GitLab.

Важно: semantic-release может полностью автоматизировать выпуск, но требует настроек и правил коммитов. Если хотите простой рабочий процесс, используйте npm version patch/minor/major в скриптах CI.

Когда это не подойдёт (контрпримеры)

  • Если у вас несколько кардинально разных кодовых баз (например backend Node.js и frontend React) — один конфиг может стать громоздким. Вместо этого создавайте несколько специализированных пакетов (eslint-config-backend, eslint-config-frontend).
  • Если команда предпочитает локально настраиваемые правила под проект — централизованный подход может вызвать сопротивление. Всегда давайте способ переопределять правила в локальных .eslintrc.
  • Если у вас ограниченный доступ к GitLab (например, некоторые подрядчики находятся вне вашей инсталляции) — приватный реестр усложнит доступ. В таких случаях используйте частично публичные пакеты или альтернативные каналы распространения.

Альтернативные подходы

  • Git submodule / subtree: хранить конфигурацию в отдельном репозитории и подключать как подмодуль. Плюс — прямо видны файлы; минус — сложность управления обновлениями.
  • monorepo с workspaces: хранить конфигурацию в том же репозитории монорепозитория и подключать через workspaces. Плюс — быстрые локальные изменения; минус — не подходит для отдельных проектов вне репозитория.
  • Публикация в публичный npm (npmjs.com): удобно для общедоступных библиотек, но не подходит для внутренней политики или приватных правил компании.

Playbook: пошаговая инструкция для разработчика

  1. Создайте проект в GitLab: eslint-config-.
  2. Напишите package.json (см. пример). Убедитесь, что name — с правильным scope.
  3. Добавьте .eslintrc.js с базовыми правилами.
  4. Протестируйте локально: в другом тестовом проекте установите пакет через npm link или локальную установку.
  5. Создайте Personal Access Token с read_registry и write_registry.
  6. Настройте npm config для project-level publish (см. инструкции выше).
  7. Выполните npm publish.
  8. Подключите пакет в целевых проектах как devDependency и добавьте eslintConfig -> extends.
  9. Добавьте шаги аутентификации в CI, закиньте токены в переменные и прогоните lint в пайплайне.
  10. Документируйте процесс в README репозитория-конфига.

Checklist по ролям

Разработчик:

  • Добавил @scope/eslint-config в devDependencies
  • Добавил “eslint” в зависимости проекта
  • Запускал npm run lint локально и в CI

Владелец конфига / Maintainer:

  • Поддерживает README с инструкциями по логину в реестр
  • Обновляет список правил и обосновывает изменения
  • Нумерует релизы и ведёт CHANGELOG

Инженер CI:

  • Добавил переменную API_TOKEN в GitLab CI/CD
  • Настроил шаги npm auth до npm ci
  • Обеспечил, чтобы публикация выполнялась с корректной версией

Decision flow — какой реестр использовать

flowchart TD
  A[Нужно ли публиковать пакет в приватный реестр?]
  A -- Да --> B{Будут ли пакеты устанавливаться из разных групп?}
  A -- Нет --> C[Используйте локальные или monorepo-решения]
  B -- Да --> D[Настройте instance-level для установки, project-level для публикации]
  B -- Нет --> E[Можно ограничиться project-level для установки и публикации]
  D --> F[Документируйте scope и токены]
  E --> F
  C --> F

Шаблон README — короткая вставка для пользователей

Скопируйте и вставьте в README проектов-потребителей:

  • Установите зависимости:
npm config set @example-group:registry https://gitlab.example.com/api/v4/packages/npm/
npm config set -- '//gitlab.example.com/api/v4/packages/npm/:_authToken' "$API_TOKEN"
npm ci
  • Добавьте в package.json:
"devDependencies": {
  "@example-group/eslint-config": "^1.1",
  "eslint": "^7.2"
}
  • Запуск линтинга:
npm run lint

Критерии приёмки

  • Конфигурация опубликована в GitLab Packages и видна в разделе Packages & Registries.
  • Проект-потребитель успешно устанавливает пакет с помощью npm ci без ручной подстановки таргетных файлов.
  • CI-пайплайн использует переменные CI/CD для токенов и успешно прогоняет npm run lint.
  • Документация в README покрывает процесс логина и обновления версии.

1-строчная глоссарий

  • scope: область имени пакета npm вида @org/name; используется для разделения пакетов и привязки к реестру.
  • instance-level: endpoint реестра, доступный на уровне всей инсталляции GitLab.
  • project-level: endpoint реестра, привязанный к конкретному проекту в GitLab.

Риски и меры смягчения

  • Утечка токена: храните токены в GitLab CI/CD variables, пометив их как protected/masked.
  • Несовместимость ESLint: фиксируйте минимальную поддерживаемую версию ESLint в peerDependencies и поддерживайте совместимость.
  • Перекрытие правил: документируйте возможность переопределения правил локально и приводите примеры.

Заключение

Создание и распространение общего ESLint-конфига через приватный npm-реестр GitLab упрощает поддержание единых правил, уменьшает дублирование конфигураций и делает процесс ревью кода более предсказуемым. Основные усилия — одноразовая настройка реестра и документация для команды. После этого подключение нового проекта сводится к установке devDependency и запуску CI.

Рекомендуемая следующая задача: автоматизировать версионирование релизов (npm version или semantic-release) и поддерживать CHANGELOG для прозрачности изменений.

Поделиться: X/Twitter Facebook LinkedIn Telegram
Автор
Редакция

Похожие материалы

Несколько аккаунтов Skype: Multi Skype Launcher
Программное обеспечение

Несколько аккаунтов Skype: Multi Skype Launcher

Журнал для работы: повысить продуктивность
Productivity

Журнал для работы: повысить продуктивность

Персональные звуки уведомлений на Android
Android.

Персональные звуки уведомлений на Android

Скачивание шоу Hulu для офлайн‑просмотра
Стриминг

Скачивание шоу Hulu для офлайн‑просмотра

Microsoft Start: персонализированная новостная лента
Новости

Microsoft Start: персонализированная новостная лента

Как изменить имя в Epic Games быстро
Гайды

Как изменить имя в Epic Games быстро