CI/CD-пайплайн с нуля: пошаговое руководство от коммита до продакшна | AdminWiki

CI/CD-пайплайн с нуля: пошаговое руководство от коммита до продакшна

20 ноября 2026 13 мин. чтения

Что входит в минимальный CI/CD-пайплайн

Минимальный рабочий пайплайн состоит из шести стадий после коммита: lint, test, build, publish, deploy, verify. Пуш в основную ветку запускает цепочку, каждая следующая стадия получает результат предыдущей, а деплой не стартует, если упала хотя бы одна проверка.

Границу между CI и CD удобно проводить по появлению неизменяемого артефакта с версией. Всё, что происходит до его публикации, относится к CI: линтеры, тесты, сборка. Всё, что после, относится к CD: доставка на сервер, переключение трафика и подтверждение, что сервис отвечает.

Схема переносится на любой инструмент, отличается только синтаксис описания джоб и способ передачи файлов между ними. Как это устроено в GitLab CI, GitHub Actions и Jenkins, разбираем в материале об автоматизированном развёртывании приложений через CI/CD.

СтадияЗадачаЧто ломается без неёМожно ли отложить
lintСинтаксис, стиль, очевидные ошибкиМусор доезжает до ревью и тестовНет, это самая дешёвая проверка
testЮнит- и интеграционные тестыРегрессии уходят в продНет
buildСборка бинарника или образаНечего выкатыватьНет
publishПуш образа в registry с тегом коммитаДеплой тянет что попало или ничегоНет
deployВыкат на сервер или в кластерАртефакт собран, но не доставленНет
verifyHealth-check и smoke-проверкаЗелёный пайплайн при мёртвом сервисеНет

Версии фиксируйте явно: тег образа раннера, версию CLI, версию сборщика. Плавающий latest превращает пайплайн в лотерею, потому что обновление образа на стороне registry меняет поведение сборки без единого коммита в вашем репозитории.

Стадии пайплайна и их порядок

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

СтадияПорядок величиныЧто блокирует при падении
lintсекундывсе последующие стадии
testот десятков секунд до нескольких минутсборку, публикацию, деплой
buildминутыпубликацию и деплой
publishдесятки секунд плюс загрузка в registryдеплой
deployдесятки секундhealth-check и отметку релиза
verifyсекунды плюс ретраизакрытие релиза как успешного

Значения в таблице дают порядок величины, а не норматив: цифры зависят от проекта, раннера и размера образа. Поведение fail-fast настраивается в самом CI. В GitLab CI по умолчанию пайплайн останавливает выполнение последующих стадий, если джоба на более ранней стадии упала, а продолжение запуска последующих джоб настраивается через allow_failure — это описано в справочнике по синтаксису CI/CD YAML в документации GitLab. Проверяется это практикой: сломайте тест в отдельной ветке и убедитесь, что деплой остался в статусе skipped.

Что можно отложить на потом

Сначала нужен сквозной путь от коммита до работающего сервиса. Всё остальное добавляйте после того, как первая версия отработала на тестовой среде.

  • Матрицы версий языка и параллельные джобы: ускоряют прогон, но усложняют чтение конфига.
  • Тяжёлое кэширование зависимостей и слоёв: даёт выигрыш в минутах, когда пайплайн уже стабилен.
  • SAST, сканирование образа на уязвимости, SBOM: полезно, но это отдельный слой, который не мешает доставке работать.
  • Несколько окружений (dev, stage, prod) и стратегии blue-green или canary: требуют минимум двух площадок и переключения трафика.
  • Сбор метрик DORA: время до прода, частота релизов, доля отказов.

Три вещи не откладываются: хранение секретов, ручное подтверждение перед продом и отработанный откат. Их отсутствие превращает автоматизацию в источник инцидентов, потому что скорость доставки растёт, а цена ошибки остаётся прежней.

Как настроить CI/CD-пайплайн: структура конфигурации

Конфигурация описывает стадии, джобы, зависимости между ними, артефакты и кэш, плюс правила запуска. Ниже скелет в общем виде, чтобы увидеть структуру до привязки к синтаксису.

stages: [lint, test, build, publish, deploy]

lint:    { stage: lint,    needs: [] }
test:    { stage: test,    needs: [lint] }
build:   { stage: build,   needs: [test] }
publish: { stage: publish, needs: [build], только main }
deploy:  { stage: deploy,  needs: [publish], ручное подтверждение, окружение production }

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

Стадии, джобы и зависимости

