Привет, Хабр!

Сегодня рассмотрим, как подружить, казалось бы, несовместимое: динамичный мир CI/CD с его автоматизацией и бешеной скоростью и консервативный, бизнес-ориентированный Bitrix24.

Настраиваем окружение и репозиторий

Первый шаг на пути к автоматизации в том, чтобы привести проект в порядок. Обычно кастомный модуль для Bitrix24 живёт в папке /local/modules/ваш.модуль. Будем хранить в Git только свой код, а не весь core Битрикса.

Ядро Bitrix24 обновляется отдельно да и сам по себе Bitrix тяжеловесный, тысячи файлов ядра вам ни к чему в репозитории. Поэтому добавляем в .gitignore всё лишнее: логи, кеши, бэкапы, загруженные файлы и конфиги. Например, типичный .gitignore для битрикс-проекта может выглядеть так:

# Логи и служебное
*.log
*.swp
/.idea/
/bitrix/backup/
/bitrix/cache/
/bitrix/managed_cache/
/bitrix/stack_cache/
/bitrix/html_pages/

# Конфиги с паролями
/bitrix/php_interface/dbconn.php
/bitrix/.settings.php

# Загруженные файлы и прочее
/upload/
/bitrix/updates/
/bitrix/tmp/

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

Одновременно готовим тестовый стенд, отдельную копию Bitrix24 для прогона обновлений. Это может быть виртуальная машина Bitrix, Docker-контейнер или просто отдельный сервер. Главное, чтобы у CI была возможность развернуть там обновление модуля и прогнать тесты. Кстати, Bitrix-tools имеет Docker-контейнеры для Bitrix24, можно использовать их для изоляции окружения. Можно к примеру поднять локально BitrixVM для тестов, быстро и сердито.

Настраиваем доступы: генерация SSH-ключей для доступа CI к серверу, пользователю bitrix даём нужные права. Если используете GitLab CI, полезно, чтобы runner выполнялся под пользователем bitrix – тогда не будет проблем с правами на файлы. В общем, подготовительные шаги могут показаться скучными, но без этого автоматизация не взлетит.

Выбор инструмента CI/CD

Теперь определимся, чем именно реализовать pipeline. Популярные варианты:

• GitLab CI – отличный выбор, если код хранится в GitLab.

• Jenkins – старый добрый Jenkins, гибкий и всемогущий. .

• GitHub Actions – аналогично GitLab CI, если репо на GitHub.

На CI-сервере потребуется Runner с доступом к нашему коду и серверу. Это может быть отдельная виртуалка или контейнер. Главное чтобы были установлены нужные утилиты: PHP (для запуска тестов скриптов, если планируются), Composer (если используете зависимости через composer), Git, SSH, rsync и пр. Если runner Docker-based, то образ должен содержать всё необходимое.

Конфигурация CI-пайплайна

Приступаем к созданию .gitlab-ci.yml (или настроек pipeline в вашем CI). Стратегия такая: разбиваем процесс на этапы, например, build, test, deploy. Для простого PHP-модуля этап build может быть символическим (ничего компилировать не надо), но сюда часто включают, например, установку зависимостей и сборку фронтенда. Да, некоторые модули Bitrix24 содержат фронтенд-часть: скажем, панель на Vue или React, которая общается с вашим модулем через REST. Если у вас такой случай, то на этапе сборки нужно запускать npm install && npm run build внутри директории фронта, чтобы собрать статические файлы. Результат сборки можно сохранить как артефакт.

Приведу упрощённый пример .gitlab-ci.yml для модуля Bitrix:

image: php:8.1

stages:
  - build
  - test
  - deploy

variables:
  # Пути и настройки
  APP_PATH: "/var/www/bitrix24"    # путь к установленному Bitrix на сервере
  SSH_USER: "bitrix"
  SSH_HOST: "bitrix24-dev.example.com"
  # SSH ключ добавлен как защищённая переменная CI SSH_KEY

before_script:
  - apt-get update && apt-get install -y git ssh rsync

