Серверы Дизайн Сайты Безопасность Домены PHP Кейсы клиентов

GitLab CI/CD: руководство по настройке

Вы вручную собираете и тестируете код, тратите время на повторяющиеся задачи и рискуете пропустить ошибки? GitLab CI/CD решит эти проблемы: автоматизирует процессы и обеспечит надежное развертывание. В руководстве покажем, как настроить CI/CD с нуля.

Что такое GitLab CI/CD и зачем он нужен разработчикам

GitLab CI/CD – встроенный инструмент GitLab для автоматической сборки, тестирования и развертывания кода. Достаточно настроить его один раз: после этого GitLab сам будет проверять новый код, собирать приложение и при необходимости обновлять версию – без ручного вмешательства.

CI/CD состоит из двух основных частей:

CI – Continuous Integration, или непрерывная интеграция. Она отвечает за регулярную проверку изменений: сборку проекта, запуск тестов, анализ кода.
CD – Continuous Delivery / Deployment, или непрерывная доставка и развертывание. Эта часть помогает автоматически подготовить приложение к выпуску или сразу развернуть его на сервере.

GitLab CI/CD помогает разработчикам быстрее находить ошибки: например, если после добавления нового кода тесты сломались, система сразу сообщит об этом – еще до того, как изменения попадут в основную ветку или на production.

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

Как работает CI/CD в GitLab

Работа GitLab CI/CD строится вокруг пайплайна – цепочки автоматических действий, которые запускаются после изменений в репозитории.

Главный файл настройки GitLab CI/CD – .gitlab-ci.yml. Он располагается в корне репозитория и задаёт весь процесс работы с кодом: от установки зависимостей и сборки приложения до запуска тестов, проверки кода, подготовки артефактов и развёртывания проекта на сервере. С его помощью автоматизируются рутинные задачи.

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

Разработчик отправляет изменения в GitLab.
GitLab находит файл .gitlab-ci.yml.
Запускается пайплайн.
Пайплайн выполняет jobs – отдельные задачи.
Jobs распределяются по stages – этапам выполнения.
GitLab показывает результат: успешно, с ошибкой, отменено или ожидает ручного запуска.

Например, пайплайн может состоять из трех этапов:

stages:
  - test
  - build
  - deploy

Сначала GitLab запускает тесты. Если они прошли успешно, начинается сборка. После сборки можно выполнить деплой. Если на одном из этапов возникает ошибка, следующие этапы обычно не запускаются. Это помогает остановить проблемный код до того, как он попадет дальше.

Основные компоненты GitLab CI/CD

GitLab CI/CD состоит из нескольких базовых элементов:

.gitlab-ci.yml – главный файл настройки. В нем описывают, какие команды нужно выполнить, в каком порядке и при каких условиях.
Pipeline – весь процесс CI/CD. Он запускается после push, merge request, по расписанию или вручную.
Stages – этапы пайплайна. Например: test, build, deploy. Они задают порядок выполнения задач.
Jobs – отдельные задачи внутри этапов. Один job может запускать тесты, другой – собирать приложение, третий – выполнять деплой.
GitLab Runner – агент, который выполняет jobs. Он получает задачу от GitLab и запускает команды на сервере, виртуальной машине или в Docker-контейнере.
Variables – переменные для настроек и секретов: токенов, адресов серверов, режимов запуска.
Artifacts – файлы, которые сохраняются после выполнения job: сборки, отчеты, логи.
Cache – временное хранилище для зависимостей. Оно ускоряет повторные запуски пайплайна.
Environments – окружения для деплоя, например staging или production.

Подготовка окружения для CI/CD

Сначала проверьте, что в проекте есть нужные файлы и команды. Например, для Node.js это package.json, npm test и npm run build, для PHP – composer.json, для Python – requirements.txt или pyproject.toml.

Среду выполнения чаще всего задают через Docker-образ:

test_app:
  image: node:20
  script:
    - npm install
    - npm test

Так pipeline запускается в предсказуемом окружении и не зависит от настроек компьютера разработчика.

Если для тестов нужны дополнительные сервисы, их подключают через services, например базу данных:

test_app:
  image: node:20
  services:
    - postgres:16
  script:
    - npm install
    - npm test

Также нужно убедиться, что проекту доступен GitLab Runner. Он будет получать jobs от GitLab и выполнять команды из pipeline.

Для полноценной настройки CI/CD часто нужна отдельная серверная инфраструктура: с root-доступом, возможностью устанавливать Docker, GitLab Runner, SSH-клиент и другие DevOps-инструменты. Для этого подойдут виртуальные серверы Spaceweb. На таком сервере можно гибко настроить окружение под CI/CD пайплайны, запускать сборку и тесты, хранить нужные зависимости и автоматизировать деплой проектов. У Spaceweb есть разные конфигурации VPS/VDS, варианты на NVMe, поддержка популярных ОС и готовые приложения, включая Docker, поэтому сервер можно подобрать под нагрузку проекта и задачи команды.

Типы GitLab Runner и их особенности

