`.gitlab-ci.yml` — это главный файл, который описывает, как GitLab будет собирать, тестировать и деплоить ваш проект. Если объяснять просто: именно он превращает ручные действия разработчика в автоматический CI/CD-пайплайн.
Что такое `.gitlab-ci.yml`
Файл размещается в корне репозитория и задаёт:
- stages — этапы пайплайна
- jobs — конкретные задачи
- rules / only / except — когда запускать задачи
- artifacts — что сохранять после выполнения
- variables — переменные окружения
- image / before_script / script — среду и команды выполнения
Базовая структура
Пример минимального пайплайна:
stages:
- build
- test
- deploy
build_app:
stage: build
script:
- npm install
- npm run build
test_app:
stage: test
script:
- npm test
deploy_prod:
stage: deploy
script:
- echo "Deploy to production"
Здесь jobs выполняются по этапам: сначала build, затем test, потом deploy. Если один этап падает, следующий не стартует ⚙️
Ключевые элементы
- stage — определяет, на каком этапе работает job
- script — команды, которые запускаются runner’ом
- image — Docker-образ для выполнения, например node:20
- tags — выбор нужного runner
- variables — токены, пути, параметры сборки
- artifacts — файлы сборки, логи, отчёты
- cache — ускорение повторных запусков за счёт зависимостей 📦
Пример с образом и кэшем:
image: node:20
cache:
paths:
- node_modules/
build_app:
stage: build
script:
- npm ci
- npm run build
Когда запускать job
Частый запрос пользователей — как запускать задачи только для ветки main или merge request.
Современный способ — rules:
deploy_prod:
stage: deploy
script:
- ./deploy.sh
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
Для merge request:
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
Artifacts и зависимости
Если сборка создаёт файлы, их можно передать дальше:
build_app:
stage: build
script:
- npm run build
artifacts:
paths:
- dist/
test_app:
stage: test
script:
- ls dist
Это удобно для фронтенда, Java, Python и любых multi-stage процессов 🧩
Полезные практики
- Используйте npm ci, а не npm install в CI
- Храните секреты в GitLab CI/CD Variables, а не в YAML
- Разделяйте пайплайн на короткие и понятные jobs
- Добавляйте lint и unit-тесты до деплоя
- Используйте rules, а не устаревшие сложные only/except
- Проверяйте YAML через CI Lint в GitLab 🔍
Частые ошибки
- Неверные отступы в YAML
- Отсутствие нужного runner
- Попытка использовать секреты прямо в репозитории
- Слишком длинные универсальные jobs вместо нескольких маленьких
- Отсутствие кэша, из-за чего сборки идут медленно 🛠️
Вывод
`.gitlab-ci.yml` — это основа автоматизации в GitLab. Хорошо настроенный файл даёт:
- стабильные сборки
- быстрые тесты
- предсказуемый деплой
- меньше ручной рутины
- выше качество релизов ✅
📌 Если работаете с DevOps, backend, frontend или QA automation — стоит посмотреть подборку каналов про IT: там много практики, инструментов и полезных разборов.