Повне налаштування Husky для Git-хуків вебпроєкту

Husky Git hooks: де ламається перевірка перед комітом

Хуки закомічені, локально лінтер проходить — а в частині команди коміт іде без жодної перевірки.

Типові причини: каталог хуків не виставлений через налаштування шляхів, файл втратив право на виконання під час перенесення між файловими системами, встановлення залежностей у збірці відбувається з вимкненими скриптами збірки.

Husky робить git-хуки в проєкті частиною репозиторію, а не особистим налаштуванням розробника — але лише за відтворюваного встановлення.

Ціна збоїв на коміті проявляється не одразу. Стиль розходиться між гілками, і ревʼю перетворюється на суперечку про форматування: реальні правки губляться серед переформатованих рядків.

Помилки типів і синтаксису спливають уже на злитті, коли автор перемкнувся на інше завдання, збірка червона, а реліз зсувається.

Друга половина відмов — конфігурація самого хука. Передкомітна перевірка запускається по всьому дереву замість застейджених файлів: на середньому проєкті це десятки секунд, і обхід через --no-verify стає звичкою.

За часткового індексу (git add -p) лінтер читає робочу копію, а в коміт іде версія з індексу — неперевірена. У репозиторії з кількома пакетами спільний хук лінтує все цілком.

За галузевими оцінками процесу розробки, дефект, спійманий до збірки, обходиться в рази дешевше за трудовитратами, ніж той самий дефект на інтеграції.

Розбираємо, як це закривається: відтворюване встановлення хуків, перевірка саме тих рядків, що потрапляють у коміт, і відгук у межах пари секунд.

Що дає автоматична перевірка коду перед надсиланням

Зворотний зв'язок за секунди замість очікування ревʼю

Лінтер перед комітом і перевірка типів запускаються локально за секунди — розробник дізнається про помилку до того, як код піде в спільну гілку. Раніше та сама помилка спливала на збірці або на ревʼю через кілька годин, і час ішов на перемикання контексту. Швидкий зворотний зв'язок скорочує цикл правки з годин до хвилин.

Єдиний стиль і менше правок під час злиття гілок

Автоматична перевірка коду фіксує форматування, порядок імпортів і правила найменування до злиття, тому спірні правки в ревʼю відходять у минуле. Частка зауважень, що стосуються стилю, падає майже до нуля — обговорення зміщується до логіки й архітектури.

Єдиний стиль коду знімає й частину конфліктів під час злиття: розбіжності форматування перестають давати хибні відмінності у файлах.

Збірка перестає падати через дрібниці

Перевірки відсікають те, що раніше ламало збірку: незакриті типи, забуті налагоджувальні виводи, невикористані залежності. Частка відмов збірки знижується кратно, а вивільнений час іде на завдання, а не на розбір чужих одруків.

Обсяг повторних виправлень в одному й тому самому файлі теж падає — правило спрацьовує один раз і працює для всієї команди.

Хуки, які запускає Husky, налаштовуються під конкретний репозиторій: важкі каталоги виключаються з перевірки, а для термінової правки залишається явний обхід. Правила живуть у самому проєкті, тому однаково працюють у всіх — і в нового розробника з першого дня.

Способи підключення перевірок: локально, у збірці, у репозиторії

Перевірки можна ввімкнути на трьох рівнях: на машині розробника, у складальній лінії та в спільному репозиторії. Рівні не замінюють один одного — вони ловлять різні класи порушень: від одруку в коміті до потрапляння секрету в спільну гілку. Нижче — що дає кожен варіант і коли його достатньо.

Коли локального контролю достатньо

Поки правила стосуються формату, лінтера й повідомлень комітів, вистачить локальних хуків — вони дають зворотний зв'язок за секунди, до того як код пішов у спільну гілку.

Достатньо, щоб залежності ставилися на кроці встановлення пакетів, а не окремою командою, яку новачок забуде виконати.

Коли потрібен контроль на боці збірки

Щойно в репозиторії з'являються кілька команд або релізні гілки, локальний контроль перестає бути гарантією: прапорець обходу ніхто не скасовував.

Тоді ті самі перевірки дублюються на збірці й стають обов'язковою умовою злиття — порушення не проходить далі, навіть якщо його обійшли на машині. Локальні хуки при цьому залишаються: вони економлять час, а збіркові — захищають спільну гілку.

Упровадження Git-хуків: етапи інженерної роботи над проєктом

