GitLab CI: lint, test и сборка образов
GitLab CI: lint, test и сборка образов
CI (Continuous Integration) - автоматизация рутины: тесты, линтинг, сборка образов, деплой. GitLab CI запускает пайплайн при каждом пуше - робот делает скучное за тебя.
Структура пайплайна от языка не зависит: stages, jobs, образ на джобу, артефакты между этапами. Меняются только команды внутри script и базовый образ - примеры для Go, PHP и Python ниже во вкладках.
Как работает GitLab CI
Пайплайн = набор stages (этапов), выполняемых последовательно. Внутри stage - jobs (задачи), которые могут выполняться параллельно.
.gitlab-ci.yml - базовая структура
Каркас одинаковый для всех: этапы, а внутри - джобы бэкенда и фронтенда.
stages:
- lint
- test
- build
# ---------- Frontend: одинаково при любом бэкенде ----------
frontend:lint:
image: node:20-alpine
stage: lint
script:
- cd frontend
- npm ci
- npm run lint
only:
- merge_requests
frontend:test:
image: node:20-alpine
stage: test
script:
- cd frontend
- npm ci
- npm run test -- --run
only:
- merge_requests
Джобы бэкенда отличаются образом и командами:
variables:
GOFLAGS: "-count=1" # без кэша тестов
backend:lint:
image: golangci/golangci-lint:latest
stage: lint
script:
- cd backend
- golangci-lint run ./...
only:
- merge_requests
backend:test:
image: golang:1.22-alpine
stage: test
script:
- cd backend
- go test ./...
only:
- merge_requests
backend:lint:
image: php:8.3-cli-alpine
stage: lint
before_script:
- curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
- cd backend && composer install --no-interaction --no-progress
script:
- vendor/bin/phpstan analyse
- vendor/bin/php-cs-fixer fix --dry-run --diff
only:
- merge_requests
backend:test:
image: php:8.3-cli-alpine
stage: test
before_script:
- curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
- cd backend && composer install --no-interaction --no-progress
script:
- vendor/bin/phpunit
only:
- merge_requests
backend:lint:
image: python:3.12-slim
stage: lint
before_script:
- cd backend && pip install --no-cache-dir ruff mypy
script:
- ruff check .
- mypy .
only:
- merge_requests
backend:test:
image: python:3.12-slim
stage: test
before_script:
- cd backend && pip install --no-cache-dir -r requirements.txt
script:
- pytest -q
only:
- merge_requests
Обрати внимание на общий приём: установка зависимостей вынесена в before_script, а проверка остаётся в script. Тогда в логе видно, что упало - подготовка окружения или сама проверка.
ℹ️ only: merge_requests
Линтинг и тесты запускаются только на Merge Request - не тратим ресурсы на каждый коммит в feature-ветку. Для
mainзапускается build + deploy.
only/except GitLab больше не развивает, в новых пайплайнах то же условие пишут через rules:. А чтобы только что подключённый линтер с сотней замечаний не блокировал пайплайн, пока их разбирают, джобе временно ставят allow_failure: true:
backend:lint:
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
allow_failure: true
То же условие часто пишут короче: - if: $CI_MERGE_REQUEST_IID - переменная с номером MR существует только в пайплайне merge request.
npm ci и lockfile
npm ci работает только с package-lock.json. Без него - ошибка:
npm ERR! The `npm ci` command can only install with an existing package-lock.json or
npm ERR! npm-shrinkwrap.json with lockfileVersion >= 1.
А если lock-файл есть, но отстал от package.json (добавили зависимость и не закоммитили lock), ошибка другая:
npm ERR! `npm ci` can only install packages when your package.json
npm ERR! and package-lock.json are in sync.
Решение:
cd frontend
npm install # создаёт package-lock.json
git add package-lock.json
git commit -m "chore: add lockfile"
⚠️ Не добавляй node_modules в git
В
.gitignoreдолжен бытьnode_modules/. В CI зависимости ставятся с нуля черезnpm ci. Lock-файл гарантирует одинаковые версии.
Кэширование зависимостей
Без кэша каждый job скачивает зависимости заново. С кэшем - использует сохранённые:
backend:test:
image: golang:1.22-alpine
stage: test
script:
- cd backend
- go test ./...
cache:
key: go-${CI_COMMIT_REF_SLUG}
paths:
- backend/.go/pkg/mod/
variables:
GOPATH: "${CI_PROJECT_DIR}/backend/.go"
frontend:test:
image: node:20-alpine
stage: test
script:
- cd frontend
- npm ci --cache .npm --prefer-offline
- npm run test -- --run
cache:
key:
files:
- frontend/package-lock.json
paths:
- frontend/.npm/
${CI_COMMIT_REF_SLUG} - имя ветки. Каждая ветка имеет свой кэш. Для Go так же можно взять ключом файл зависимостей: key: files: [backend/go.sum] - кэш pkg/mod обновится, только когда поменяются зависимости. Для npm кешируют не node_modules (npm ci первым делом его удаляет), а каталог загрузок .npm, и ключом берут сам package-lock.json: поменялись зависимости - новый кеш.
Сборка Docker-образов
Вариант 1: Docker-in-Docker (DinD)
build:docker:
image: docker:24
stage: build
services:
- docker:24-dind
variables:
DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_CERTDIR: "/certs"
script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -t $CI_REGISTRY_IMAGE/backend:$CI_COMMIT_SHA ./backend
- docker push $CI_REGISTRY_IMAGE/backend:$CI_COMMIT_SHA
only:
- main
DinD запускает Docker daemon внутри Docker-контейнера. Работает, но медленный (нет кэша слоёв между сборками). Кэш слоёв можно взять из прошлого образа в registry: docker pull $CI_REGISTRY_IMAGE/backend:latest || true, затем docker build --cache-from $CI_REGISTRY_IMAGE/backend:latest ... (с BuildKit прошлый образ должен быть собран с --build-arg BUILDKIT_INLINE_CACHE=1).
Вариант 2: Kaniko (без Docker daemon)
build:kaniko:
image:
name: gcr.io/kaniko-project/executor:v1.21.0-debug
entrypoint: [""]
stage: build
script:
# демона нет, docker login недоступен: учётку registry kaniko берёт из config.json
- echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json
- /kaniko/executor
--context ./backend
--dockerfile ./backend/Dockerfile
--destination $CI_REGISTRY_IMAGE/backend:$CI_COMMIT_SHA
--cache=true
only:
- main
Оригинальный репозиторий kaniko от Google в 2025 году переведён в архив. Принцип «сборка без демона» от этого не устарел: те же задачи решают BuildKit в rootless-режиме и Buildah, а для kaniko есть поддерживаемые форки.
| Docker-in-Docker | Kaniko | |
|---|---|---|
| Docker daemon | Нужен (privileged) | Не нужен |
| Безопасность | Требует privileged mode | Работает без привилегий |
| Кэш слоёв | Нет (по умолчанию) | Да (--cache=true) |
| Скорость | Медленнее | Быстрее (с кэшем) |
| Настройка | Проще | Сложнее первый раз |
ℹ️ GitLab Container Registry
Встроенный registry для Docker-образов. Адрес:
registry.gitlab.com/username/project. Авторизация через CI-переменные$CI_REGISTRY_USERи$CI_REGISTRY_PASSWORD- они автоматически доступны в пайплайне.
Переменные окружения в CI
variables:
# Глобальные переменные (доступны во всех jobs)
GOFLAGS: "-count=1"
backend:test:
variables:
# Переменные конкретного job
DATABASE_URL: "postgres://postgres:postgres@postgres:5432/test?sslmode=disable"
# без пароля образ postgres не инициализируется и сервис сразу завершится
POSTGRES_PASSWORD: postgres
POSTGRES_DB: test
services:
- postgres:16-alpine
Секреты (пароли, токены) - через Settings → CI/CD → Variables в GitLab. Они доступны как $VARIABLE_NAME, но не видны в логах (masked).
Артефакты
Артефакты - файлы, которые передаются между jobs или доступны для скачивания:
backend:test:
script:
- cd backend
- go test -coverprofile=coverage.out ./...
- go tool cover -html=coverage.out -o coverage.html
artifacts:
paths:
- backend/coverage.html
expire_in: 7 days
Полный production .gitlab-ci.yml
stages:
- lint
- test
- build
- deploy
backend:lint:
image: golangci/golangci-lint:latest
stage: lint
script:
- cd backend && golangci-lint run ./...
only:
- merge_requests
backend:test:
image: golang:1.22-alpine
stage: test
script:
- cd backend && go test ./...
only:
- merge_requests
build:
image:
name: gcr.io/kaniko-project/executor:v1.21.0-debug
entrypoint: [""]
stage: build
script:
- echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json
- /kaniko/executor
--context ./backend
--dockerfile ./backend/Dockerfile
--destination $CI_REGISTRY_IMAGE/backend:$CI_COMMIT_SHA
--cache=true
only:
- main
deploy:
image: alpine:3.20
stage: deploy
before_script:
# SSH_PRIVATE_KEY и SSH_KNOWN_HOSTS - переменные в Settings → CI/CD → Variables
- apk add --no-cache openssh-client
- eval $(ssh-agent -s)
- echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
- mkdir -p ~/.ssh && echo "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
script:
# в compose на сервере: image: ${CI_REGISTRY_IMAGE}/backend:${IMAGE_TAG}
- ssh deploy@$SERVER "cd /opt/app && IMAGE_TAG=$CI_COMMIT_SHA docker compose pull && IMAGE_TAG=$CI_COMMIT_SHA docker compose up -d"
only:
- main
when: manual # ручное подтверждение деплоя
Мини-задание
- Создай
.gitlab-ci.ymlс двумя stages:testиbuild - Добавь
package-lock.jsonв репозиторий - Настрой кэширование загрузок npm (
.npm) и Go-модулей - Добавь
only: merge_requestsдля тестов - Проверь пайплайн в GitLab → CI/CD → Pipelines
Итог
- CI = автоматизация: lint → test → build → deploy при каждом пуше/MR. Как выглядит весь командный процесс вокруг этого pipeline (защита веток, MR, релизы по тегам) - в мини-проекте трека Git.
.gitlab-ci.yml- stages (последовательно), jobs (параллельно внутри stage).npm ci+package-lock.json- детерминированные зависимости в CI.- Кэширование: кеш npm (
.npm) и Go-модули - экономия минут на каждом запуске. - Docker-образы: DinD (просто) vs Kaniko (безопасно + быстро с кэшем).
- Секреты - через GitLab CI Variables, не в
.gitlab-ci.yml.
Типичная ошибка
Забыть package-lock.json в git - npm ci упадёт. Lock-файл должен быть в репозитории и обновляться через npm install локально.
Другая ошибка - хранить секреты (пароли, токены, SSH-ключи) в .gitlab-ci.yml. Даже если репозиторий приватный - secrets должны быть в GitLab CI Variables (Settings → CI/CD → Variables, с флагом masked).
Мини-практика (10-15 минут)
Создай минимальный .gitlab-ci.yml для Go-проекта и запусти локально через gitlab-runner:
# Установи gitlab-runner (если есть Docker)
# Или проверь на GitLab - создай тестовый репозиторий
# Минимальный .gitlab-ci.yml:
cat > .gitlab-ci.yml <<'EOF'
stages:
- test
go:test:
image: golang:1.22-alpine
stage: test
script:
- go version
- go test ./... -v
EOF
# Пуш в GitLab → смотри Pipelines
git add .gitlab-ci.yml
git commit -m "ci: add basic pipeline"
git push
Открой GitLab → CI/CD → Pipelines - увидишь свой пайплайн.