Гит-хук

Гит-хук — это сервис, который работает как «крючок» (hook) на удалённом сервере и связан с системой контроля версий Git. Он имеет большой потенциал, но в настоящее время его реализация довольно проста. В настоящее время большинство платформ для управления репозиториями Git поддерживают настройку обратного вызова URL, включая GitHub, Oschina и Coding. Когда разработчик отправляет код на удалённый сервер, он инициирует запрос к этому URL. Сервер, который получает этот запрос, может запускать настроенную команду на локальном компьютере. Этот инструмент предназначен для управления этими командами.

Особенности:

• Односерверная архитектура: требуется установка на сервере, где будут выполняться команды.
• Поддержка различных платформ: включая GitHub, Oschina, Coding и другие.
• Конфигурация через YAML-файлы: простой и удобный синтаксис.
• Настройка команд: поддержка параметров user, group, cwd, stdout и stderr для перенаправления вывода.
• Дружелюбные сообщения об ошибках и логирование.

Быстрая настройка

Предварительные условия:

1. Система Linux.
2. Установлены Node.js и Yarn, версия Node.js должна быть не ниже 6.

Шаги настройки:

1. Выполнить команду yarn.
2. Следовать правилам конфигурации файлов, описанным ниже.
3. Запустить сервер командой yarn start.

Перезапуск

После каждого изменения в конфигурационных файлах необходимо перезапускать сервер для перезагрузки конфигурации.

О sudo

Для запуска сервера необходимо использовать команду sudo, чтобы обеспечить выполнение команд от имени пользователя root. Это связано с тем, что инструмент поддерживает переключение пользователей и групп для выполнения команд, и только пользователь root может выполнять эти операции без проблем. Однако можно запустить сервер и без использования sudo, но тогда в конфигурационном файле поля user и group должны быть установлены на текущего пользователя и группу, иначе сервер выдаст ошибку.

Параметры команды

При запуске сервера можно указать следующие параметры:

• -p или --port: порт сервера.

Правила конфигурационного файла

Конфигурационные файлы хуков хранятся в каталоге config. Файлы конфигурации имеют расширение .yml. Структура файлов конфигурации описана в примерах simple-hook.yml и full-hook.yml. Путь к файлу конфигурации соответствует пути URL относительно каталога config. Например, файл конфигурации a.yml в каталоге config будет соответствовать URL /a, а файл конфигурации a/b.yml — URL /a/b.

В конфигурационных файлах используются следующие поля:

• token: ключ для проверки подлинности запроса. Если установлено, запросы без соответствующего токена будут отклонены. Рекомендуется установить это поле.
• branch: фильтр для ветвей Git. Запросы, которые не соответствуют указанному фильтру, будут отклонены текущим конфигурационным файлом, но последующие конфигурационные файлы могут принять эти запросы. По умолчанию используется значение * (любой запрос).
• event: фильтр событий Git, таких как push или merge request. Запросы, не соответствующие указанному фильтру, будут отклонены текущим конфигурационным файлом, но последующие конфигурационные файлы могут принять их. По умолчанию используется значение * (любое событие).
• executor: исполнитель команды. Для большинства пользователей достаточно использовать spawn.
• command: команда для выполнения.
• cwd: текущий каталог для выполнения команды.
• user: пользователь для выполнения команды.
• group: группа пользователей для выполнения команды.
• stdout: путь для перенаправления стандартного вывода команды.
• stderr: путь для перенаправления стандартной ошибки команды.

Все поля являются обязательными и рекомендуется заполнить их все.

Специальные конфигурационные файлы default.yml и ключ default

Файл default.yml в корневом каталоге содержит значения по умолчанию для всех конфигураций. Файл full-hook.yml содержит пример использования ключа default для задания значений по умолчанию в других конфигурациях. Значения полей в конфигурациях переопределяются в следующем порядке: ключ default, файл default.yml.

Правила URL для хуков

Полный формат URL выглядит следующим образом:

http://{domain}:{port}/{path}?normalizer={normalizer}

Каждый элемент URL имеет своё значение:

• domain: домен, доступный для доступа к серверу.
• port: порт, на котором запущен сервер. Можно указать при запуске сервера с помощью параметра. По умолчанию — 3000.
• path: соответствует пути к конфигурационному файлу.
• normalizer: метод нормализации, обычно название платформы, например GitHub, Oschina или Coding. На данный момент поддерживается только Coding, планируется добавить поддержку других платформ. Также можно создать собственный плагин нормализации.

Например, если вы используете платформу Coding для настройки хука и ваш конфигурационный файл находится в config/a/b.yml, то путь должен быть указан следующим образом:

http://your-domain:port/a/b?normalizer=coding

Команды и среда выполнения

На платформе Linux команды и среда выполнения тесно связаны друг с другом. Node предоставляет метод child_process.spawn для вызова внешних команд, но этот метод может вызывать проблемы при выполнении некоторых команд. Чтобы решить эту проблему, git-hook позволяет пользователям самостоятельно определять способ выполнения команд. В конфигурационном файле есть поле executor, которое указывает на исполняемый файл в плагинах/executors.

Создание собственных плагинов

Плагины делятся на два типа: исполнители и нормализаторы. Они размещаются в соответствующих папках plugins. Плагины представляют собой файлы JavaScript, которые являются модулями Node.js.

Исполнители

Исполнители выполняют реальные команды. Каждый исполнитель представляет собой файл JavaScript, который является модулем Node.js, возвращающим функцию. Исполнители размещаются в папке plugins/executors/. Типичный пример исполнителя:

module.exports = function ({ command, cwd, uid, gid, stderr, stdout }) {
  // 执行command并写入到stdout、stderr的代码
}

Нормализаторы

Нормализаторы преобразуют исходные данные JSON в формат, понятный инструменту. Благодаря нормализаторам, можно поддерживать множество различных платформ, таких как GitHub, Oschina и Coding.

Типичный пример нормализатора:

module.exports = function ({ path, query, data, headers, request }) {
  return normalizedData
}

Разработка и отладка

Сначала скопируйте файл examples/simple-hook.yml в каталог config и внесите изменения в каждый параметр. Затем запустите сервер разработки:

yarn dev

Чтобы протестировать сервер, выполните следующий запрос:

curl -XPOST http://localhost:3000/simple-hook -d '{"branch":"master", "event":"test", "token":"token"}'

Незавершённые задачи

• Создание папки для лог-файла при ошибке.
• Проблема с использованием console.log в HandlerResolver.js при запуске сервера.
• Ошибка в JSON при нормализации запросов для платформы Coding.