Упровадження git-хуків починається не зі встановлення Husky, а з аудиту репозиторію: дивимося, які перевірки вже живуть на сервері збірки, скільки гілок живе довго, де заявлені правила розходяться з фактичним кодом.

За результатами збираємо план робіт, у якому кожен хук прив'язаний до конкретного класу помилок, а не до абстрактного «треба перевіряти все». Нижче — етапи налаштування від аудиту до передавання команді.

Що робимо на кожному кроці

1. Аудит репозиторію: інвентаризація лінтерів, форматерів і тестів, пошук дублів із безперервною інтеграцією, вимірювання часу прогонів.
2. Схема хуків: commit-msg відповідає за формат повідомлення, pre-commit — за файли в індексі, pre-push — за типи й швидкі тести.
3. Налаштування середовища команди: залежності та prepare-скрипт у маніфесті — хуки встановлюються під час інсталяції, без ручних кроків на кожній машині.
4. Підключення перевірок стилю й типів: спільні конфіги, щоб редактор, хуки та сервер збірки читали одне джерело правил.
5. Налагодження на реальних гілках: довга гілка, масове перейменування, злиття — дивимося час перевірки та тертя за частих комітів.
6. Перевірка поведінки під час обходу: що відбувається з --no-verify, що при цьому потрапляє в історію та як це підхоплює сервер збірки. Обхід не забороняємо, але робимо помітним.
7. Передавання та інструктаж: інструкція з ручного запуску, оновлення конфігів і розбору спрацьовувань, коротка сесія з командою.

Точки погодження з командою

Погоджуємо склад хуків і поріг суворості: що блокує коміт, а що дає попередження. Окремо фіксуємо, хто володіє конфігами й як вносити правки — інакше правила розійдуться між машинами та сервером збірки за пару тижнів.

Комплект на виході: конфігурації, схеми, регламенти, документація

Комплект збираємо так, щоб новий інженер включився в роботу без усних пояснень, а правила жили в репозиторії, а не в листуванні. Нижче — що саме передаємо замовнику разом із налаштованими Git-хуками.

Технічна документація

• Файли конфігурації перевірок: налаштування хуків і пов'язаних аналізаторів коду в репозиторії, з коментарями щодо кожного правила та розміткою, що перевіряється на коміті, а що — перед надсиланням у спільну гілку.
• Схема проходження коміту за етапами: від правки в робочій копії до злиття — які перевірки запускаються, що відбувається при помилці та як виглядає коректний прохід без обходу.
• Карта документації за проєктом: де лежать правила стилю, конфігурація перевірок і як вони пов'язані з локальними налаштуваннями інженера.

Регламенти та інструкції для команди

• Регламент розробки: правила найменування гілок і повідомлень, формат заголовка й тіла, вимоги до розбиття змін на атомарні коміти.
• Політика обходу перевірок: коли аварійний пропуск допустимий, хто його підтверджує, що залишається в історії та як інцидент розбирається після.
• Інструкція для нових розробників: покрокове встановлення середовища, перший коміт, типові помилки та способи їх виправлення.
• Регламент оновлення правил: хто вносить зміни в конфігурацію перевірок, як проходить погодження та як переконатися, що нові правила не блокують роботу команди.

Кейс: передкомітна перевірка замість збоїв в основній гілці

Було і стало в цифрах

До впровадження перевірок на боці розробника основна гілка збиралася як пощастить.

За логами сервера збірки: 34% запусків падали на етапі лінтера й тестів — майже кожен третій; перший зворотний зв'язок надходив у середньому через 11 хвилин, а на правках форматування очікування розтягувалося до пів години.

Повернень завдання в роботу після ревʼю було стільки ж — правки прилітали вже після прогону на сервері.

Після перенесення базових перевірок у локальний цикл через Husky частка відмов збірки в основній гілці впала до 6%, перший зворотний зв'язок надходить за 30-40 секунд на тому самому наборі перевірок, а повернення в роботу скоротилися до одного завдання з дванадцяти.

Перевірки запускаються за зміненими файлами, а не по всьому репозиторію, тому очікування залишається коротким навіть на великій кодовій базі.

Що зробили і що змінилося

Налаштували передкомітний хук на форматування й лінтер з автовиправленням, на pre-push винесли модульні тести за зачепленими модулями та перевірку типів. Важкі сценарії залишили на сервері збірки, щоб локальний цикл не перетворювався на очікування.

Конфігурація хуків лежить у репозиторії та розкочується разом зі встановленням залежностей — новий інженер отримує ті самі правила першого дня, без усних домовленостей.