Стадия задаёт фазу, джоба описывает конкретную работу внутри фазы. Джобы одной стадии идут параллельно, переход к следующей происходит после успеха всех джоб предыдущей. Ключевое слово needs строит граф напрямую: джоба деплоя зависит от публикации образа, а не от всех стадий подряд, и лишние джобы в цепочку не попадают.

stages:
  - lint
  - test
  - publish
  - deploy

lint:
  stage: lint
  image: python:3.12-slim
  script:
    - pip install ruff==0.6.9
    - ruff check .

test:
  stage: test
  image: python:3.12-slim
  script:
    - pip install -r requirements.txt
    - pytest -q --junitxml=report.xml
  artifacts:
    when: always
    paths:
      - report.xml

build-and-push:
  stage: publish
  image: docker:27-cli
  needs: ["test"]
  script:
    - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
    - docker build -t "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA" .
    - docker push "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

deploy-prod:
  stage: deploy
  needs: ["build-and-push"]
  environment:
    name: production
    url: https://app.example.com
  when: manual
  script:
    - echo "deploy $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA"

В этом фрагменте GitLab CI: стадии объявлены списком, CI_REGISTRY_IMAGE и CI_COMMIT_SHORT_SHA приходят из предопределённых переменных, пароль передаётся через --password-stdin, чтобы не осесть в истории shell, artifacts с when: always сохраняет отчёт тестов даже при падении джобы.

Сборку и публикацию в GitLab CI обычно объединяют в одну джобу. Каждый джоб выполняется на чистом раннере, локальный docker-кэш между джобами не переживает, и второй джоб собирал бы образ заново. Альтернатива для больших проектов: сборка через buildx с экспортом кэша в registry через --cache-to type=registry. Docker Buildx поддерживает registry как бэкенд хранения кэша, и такой кэш нужно явно экспортировать и явно импортировать — см. описание бэкендов кэша в документации Docker и справочник по docker buildx build. Отдельную джобу публикации в этом случае добавляют, чтобы разделить сборку и пуш, но выигрыш зависит от того, насколько стабильно кэш переиспользуется между запусками.

name: ci
on:
  push:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - run: pip install ruff==0.6.9
      - run: ruff check .

  deploy:
    needs: [lint]
    runs-on: ubuntu-24.04
    environment: production
    steps:
      - run: echo "deploy ${GITHUB_SHA}"

В GitHub Actions окружение environment: production связывается с protection rules, где задаются обязательные ревьюеры, список разрешённых ветвей и права на запуск. Номера версий в примерах условные, подставьте актуальные теги под свой стек и зафиксируйте их в файле, а не в переменной сборочного сервера.

Артефакты и кэш: что передавать между стадиями

Артефакт это результат, который нужен дальше: собранный бинарник, docker-образ, отчёт тестов, SBOM. Кэш это ускоритель повторных запусков: скачанные зависимости, слои сборки, каталог пакетного менеджера. Артефакт версионируется и не меняется, кэш можно потерять в любой момент, и пайплайн от этого не должен падать.

  • Тег образа привязывайте к коммиту (короткий SHA), при необходимости добавляйте semver. latest оставьте как указатель, деплойте по неизменяемому тегу.
  • Кэш не источник истины: если джоба собралась только благодаря кэшу, результат невоспроизводим на чистом раннере.
  • Кэш между ветками не смешивайте: содержимое может быть подменено коммитом из непревилегированной ветки.
  • Отчёты тестов сохраняйте как артефакт с when: always, иначе при падении лог и отчёт пропадут.
  • Ограничивайте срок хранения артефактов: образы живут в registry, а не в артефактах CI.

Секреты в пайплайне: переменные окружения и защищённые хранилища

Правило одно: секретов нет в репозитории, в конфиге пайплайна и в логах. Токены и пароли живут в защищённом хранилище CI (masked и protected variables, secrets manager, внешний Vault) и попадают в джобу как переменные окружения на время выполнения.

Переменные окружения против файлов .env

.env в репозитории это утечка, даже если файл удалён следующим коммитом. Он остаётся в истории git, в форках и в клонах у всех, кто успел сделать pull. Проверьте историю:

git log --all --oneline -- .env
git log --all -p -S "API_KEY" -- . ':!*.md'

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

Приложение читает .env, значит файл генерируется на этапе деплоя из защищённых переменных и попадает в .gitignore и в .dockerignore. Второй пункт критичен: без него файл уедет внутрь образа и останется в слое, даже если следующий слой его удалит.

Полную проверку репозиториев, пайплайнов и артефактов на утечки разбираем в материале об аудите безопасности DevOps-цепочки.

Права доступа и маскирование