build:
  stage: build
  script:
    - composer install --no-dev
    - npm ci && npm run build     # если есть фронтенд
  artifacts:
    paths:
      - local/modules/my.module/**

test:
  stage: test
  script:
    - php vendor/bin/phpunit --colors=always || echo "No unit tests"
    - php vendor/bin/phpcs -p --standard=PSR12 local/modules/my.module/ || echo "Lint warnings"
    - echo "Tests passed"

deploy:
  stage: deploy
  when: manual        # вручную запускаем деплой на прод (для осторожности)
  script:
    # Раскатываем файлы на тестовый сервер
    - ssh -i $SSH_KEY $SSH_USER@$SSH_HOST "mkdir -p ${APP_PATH}_backup && cp -R $APP_PATH/local/modules/my.module ${APP_PATH}_backup/my.module_$(date +%Y%m%d)"
    - rsync -avz -e "ssh -i $SSH_KEY" --delete local/modules/my.module/ $SSH_USER@$SSH_HOST:$APP_PATH/local/modules/my.module/
    - ssh -i $SSH_KEY $SSH_USER@$SSH_HOST "php $APP_PATH/bitrix/modules/my.module/install/index.php"

Использовали Docker-образ с PHP 8.1 для раннера. В этапе сборки ставим зависимости, вдруг модуль использует сторонние пакеты? Сборка фронта тоже тут. Артефакты (папка модуля) сохраняем, чтобы передать на этап деплоя.

Этап тестирования является очень важным для CI. Здесь можно запускать разные проверки: unit-тесты, статический анализ кода (PHP_CodeSniffer, PHPStan и т.д.), возможно, интеграционные тесты. Честно говоря, unit-тесты для Bitrix-модуля редкая зверушка, чаще проверяют работоспособность вручную на стенде. Но хотя бы линтер и базовые тесты полезны.

В примере выше запускаем PHPUnit (если он настроен) и PHPCS для проверки кодстайла (по PSR-12, на вкус). Ничего страшного, если тестов пока нет, CI не упадёт (добавили || echo чтобы продолжить, даже если команды не найдены или вернули ошибку). Зато сам факт, что этап test есть, дисциплинирует.

Этап деплоя . В примере он помечен как when: manual, то есть будет ждать ручного запуска даже при успешных тестах. Это сделано специально, чтобы случайно не выкатить сырую версию на бой. Вы можете сделать два deploy джоба, например, deploy:dev (автоматический на dev-сервер при каждом пуше в master) и deploy:prod (ручной запуск на прод).

Скрипт деплоя делает простые вещи:

1. Делает бэкап текущей версии модуля на сервере (копирует папку модуля в резервную директорию с датой). Бережёного бог бережёт.

2. Синхронизирует файлы модуля на сервере с теми, что собраны в пайплайне, с помощью rsync. Флаг --delete удаляет на сервере файлы, которые были удалены в репозитории – чтобы прям полный актуальный набор получить. Здесь используем SSH-ключ, заранее сохраненный в CI переменных, для доступа на сервер без пароля.

3. Выполняет установочный скрипт модуля. В Bitrix у каждого модуля есть файл /install/index.php с классом-инсталлятором, обычно содержащим методы InstallDB, InstallFiles, InstallEvents и т.п. Если модуль уже установлен, можно вызвать его обновление.

После этих шагов на тестовом сервере должна появиться обновлённая версия модуля. Можно настроить, чтобы далее автоматически запускались UI-тесты или просто отправлялось уведомление тестировщикам.

Автоматизация обновления базы и другие нюансы

Помимо копирования файлов, модуль Bitrix24 часто требует изменения в базе данных при обновлении (новые таблицы, поля, параметры в настройках). Как быть с ними? Хороший тон использовать миграции. Есть отличный модуль Sprint.Migration который позволяет описывать изменения БД в PHP-скриптах и версионировать их.

Настоятельно рекомендую его подключить, тогда каждый апдейт базы фиксируется, и можно прогонять миграции на тестовом и боевом окружении командой php sprint.php migrate. В CI можно автоматизировать, после деплоя вызывать применение миграций на сервере. Но всегда делайте резервную копию базы перед автоматическими миграциями, особенно в Bitrix. Битриксовская БД это вам не легковесный ORM, можно легко что-то потерять.

Другой нюанс в файлах и контенте, добавленном через админку.

В идеале всё, что может меняться пользователями, тоже следует мигрировать через код. Но жизнь сложнее, иногда менеджеры правят что-то напрямую. Если толкнулись с этим, придётся выстраивать процесс синхронизации, либо запретить такие правки и всё делать через dev -> prod, либо периодически выкачивать изменения с прода и коммитить их. В плохом варианте CI/CD теряет смысл. В хорошем мягко перевоспитываем команду, переводя всё в код.

Проверка

В репозитории вы сразу видите статус сборки (прошла или упала). Если что-то падает, в логах джобы подробнейшая информация, какой шаг не удался. Также интегрируем уведомления: GitLab умеет слать в Telegram отчет о падении пайплайна, либо можно email.

Кстати, о безопасности и доступе, убедитесь, что деплой-скрипт не оставляет открытых дыр. SSH-ключ без пароля храните только в CI (или в агенте-раннере), ограничьте права этого ключа (можно разрешить логин только от определённого пользователя и только выполнение определённых команд, хотя это сложно – тогда лучше обособленный деплой-юзер без лишних прав). Команды, которые выполняются на сервере, тоже продумайте: мы, например, делаем git reset --hard или rsync --delete опасные штуки, если конфигурацию перепутает.

Заключение

Подытожу ключевые моменты:

• Храните код в репозитории, не правьте на живом сайте.

• Описывайте инфраструктуру и данные в коде: настройки, миграции БД, контент – всё, что возможно.

• Настройте CI-сервер (GitLab CI, Jenkins и пр.) и разберите процесс на этапы: сборка, тесты, деплой.

• Автотесты и статические анализаторы встраивайте в pipeline, даже если их немного – это повышает качество.

• Автодеплой на стенд экономит уйму времени. На прод выкатывайте либо вручную с кнопки (для безопасности), либо через отдельный pipeline с подтверждением.

• Учитывайте специфику Bitrix: контент-правки, кеш, обновления ядра. Автоматизация должна эти моменты учитывать, чтобы ничего не потерять.

• Документируйте и обучайте команду: толку мало, если только вы понимаете, как всё устроено.

Автоматизируйте с удовольствием!

Если хочется, чтобы Bitrix24 был не «ещё одной системой», а частью цельной инженерной среды, одной автоматизацией деплоя не обойтись. Курс OTUS «Интегратор Битрикс24» помогает выстроить сами бизнес-процессы: от диагностики и блок-схем до сложной автоматизации через роботов, смарт-процессы, RPA и встроенные бизнес-процессы портала.

Для знакомства с форматом обучения и экспертами приходите на бесплатные демо-уроки:

• 8 декабря: Автоматизация лидов из CRM-форм: настройка мгновенного распределения и контроля в Битрикс24. Записаться

• 18 декабря: Организация команды разработки с использованием инструментов Битрикс24. Записаться