Обхідний шлях теж закрито: спільні хуки на боці сервера ігнорують локальні послаблення, а будь-яка зміна конфігурації проходить ревʼю як звичайний код.

За потреби хук знімається однією командою, історія правок зберігається — відкат до попереднього режиму не потребує перезбирання проєкту.

Що робити, якщо перевірки вже частково налаштовані в проєкті?

Частково налаштовані хуки — норма, а не виняток: зазвичай у проєкті вже стоїть Husky з лінтером на передкомітному етапі, плюс пара локальних скриптів і дублювальна перевірка на серверному конвеєрі.

Починаємо з інвентаризації: виписуємо кожне правило, етап його запуску, час роботи та файли, яких воно торкається. Без такої карти будь-яка правка конфігурації перетворюється на вгадування, чому в одного інженера коміт проходить, а в іншого падає.

Далі розкладаємо правила за групами. Швидкі — форматування, лінтер, перевірка типів за зміненими файлами — залишаються на етапі коміту. Важкі — збірка, тести, перевірка залежностей — переїжджають на pre-push-етап або на сервер.

Дублі прибираємо на користь одного джерела правди: правило, що живе у трьох місцях, розходиться за версіями після першої ж правки.

Перехід без зупинки робіт будується на режимі попередження: нове правило спочатку друкує зауваження, але не блокує коміт, і стає блокуючим після періоду спостереження, коли спрацьовувань стає мало. Так команда не йде в обхід через пропуск перевірок і не втрачає звичний ритм.

Міграція перевірок потребує наступності: локальні скрипти видаляємо лише після того, як їхню поведінку відтворено в спільному конфізі, а зміни оформлюємо одним комітом, який можна відкотити цілком. Винятки для окремих шляхів тримаємо у файлах-винятках, а не в тілі хука.

Команди запускаємо через спільну обгортку — тоді поведінка однакова на всіх платформах і передбачувана за часом.

Технічні сумніви перед упровадженням перевірок у проєкті

Перед увімкненням хуків у спільний процес у команд спливають ті самі сумніви: чи обійдуть перевірку, чи не почне коміт займати хвилини, як це уживається зі спільним репозиторієм. Нижче — короткі відповіді на те, що запитують найчастіше.

Чи не сповільнить це роботу на великому проєкті?

Сповільнює не хук, а наївний прогін усіх правил по всьому дереву. Перевірки йдуть лише за зміненими файлами з кешем результатів, тому на проєкті в десятки тисяч файлів коміт залишається в межах секунд. Важкі прогони переносимо на pre-push або на сервер.

У нас спільний репозиторій, у всіх свої налаштування

Конфігурацію тримаємо в репозиторії, а не в локальних налаштуваннях: після клонування її підхоплює prepare-скрипт, і в нового учасника правила з'являються одразу. Особисті експерименти виводимо окремим шляхом через core.hooksPath, щоб вони не розходилися зі спільним набором.

Хто підтримує правила, коли код розвивається?

Правила лежать поруч із кодом і оновлюються тією ж правкою, що й код: змінюється архітектура — змінюються й перевірки. Раз на квартал робимо ревізію та прибираємо правила, які перестали ловити помилки, інакше хуки лише сповільнюють коміти.

Обговоримо завдання і повернемося з оцінкою та планом робіт

Щоб оцінка була точною, а не «плюс-мінус», розмову варто почати з вступних про проєкт.

Налаштування Husky та хуків на pre-commit і pre-push — завдання, де результат залежить від деталей: скільки розробників у команді, які перевірки вже існують і скільки займає повна збірка на машині розробника.

Що корисно надіслати заздалегідь:

• структура репозиторію: монорепозиторій або набір пов'язаних пакетів;
• поточні перевірки — лінтер, типи, тести, форматування — і що з цього запускається вручну;
• склад команди та режим роботи: скільки людей і як часто йдуть коміти;
• болі в процесі: повільні перевірки, конфлікти під час злиття, обхід правил через прапорець пропуску;
• вимоги безпеки: закритий контур, заборона на надсилання коду до зовнішніх сервісів;
• бажані терміни та точки, до яких потрібно прийти;
• порядок доступу до репозиторію та передавання проєкту, якщо працюємо на вашому боці.

За цими вступними ми повертаємося з оцінкою та планом робіт: що робимо насамперед, що можна відкласти, як перевіряємо результат на кожному кроці. Опишіть завдання у зручному форматі — повернемося з оцінкою, планом і порядком передавання проєкту вашій команді.