Как настроить запуск сборки при коммитах в GitLab CI

Настройка GitLab CI/CD для автоматической сборки при коммитах

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

1. Создание базового конфигурационного файла .gitlab-ci.yml

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

stages:
  - build
  - test
  - deploy

variables:
  DOCKER_DRIVER: overlay2

before_script:
  - echo "Начало выполнения пайплайна для ветки $CI_COMMIT_REF_NAME"

build_job:
  stage: build
  script:
    - echo "Сборка проекта..."
    - mvn clean compile  # для Java Maven проектов
  only:
    - main
    - develop
    - merge_requests
  tags:
    - docker

2. Основные секции конфигурации

Определение стадий (stages)

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

stages:
  - pre-build
  - build
  - unit-test
  - integration-test
  - deploy

Настройка условий запуска (only/except)

Чтобы пайплайн запускался именно при коммитах, используйте директивы only или правила rules:

# Классический подход с only
build:
  stage: build
  script:
    - ./build.sh
  only:
    - pushes          # запуск при push
    - merge_requests  # и при создании merge request
    - tags            # и при создании тегов

# Современный подход с rules (рекомендуется с GitLab 12.3+)
build:
  stage: build
  script:
    - ./build.sh
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'
      when: always
    - if: '$CI_COMMIT_BRANCH =~ /^feature\/.*/'
      when: manual
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
      when: always

Использование переменных окружения

Переменные позволяют параметризовать процесс сборки:

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository"
  NODE_VERSION: "16"

cache:
  paths:
    - .m2/repository/
    - node_modules/

3. Регистрация и настройка GitLab Runner

Для выполнения заданий необходимо установить и зарегистрировать GitLab Runner:

# Установка на Linux (Debian/Ubuntu)
sudo curl -L --output /usr/local/bin/gitlab-runner "https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64"
sudo chmod +x /usr/local/bin/gitlab-runner
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-runner start

# Регистрация раннера
sudo gitlab-runner register \
  --url "https://gitlab.example.com/" \
  --registration-token "PROJECT_REGISTRATION_TOKEN" \
  --executor "docker" \
  --description "Docker runner" \
  --docker-image "alpine:latest" \
  --tag-list "docker,linux"

4. Расширенная конфигурация для различных сценариев

Кеширование зависимостей

Для ускорения сборок настройте кеширование:

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - vendor/ruby
    - node_modules/
  policy: pull-push

Артефакты сборки

Сохранение результатов сборки для последующих стадий:

build:
  stage: build
  script:
    - mvn package -DskipTests
  artifacts:
    paths:
      - target/*.jar
    expire_in: 1 week
  only:
    - main

Параллельное выполнение тестов

Оптимизация времени выполнения пайплайна:

unit_tests:
  stage: test
  script:
    - ./run_unit_tests.sh
  parallel: 5
  only:
    - branches

5. Триггеры и веб-хуки для дополнительной гибкости

Для запуска пайплайнов из внешних систем или по расписанию:

# Пайплайн по расписанию
scheduled_build:
  stage: build
  script:
    - ./nightly_build.sh
  only:
    - schedules  # Запускается только по расписанию

# Внешний триггер через API
trigger_build:
  stage: deploy
  script:
    - curl -X POST -F "token=$CI_JOB_TOKEN" -F "ref=main" https://gitlab.example.com/api/v4/projects/1/trigger/pipeline

6. Лучшие практики и рекомендации

• Используйте rules вместо `only/except для более гибкой логики
• Настройте разделение кешей для разных веток с помощью CI_COMMIT_REF_SLUG
• Оптимизируйте образы Docker для быстрого старта заданий
• Реализуйте инкрементальную сборку для больших проектов
• Настройте уведомления о статусе сборки в Slack/Telegram/Email
• Используйте динамическое определение окружений для feature-веток:

review_app:
  stage: deploy
  script:
    - deploy_review.sh
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com
  only:
    - branches
  except:
    - main

7. Мониторинг и отладка

Для мониторинга пайплайнов используйте встроенные возможности GitLab:

• CI/CD Analytics в разделе Analytics проекта
• Pipeline graphs для визуализации зависимостей
• Job logs для детального анализа ошибок

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