GitLab CI: lint, test и сборка образов

GitLab CI: lint, test и сборка образов

CI (Continuous Integration) - автоматизация рутины: тесты, линтинг, сборка образов, деплой. GitLab CI запускает пайплайн при каждом пуше - робот делает скучное за тебя.

Структура пайплайна от языка не зависит: stages, jobs, образ на джобу, артефакты между этапами. Меняются только команды внутри script и базовый образ - примеры для Go, PHP и Python ниже во вкладках.

Как работает GitLab CI

git push → парсинг .gitlab-ci.yml → pipeline запускает stages lint → test → build по очереди

Пайплайн = набор stages (этапов), выполняемых последовательно. Внутри stage - jobs (задачи), которые могут выполняться параллельно.

GitLab CI pipeline: lint -> test -> build -> deploy, jobs внутри stage параллельно; в MR и в main запускаются разные stages

.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-DockerKaniko
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 - увидишь свой пайплайн.

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.