GitLab Runner можно разделить по двум критериям: по области доступа и по способу выполнения jobs.

По области доступа бывают:

project runner – доступен только одному проекту;
group runner – доступен всем проектам внутри группы;
instance runner – доступен всем проектам на GitLab-инстансе.

По способу выполнения jobs runner использует executor. Самые частые варианты:

Docker executor запускает jobs в контейнерах. Удобен для большинства проектов, потому что позволяет задавать нужное окружение через Docker-образ.
Shell executor выполняет команды прямо на сервере, где установлен runner. Прост в настройке, но хуже изолирует задачи, поэтому его лучше использовать для внутренних и контролируемых проектов.
Kubernetes executor запускает jobs в Kubernetes-кластере. Подходит для команд, которые уже используют Kubernetes и хотят гибко масштабировать CI/CD.

Установка и настройка GitLab Runner

GitLab Runner – это агент, который выполняет jobs из пайплайна. Его можно установить на отдельный сервер, виртуальную машину или локальную машину.

Чтобы установить его на Ubuntu/Debian, нужно выполнить:

curl -L "https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh" -o script.deb.sh
less script.deb.sh
sudo bash script.deb.sh
sudo apt install gitlab-runner

Затем runner нужно зарегистрировать в GitLab. Для этого в проекте откройте Settings → CI/CD → Runners, создайте runner и скопируйте authentication token.

Выполните команду:

sudo gitlab-runner register

Во время регистрации нужно указать:

URL GitLab, например https://gitlab.com;
token runner;
описание runner;
tags, если jobs должны запускаться только на определенных runners;
executor – среду, в которой будут выполняться jobs.

Чаще всего выбирают Docker executor. Он запускает jobs в контейнерах, поэтому окружение получается более предсказуемым:

sudo gitlab-runner register \
  --url "https://gitlab.com" \
  --token "glrt-XXXXXXXXXXXX" \
  --executor "docker" \
  --docker-image "alpine:latest"

После регистрации настройки сохраняются в файле config.toml. Через него можно менять лимиты параллельных jobs, параметры executor, кэширование и другие настройки runner.

Проверить статус runner можно командой:

sudo gitlab-runner status

Если runner активен, добавьте в .gitlab-ci.yml простой job и запустите pipeline:

test_runner:
  script:
    - echo "Runner works"

Если job выполнился успешно, runner установлен и готов к работе.

Файл .gitlab-ci.yml: структура и синтаксис

Файл .gitlab-ci.yml – это основной файл настройки GitLab CI/CD. В нем описывают пайплайн: какие задачи запускать, в каком порядке, в какой среде и при каких условиях. Файл размещают в корне репозитория, чтобы GitLab мог найти его при запуске пайплайна. Базовая структура у файла следующая:

stages:
  - test
  - build
  - deploy

variables:
  APP_ENV: "test"

test_app:
  stage: test
  image: node:20
  script:
    - npm install
    - npm test

build_app:
  stage: build
  script:
    - npm run build
  artifacts:
    paths:
      - dist/

deploy_app:
  stage: deploy
  script:
    - echo "Deploy project"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

В начале файла обычно указывают stages – список этапов пайплайна. Они выполняются сверху вниз: сначала test, потом build, затем deploy.

Блок variables используют для переменных, которые нужны внутри jobs. Например, можно задать режим окружения, путь к директории или имя приложения.

Дальше описываются jobs – отдельные задачи пайплайна. В примере это test_app, build_app и deploy_app. Названия можно задавать самостоятельно, главное – чтобы они были понятны команде.

У каждого job обычно есть несколько ключевых параметров:

stage указывает, на каком этапе выполняется задача;
image задает Docker-образ, если job должен запускаться в контейнере;
script содержит команды, которые выполнит runner;
artifacts сохраняет файлы после выполнения job, например сборку или отчеты;
rules задает условия запуска job.

Основной параметр в job – script. В нем описывают команды: установить зависимости, запустить тесты, собрать проект или выполнить деплой.

Важно! Не забывайте соблюдать YAML-синтаксис: использовать пробелы вместо табуляции и следить за отступами. Даже небольшая ошибка в структуре может помешать запуску пайплайна. Проверить файл можно через CI Lint в GitLab – он покажет, корректно ли написан .gitlab-ci.yml.

Как создать первый пайплайн

Первый пайплайн можно создать через файл .gitlab-ci.yml. Добавьте его в корень репозитория и опишите в нем хотя бы один job – задачу, которую должен выполнить GitLab Runner. GitLab запускает пайплайн после коммита этого файла в репозиторий.

Пример минимального пайплайна:

stages:
  - test

test_job:
  stage: test
  script:
    - echo "Pipeline is running"
    - echo "Tests will be here"

В этом примере есть один этап test и один job test_job. Runner выполнит команды из блока script, а результат появится в GitLab.

Чтобы запустить pipeline:

Создайте файл .gitlab-ci.yml в корне проекта.
Добавьте в него конфигурацию.
Сделайте commit и push в GitLab.
Откройте Build → Pipelines или CI/CD → Pipelines в интерфейсе проекта.
Проверьте статус пайплайна и логи job.