Маскирование скрывает значение в логе джобы, но не мешает записать его в файл и приложить артефактом. В GitLab CI переменные по умолчанию создаются как masked, и значение скрывается в логах джобы, но только если оно соответствует определённым требованиям к маске. Многострочные значения в переменных GitLab CI сейчас не поддерживаются из-за ограничений скриптового окружения Auto DevOps, поэтому приватные ключи и сертификаты через обычную переменную не передать: используйте файловые переменные или выдачу из хранилища на время шага. Это описано в документации GitLab по CI/CD-переменным.

Protected-переменные GitLab доступны только в пайплайнах, запущенных на protected branches или protected tags, то есть прод-секреты не видны в пайплайнах feature-веток. В GitHub Actions secrets окружения привязываются к окружению с protection rules, а сборки из форков прод-токены не получают.

Токен CI ограничивайте по области действия: read-only доступ к registry, конкретный namespace, короткий срок жизни. Права на изменение настроек CI тоже привилегия: тот, кто может править конфиг пайплайна, может вывести любой секрет в лог.

  • Маскирование включено для всех значений, которые поддерживают маску.
  • Прод-секреты привязаны к защищённым веткам и защищённому окружению.
  • В логах нет вывода env целиком: команды вида env, printenv, set в скриптах пайплайна не используются.
  • При подозрении на утечку секрет ротируется, а не оправдывается объяснением в чате.

Безопасный выкат: ручное подтверждение, откат и health-check

Три механизма закрывают главный страх: «деплой сломает прод». Подтверждение не даёт выкату случиться незаметно, откат ограничивает время деградации, health-check не позволяет считать успешным релиз, после которого сервис не отвечает.

Ручное подтверждение на деплой

В GitLab CI джоба помечается как ручная добавлением when: manual в .gitlab-ci.yml; по умолчанию такие джобы отображаются как skipped при старте пайплайна. Protected environments можно использовать, чтобы требовать ручные подтверждения перед деплоем и гарантировать, что деплой в окружение выполняют только пользователи с соответствующими привилегиями. Вместе с блокирующими ручными джобами protected environments задают список пользователей, которым разрешено подтверждать последующие стадии пайплайна: следующие стадии запускаются только после срабатывания ручной джобы. Protected branches дополнительно строже защищают ручные деплои от запуска неавторизованными пользователями. Подробности — в документации GitLab по управлению запуском джоб и в разделе о защищённых окружениях.

В GitHub Actions окружение с protection rules и обязательными ревьюерами даёт тот же эффект: деплой ждёт одобрения назначенных ревьюеров. Доступ к окружению ограничьте ролями: подтверждать прод должен не любой участник проекта, а дежурный или ответственный за релиз.

Подтверждение должно быть осознанным действием. Перед нажатием проверьте, что именно выкатывается: тег образа, коммит, список изменений. Полезно вывести это в лог джобы первой строкой, чтобы в истории осталась привязка релиза к коммиту.

Процедура отката

Откат возвращает предыдущий рабочий тег образа. Пересборка из старого коммита даёт другой артефакт: базовый образ и зависимости могли измениться, и вы получите не то состояние, которое работало вчера.

docker service update --image registry.example.com/app:<previous-sha> app_web

docker pull registry.example.com/app:<previous-sha>
docker compose up -d app

Первая команда обновляет сервис в Docker Swarm, вторая пара относится к Docker Compose: сначала скачиваем нужный тег, затем перезапускаем сервис. Подставьте тег предыдущего успешного релиза, он должен быть заранее известен.

Откат кода не откатывает схему базы данных. Миграции пишите обратно совместимыми: новая версия кода работает со старой и новой схемой, миграция накатывается отдельным шагом, а удаление столбцов откладывается на релиз, когда предыдущая версия гарантированно выведена из эксплуатации. Перед любыми изменениями на сервере сделайте резервную копию базы и проверьте процедуру отката на тестовой среде: непроверенный откат это надежда, а не план.

Health-check после публикации

Деплой считается успешным только после ответа сервиса. Простейший вариант: опрос эндпоинта здоровья с ретраями и проверкой кода ответа.

