Что должно быть в пайплайне Docker: пять шагов и точка контроля
Пайплайн для Docker-образа решает пять задач в жёстком порядке: собрать образ из Dockerfile, переиспользовать слои прошлых сборок, присвоить теги, привязанные к коммиту, отправить образ в registry и подтвердить, что он там есть и запускается. Пятый шаг пропускают чаще всего, и именно он отличает зелёную джобу от рабочего артефакта: код возврата 0 сообщает только о том, что команда завершилась без ошибки.
Два ограничения задают рамки любого примера ниже. Синтаксис шагов определяет CI-инструмент: команда docker build в GitLab CI и GitHub Actions оформлена по-разному, поэтому даём фрагменты для обоих. Поведение кэша, поддерживаемые флаги и обработка тегов зависят от версии Docker и драйвера BuildKit, поэтому версии фиксируем в самом пайплайне и печатаем в лог.
Официальный маршрут обучения Docker выстраивает ту же последовательность: Dockerfile для реального приложения, быстрая сборка, компактный образ, публикация в Docker Hub (docs.docker.com/learn/paths). Разница в акцентах: в CI важна воспроизводимость, а не разовый успешный результат на рабочей машине.
Схема, к которой возвращаемся при настройке:
- Зафиксировать версии: образ docker:27-cli вместо плавающего docker:cli, вывод docker version и docker buildx version первой командой джобы.
- Авторизоваться в registry: docker login с токеном из переменных CI.
- Собрать образ с внешним кэшем и OCI-метками, где указан commit SHA.
- Проставить теги: неизменяемый тег по SHA, релизный semver, latest только на релизной сборке.
- Опубликовать и проверить: docker push, docker manifest inspect, smoke-запуск.
Чек-лист перед публикацией, по которому удобно проверять любую правку пайплайна:
- тег образа содержит commit SHA, и метка revision совпадает с коммитом;
- секретов нет ни в контексте сборки, ни в слоях образа;
- базовый образ зафиксирован по тегу или digest, а не взят как latest;
- пуш подтверждён не только кодом возврата, но и digest из registry.
Какие версии Docker и CI фиксируем в примерах
BuildKit работает как сборщик по умолчанию в Docker 23.0 и новее, а docker buildx поставляется отдельным плагином docker-buildx-plugin. Примеры ниже рассчитаны на Docker Engine 24 и новее. Если ваш CI-образ тянет docker:cli без тега, вы получаете плавающую версию: одна и та же джоба через месяц может вести себя иначе. Укажите конкретный тег вида docker:27-cli, подставив мажорную версию, которую используете в проде.
Версию печатаем в лог до сборки, чтобы при разборе ошибки не гадать об окружении:
docker version docker buildx version docker info
docker version показывает клиент и сервер отдельно, docker info добавляет драйвер сборщика и хранилище. Если версия Docker в CI отличается от локальной, поведение кэша и набор доступных флагов могут расходиться: проверяйте на своей версии, а не на версии из статьи.
Сборка образа в CI: Dockerfile, контекст и шаги для GitLab CI и GitHub Actions
Для CI важна структура Dockerfile, а не только его содержимое. Multi-stage отделяет установку зависимостей от рантайма: в финальный образ попадают рабочие файлы и прод-зависимости, без компилятора и dev-пакетов. Шаблон продакшн-сборки с порядком слоёв под кэш, non-root и HEALTHCHECK разбираем отдельно (Dockerfile для продакшна). Пример для приложения на Node.js:
# syntax=docker/dockerfile:1 FROM node:22-alpine AS deps WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci --omit=dev FROM node:22-alpine AS runtime ENV NODE_ENV=production WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY package.json ./ COPY src ./src USER node EXPOSE 3000 CMD ["node", "src/server.js"]
Что даёт такая схема: слой npm ci пересобирается только при изменении package.json или package-lock.json, копирование исходников идёт после установки пакетов и не сбрасывает её. USER node переключает процесс на непривилегированного пользователя. Если у приложения есть шаг компиляции, добавьте стадию builder с полными зависимостями и копируйте в runtime только собранный артефакт.
GitLab CI: сборка в контейнере docker:27-cli, демон docker:dind как service, учётные данные из предопределённых переменных CI_REGISTRY, CI_REGISTRY_USER, CI_REGISTRY_PASSWORD, CI_REGISTRY_IMAGE, CI_COMMIT_SHA. Для dind нужен runner с privileged = true или смонтированный docker socket, иначе docker build внутри джобы не увидит демон.
build:
stage: build
image: docker:27-cli
services:
- docker:dind
variables:
DOCKER_TLS_CERTDIR: "/certs"
before_script:
- docker version
- docker buildx version
- echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
- docker buildx create --driver docker-container --name ci --use
script:
- >
docker buildx build
--push
--tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA"
--label org.opencontainers.image.revision=$CI_COMMIT_SHA
--cache-from type=registry,ref=$CI_REGISTRY_IMAGE:buildcache
--cache-to type=registry,ref=$CI_REGISTRY_IMAGE:buildcache,mode=max
.
Драйвер docker-container нужен для экспорта кэша в registry: встроенный драйвер docker не поддерживает --cache-to type=registry. На постоянном self-hosted раннере билдер создают один раз, иначе команда падает на существующем имени, поэтому либо убирайте docker buildx create из каждой джобы, либо добавляйте проверку существования билдера. Если внешний кэш не нужен, удалите строки с cache-from и cache-to.
GitHub Actions: docker/build-push-action@v6 принимает tags, labels и параметры кэша, а кэш типа gha хранится в инфраструктуре Actions и переживает запуски. Токен ghcr.io берём из secrets.GITHUB_TOKEN с правом packages: write.
name: build-and-push
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v4
- run: docker version && docker buildx version
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- uses: docker/build-push-action@v6
with:
context: .
push: true
tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
labels: org.opencontainers.image.revision=${{ github.sha }}
cache-from: type=gha
cache-to: type=gha,mode=max
Проверка результата сборки до пуша: docker image ls с ожидаемым тегом и размером, отсутствие ошибок в логе сборки. Разбор флагов docker build, включая -t, -f, --build-arg и --no-cache, есть в материале про команду docker build.
Что исключить из контекста сборки через .dockerignore
Контекст передаётся демону целиком, поэтому лишние файлы замедляют передачу и могут оказаться в слое. Минимальный набор исключений:
.git .env .env.* node_modules dist coverage *.log .idea
Отдельно про .env: файл с секретами не должен ни уезжать в контекст, ни попадать в образ через COPY . . . Проверка: в выводе BuildKit строка transferring context показывает размер контекста, а docker history --no-trunc по собранному образу показывает команды слоёв. Файлов с токенами в истории быть не должно.
Почему сборка падает в CI и как это диагностировать
Смотрите первый упавший шаг, а не последний: остальные ошибки обычно следствие. Категории причин, которые закрывают почти все случаи:
- нет доступа к registry базового образа: docker login нужен до сборки, если базовый образ приватный;
- у runner нет прав: dind требует privileged, альтернатива - смонтированный docker socket;
- неверный путь к Dockerfile или контексту: флаг -f и последний аргумент команды должны указывать на существующие файлы;
- базовый образ с тегом, которого нет в registry, или снятый тег.
Порядок диагностики: выполните ту же команду docker build локально с тем же тегом и тем же контекстом, затем docker info в джобе, чтобы увидеть версию демона и драйвер сборщика. Тексты ошибок зависят от версии, ориентируйтесь на категорию, а не на формулировку.
Кэширование слоёв Docker: как порядок инструкций и внешний кэш ускоряют сборку
BuildKit переиспользует слой, пока не изменилась инструкция и входные файлы этой инструкции. Отсюда правило: редко меняющиеся шаги идут в Dockerfile раньше, часто меняющиеся позже. Антипример:
COPY . . RUN npm ci --omit=dev
Здесь любая правка в исходниках сбрасывает кэш установки зависимостей, и повторная сборка идёт столько же, сколько первая. Исправленный порядок:
COPY package.json package-lock.json ./ RUN npm ci --omit=dev COPY . .
Кэш инвалидируется по содержимому файлов из COPY и по строке инструкции: правка package-lock.json пересобирает слой npm ci, правка src/* оставляет его нетронутым.
Локальный кэш помогает только при повторных сборках на той же машине. Эфемерный раннер (облачный CI, контейнер на один запуск) кэш теряет, и каждая сборка начинается с нуля. Внешний кэш решает это: buildx экспортирует кэш в registry или в кэш CI и импортирует его в следующей джобе.
docker buildx build \ --tag "$REGISTRY/$IMAGE:$TAG" \ --cache-from type=registry,ref=$REGISTRY/$IMAGE:buildcache \ --cache-to type=registry,ref=$REGISTRY/$IMAGE:buildcache,mode=max \ --push .
mode=max кэширует все стадии, включая промежуточные, mode=min только финальный образ. Для GitHub Actions те же параметры передаются строками cache-from: type=gha и cache-to: type=gha,mode=max. Для GitLab CI вариант с registry-кэшем не требует внешнего хранилища, но занимает место в registry.
Кэш в registry против кэша на runner
| Критерий | Кэш на runner | Кэш в registry или gha |
|---|---|---|
| Где живёт | локальный диск раннера | registry проекта или кэш CI |
| Переживает пересоздание раннера | нет | да |
| Работает при нескольких раннерах | нет | да |
| Стоимость | диск раннера | место в registry, нужен retention |
| Когда выбирать | один постоянный self-hosted раннер | облачный CI, несколько раннеров |
Кэш в registry растёт, если его не чистить: задайте retention или отдельный тег с ограниченным сроком хранения, иначе через полгода кэш займёт больше места, чем сами образы.
Когда кэш мешает: устаревшие зависимости и инвалидация
Кэш подставит старые пакеты, если lock-файл не скопирован отдельным слоем: установщик видит прежний манифест и ставит версии из него. Лечится порядком инструкций, а не флагом --no-cache. Флаг полезен как диагностика: он показывает, воспроизводится ли проблема без кэша.
Проверка инвалидации: измените одну строку в package-lock.json и запустите сборку. В выводе BuildKit напротив слоя установки зависимостей не должно быть отметки CACHED, а неизменные слои остаются CACHED. Сравните лог первой и второй джобы: время повторной сборки должно быть заметно меньше.
Не отключайте проверку подписи пакетов ради скорости и не переходите со lock-файла на свободные диапазоны версий: это ломает воспроизводимость сильнее, чем любой кэш.
Стратегия тегирования: semver, commit SHA и почему latest публикуют не вслепую
Тег это единственная связь между артефактом в registry и кодом в git. Три рабочие схемы и их роли:
| Схема | Что даёт | Где применять | Ограничение |
|---|---|---|---|
| commit SHA | уникальный тег, ставится автоматически, указывает на конкретный коммит | деплой, откат, трассировка | нечитаем для человека |
| semver (1.4.2) | читаемый релиз, ставится на аннотированный git-тег | релизы, коммуникация с заказчиком | требует дисциплины в git-тегах |
| latest | плавающий указатель на последнюю сборку | локальный запуск, быстрый старт | не даёт отката и не говорит о версии |
Рекомендация: в деплой уходит SHA или semver, latest обновляется только на релизной сборке. Один образ получает несколько тегов, сборка при этом одна:
docker tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" "$CI_REGISTRY_IMAGE:1.4.2" docker tag "$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA" "$CI_REGISTRY_IMAGE:latest"
Перезапись тега в registry технически возможна, поэтому для продакшена надёжнее неизменяемые теги плюс сверка по digest: digest меняется вместе с содержимым образа и не зависит от того, кто и когда переставил тег. Практику фиксации версий и digest для воспроизводимых сборок разбираем в материале про воспроизводимые окружения.
Как связать тег образа с коммитом
SHA берётся из предопределённой переменной CI: CI_COMMIT_SHA в GitLab CI, github.sha в GitHub Actions. Значение попадает и в имя тега, и в OCI-метки, которые видны в registry:
docker buildx build \ --tag "$REGISTRY/$IMAGE:$CI_COMMIT_SHA" \ --label org.opencontainers.image.revision="$CI_COMMIT_SHA" \ --label org.opencontainers.image.source="$CI_PROJECT_URL" \ --label org.opencontainers.image.version="$CI_COMMIT_TAG" \ --push .
CI_COMMIT_TAG заполняется только в пайплайне по git-тегу, в обычной сборке метка version останется пустой. Это нормально, ключевая метка здесь revision. Проверка двусторонней связи: метка в образе должна совпадать с HEAD коммитом.
docker inspect --format '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$REGISTRY/$IMAGE:$TAG"
git log -1 --format=%H
Обе команды возвращают один и тот же хеш. Пустая метка означает, что сборка шла без label или тег проставлен вручную после пуша.
Как откатиться на предыдущий образ
Порядок без пересборки: возьмите из истории деплоя предыдущий рабочий тег, задеплойте его тем же способом, что и текущий, сверьте метку revision и выполните smoke-запуск. Latest для отката не подходит: неизвестно, какой коммит за ним стоит, а после следующего пуша указатель сдвинется. Если latest должен снова указывать на откатанную версию, перетегируйте осознанно, отдельным действием и с записью в журнале изменений.
Проверка после отката: docker inspect по образу и сверка revision с ожидаемым коммитом, затем запуск контейнера с healthcheck. Для критичных сервисов держите историю «тег образа - коммит - дата деплоя», иначе откат превращается в поиск по логам CI.
Публикация образа в registry: docker login, docker push и проверка результата
Публикация начинается с логина. Токен передаём через stdin, чтобы он не осел в истории команд и в логе:
echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"
Дальше push по каждому тегу. Путь образа зависит от registry: Docker Hub использует docker.io/<namespace>/<image>, GitLab Container Registry - registry.gitlab.com/<group>/<project>, GitHub Container Registry - ghcr.io/<owner>/<repo>. Синтаксис шагов задаёт CI-инструмент, сами команды docker login и docker push одинаковы.
for tag in "$CI_COMMIT_SHA" "$VERSION" latest; do docker push "$CI_REGISTRY_IMAGE:$tag" done
Зелёная джоба означает только код возврата 0. Проверять нужно registry: образ мог не дойти из-за прав, квоты или неверного имени тега. Пошаговая процедура загрузки в публичный и приватный реестр с разбором вывода docker push есть в отдельном руководстве (добавление образа в registry).
Проверка, что образ в registry и корректен
- docker manifest inspect "$REGISTRY/$IMAGE:$TAG": выводит манифест, слои и digest; ошибка об отсутствии манифеста означает, что тега в registry нет. В старых версиях CLI команда требовала включённых экспериментальных возможностей, там используйте docker buildx imagetools inspect.
- docker pull "$REGISTRY/$IMAGE:$TAG" на чистой машине: подтверждает доступность и права; для приватного registry нужен docker login.
- docker run --rm "$REGISTRY/$IMAGE:$TAG": smoke-запуск, ожидаемый вывод зависит от приложения или healthcheck.
- docker inspect --format '{{.RepoDigests}}' "$REGISTRY/$IMAGE:$TAG": сверка digest с тем, что показал манифест.
manifest inspect обращается к registry напрямую и не трогает локальный кэш образов, pull скачивает слои. Для ответа на вопрос «образ доступен другим» нужен первый вариант, желательно с машины, где локальной копии нет.
Секреты в CI: как не закоммитить токен registry
- токен только в masked и protected переменных GitLab CI или в GitHub Secrets, в конфиге пайплайна его нет;
- не передавайте секреты через ARG: значения ARG видны в docker history;
- приватные пакеты ставьте через BuildKit secrets, файл монтируется на один шаг и не остаётся в слое;
- не печатайте .npmrc, .env и конфиги целиком в лог: маскирование скрывает известные значения, а не весь файл.
# в Dockerfile RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci --omit=dev # команда сборки docker buildx build --secret id=npmrc,src="$HOME/.npmrc" --tag "$IMAGE:$TAG" --push .
Проверка: docker history --no-trunc по образу не должен содержать значений токенов. Если секрет уже попал в коммит или в слой, отзовите его в registry и выпустите новый: удаление строки из репозитория утечку не отменяет.
Безопасность цепочки поставки: доверенный базовый образ, сканирование и подпись
Отправная точка безопасности цепочки поставки - доверенный базовый образ. Дальше нужно находить и исправлять то, что реально эксплуатируется, подписывать собранное и допускать в production только проверяемое (docs.docker.com/learn/paths). На практике это означает фиксированный тег или digest базового образа, регулярное обновление базы и политику допуска образа в прод.
Порядок шагов: сканер в пайплайне с падением джобы по порогу severity, исправление находок высокого приоритета, подпись образа после успешного пуша и проверка подписи на стороне деплоя. Конкретные инструменты и их флаги зависят от вашей политики: для сканирования достаточно понимать, что порог задаётся в конфиге пайплайна, а «ноль находок» в реальном проекте недостижим, и погоня за ним останавливает релизы.
Уровни разделяем честно: сборка и пуш это обязательный минимум, сканирование и подпись - следующий слой, который включают по требованиям безопасности. Готовые конфигурации для Jenkins, GitLab CI и GitHub Actions с проверкой уязвимостей разбираем в материале про интеграцию реестра с CI/CD.
Минимальный чек-лист перед публикацией
- базовый образ зафиксирован по тегу или digest;
- .dockerignore исключает .env, .git и node_modules;
- секреты только в переменных CI или BuildKit secrets;
- тег содержит commit SHA, метка revision совпадает с коммитом;
- latest обновляется только на релизной сборке;
- внешний кэш настроен, в логе повторной сборки есть CACHED;
- после пуша выполнен docker manifest inspect и smoke-запуск;
- сканирование и подпись включены, если этого требует политика.
Итог: порядок шагов пайплайна и что проверять после каждого
- Зафиксировать версии: docker version, docker buildx version. Проверка: в логе видны клиент, сервер и драйвер сборщика.
- Авторизоваться: docker login с токеном из переменных CI. Проверка: шаг завершается без ошибки авторизации, токен в логе замаскирован.
- Собрать с кэшем и метками: docker buildx build с --cache-from, --cache-to и --label. Проверка: docker image ls показывает ожидаемый тег, в повторной сборке есть CACHED.
- Проставить теги: SHA, semver, latest по правилу. Проверка: docker inspect возвращает revision, равный git log -1 --format=%H.
- Опубликовать: docker push по каждому тегу. Проверка: docker manifest inspect показывает манифест и digest.
- Проверить запуск: docker pull и docker run с healthcheck или коротким smoke-тестом. Проверка: приложение отвечает, контейнер не падает.
- Подключить сканирование и подпись, если требуются политикой. Проверка: джоба падает на находке выше порога, подпись проверяется при деплое.
Два ограничения остаются в силе при любом копировании примеров: синтаксис шагов задаёт ваш CI-инструмент, а поведение кэша и обработка тегов зависят от версии Docker и драйвера. Прогоняйте изменённый пайплайн на тестовой ветке и сравнивайте логи первой и второй сборки, прежде чем включать его для продакшена.