Если job завершился успешно, пайплайн настроен правильно.

Автоматическая сборка и тестирование проекта

Создав первый пайплайн, вы можете добавить автоматическую сборку и тестирование. Это помогает быстро проверить, работает ли проект после новых изменений.

Как правило, пайплайн состоит минимум из двух этапов:

stages:
  - test
  - build

На этапе test запускают проверки: unit-тесты, линтеры, статический анализ кода. На этапе build собирают приложение или создают файлы, готовые к публикации.

Пример для Node.js-проекта:

stages:
  - test
  - build

test_app:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test

build_app:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
  artifacts:
    paths:
      - dist/

В этом примере job test_app устанавливает зависимости и запускает тесты. Если тесты завершатся с ошибкой, пайлайн остановится, а сборка не начнется. Это защищает проект от попадания нерабочего кода в следующие этапы.

Job build_app собирает проект и сохраняет результат в artifacts. Например, для фронтенд-приложения это может быть папка dist/, которую потом можно использовать для деплоя.

Использование Docker в GitLab CI/CD

Docker в GitLab CI/CD используют, чтобы запускать jobs в изолированном и предсказуемом окружении. Вместо настройки зависимостей на сервере можно указать готовый Docker-образ прямо в .gitlab-ci.yml. GitLab Runner запустит job внутри контейнера.

Простой пример:

test_app:
  image: node:20
  script:
    - npm ci
    - npm test

Здесь job выполняется в контейнере на базе образа node:20. Внутри уже есть Node.js, поэтому не нужно устанавливать его вручную перед запуском тестов. Если проекту нужны дополнительные сервисы, их подключают через services.

Например, для тестов с PostgreSQL:

test_app:
  image: node:20
  services:
    - postgres:16
  script:
    - npm ci
    - npm test

Для выполнения Docker-команд внутри pipeline runner должен быть настроен с поддержкой Docker. Часто для этого используют Docker executor. Он запускает jobs в отдельных контейнерах и помогает сохранять одинаковое окружение между запусками.

На практике Docker в GitLab CI/CD нужен для трех задач: запускать тесты в нужной версии окружения, подключать сервисы вроде баз данных и собирать контейнерные образы для деплоя.

Безопасная работа с секретами

Секреты – это данные, которые дают доступ к инфраструктуре или внешним сервисам: пароли, API-токены, SSH-ключи, ключи от registry, доступы к базе данных. Их нельзя хранить в .gitlab-ci.yml или прямо в коде проекта.

В GitLab для этого используют CI/CD Variables. Переменные добавляют в настройках проекта: Settings → CI/CD → Variables. После этого их можно использовать в пайплайне как обычные переменные окружения:

deploy_app:
  stage: deploy
  script:
    - ssh $SERVER_USER@$SERVER_HOST "cd /var/www/app && git pull"

Для секретов стоит включать параметры Masked и Protected. Masked скрывает значение переменной в логах, а Protected разрешает использовать ее только в защищенных ветках и тегах, например в main.

Настройка деплоя через GitLab CI/CD

Деплой в GitLab CI/CD настраивают как отдельный этап пайплайна. Обычно он запускается после тестов и сборки, чтобы на сервер попадал только проверенный код.

Пример структуры:

stages:
  - test
  - build
  - deploy

Job для деплоя можно описать так:

deploy_production:
  stage: deploy
  script:
    - echo "Deploy to production"
    - ssh $SERVER_USER@$SERVER_HOST "cd /var/www/app && git pull && npm install && npm run build && pm2 restart app"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
  environment:
    name: production

В этом примере деплой запускается только для ветки main. Runner подключается к серверу по SSH, переходит в директорию проекта, обновляет код, устанавливает зависимости, собирает приложение и перезапускает процесс. Пароли, токены, адрес сервера и SSH-ключи не нужно хранить в .gitlab-ci.yml. Их добавляют в Variables. Если для деплоя используется SSH-ключ, перед подключением его нужно подготовить внутри job:

before_script:
  - apt-get update -y
  - apt-get install -y openssh-client
  - eval $(ssh-agent -s)
  - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -

Для продакшна лучше добавить ручной запуск:

deploy_production:
  stage: deploy
  script:
    - echo "Deploy to production"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: manual
  environment:
    name: production

Так пайплайн выполнит тесты и сборку автоматически, но деплой на продакшн начнется только после подтверждения.

Итоги

GitLab CI/CD помогает автоматизировать основные этапы разработки: проверку кода, тестирование, сборку и деплой. Вся логика пайплайна описывается в файле .gitlab-ci.yml, а jobs выполняются через GitLab Runner в выбранном окружении – например, в Docker-контейнере или на отдельном сервере.

Чтобы CI/CD был удобным и безопасным, важно продумать структуру пайплайна, не хранить секреты в репозитории, использовать переменные окружения, кешировать зависимости и запускать только нужные jobs. Так вы ускорите работу команды, снизите риск ошибок и сделаете выпуск обновлений более предсказуемым.

Перейти на оригинал