for i in $(seq 1 10); do
  code=$(curl -s -o /dev/null -w "%{http_code}" https://app.example.com/healthz)
  if [ "$code" = "200" ]; then
    echo "ok: $code"
    exit 0
  fi
  sleep 6
done
echo "health-check failed"
exit 1

Ожидаемый результат: строка ok: 200 и код выхода 0. При провале джоба завершается с ненулевым кодом, пайплайн становится красным, релиз не помечается успешным, дежурный получает уведомление и запускает откат. Дополнительно проверьте статус контейнера, если в образе объявлен HEALTHCHECK:

docker inspect --format '{{.State.Health.Status}}' app_web
docker ps --filter "name=app_web" --format "{{.Status}}"

Health-check подтверждает, что процесс жив. Бизнес-логику он не проверяет: приложение с мёртвым пулом соединений к базе может отвечать 200 на /healthz, если эндпоинт смотрит только на сам факт запуска. Добавьте smoke-тест на ключевой сценарий, например запрос к API, который действительно читает данные.

Как проверить, что пайплайн работает

Проверка идёт сверху вниз: запуск на тестовой ветке, порядок стадий, поведение при падении, отсутствие секретов в логах, ручное подтверждение, откат, health-check. Методику тестирования инфраструктурного кода и пайплайнов на стенде разбираем в материале о надёжном CI/CD-пайплайне.

Команды проверки статуса пайплайна

Статус смотрится в веб-интерфейсе CI, через CLI инструмента или через API. Точный синтаксис зависит от CI, ниже распространённые варианты.

gh run list --limit 5
gh run view <run-id> --log

Для GitHub CLI ожидаемый вывод: список запусков со статусом completed и заключением success, либо failure с указанием упавшей джобы. Для GitLab при установленном CLI подойдёт glab ci status в каталоге репозитория, универсальный вариант без CLI это API:

curl -s --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.example.com/api/v4/projects/<project-id>/pipelines?ref=main&per_page=1"

В ответе смотрите поля status (success, failed, running, manual) и id пайплайна. Статус manual означает, что пайплайн дошёл до джобы деплоя и ждёт подтверждения, это нормальное состояние перед продом. В Jenkins статус последней сборки отдаёт API джобы:

curl -s "https://jenkins.example.com/job/<job-name>/lastBuild/api/json"

Чек-лист перед первым деплоем на прод

  • Секреты лежат в защищённом хранилище, маскирование включено, в логах нет вывода env.
  • .env и ключи отсутствуют в репозитории, в истории git и в .dockerignore.
  • Версии образов и раннеров зафиксированы тегами, latest в деплое не используется.
  • Прод-окружение защищено, деплой требует ручного подтверждения и доступен ограниченному кругу.
  • Откат отработан на тестовой среде, тег предыдущего релиза известен и хранится рядом с пайплайном.
  • Health-check входит в пайплайн, при его провале релиз помечается как неуспешный.
  • Резервная копия базы сделана, миграции обратно совместимы.
  • Уведомления о падении пайплайна приходят в рабочий канал, а не в никуда.

Тестовый стенд для такой проверки проще держать отдельно от прода, чтобы отработка отката не касалась боевых данных. Подойдёт небольшой VPS или отдельный namespace в кластере, например на облачной инфраструктуре Timeweb Cloud.

Типичные ошибки при сборке первого пайплайна

ОшибкаПоследствиеКак исправить
latest вместо фиксированного тегаНевозможно понять, что именно работает на проде, откат неоднозначенТег по короткому SHA коммита, latest только как указатель
Секреты в логах и артефактахУтечка токена в историю сборок и в отчётыУбрать printenv и echo секретов, включить маскирование, ротировать токен
Деплой без health-checkЗелёный пайплайн при недоступном сервисеДобавить стадию verify с опросом эндпоинта здоровья и кодом выхода
Нет процедуры откатаВремя деградации растягивается на часы ручной сборкиХранить предыдущие теги, откатывать переключением тега, репетировать на стенде
Кэш воспринимается как источник истиныСборка проходит локально и падает на чистом раннереПроверочный прогон с отключённым кэшем перед релизом
Слишком широкие права токена CIКомпрометация раннера даёт доступ ко всем репозиториям и registryRead-only scope, отдельный токен на задачу, ротация
Автодеплой на каждый коммитПрод меняется без ревью и вне окна релизаРучное подтверждение и защищённое окружение на прод-стадии
Секреты в образе через .dockerignoreЗначение остаётся в слое даже после удаления файлаГенерировать конфиг при деплое, не копировать .env в контекст сборки

Отдельная ошибка системного уровня: пайплайн проверяет код, но не проверяет сам процесс доставки. Аудит цепочки с интеграцией проверок в CI разбираем в материале об аудите безопасности для DevOps.

Начните с одного действия: соберите сквозной путь на тестовой ветке и прогоните его целиком, включая искусственно сломанный тест и ручной откат. Пайплайн, который вы ни разу не роняли и не откатывали, проверен наполовину.

Поделиться: